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