inchstep/docs/数据库设计文档.md

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