# 数据模型：每张表为何存在

前一站：[架构](architecture.md) · 下一站：[迁移清单](migration.md)

完整建表定义在 [schema.sql](../../internal/database/schema.sql)。所有时间字符串以 UTC RFC3339 保存，例如 `2026-11-14T12:00:00Z`；会话和验证码的过期时间使用 Unix 秒。页面日期显示与存储时区要区分。

## 关联图

```mermaid
erDiagram
    users ||--o{ sessions : 登录
    users ||--o{ notes : 创作
    users ||--o{ note_likes : 点赞
    users ||--o{ collections : 收藏
    users ||--o{ comments : 评论
    users ||--o{ follows : 关注
    notes ||--o{ note_likes : 被赞
    notes ||--o{ collections : 被收藏
    notes ||--o{ comments : 讨论
    comments ||--o{ comment_likes : 被赞
```

图中 follows 同时以 user_id 和 target_id 引用 users，comments 以 parent_id/reply_id 自引用。图省略了这些重复箭头，字段才是准确依据。

## 用户与认证

| 表 | 关键字段 | 规则 |
| --- | --- | --- |
| users | id、phone、password_hash、nickname、handle、avatar、introduction、sex、birthday、role、status、deleted、created_at | phone/handle 唯一；sex=0/1/2；role=user/admin；status=0正常/1黑名单 |
| sessions | id、user_id、expires_at | id 是 JWT jti，必须存在且未过期，token 才有效 |
| verification_codes | phone、digest、expires_at、sent_at、attempts | 每个号码当前一条；5分钟有效；60秒发送间隔；最多5次错误尝试 |
| audit_log | actor_id、action、target_id、created_at | 管理员停用、解除、软删除同事务记审计 |

管理员在 users 中使用 `admin:<用户名>` 作为内部 phone 标识，普通手机号登录不能匹配这个格式。教学普通用户没有默认密码哈希，必须先验证码登录再设置密码。

status 和 deleted 不互相替代：黑名单可解除；deleted 表示软删除。解除黑名单不会重建先前被删除的 sessions。公开计数与列表会过滤已停用/删除用户，原关系行仍可保留。

## 笔记与互动

| 表 | 字段 | 规则 |
| --- | --- | --- |
| notes | creator_id、type、title、content、images、video_uri、topic_id、visible、is_top、deleted、created_at、updated_at | type=0图文/1视频；visible=0公开/1自己；images 是 JSON 数组 |
| note_likes | user_id、note_id | 组合主键保证同人同篇唯一 |
| collections | user_id、note_id | 独立收藏关系，不与点赞共用标记 |
| follows | user_id、target_id、created_at | 有方向；组合唯一；CHECK 禁止自关注 |

notes.id 和 users.id 在数据库递增产生，限制不超过 JavaScript 安全整数 `9007199254740991`。原 Snowflake 长整数可能超过此范围，已有数据迁移时不能把它直接转成前端 number，否则会精度丢失。当前接口沿用 number 类型，新生成的 ID 范围受到约束。

topic_id 目前是可选数字元数据，没有话题目录管理和独立话题搜索，不把它描述成已实现完整话题系统。笔记正文与图片地址同一笔 SQL 保存，不再分 Cassandra KV 和 MySQL 元数据。

## 评论层级

comments 存 note_id、user_id、parent_id、reply_id、content、image_url、deleted、created_at。一级评论 parent_id=NULL。回复一级评论时 parent_id=一级ID；继续回复某条回复时 parent_id 仍指一级ID，reply_id 指实际被回复者。这是“二层展示、保留回复对象”，不是无限嵌套树。

comment_likes 以 `(user_id,comment_id)` 为组合主键。删除一级评论时同事务标记它与所有 parent_id 指向它的回复；删除某条回复不会删除其他同级回复。读评论要先判断所属笔记对当前人可见，再过滤被删除或作者停用的记录。

## 索引要对应查询

笔记作者列表使用 `(creator_id,deleted,id)`；首页使用 `(deleted,visible,id)`；评论列表使用 `(note_id,parent_id,deleted,id)`；点赞/收藏/关注反向统计还有 target/note 索引。LIKE `%关键词%` 通常无法利用普通前缀索引做全文加速；这不是给标题加一个普通索引就能解决的问题。

## 迁移和备份不变量

schema_migrations 当前记录初始版本 1。新增字段应增加明确迁移版本与已有数据回填，而不是只在 CREATE TABLE IF NOT EXISTS 改一个字段就宣称旧库会自动变化。备份包括数据库、开发密钥或生产密钥的独立保存、uploads。恢复后检查 foreign_key_check、登录、详情和文件读取。

练习：手画 A 发笔记、B 点赞、B 评论、A 回复需要增加哪些行；不允许只写“总数加一”。
