首次提交

2026-06-25 08:39:47 +08:00
parent 20a93c703a
commit c5cccd346b
169 changed files with 24720 additions and 0 deletions
@@ -0,0 +1,689 @@
+# 寸进（InchStep）API 设计文档
+
+> 文档版本：v1.0  
+> 对应后端：Go + Gin + GORM  
+> 基础 URL：http://localhost:8080  
+> 认证方式：JWT Bearer Token（7 天有效期）
+
+---
+
+## 目录
+
+1. 通用规范
+2. 认证模块
+3. 用户模块
+4. 打卡模块
+5. 社交模块
+6. 成就模块
+7. 健康检查
+
+---
+
+## 1. 通用规范
+
+### 1.1 统一响应格式
+
+`json
+{
+  "code": 0,
+  "message": "ok",
+  "data": { ... }
+}
+`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| code | int | 0=成功，非 0=错误码 |
+| message | string | 提示信息 |
+| data | any | 响应数据（成功时） |
+
+### 1.2 错误码
+
+| code | HTTP 状态 | 说明 |
+|------|-----------|------|
+| 0 | 200 | 成功 |
+| 400 | 400 | 请求参数错误 |
+| 401 | 401 | 未认证或令牌无效 |
+| 404 | 404 | 资源不存在 |
+| 409 | 409 | 资源冲突 |
+| 500 | 500 | 服务器内部错误 |
+
+### 1.3 认证方式
+
+所有需要认证的接口在 Header 中传递：
+
+`
+Authorization: Bearer <jwt_token>
+`
+
+### 1.4 公共查询参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| page | int | 页码，从 1 开始 |
+| pageSize | int | 每页数量，默认 20，最大 100 |
+
+---
+
+## 2. 认证模块
+
+> 前缀：/api/auth | 无需认证
+
+### 2.1 注册
+
+`
+POST /api/auth/register
+`
+
+**请求体：**
+
+`json
+{
+  "phone": "13800138000"
+}
+`
+
+**响应：**
+
+`json
+{
+  "code": 0,
+  "message": "ok",
+  "data": {
+    "user": {
+      "id": "abc123def456",
+      "phone": "13800138000",
+      "nickname": null,
+      "avatar": null,
+      "privacy": 2,
+      "points": 0,
+      "createdAt": "2026-06-24T10:00:00+08:00"
+    },
+    "token": "eyJhbGciOiJIUzI1NiIs..."
+  }
+}
+`
+
+### 2.2 登录（手机号）
+
+`
+POST /api/auth/login
+`
+
+**请求体：**
+
+`json
+{
+  "phone": "13800138000"
+}
+`
+
+**逻辑**：
+- 手机号已注册 → 返回用户信息 + Token
+- 手机号未注册 → 自动注册后返回用户信息 + Token
+
+**响应：** 同注册接口
+
+---
+
+## 3. 用户模块
+
+> 前缀：/api/users | 需认证
+
+### 3.1 获取个人资料
+
+`
+GET /api/users/profile
+`
+
+**响应：**
+
+`json
+{
+  "code": 0,
+  "message": "ok",
+  "data": {
+    "id": "abc123def456",
+    "phone": "13800138000",
+    "nickname": "小明",
+    "avatar": "https://cdn.example.com/avatars/abc.jpg",
+    "bio": "每天进步一点点",
+    "motto": "寸进，日日皆有成长",
+    "privacy": 2,
+    "points": 42,
+    "createdAt": "2026-06-24T10:00:00+08:00",
+    "updatedAt": "2026-06-24T10:00:00+08:00"
+  }
+}
+`
+
+### 3.2 更新个人资料
+
+`
+PUT /api/users/profile
+`
+
+**请求体（仅包含要更新的字段）：**
+
+`json
+{
+  "nickname": "小明",
+  "bio": "每天进步一点点",
+  "motto": "寸进",
+  "avatar": "https://cdn.example.com/avatars/new.jpg",
+  "privacy": 2
+}
+`
+
+**可更新字段**：
+ickname、vatar、io、motto、privacy
+
+### 3.3 获取积分
+
+`
+GET /api/users/points
+`
+
+**响应：**
+
+`json
+{
+  "code": 0,
+  "data": { "points": 42 }
+}
+`
+
+### 3.4 注销账号
+
+`
+DELETE /api/users/account
+`
+
+**响应：** { "code": 0, "message": "ok" }
+
+**逻辑**：清除手机号、昵称、头像等敏感信息，保留打卡历史。
+
+---
+
+## 4. 打卡模块
+
+> 前缀：/api/checkin | 需认证
+
+### 4.1 打卡项管理
+
+#### 4.1.1 创建打卡项
+
+`
+POST /api/checkin/items
+`
+
+**请求体：**
+
+`json
+{
+  "name": "每天背单词",
+  "icon": "📚",
+  "category": "study",
+  "dailyGoal": "背 50 个单词",
+  "cycleType": "daily",
+  "privacy": 2
+}
+`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| name | string | 是 | 打卡项名称 |
+| icon | string | 否 | emoji 或图标名 |
+| category | string | 是 | study health habit hobby goal |
+| dailyGoal | string | 否 | 每日目标描述 |
+| cycleType | string | 是 | daily weekly every_other_day custom |
+| privacy | int | 否 | 1=公开 2=好友 3=私密（默认 2） |
+
+**响应：**
+
+`json
+{
+  "code": 0,
+  "data": {
+    "id": "item_abc123",
+    "userId": "abc123def456",
+    "name": "每天背单词",
+    "icon": "📚",
+    "category": "study",
+    "dailyGoal": "背 50 个单词",
+    "cycleType": "daily",
+    "privacy": 2,
+    "status": "active",
+    "createdAt": "2026-06-24T10:00:00+08:00"
+  }
+}
+`
+
+#### 4.1.2 获取打卡项列表
+
+`
+GET /api/checkin/items
+`
+
+**响应：**
+
+`json
+{
+  "code": 0,
+  "data": [
+    { "id": "...", "name": "每天背单词", "category": "study", "status": "active", ... },
+    { "id": "...", "name": "每晚冥想", "category": "habit", "status": "active", ... }
+  ]
+}
+`
+
+**说明**：只返回状态非 deleted 的打卡项，按创建时间倒序。
+
+#### 4.1.3 获取打卡项详情
+
+`
+GET /api/checkin/items/:id
+`
+
+#### 4.1.4 更新打卡项
+
+`
+PUT /api/checkin/items/:id
+`
+
+**可更新字段**：
+ame icon category daily_goal cycle_type privacy
+
+#### 4.1.5 删除打卡项（软删除）
+
+`
+DELETE /api/checkin/items/:id
+`
+
+**说明**：将 status 标记为 deleted，保留历史记录。
+
+#### 4.1.6 暂停打卡项
+
+`
+POST /api/checkin/items/:id/pause
+`
+
+**说明**：状态变为 paused。
+
+#### 4.1.7 恢复打卡项
+
+`
+POST /api/checkin/items/:id/resume
+`
+
+**说明**：状态回到 ctive。
+
+### 4.2 打卡记录
+
+#### 4.2.1 提交打卡
+
+`
+POST /api/checkin/records
+`
+
+**请求体：**
+
+`json
+{
+  "itemId": "item_abc123",
+  "checkDate": "2026-06-24",
+  "note": "今天背了 60 个单词",
+  "images": "[\"url1.jpg\",\"url2.jpg\"]"
+}
+`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| itemId | string | 是 | 打卡项 ID |
+| checkDate | string | 否 | 打卡日期（默认当天），格式 YYYY-MM-DD |
+| note | string | 否 | 备注文字（≤500字） |
+| images | string | 否 | JSON 数组字符串，图片 URL 列表 |
+
+**逻辑**：
+1. 验证打卡项存在且状态为 ctive
+2. 检查当日是否已打卡（防止重复）
+3. 创建打卡记录
+4. 发放打卡积分（+1）
+5. 返回记录
+
+**响应：**
+
+`json
+{
+  "code": 0,
+  "data": {
+    "id": "rec_abc123",
+    "itemId": "item_abc123",
+    "userId": "abc123def456",
+    "checkDate": "2026-06-24T00:00:00+08:00",
+    "status": "normal",
+    "note": "今天背了 60 个单词",
+    "images": "[\"url1.jpg\",\"url2.jpg\"]",
+    "createdAt": "2026-06-24T10:00:00+08:00"
+  }
+}
+`
+
+#### 4.2.2 查询打卡记录
+
+`
+GET /api/checkin/records?itemId=xxx&start=2026-06-01&end=2026-06-24
+`
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| itemId | string | 否 | 打卡项筛选 |
+| start | string | 否 | 起始日期（默认 30 天前） |
+| end | string | 否 | 结束日期（默认当天） |
+
+#### 4.2.3 补卡
+
+`
+POST /api/checkin/records/makeup
+`
+
+**请求体：**
+
+`json
+{
+  "itemId": "item_abc123",
+  "checkDate": "2026-06-22"
+}
+`
+
+**逻辑**：
+1. 只允许补签最近 7 天的记录
+2. 每月前 3 次免费
+3. 超出部分扣除 5 积分
+4. 记录状态标记为 makeup
+
+### 4.3 统计
+
+#### 4.3.1 获取连续天数
+
+`
+GET /api/checkin/streak/:id
+`
+
+**响应：**
+
+`json
+{
+  "code": 0,
+  "data": {
+    "itemId": "item_abc123",
+    "streak": 7
+  }
+}
+`
+
+**算法**：时区感知（Asia/Shanghai），从最近打卡日向前遍历。
+
+#### 4.3.2 月度统计
+
+`
+GET /api/checkin/stats/monthly?year=2026&month=6
+`
+
+**响应：**
+
+`json
+{
+  "code": 0,
+  "data": {
+    "totalItems": 3,
+    "totalRecords": 45,
+    "byCategory": [
+      { "Category": "study", "Count": 20 },
+      { "Category": "habit", "Count": 15 }
+    ]
+  }
+}
+`
+
+---
+
+## 5. 社交模块
+
+> 前缀：/api/social | 需认证
+
+### 5.1 好友
+
+#### 5.1.1 发送好友请求
+
+`
+POST /api/social/friends/request
+`
+
+`json
+{ "friendId": "user_xyz789" }
+`
+
+#### 5.1.2 接受好友请求
+
+`
+POST /api/social/friends/accept
+`
+
+`json
+{ "friendId": "user_xyz789" }
+`
+
+#### 5.1.3 删除好友
+
+`
+DELETE /api/social/friends/:userId
+`
+
+#### 5.1.4 获取好友列表
+
+`
+GET /api/social/friends
+`
+
+**响应：** 好友 User 对象数组
+
+### 5.2 动态广场
+
+#### 5.2.1 发布动态
+
+`
+POST /api/social/posts
+`
+
+`json
+{
+  "content": "今天打卡背了 60 个单词！",
+  "images": "[\"url1.jpg\"]",
+  "privacy": 1
+}
+`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| content | string | 动态文字内容 |
+| images | string | JSON 数组（图片 URL） |
+| privacy | int | 1=公开 2=好友可见 3=私密 |
+
+#### 5.2.2 获取动态广场
+
+`
+GET /api/social/feed?page=1&pageSize=20
+`
+
+**响应：**
+
+`json
+{
+  "code": 0,
+  "data": {
+    "list": [
+      {
+        "id": "post_abc",
+        "userId": "user_123",
+        "content": "今天打卡背了 60 个单词！",
+        "likes": 5,
+        "comments": 2,
+        "createdAt": "...",
+        "user": { "nickname": "小明", "avatar": "..." }
+      }
+    ],
+    "total": 120,
+    "page": 1
+  }
+}
+`
+
+#### 5.2.3 点赞
+
+`
+POST /api/social/posts/:id/like
+`
+
+#### 5.2.4 评论
+
+`
+POST /api/social/posts/:id/comment
+`
+
+### 5.3 打卡小组
+
+#### 5.3.1 创建小组
+
+`
+POST /api/social/groups
+`
+
+`json
+{
+  "name": "英语学习小组",
+  "cover": "https://...",
+  "intro": "一起学英语，互相监督",
+  "type": "public",
+  "maxMember": 50
+}
+`
+
+#### 5.3.2 加入小组
+
+`
+POST /api/social/groups/:id/join
+`
+
+#### 5.3.3 退出小组
+
+`
+POST /api/social/groups/:id/leave
+`
+
+#### 5.3.4 获取小组成员
+
+`
+GET /api/social/groups/:id/members
+`
+
+---
+
+## 6. 成就模块
+
+> 前缀：/api/achievements | 需认证
+
+### 6.1 获取所有成就
+
+`
+GET /api/achievements
+`
+
+**响应：**
+
+`json
+{
+  "code": 0,
+  "data": [
+    {
+      "id": "first_checkin",
+      "name": "初露锋芒",
+      "rarity": "bronze",
+      "condition": "完成第 1 次打卡",
+      "icon": null
+    }
+  ]
+}
+`
+
+### 6.2 获取我的成就
+
+`
+GET /api/achievements/mine
+`
+
+**响应：**
+
+`json
+{
+  "code": 0,
+  "data": [
+    {
+      "userID": "user_123",
+      "achievementID": "first_checkin",
+      "unlockedAt": "2026-06-24T10:00:00+08:00",
+      "Achievement": {
+        "id": "first_checkin",
+        "name": "初露锋芒",
+        "rarity": "bronze"
+      }
+    }
+  ]
+}
+`
+
+---
+
+## 7. 健康检查
+
+`
+GET /health
+`
+
+**响应：** { "status": "ok" }
+
+---
+
+## 附录：路由总览
+
+| 分组 | 路由 | 方法 | 认证 |
+|------|------|------|------|
+| 公开 | /health | GET | ✗ |
+| 公开 | /api/auth/register | POST | ✗ |
+| 公开 | /api/auth/login | POST | ✗ |
+| 用户 | /api/users/profile | GET | ✓ |
+| 用户 | /api/users/profile | PUT | ✓ |
+| 用户 | /api/users/points | GET | ✓ |
+| 用户 | /api/users/account | DELETE | ✓ |
+| 打卡项 | /api/checkin/items | GET/POST | ✓ |
+| 打卡项 | /api/checkin/items/:id | GET/PUT/DELETE | ✓ |
+| 打卡项 | /api/checkin/items/:id/pause | POST | ✓ |
+| 打卡项 | /api/checkin/items/:id/resume | POST | ✓ |
+| 记录 | /api/checkin/records | GET/POST | ✓ |
+| 记录 | /api/checkin/records/makeup | POST | ✓ |
+| 统计 | /api/checkin/streak/:id | GET | ✓ |
+| 统计 | /api/checkin/stats/monthly | GET | ✓ |
+| 好友 | /api/social/friends/request | POST | ✓ |
+| 好友 | /api/social/friends/accept | POST | ✓ |
+| 好友 | /api/social/friends/:userId | DELETE | ✓ |
+| 好友 | /api/social/friends | GET | ✓ |
+| 动态 | /api/social/feed | GET | ✓ |
+| 动态 | /api/social/posts | POST | ✓ |
+| 动态 | /api/social/posts/:id/like | POST | ✓ |
+| 动态 | /api/social/posts/:id/comment | POST | ✓ |
+| 小组 | /api/social/groups | POST | ✓ |
+| 小组 | /api/social/groups/:id/join | POST | ✓ |
+| 小组 | /api/social/groups/:id/leave | POST | ✓ |
+| 小组 | /api/social/groups/:id/members | GET | ✓ |
+| 成就 | /api/achievements | GET | ✓ |
+| 成就 | /api/achievements/mine | GET | ✓ |