数据库设计

05 · 数据库设计

DDL 源码：[install/schema.php](../install/schema.php)（`clara_schema()` 返回 DDL 数组，`{P}` 为表前缀占位符，安装时替换为实际前缀如 `clara_`）。引擎统一 InnoDB + utf8mb4\_unicode\_ci。

新装站点由安装向导执行全量 DDL；存量站点升级走后台「系统工具 → 数据库升级」（对比 schema 声明增量执行）。

1. 表清单总览（52 张核心表 · install/schema.php 建表，另有 cron_runs 等升级增量表）

插件自建表（前缀 `plugin_{目录名}_`）：

2. 核心表结构详解

users（用户主表）

id, username(uk), nickname, email(uk), password,            -- 账号
avatar, avatar_frame,                                         -- 头像 + 佩戴头像框
group_id(idx),                                                -- 主组
email_verified, status,                                       -- status>=0 可登录，-1 封禁
signature, bio, gender, homepage, location,                   -- 资料
thread_count, post_count,                                     -- 冗余计数
exp,                                                          -- 经验值
checkin_days, checkin_total, checkin_last_date,               -- 签到统计
remember_token,                                               -- 记住我（64 hex）
invite_by, last_login_at, last_ip, created_at,
privacy_no_follow, privacy_no_reply, privacy_hide_social,     -- 隐私开关
pwd_code, pwd_code_expires,                                   -- 找回密码验证码
login_fails, locked_until                                     -- 登录安全闭环（连续失败计数 / 临时锁定到期）

user\_groups（用户组 — 权限与等级合一）

id, name, color,          -- 组名与徽章色
perms TEXT,               -- 权限 JSON {"view":1,"thread":1,...}（16 键，含 attach/poll/bounty/anon_reply 内容形态键）
is_system, is_admin,      -- 系统组 / 管理员组（全权限）
min_exp, auto_upgrade,    -- 经验门槛 / 是否参与经验自动升级（等级组）
sort

等级组 = `auto_upgrade=1 AND is_admin=0`，经 `exp_level_groups()` 按 min\_exp 升序读取；管理员/版主等特殊组不参与自动升降级，前端也不显示经验进度。

forums（版块）

id, parent_id(idx),       -- type=1 分类（容器）、type=2 版块（发帖）
type, name, description, icon, sort,
thread_count, post_count, last_thread_id, last_post_at,   -- 冗余统计
perms TEXT,               -- 版块级组权限覆盖 JSON {"{gid}":{"view":1,"reply":0}}
moderators VARCHAR(255),  -- 版主 uid 逗号分隔
status,                   -- 0 关闭（仅管理员可见）
seo_keywords, seo_description, created_at

threads / posts（内容）

threads: forum_id(idx), user_id(idx), title, content(MEDIUMTEXT),
         views, replies, likes, favorites, gifts,          -- 计数冗余
         is_top, is_essence, is_closed, status,            -- status=1 正常 / 0 隐藏（回收站）
         deleted_at,                                      -- 前台软删时间戳（回收站保留计时；NULL = 后台隐藏，不自动清理）
         tags VARCHAR(150),                                -- 半角逗号分隔（FIND_IN_SET 查询）
         created_at, updated_at, edited_at,
         last_post_at(idx 组合), last_post_user_id         -- 列表排序与「最后回复」展示

posts:   thread_id(idx), user_id(idx), reply_post_id,      -- 楼中楼：指向被回复的 post id
         content(MEDIUMTEXT), likes, status, created_at

checkins（签到）

user_id, check_date(DATE, uk 组合), days,    -- 当日连签天数快照
rewards VARCHAR(500),                        -- 奖励 JSON；补签记录为 '{"repair":1}'
created_at

credit\_rules / credit\_logs（积分规则引擎）

credit_rules:  id, event VARCHAR(40),        -- thread_create / post_create / be_liked /
                                             -- be_post_liked / be_favorited / thread_delete / post_delete
               currency_id, amount DECIMAL,  -- 正数奖励 / 负数扣除
               daily_limit INT(0 不限), enabled, created_at
credit_logs:   id, user_id, event, currency_id, amount,
               operator_uid,                 -- 触发人（他人触发类事件；自赞不发放）
               source_id,                    -- 主题/回复 id（与 operator_uid 组成去重键）
               log_date DATE,                -- 每日上限计数键
               created_at
               UNIQUE(event, operator_uid, source_id, user_id)   -- 去重：点赞反复切换只发一次

发放链路：`CreditRuleService::apply()` → INSERT IGNORE 占位 → `currency_change(type='credit_rule')` 入账 → 失败（惩罚余额不足）回滚占位；规则长缓存 `Cache('credit_rules')`，后台变更主动失效。

3. 实体关系（ER 摘要）

user_groups 1──n users（group_id 主组）        user_group_maps n──n（附加组）
users 1──n threads / posts（user_id）
forums 1──n threads（forum_id）；forums 自关联（parent_id 分类树）
threads 1──n posts（thread_id）；posts 自关联（reply_post_id 楼中楼链）
users n──n threads（likes: user+target+target_id / favorites: user+thread）
users 1──n user_currency / currency_logs（经 currencies 关联）
users 1──n user_memberships n──1 memberships（叠加，取 end_at 最晚）
users 1──n user_frames n──1 avatar_frames（uk user+frame）
users 1──n user_medals n──1 medals（uk user+medal 幂等）
users n──n follows（user_id → target_id）
users 1──n notifications / checkins / exp_logs

4. 数据一致性约定

• 冗余计数：threads.replies、forums.thread\_count/post\_count、users.thread\_count/post\_count 均为冗余字段，随发帖/回帖/删除同步增减；漂移时用后台「系统工具 → 重算统计」对账。

• 软删除：threads/posts 用 status=-1；列表查询统一走 `thread_visibility_sql()`（管理员见全部，普通用户只见 status=1）。

• 唯一键幂等：签到（user+date）、勋章（user+medal）、头像框（user+frame）、点赞（user+target+target\_id）均靠唯一键防重。

• 流水快照：currency\_logs/exp\_logs 记录变动后余额（after 列），便于审计与防刷统计（当日计数查询）。

• JSON 字段：user\_groups.perms、forums.perms、checkins.rewards 为 JSON 文本；写入方负责 `json_decode` 容错（`?: array()` 兜底）。

5. settings 表关键键位