先改后缀为md到本地来看

**交接总览**

- 这份“后端打工人保命指南”专治历史误会与产品反转。
- TL;DR：聊天功能服务的是小程序，不是后台；尽快把角色从`sys_template`切回正宗`sys_role`，并统一接口风格与命名。

**背景反转**

- 项目是标准的 Spring Boot 前后端分离。
- 我一度以为“聊天要在后台界面实现”，后来才知道“聊天其实是给微信小程序用的”。
- 现状：`ChatController`看起来像后台接口，实际上灵魂绑定了小程序；角色设计用的是`sys_template`而不是正统`sys_role`。

**现状雷区（请技术同学小心走位）**

- 角色体系割裂：接口里用`sys_template`当角色，脱离系统正统`sys_role`，后续权限/菜单/审计容易不一致。
- 接口风格不统一：部分返回结构不走统一响应包装，出现“有的给`code/message`，有的直接给字符串”的尴尬混搭。
- ChatController 与后台领域边界模糊：路由与命名既像后台，又服务小程序，后期联动容易误配。
- 兼容层过度宽松：为“小程序能跑”做了魔改，继续叠加功能可能埋下小 bug（空指针、字段映射、默认值缺失）。
- 文档误导：团队容易把聊天当“管理端功能”，实际是“C 端小程序功能”。

**立刻止损指南（快修清单）**

- 统一角色来源：移除`sys_template`在业务中的角色职能，回归`sys_role`为唯一运行时角色。
- 归位聊天接口：将小程序相关接口归到明确的命名空间，如`/api/mp/chat`，清晰隔离后台路由。
- 统一响应格式：所有接口走同一响应包装（如`{ code, message, data }`），避免“风格随缘”。
- 清理文档与注释：删除或归档“聊天=后台”的旧叙事，明确“聊天=小程序”。

**推荐改造路线（分阶段稳妥推进）**

- 阶段一：信息梳理
  - 盘点`ChatController`的所有路由、入参、出参、依赖实体与服务。
  - 搜索全局对`sys_template`的引用，标记为“角色相关调用”。

- 阶段二：模型正名
  - 将角色相关逻辑替换为`sys_role`，在服务层聚合角色配置（人格提示词、上下文长度等）。
  - 如需保留“模板”概念，限定为“角色初始配置模板”，不可充当运行时角色。

- 阶段三：接口归位
  - 小程序路由统一到`/api/mp/chat/...`。
  - 后台保留管理接口到`/api/admin/...`。
  - 中间层封装统一响应与错误码，避免 Controller 内部自己拼 JSON。

- 阶段四：平滑迁移
  - 保留旧`sys_template`接口一版只读兼容层，打`@Deprecated`并在响应中附迁移提示。
  - 数据迁移：将现有模板绑定的“人格配置”迁移到`sys_role`，编写一次性 SQL/脚本。

- 阶段五：验证与发布
  - 编写集成测试：发送消息、拉取历史、选择角色/人格、历史分页、并发发送。
  - 预发布环境跑全回归；发布后观察日志与告警一周。

**命名与路由建议**

- 小程序聊天接口（示例）
  - `GET /api/mp/chat/roles`：获取可用`sys_role`人格列表
  - `POST /api/mp/chat/message`：发送消息
  - `GET /api/mp/chat/history`：拉取历史
  - `POST /api/mp/chat/role/select`：选择当前会话角色

- 后台管理接口（示例）
  - `GET /api/admin/roles`、`POST /api/admin/roles`：标准角色的增删改查
  - 明确禁止在后台接口使用`sys_template`做运行时角色

**数据迁移草案（示意）**

- 将“模板-人格映射”迁入`sys_role`：
  - 在`sys_role`增加必要字段以承载模板中的人格配置（如性格、提示词、上下文长度等）。
  - 编写一次性迁移脚本：将`sys_template`中的可运行配置复制/合并到`sys_role`对应记录。
  - 停止业务层对`sys_template`的运行时读取，只保留为“初始模板”与离线导出。

**统一响应示例（建议约定）**

- 成功：`{ "code": 0, "message": "ok", "data": { ... } }`
- 失败：`{ "code": 1001, "message": "role not found" }`
- 统一在服务层映射错误码，禁止字符串随缘返回。

**自检发布清单**

- 查找并删除/替换所有运行时对`sys_template`的使用。
- 为`ChatController`写 5 个关键集成用例：成功、角色缺失、历史分页、并发发送、接口返回一致性。
- 路由分区是否明确：`/api/mp/...`与`/api/admin/...`不串线。
- 文档是否改写：README 与部署文档明确“聊天=小程序”。
- 日志是否规范：关键链路打点，错误码落日志，方便灰度回滚。

**保命锦囊（恶搞版）**

- 若发现还有接口“口嫌体正直”用着`sys_template`：请高喊“模板是模板，角色是角色”，然后删。
- 若有人想把聊天再接回后台：请温柔劝退，“这是给用户的小程序功能，不是管理员的自嗨面板”。
- 若上线后出现“消息消失/人格错乱”：第一时间核对角色来源是否仍读取了`sys_template`。

**后续工作建议**

- 在`/src/main/java/com/xiaozhi/controller/`内核对`RoleController`与`ChatController`职责边界，避免领域耦合。
- 将角色人格配置抽象到服务层，减少 Controller 内部拼装。
- 完善测试与文档，新增“聊天接口 for 小程序”章节，删除一切让人误以为是“后台聊天”的描述。

祝后续同学下刀稳、上线稳、老板更稳。

**支付代码说明**

- 项目同样存在支付相关代码，但目前未实际使用、未测试、未上线。
- 如需了解或启用，请先阅读以下文档：
  - `\root\xiaozhi-esp32-server-java\微信小程序会员绑定系统需求规格说明书.md`
  - `\root\xiaozhi-esp32-server-java\微信小程序支付上线配置修改清单.md`

2025年10月15日

如果觉得修改代码不如重写，那你可以看一下这个目录 `/root/xiaozhi-esp32-server-java-bak-before-change-git`