## Context 系统已经存在 `ArtNotification` 顶部通知组件，但组件中的通知、消息和待办列表都是静态数据，顶部通知按钮处于注释状态。新的通知能力需要同时服务顶部快速查看和完整通知中心，并确保用户在任一入口执行已读操作后未读数与列表状态一致。 ## Goals / Non-Goals - Goals: 提供余额预警、临期提醒、审批结果和系统告警统一的站内通知入口。 - Goals: 在顶部快速查看最近 10 条通知，并提供进入通知中心的入口。 - Goals: 支持通知分类、类型、严重级别和已读状态筛选。 - Goals: 将通知点击导航限制在前端认可的业务目标内，禁止任意 URL 跳转。 - Goals: 单条已读、全部已读、抽屉和通知中心共享同一份未读状态。 - Non-Goals: 不实现 C 端通知页面。 - Non-Goals: 不实现推送通道或服务端通知生成规则。 - Non-Goals: 不让前端根据通知正文推断跳转地址。 ## Decisions - Decision: 通知铃铛放在顶部全局导航的设置按钮和用户头像菜单附近。 - Rationale: 该区域已承载全局设置和用户级入口，适合放置跨页面可访问的通知入口，也符合产品指定位置。 - Decision: 顶部抽屉只加载最近 10 条，完整通知中心使用独立路由 `/notifications`。 - Rationale: 顶部入口保持轻量，筛选和完整历史查询放在独立页面，避免挤占全局导航空间。 - Decision: 未读数使用独立接口获取，单条通知和全部已读成功后立即更新本地共享状态，并以接口返回值为最终结果。 - Rationale: 未读数是全局状态，不能依赖当前抽屉或列表的局部数量推导。 - Decision: 点击通知先调用单条已读接口，再调用目标接口，根据返回的受控 route name/route params 跳转。 - Rationale: 已读状态必须在导航前落库，目标由后端业务引用解析，前端不执行通知携带的任意 URL。 - Decision: 未知 `ref_type` 或目标接口无可用目标时只展示通知正文和状态，不跳转。 - Rationale: 保证安全，同时让无法关联页面的系统通知仍然可读。 - Decision: `unread-summary` 为顶部抽屉分类提供数据，`notifications` 为通知中心筛选列表提供数据。 - Rationale: 顶部快速查看与完整列表的数据量和筛选职责不同，避免顶部加载完整历史数据。 ## Data Contract - Notification item: id, title, content, category, type, severity, read status, created time and optional `ref_type`/reference ID. - Unread count: non-negative integer; frontend formats it as `0`, `1`-`99` or `99+`. - Unread summary: category counts and recent notification items, limited to the latest 10 items for the drawer. - Notification list: paginated items plus total count, with category, type, severity and read-state filters. - Target response: controlled internal route information, such as route name/path and route params; no arbitrary executable URL. ## Risks / Trade-offs - Risk: 后端通知字段或枚举名称与文档不一致。 - Mitigation: 在任务阶段先确认字段契约，类型层保留稳定的可选字段和未知值占位展示。 - Risk: 用户在多个标签页同时读通知，单页本地未读数短暂不一致。 - Mitigation: 操作成功后刷新未读数和当前列表；跨标签实时同步不作为本期强制目标。 - Risk: 目标记录已删除或用户权限发生变化。 - Mitigation: 目标接口返回不可跳转时只展示正文，并处理权限/不存在状态，不回退到任意 URL。 ## Migration Plan 1. 确认通知列表、摘要、未读数和目标接口字段及枚举。 2. 新增通知 API service、类型和共享状态。 3. 将顶部通知按钮放入设置/头像区域，接入未读数和最近通知抽屉。 4. 新增 `/notifications` 路由及通知中心页面。 5. 实现筛选、单条已读、全部已读和受控目标跳转。 6. 删除或替换 `ArtNotification` 中的静态 mock 数据，并验证四类通知展示一致。 ## Open Questions - 通知中心是否需要分页参数名称 `page/page_size`，以及默认每页数量需要后端确认。 - `category`、`type`、`severity` 和 `read_status` 的枚举值及展示名称需要后端确认。 - 目标接口返回 route name、path 还是 route key + params，需要与路由菜单契约确认。 - 未读数是否需要页面进入时定时刷新或仅在打开抽屉/完成操作时刷新，本期默认按接口调用时机刷新。 - 通知中心菜单权限和按钮权限编码需要后端权限表确认。