xiangqinxiaochengxu/系统修复清单.md

系统修复清单

目的：记录当前项目中需要优先修复的功能缺口、契约风险和稳定性问题，便于后续按优先级逐项整改。

一、优先级说明

• P0：会直接导致功能不可用、权限错误或数据异常的问题
• P1：会明显影响核心体验、稳定性或上线质量的问题
• P2：体验优化、容错增强、后续完善项

---

二、P0 级修复项

1. 修复 /auth/refresh 刷新令牌逻辑

问题描述

• 当前刷新接口存在明显实现问题，刷新后的 token 里 user_id 被写死为 1。
• 这会导致刷新出来的登录态不属于当前用户，存在权限串号风险。

影响范围

• 小程序登录态刷新
• 未来接入 token 自动续期时的安全性

建议修复

• 改为根据 refresh token 解析出真实用户身份。
• 增加 refresh token 有效性校验与失效处理。
• 若暂未完成完整刷新机制，先关闭前端对该接口的调用。

---

2. 统一登录态失效后的重试逻辑

问题描述

• 小程序 request.js 会在 401 时自动触发重新登录并重试。
• 若登录失败或后端持续返回 401，容易造成重复提示，部分场景下可能出现重试链路不清晰。

影响范围

• 所有依赖登录态的小程序页面

建议修复

• 明确区分：未登录、登录过期、登录失败、后端不可用。
• 对自动重试增加次数限制与失败兜底。
• 统一输出标准化错误对象，避免页面侧拿不到 message。

---

3. 修复匹配与用户信息返回结构的强依赖问题

问题描述

• 小程序“我的匹配”“候选推荐”等页面对后端返回结构依赖很强。
• 例如 other_user、personality_tags、match_reasons 等字段一旦为空或类型变化，前端容易展示异常。

影响范围

• 我的匹配
• 匹配候选
• 活动内匹配展示

建议修复

• 后端使用明确的 Pydantic schema，尽量不要直接返回裸 dict。
• 前端对数组、对象字段做空值保护。
• 对字符串/数组字段统一约定数据类型。

---

三、P1 级修复项

4. 增强活动列表、活动详情页的异常兜底

问题描述

• 活动列表和详情页依赖多个派生字段，例如：
  • is_registered
  • can_register
  • registered_male
  • registered_female
  • match_limit
  • match_count
  • match_remaining
• 当前前端虽然能展示，但在字段缺失或数据异常时容错不足。

建议修复

• 后端保证这些字段稳定输出。
• 前端增加默认值与类型判断。
• 对报名状态、匹配状态增加更明确的空态文案。

---

5. 补强小程序首页与列表页的登录失败引导

问题描述

• 首页、活动页、匹配页在 ensureLogin() 失败后大多只是记录日志。
• 用户在后端不可用或微信登录失败时，容易看到空白内容，不知道下一步怎么做。

建议修复

• 在首页、活动页、匹配页增加统一错误态。
• 提示用户检查网络、后端地址、微信开发者工具配置等。
• 必要时提供“重试登录”按钮。

---

6. 规范后台与小程序的接口契约

问题描述

• 当前项目整体能跑通，但部分接口返回结构仍偏宽松。
• 管理端与小程序对同一业务对象的字段约定不够集中。

建议修复

• 为活动、公告、匹配、用户信息建立统一 schema。
• 后端输出固定字段名和固定类型。
• 前端禁止依赖未定义字段。

---

7. 提升公共配置能力的可用性

问题描述

• 小程序通过 /auth/public-config 获取 API 地址和客服微信号。
• 当前虽然有配置能力，但若后台未配置，就会回落到默认占位值。

建议修复

• 后台系统设置中明确标注必填项与默认值。
• 前端在缺少真实客服信息时，显示更友好的引导文案。
• 记录公共配置加载失败时的错误日志。

---

8. 完善后台管理端的权限与审计能力

问题描述

• 后台已有登录、活动、公告、审核、看板等入口。
• 但权限控制、操作审计、批量处理等能力仍偏基础。

建议修复

• 增加更细粒度的角色权限校验。
• 记录关键操作日志，如发布、删除、审核、修改系统配置。
• 为高风险操作增加二次确认。

---

四、P2 级修复项

9. 优化 AI 推荐与匹配体验

问题描述

• 当前 AI 推荐属于“可用但不够稳定”的状态。
• 当推荐结果为空时，用户体验一般。

建议修复

• 增加推荐为空时的解释文案。
• 支持缓存最近一次推荐结果。
• 增加推荐理由展示一致性。

---

10. 补充自动化测试

问题描述

• 目前缺少覆盖核心链路的自动化测试。

建议修复

• 后端增加接口测试：登录、活动列表、报名、匹配、后台管理。
• 前端补充关键页面的基础回归检查。
• 对高风险逻辑增加单元测试。

---

11. 增强文档与交付说明一致性

问题描述

• README、交付说明、后台使用说明等文档已存在，但在功能完成度上还可继续统一口径。

建议修复

• 标注哪些功能已完成、哪些是预留、哪些是待修复。
• 明确依赖外部配置的功能项。
• 给出上线前必检项。

---

五、建议修复顺序

第一阶段：先修 P0

1. 修复 /auth/refresh 逻辑
2. 统一 401 登录失效重试逻辑
3. 规范匹配数据返回结构

第二阶段：再修 P1

4. 增强活动页/详情页兜底
5. 补强登录失败引导
6. 统一接口契约
7. 完善公共配置
8. 强化后台权限与审计

第三阶段：最后修 P2

9. 优化 AI 推荐体验
10. 补自动化测试
11. 统一文档口径

---

六、补充说明

本清单面向当前代码状态，重点关注的是：

• 核心链路是否可用
• 接口契约是否稳定
• 异常场景是否有兜底
• 上线前是否存在明显风险

如果后续代码有更新，建议同步更新本清单，保持与真实系统状态一致。