完整建表定义在 schema.sql ↗。所有时间字符串以 UTC RFC3339 保存,例如 2026-11-14T12:00:00Z;会话和验证码的过期时间使用 Unix 秒。页面日期显示与存储时区要区分。
关联图#
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 回复需要增加哪些行;不允许只写“总数加一”。