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