# 寸进（InchStep）数据库设计文档

> 文档版本：v1.0  
> 数据库：MySQL 8.0  
> ORM：GORM（AutoMigrate）  
> 字符集：utf8mb4 / utf8mb4_unicode_ci  
> 更新日期：2026-06-24

---

## 目录

1. 文档概述
2. 数据库全局配置
3. 数据模型详情
4. ER 关系图
5. 索引策略
6. 迁移说明
7. 查询场景与优化

---

## 1. 文档概述

本文档定义寸进平台 v1.0 的全部数据模型、表结构、索引策略和迁移策略。数据模型映射自 server/internal/models/ 中的 Go 结构体，通过 GORM AutoMigrate 自动管理表结构。

---

## 2. 数据库全局配置

`ini
# 连接参数
DB_HOST=127.0.0.1
DB_PORT=13306
DB_USER=root
DB_PASS=123456
DB_NAME=inchstep
CHARSET=utf8mb4
COLLATION=utf8mb4_unicode_ci
LOC=Asia/Shanghai
`

### 2.1 GORM 连接配置

`go
dsn := "root:123456@tcp(127.0.0.1:13306)/inchstep?charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai"

// 关键配置：
// - parseTime=true: 将 MySQL DATETIME 映射为 Go time.Time
// - loc=Asia/Shanghai: 时区感知，影响连续天数计算
`

---

## 3. 数据模型详情

### 3.1 users（用户表）

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | varchar(32) | PK | 唯一 ID（cuid 风格） |
| phone | varchar(20) | UNIQUE, NULL | 手机号 |
| nickname | varchar(50) | NULL | 昵称 |
| avatar | varchar(255) | NULL | 头像 URL |
| bio | varchar(100) | NULL | 个性签名 |
| motto | varchar(50) | NULL | 个人目标简介 |
| privacy | int | DEFAULT 2 | 1=公开 2=好友 3=私密 |
| points | int | DEFAULT 0 | 总积分 |
| created_at | datetime | NOT NULL | 创建时间 |
| updated_at | datetime | NOT NULL | 更新时间 |

**GORM 映射：**

`go
type User struct {
    ID        string       gorm:"primaryKey;type:varchar(32)" json:"id"
    Phone     *string      gorm:"uniqueIndex;type:varchar(20)" json:"phone,omitempty"
    Nickname  *string      gorm:"type:varchar(50)" json:"nickname,omitempty"
    Avatar    *string      gorm:"type:varchar(255)" json:"avatar,omitempty"
    Bio       *string      gorm:"type:varchar(100)" json:"bio,omitempty"
    Motto     *string      gorm:"type:varchar(50)" json:"motto,omitempty"
    Privacy   PrivacyLevel gorm:"default:2" json:"privacy"
    Points    int          gorm:"default:0" json:"points"
    CreatedAt time.Time    gorm:"column:created_at" json:"createdAt"
    UpdatedAt time.Time    gorm:"column:updated_at" json:"updatedAt"
}
`

**索引**：
- PRIMARY KEY (id)
- UNIQUE INDEX idx_phone (phone)

### 3.2 checkin_items（打卡项表）

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | varchar(32) | PK | 唯一 ID |
| user_id | varchar(32) | FK, NOT NULL, INDEX | 所属用户 |
| name | varchar(100) | NOT NULL | 打卡项名称 |
| icon | varchar(50) | NULL | 图标 |
| category | varchar(20) | NOT NULL | 分类：study/health/habit/hobby/goal |
| daily_goal | varchar(200) | NULL | 每日目标 |
| cycle_type | varchar(20) | DEFAULT 'daily' | 周期：daily/weekly/every_other_day/custom |
| privacy | int | DEFAULT 2 | 隐私级别 |
| status | varchar(20) | DEFAULT 'active' | 状态：active/paused/archived/deleted |
| created_at | datetime | NOT NULL | 创建时间 |

**GORM 映射：**

`go
type CheckInItem struct {
    ID        string          gorm:"primaryKey;type:varchar(32)" json:"id"
    UserID    string          gorm:"column:user_id;type:varchar(32);not null;index" json:"userId"
    Name      string          gorm:"type:varchar(100);not null" json:"name"
    Icon      *string         gorm:"type:varchar(50)" json:"icon,omitempty"
    Category  CheckInCategory gorm:"type:varchar(20);not null" json:"category"
    DailyGoal *string         gorm:"column:daily_goal;type:varchar(200)" json:"dailyGoal,omitempty"
    CycleType CycleType       gorm:"column:cycle_type;default:daily;type:varchar(20)" json:"cycleType"
    Privacy   PrivacyLevel    gorm:"default:2" json:"privacy"
    Status    ItemStatus      gorm:"default:active;type:varchar(20)" json:"status"
    CreatedAt time.Time       gorm:"column:created_at" json:"createdAt"
}
`

**索引**：
- PRIMARY KEY (id)
- INDEX idx_user_id (user_id)

### 3.3 checkin_records（打卡记录表）

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | varchar(32) | PK | 唯一 ID |
| item_id | varchar(32) | FK, NOT NULL, INDEX | 所属打卡项 |
| user_id | varchar(32) | FK, NOT NULL, INDEX | 所属用户 |
| check_date | datetime | NOT NULL, INDEX | 打卡日期 |
| status | varchar(20) | DEFAULT 'normal' | normal/makeup |
| note | varchar(500) | NULL | 备注文字 |
| images | text | NULL | 图片 URL（JSON 数组） |
| created_at | datetime | NOT NULL | 记录创建时间 |

**GORM 映射：**

`go
type CheckInRecord struct {
    ID        string       gorm:"primaryKey;type:varchar(32)" json:"id"
    ItemID    string       gorm:"column:item_id;type:varchar(32);not null;index" json:"itemId"
    UserID    string       gorm:"column:user_id;type:varchar(32);not null;index" json:"userId"
    CheckDate time.Time    gorm:"column:check_date;not null;index" json:"checkDate"
    Status    RecordStatus gorm:"default:normal;type:varchar(20)" json:"status"
    Note      *string      gorm:"type:varchar(500)" json:"note,omitempty"
    Images    *string      gorm:"type:text" json:"images,omitempty"
    CreatedAt time.Time    gorm:"column:created_at" json:"createdAt"
}
`

**索引**：
- PRIMARY KEY (id)
- INDEX idx_user_id (user_id)
- INDEX idx_item_id (item_id)
- INDEX idx_check_date (check_date)
- COMPOSITE INDEX idx_user_date (user_id, check_date)（查询推荐）

### 3.4 achievements（成就定义表）

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | varchar(50) | PK | 成就 ID（如 irst_checkin） |
| name | varchar(100) | NOT NULL | 成就名称 |
| description | varchar(200) | NULL | 描述 |
| icon | varchar(50) | NULL | 图标 |
| rarity | varchar(20) | DEFAULT 'bronze' | bronze/silver/gold |
| condition | varchar(200) | NULL | 达成条件描述 |

**GORM 映射：**

`go
type Achievement struct {
    ID          string  gorm:"primaryKey;type:varchar(50)" json:"id"
    Name        string  gorm:"type:varchar(100);not null" json:"name"
    Description *string gorm:"type:varchar(200)" json:"description,omitempty"
    Icon        *string gorm:"type:varchar(50)" json:"icon,omitempty"
    Rarity      string  gorm:"default:bronze;type:varchar(20)" json:"rarity"
    Condition   *string gorm:"type:varchar(200)" json:"condition,omitempty"
}
`

### 3.5 user_achievements（用户成就关联表）

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| user_id | varchar(32) | PK, FK | 用户 ID |
| achievement_id | varchar(50) | PK, FK | 成就 ID |
| unlocked_at | datetime | NOT NULL | 解锁时间 |

**联合主键**：(user_id, achievement_id)

### 3.6 posts（动态表）

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | varchar(32) | PK | 唯一 ID |
| user_id | varchar(32) | FK, NOT NULL, INDEX | 发布者 |
| content | text | NULL | 文字内容 |
| images | text | NULL | 图片 URL（JSON 数组） |
| privacy | int | DEFAULT 1 | 1=公开 2=好友 3=私密 |
| likes | int | DEFAULT 0 | 点赞数（计数器） |
| comments | int | DEFAULT 0 | 评论数（计数器） |
| created_at | datetime | NOT NULL | 发布时间 |

**索引**：
- PRIMARY KEY (id)
- INDEX idx_created_at (created_at)（广场排序）
- INDEX idx_user_id (user_id)

### 3.7 friends（好友关系表）

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| user_id | varchar(32) | PK, FK | 用户 A |
| friend_id | varchar(32) | PK, FK | 用户 B |
| status | varchar(20) | DEFAULT 'pending' | pending/accepted |
| created_at | datetime | NOT NULL | 请求时间 |

**联合主键**：(user_id, friend_id)（双向好友关系需两条记录）

### 3.8 groups（打卡小组表）

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | varchar(32) | PK | 唯一 ID |
| name | varchar(20) | NOT NULL | 小组名称 |
| cover | varchar(255) | NULL | 封面图片 |
| intro | varchar(200) | NULL | 小组简介 |
| type | varchar(20) | DEFAULT 'public' | public/private |
| max_member | int | DEFAULT 50 | 人数上限 |
| created_by | varchar(32) | NOT NULL | 创建者 |
| created_at | datetime | NOT NULL | 创建时间 |

### 3.9 group_members（小组成员表）

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| group_id | varchar(32) | PK, FK | 小组 ID |
| user_id | varchar(32) | PK, FK | 用户 ID |
| role | varchar(20) | DEFAULT 'member' | admin/member |
| joined_at | datetime | NOT NULL | 加入时间 |

**联合主键**：(group_id, user_id)

---

## 4. ER 关系图

`
┌─────────┐       ┌──────────────┐       ┌────────────────┐
│  users  │1───N→│ checkin_items│1───N→│ checkin_records│
└─────────┘       └──────────────┘       └────────────────┘
     │ 1                                            │
     │                                              │
     │ 1                                            N
     │                                              │
     ├──────────────┐                               │
     │ 1            │ 1                             │
     ▼              ▼                               ▼
┌──────────┐  ┌──────────────┐
│ friends  │  │   posts      │
└──────────┘  └──────────────┘
     │
     │ N
     ▼
┌────────────────┐       ┌──────────────────────┐       ┌──────────────┐
│  groups        │1───N→│   group_members       │N───1│     users    │
└────────────────┘       └──────────────────────┘       └──────────────┘

┌──────────────┐       ┌──────────────────────┐       ┌──────────────┐
│ achievements │1───N→│ user_achievements     │N───1│     users    │
└──────────────┘       └──────────────────────┘       └──────────────┘
`

### 关系说明

| 左表 | 关系 | 右表 | 说明 |
|------|------|------|------|
| users | 1 → N | checkin_items | 一个用户可创建多个打卡项 |
| checkin_items | 1 → N | checkin_records | 一个打卡项有多条打卡记录 |
| users | 1 → N | checkin_records | 一个用户有多条打卡记录 |
| users | 1 → N | friends | 一个用户可有多个好友 |
| users | 1 → N | posts | 一个用户可发布多条动态 |
| users | 1 → N | user_achievements | 一个用户可解锁多个成就 |
| groups | 1 → N | group_members | 一个小组有多个成员 |
| achievements | 1 → N | user_achievements | 一个成就可被多个用户解锁 |

---

## 5. 索引策略

### 5.1 高频查询与索引覆盖

| 查询场景 | 涉及表 | 使用索引 | 优化建议 |
|----------|--------|----------|----------|
| 用户登录（手机号） | users | idx_phone | — |
| 用户打卡项列表 | checkin_items | idx_user_id | — |
| 打卡项打卡记录 | checkin_records | idx_item_id, idx_check_date | 复合索引 (item_id, check_date) |
| 连续天数计算 | checkin_records | idx_user_id, idx_check_date | 必须按 check_date DESC |
| 月度统计 | checkin_records | idx_user_id, idx_check_date | 复合索引 (user_id, check_date) |
| 动态广场排序 | posts | idx_created_at | 只查 privacy=1 |
| 好友列表 | friends | idx_user_id | — |
| 小组成员 | group_members | idx_group_id | — |

### 5.2 索引定义（迁移推荐）

`sql
-- 已有索引（由 GORM 自动创建）
-- users: PRIMARY(id), UNIQUE(phone)
-- checkin_items: PRIMARY(id), INDEX(user_id)
-- checkin_records: PRIMARY(id), INDEX(item_id), INDEX(user_id), INDEX(check_date)
-- posts: PRIMARY(id), INDEX(user_id), INDEX(created_at)

-- 推荐手动添加的复合索引
CREATE INDEX idx_records_user_date ON checkin_records(user_id, check_date);
CREATE INDEX idx_records_item_date ON checkin_records(item_id, check_date);
`

---

## 6. 迁移说明

### 6.1 开发环境（AutoMigrate）

开发环境使用 GORM AutoMigrate 自动创建/更新表结构。服务启动时执行：

`go
db.AutoMigrate(
    &models.User{},
    &models.CheckInItem{},
    &models.CheckInRecord{},
    &models.Achievement{},
    &models.UserAchievement{},
    &models.Post{},
    &models.Friend{},
    &models.Group{},
    &models.GroupMember{},
)
`

### 6.2 生产环境

生产环境建议：

1. **开发阶段**：使用 AutoMigrate 快速迭代
2. **预发布阶段**：生成 SQL 迁移脚本，人工审核后执行
3. **生产阶段**：使用版本化迁移工具（如 golang-migrate）

### 6.3 初始化数据

服务启动时自动初始化成就数据（10 个预定义成就徽章）：

`go
func (s *PointsService) InitAchievements() error {
    for _, a := range predefinedAchievements {
        s.db.Where("id = ?", a.ID).FirstOrCreate(&a)
    }
    return nil
}
`

---

## 7. 查询场景与优化

### 7.1 连续天数计算

`sql
-- 查询逻辑：按日期降序获取某打卡项的所有记录
SELECT check_date FROM checkin_records
WHERE item_id = ? AND user_id = ?
ORDER BY check_date DESC;
`

**优化策略**：
- (item_id, user_id, check_date) 复合索引
- Redis 缓存结果，打卡时更新

### 7.2 动态广场分页

`sql
SELECT p.*, u.nickname, u.avatar FROM posts p
LEFT JOIN users u ON p.user_id = u.id
WHERE p.privacy = 1
ORDER BY p.created_at DESC
LIMIT 20 OFFSET 0;
`

### 7.3 月度统计

`sql
SELECT COUNT(*) FROM checkin_records
WHERE user_id = ? AND check_date >= ? AND check_date < ?;

SELECT category, COUNT(*) as count FROM checkin_items
WHERE user_id = ? AND status = 'active'
GROUP BY category;
`

### 7.4 好友列表

`sql
SELECT friend_id FROM friends
WHERE user_id = ? AND status = 'accepted';
`

---

## 附录：表总览

| # | 表名 | 说明 | 行数预估（万 DAU） |
|---|------|------|-------------------|
| 1 | users | 用户 | 5 万 |
| 2 | checkin_items | 打卡项 | 20 万（人均 4 项） |
| 3 | checkin_records | 打卡记录 | 5000 万（日均 50 万） |
| 4 | achievements | 成就定义 | 10 条（静态） |
| 5 | user_achievements | 用户成就 | 10 万 |
| 6 | posts | 动态 | 100 万 |
| 7 | friends | 好友关系 | 20 万 |
| 8 | groups | 打卡小组 | 1 万 |
| 9 | group_members | 小组成员 | 10 万 |