112 lines
4.7 KiB
Markdown
112 lines
4.7 KiB
Markdown
# 通知中心状态持久化概念文档
|
||
|
||
## 功能一句话
|
||
|
||
为首页小铃铛通知中心补齐服务端状态接口，让同一用户在不同电脑登录时看到一致的已读、清空和隐藏状态，并优化笔记本等小屏幕下的通知弹窗可读性。
|
||
|
||
## 背景与问题
|
||
|
||
当前小铃铛通知由前端从单据中心、个人工作台摘要等数据源即时生成，但已读与清空状态主要写入浏览器 `localStorage`。这会导致同一账号在 A 电脑清空通知后，换到 B 电脑仍然看到通知。
|
||
|
||
同时，通知条数较多或屏幕高度较小时，列表内容容易挤压头部操作区，通知标题与描述也容易在窄宽度下互相挤压。
|
||
|
||
## 目标与非目标
|
||
|
||
目标：
|
||
|
||
- 提供当前用户维度的通知状态接口。
|
||
- 支持批量同步通知状态，至少覆盖已读与隐藏。
|
||
- 前端优先使用服务端状态，接口不可用时保留本地降级能力。
|
||
- 优化小屏幕通知弹窗，列表多时使用内部滚动，标题、描述与操作按钮不互相挤压。
|
||
|
||
非目标：
|
||
|
||
- 不做独立消息投递系统。
|
||
- 不新增推送、WebSocket 或邮件通知能力。
|
||
- 不改变通知来源生成逻辑，当前仍由单据中心和工作台摘要生成。
|
||
|
||
## 用户与场景
|
||
|
||
- 普通员工：在个人工作台查看待办、单据新消息，跨电脑登录后已读状态一致。
|
||
- 审批人：处理待审批单据后，通知中心不因换电脑重新显示已清空内容。
|
||
- 管理员：仍可看到系统内已有通知入口，但 admin 是否展示工作台由现有逻辑决定。
|
||
|
||
## 功能能力
|
||
|
||
- `GET /notification-states`：读取当前登录用户的通知状态集合。
|
||
- `POST /notification-states`：批量保存当前登录用户的通知状态。
|
||
- 状态字段：
|
||
- `notification_id`：前端生成的稳定通知 ID。
|
||
- `read_at`：已读时间。
|
||
- `hidden_at`：隐藏或清空时间。
|
||
- `context_json`：保留通知来源、类型等低风险上下文，便于排查。
|
||
- 前端能力：
|
||
- 打开工作台或弹窗时读取服务端状态。
|
||
- 点击通知写入已读。
|
||
- 清空通知写入隐藏。
|
||
- 接口失败时仍写入本地缓存，避免用户操作失效。
|
||
|
||
## 方案设计
|
||
|
||
后端：
|
||
|
||
- 新增 `NotificationState` SQLAlchemy 模型。
|
||
- 新增 `NotificationStateService`，负责按 `CurrentUserContext.username` 读写状态。
|
||
- 新增 `notification_states` endpoint，并挂到 API v1 router。
|
||
- 服务初始化时使用项目现有 `Base.metadata.create_all(..., tables=[...])` 模式确保表存在。
|
||
|
||
前端：
|
||
|
||
- 新增 `web/src/services/notificationStates.js` 封装接口。
|
||
- `TopBar.vue` 将 `localStorage` 状态作为初始兜底，服务端状态返回后合并覆盖。
|
||
- `markNotificationRead` 与 `clearAllNotifications` 做乐观更新，再异步同步服务端。
|
||
- 对单据通知仍调用现有 `markDocumentInboxRowRead`，同时写入通知状态接口，保证跨设备一致。
|
||
|
||
小屏幕布局：
|
||
|
||
- 弹窗宽度使用 `clamp` 与 `100vw` 约束。
|
||
- 弹窗最大高度使用 `min(..., calc(100vh - ...))`。
|
||
- 列表作为唯一滚动区域，头部和 tab 固定在弹窗网格内。
|
||
- 通知描述允许两行截断，避免窄屏时横向挤压。
|
||
|
||
## 算法与公式
|
||
|
||
当前功能不涉及显式数学公式。状态合并规则为：
|
||
|
||
$$
|
||
visible = notification\_id \notin hiddenIds
|
||
$$
|
||
|
||
$$
|
||
unread = sourceUnread \land notification\_id \notin readIds \land notification\_id \notin hiddenIds
|
||
$$
|
||
|
||
服务端状态优先，前端本地状态仅作为接口失败或首次加载前的兜底。
|
||
|
||
## 测试方案
|
||
|
||
- 后端单元测试：
|
||
- 当前用户只能读取自己的通知状态。
|
||
- 批量 upsert 后可读取 `read_at`、`hidden_at`。
|
||
- 清空通知写入 hidden 状态。
|
||
- 前端静态测试：
|
||
- `TopBar` 引用通知状态服务。
|
||
- 已读、清空操作会同步服务端。
|
||
- 小屏 CSS 使用弹窗 max-height、内部滚动和移动端约束。
|
||
- 构建验证：
|
||
- 运行前端构建确认 Vue 与服务导入无误。
|
||
- 在容器内运行后端定向 pytest。
|
||
|
||
## 指标与验收
|
||
|
||
- 同一用户跨电脑登录后，已读和清空状态由服务端保持一致。
|
||
- 接口失败时用户仍可本地清空，不阻断主要流程。
|
||
- 通知弹窗在笔记本高度下不会挤压头部按钮，列表内部滚动。
|
||
- 通知标题、描述、时间在窄屏下不横向溢出。
|
||
|
||
## 风险与开放问题
|
||
|
||
- 当前通知本身仍由前端即时生成，服务端只保存状态，不保存完整通知正文。
|
||
- 通知 ID 需要保持稳定，否则服务端状态无法命中；本次沿用现有 `document:` 和 `workbench:` 前缀。
|
||
- 历史 localStorage 状态会作为首次迁移兜底，后续服务端会逐步成为主状态源。
|