inchstep/docs/API设计文档.md

寸进（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	✓