feat: 完善接口19-顶部通知铃铛与站内通知中心

openspec/changes/update-admin-notification-center-api/design.md

@@ -0,0 +1,36 @@
+## 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
+
+1. 先更新类型、API service 和通知 store 的真实响应结构。
+2. 再更新顶部抽屉和通知中心字段、筛选及已读交互。
+3. 最后替换目标跳转映射并验证未知目标安全降级。
+
+## Open Questions
+
+- `target_type` 与 `target_key` 的完整白名单值需要以后端实际返回样例补充；未确认值统一按不可跳转处理。