# 数据库与 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` 一致  

---

## 五、推荐操作

1. **一次性补全（推荐）**  
   在备份后执行：
   ```bash
   mysql -u 用户 -p 数据库名 < soul-api/scripts/sync-users-vip-and-schema.sql
   ```
   若某条报 `Duplicate column name`，表示该列已存在，可跳过。

2. **依赖 AutoMigrate**  
   确保 soul-api 的 `database.Init` 中已对 `User`、`SystemConfig`、`Chapter` 执行 `AutoMigrate`，且未设置 `SKIP_AUTO_MIGRATE`，重启服务后会自动补全缺失列。

3. **新建库**  
   若从零建库，建议用**最新**的 `soul_miniprogram.sql` 导入后，再执行一次 `sync-users-vip-and-schema.sql`，确保 users 与 chapters 与 Model 完全一致。

---

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