2.6 KiB
2.6 KiB
Context
后端通知接口已经提供稳定的管理端 REST 合约。前端需要移除对旧字段和旧响应形态的依赖，统一使用真实接口返回的数据，并把通知目标解析限制在前端已注册的内部目标映射中。
Goals / Non-Goals
- Goals: 顶部铃铛、通知抽屉、通知中心和共享 Pinia 状态使用同一套真实 API 类型。
- Goals: 保证未读数、分类汇总、列表已读状态在单条已读和全部已读后与后端同步。
- Goals: 受控目标只能通过
target_type、target_id、target_key白名单映射到内部页面。 - Non-Goals: 不实现 C 端通知，不支持任意 URL 跳转，不改变通知产生规则。
Decisions
- Decision: 通知列表请求使用
is_read?: boolean，不再以read_status字符串代替后端参数。 - Decision: 通知正文统一使用
body；必要时仅在迁移读取阶段兼容旧数据，不再把旧content作为 API 契约类型。 - Decision: 顶部徽标优先使用
unread-count.data.display_count，数值统计使用data.count；不在前端重新格式化徽标文本。 - Decision: 未读汇总只保存四个固定分类计数和总数；抽屉最近10条通过
GET /api/admin/notifications?page=1&page_size=10获取，避免把分类汇总误当通知列表。 - Decision: 全部已读服务方法接收可选
category，请求体始终为对象；通知中心的“全部已读”传空对象，分类操作可传具体类别。 - Decision:
target_type、target_key由前端白名单映射到已注册路由，target_id仅作为参数；未知、无权限或已失效目标只展示正文，不跳转。 - Alternatives considered: 继续保留旧字段的宽松兼容类型。Rejected because it会掩盖真实 API 字段错误，并导致筛选和已读状态请求不符合后端契约。
Risks / Trade-offs
- 风险：后端新增通知类型。Mitigation：类型字段保持 string，页面对未知类型采用原值展示。
- 风险：受控目标类型新增。Mitigation：未知目标默认不可跳转，不执行后端返回的任意路径。
- 风险：列表与汇总请求并行时数据短暂不一致。Mitigation：单条已读/全部已读成功后刷新未读数、汇总和当前列表。
Migration Plan
- 先更新类型、API service 和通知 store 的真实响应结构。
- 再更新顶部抽屉和通知中心字段、筛选及已读交互。
- 最后替换目标跳转映射并验证未知目标安全降级。
Open Questions
target_type与target_key的完整白名单值需要以后端实际返回样例补充；未确认值统一按不可跳转处理。