# 系统修复清单 > 目的：记录当前项目中需要优先修复的功能缺口、契约风险和稳定性问题，便于后续按优先级逐项整改。 ## 一、优先级说明 - **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. 统一文档口径 --- ## 六、补充说明 本清单面向当前代码状态，重点关注的是： - 核心链路是否可用 - 接口契约是否稳定 - 异常场景是否有兜底 - 上线前是否存在明显风险 如果后续代码有更新，建议同步更新本清单，保持与真实系统状态一致。