zeronline
690 lines
11 KiB
Markdown
690 lines
11 KiB
Markdown
# 寸进（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 | ✓ |
|