2.6 KiB
2.6 KiB
01 — 向明确后台账号可靠投递首条站内通知
What to build: 业务事件携带稳定后台账号 ID 后，可以经公共 Outbox、Relay 和 Notification Worker 为该账号幂等生成一条纯文本站内通知；当前登录账号可以查询自己的未读数和分页列表，并将单条通知幂等标记为已读。重复投递不会重复写入，过期通知不进入用户视图，任何用户接口都不能指定或篡改接收人。
Blocked by: .scratch/tech-public-foundation/issues/03-outbox-at-least-once-delivery.md — 03 — 完成 Outbox 到 Asynq 的至少一次投递闭环
Status: ready-for-agent
架构通道: 主通道为简单写 Application，辅助通道为 Infrastructure 与 Query。
完整业务边界: 本票收口后台明确账号通知的存储、受控类型注册、Worker 幂等消费、未读数、基础列表和单条已读闭环。明确不实现角色或店铺动态接收人、个人客户通知、分类汇总、全部已读、目标解析、前端组件或具体业务场景触发规则，也不复制公共 Outbox 和 Relay。
- 通知事实包含稳定事件 ID、接收人类型与 ID、类别、类型、级别、纯文本标题正文、受控资源引用、已读与过期时间，并通过事件 ID、接收人类型和接收人 ID 唯一约束防止重复消费。
- 通知常量、中文说明、类型到类别、默认级别、模板和允许目标的注册关系统一管理；未注册类型、模板字段永久缺失或正文包含禁止敏感内容时不生成残缺通知。
- Worker 只接受结构化载荷，重复事件和并发消费最多为同一后台账号生成一条通知；瞬时数据库错误返回任务错误，原业务事务不因通知写入失败而回滚。
- 当前后台账号可以获得准确的
count:int64和display_count:string，其中 0、1～99、100 以上分别显示0、十进制文本和99+，且未读数只查询 PostgreSQL。 - 后台列表只读取当前认证账号的未过期通知，固定按创建时间和 ID 倒序，默认每页 20、最大 50，并返回统一响应与 ISO 8601 时间。
- 单条已读使用接收人条件和未读条件更新；别人通知、不存在通知和已读通知均幂等成功，首次写入的
read_at在重复请求中保持不变。 - PostgreSQL、Worker 和真实后台认证 HTTP 集成测试覆盖唯一约束、重复消费、过期排除、分页排序、接收人篡改、越权隔离及重复已读。
- 新增后台 Handler 后完成路由、RouteSpec 和两个 OpenAPI 文档生成器注册，且静态路由顺序不会被动态通知 ID 路由吞掉。