soul-yongping/.cursor/agent/后端工程师/evolution/2026-03-10.md

后端工程师 经验记录 - 2026-03-10

管理端迁移 Mycontent-temp：后端视角注意点

• 接口边界不变：管理端迁移/重构只允许调用 /api/admin/*、/api/db/*、/api/orders，严禁引入 /api/miniprogram/*。
• 概览聚合接口可选：/api/admin/dashboard/overview 可作为“优化项”提供更轻量的统计聚合，但必须保留降级策略（用 /api/db/users + /api/orders 拼）以免阻塞前端迁移与部署节奏。
• 鉴权一致性：页面入口/菜单变化不影响鉴权口径，仍以 GET /api/admin 作为 session/token 校验；401 统一跳登录并清 token。

详见会议纪要：.cursor/meeting/2026-03-10_管理端迁移Mycontent-temp菜单布局讨论.md

---

新增聚合接口 UserDashboardStats

场景：小程序「我的」页需要一个聚合接口返回阅读统计，避免多次请求。

接口：GET /api/miniprogram/user/dashboard-stats?userId=xxx

数据来源：

• readSectionIds / readCount → reading_progress WHERE user_id = userId
• totalReadMinutes → SUM(duration) / 60（秒转分，最小值 1 分钟）
• recentChapters → reading_progress ORDER BY last_open_at DESC JOIN chapters（最近 5 条去重）
• matchHistory → match_records COUNT WHERE user_id = userId

三处 bug 修复点（对比 Mycontent-temp 参考版发现）：

Bug	错误做法	正确做法
最近阅读重复	直接取前 5 条（同章节可重复）	seenRecent map 去重，保证 5 条不重复
阅读时长最小值	不足 60 秒返回 0	if totalReadSeconds > 0 && totalReadMinutes == 0 { totalReadMinutes = 1 }
DB 错误状态码	返回 200 + success:false	返回 HTTP 500 InternalServerError

规则沉淀：新增聚合接口时，先参考已有版本实现，对比 diff 后修复潜在 bug，再提交。

详见会议纪要：.cursor/meeting/2026-03-10_小程序新旧版对比与dashboard接口新增.md

---

chapters 表新增 hot_score 字段

问题

前端 ContentPage.tsx 保存章节时传递 hotScore 字段，但后端 model 和数据库均缺少该列，导致：

Error 1054 (42S22): Unknown column 'hot_score' in 'field list'

修复步骤

1. 执行迁移 SQL（soul-api/scripts/add-hot-score.sql）：

   ALTER TABLE chapters ADD COLUMN hot_score INT NOT NULL DEFAULT 0;
   

2. 同步 model（internal/model/chapter.go）：

   HotScore int `gorm:"column:hot_score;default:0" json:"hotScore"`
   

3. 重启后端服务生效

规则沉淀

• model 与 DB 必须同步：前端传入新字段时，必须先确认 DB 列存在，再确认 model struct 中有对应字段，缺一不可
• 变更流程：前端加字段 → ALTER TABLE → 更新 model struct → 重启服务
• 迁移 SQL 统一放 soul-api/scripts/ 目录，文件名格式 add-{描述}.sql

详见会议纪要：.cursor/meeting/2026-03-10_Toast通知系统全局落地.md