数据库与 Go Model 字段对照检查报告

后端工程师对照 soul-api/internal/model 与 soul_miniprogram.sql 建表结构，列出数据库表里可能缺失、但代码里在用的字段。
若当前库是由旧版 SQL 导入或从未执行过迁移脚本，按本报告执行 sync-users-vip-and-schema.sql 或依赖 AutoMigrate 即可补全。

一、结论摘要

表名	是否缺字段	缺失字段（Model 有、SQL 无）	影响
users	是（旧库可能缺）	is_vip, vip_expire_date, vip_activated_at, vip_sort, vip_role	订单列表、用户列表、VIP 设置、提现、匹配记录等接口报错（不含 vip_name/vip_avatar 等，小程序已改为直接读用户资料）
chapters	是（SQL 导出无此列）	hot_score	文章排名、热门章节等依赖热度分的接口报错
其他业务表	否	-	与当前 SQL 一致

二、users 表

Model 文件：internal/model/user.go
SQL 表：soul_miniprogram.sql 中 CREATE TABLE users 已包含 VIP 相关列；若你的库是更早的备份或未导入最新 SQL，可能缺少以下列。

列名（蛇形）	类型	说明
is_vip	TINYINT(1) NULL DEFAULT 0	是否 VIP
vip_expire_date	DATETIME(3) NULL	VIP 到期时间
vip_activated_at	DATETIME(3) NULL	成为 VIP 时间，排序用
vip_sort	INT NULL	手动排序，越小越前
vip_role	VARCHAR(50) NULL	角色：从 vip_roles 选或手动填写

（vip_name、vip_avatar、vip_project、vip_contact、vip_bio 不再在迁移中新增，小程序已改为直接读用户资料 nickname/avatar/projectIntro/phone 等；已有库可保留该五列作兼容。）

修复：执行 scripts/sync-users-vip-and-schema.sql 中 users 部分，或重启 soul-api（未设 SKIP_AUTO_MIGRATE 时 AutoMigrate 会补列）。

三、chapters 表

Model 文件：internal/model/chapter.go
SQL 表：当前 soul_miniprogram.sql 中 chapters 仅有 hot_score_override（decimal），没有 hot_score（int）。
Model 使用的是 hot_score（热度分，用于排名算法），因此仅按该 SQL 建表时，数据库缺少 hot_score。

列名（蛇形）	类型	说明
hot_score	INT NOT NULL DEFAULT 0	热度分，用于排名算法

修复：执行 scripts/sync-users-vip-and-schema.sql 中 chapters 部分，或执行 scripts/add-hot-score.sql，或依赖 soul-api 启动时对 Chapter 的 AutoMigrate。

四、已核对无缺列的表

以下表在 soul_miniprogram.sql 中的列与对应 Model 一致，无需补列（仅列名与类型一致即可，顺序可不同）：

orders：与 model.Order 一致
withdrawals：与 model.Withdrawal 一致（库中多出的 transaction_id、error_message 不影响）
admin_users：与 model.AdminUser 一致
system_config：与 model.SystemConfig 一致
referral_bindings：Model 字段在表中均存在
referral_visits：与 model.ReferralVisit 一致
user_rules：与 model.UserRule 一致
user_tracks：与 model.UserTrack 一致
reading_progress：与 model.ReadingProgress 一致（表为 section_id，Model 为 section_id）
match_records：与 model.MatchRecord 一致
mentor_consultations：与 model.MentorConsultation 一致
mentors：与 model.Mentor 一致
link_tags：与 model.LinkTag 一致
persons：与 model.Person 一致
author_config：与 model.AuthorConfig 一致
ckb_lead_records：与 model.CkbLeadRecord 一致
ckb_submit_records：与 model.CkbSubmitRecord 一致
user_addresses：与 model.UserAddress 一致
vip_roles：与 model.VipRole 一致
wechat_callback_logs：与 model.WechatCallbackLog 一致

五、推荐操作

一次性补全（推荐）
在备份后执行：
```
mysql -u 用户 -p 数据库名 < soul-api/scripts/sync-users-vip-and-schema.sql
```
若某条报 Duplicate column name，表示该列已存在，可跳过。
依赖 AutoMigrate
确保 soul-api 的 database.Init 中已对 User、SystemConfig、Chapter 执行 AutoMigrate，且未设置 SKIP_AUTO_MIGRATE，重启服务后会自动补全缺失列。
新建库
若从零建库，建议用最新的 soul_miniprogram.sql 导入后，再执行一次 sync-users-vip-and-schema.sql，确保 users 与 chapters 与 Model 完全一致。

检查日期：按代码与 SQL 导出时点生成
检查范围：soul-api 全部 internal/model 与 soul_miniprogram.sql 中对应表结构

4.8 KiB Raw Blame History Unescape Escape