OneOS1.2/docs/superpowers/specs/2026-07-22-message-hub-design.md

消息中枢（Message Hub）重构设计

日期：2026-07-22
状态：已确认并完成首期原型（2026-07-22，分支 feat/message-hub）
范围：产品架构规格 + Web 统一消息中心原型（宽首期）

1. 背景与问题

当前 OneOS 原型中的「消息/通知」能力偏弱，实质是工作台站内铃铛阅知（oneos-web-workbench-new + oneos-app-shell 桥），外加若干业务侧短信/邮件演示。缺少：

• 独立消息中心
• Web / iOS / 安卓 / 鸿蒙 / 微信服务号的统一触达与跳转模型
• 多系统消息源（OneOS、车辆数据中台、其他系统）的接入约定
• 清晰的「详情 → 来源表单/办理页」深链规则（含外部端双 App）

本设计定义统一消息中枢，并指导首期 Web 原型落地。

2. 已确认产品决策

决策点	选择
本轮交付	规格文档 + Web 统一消息中心原型；移动/服务号以路由表与示意为主，不接真推送/服务号 API
产品入口	独立「消息中心」菜单页 + 顶栏铃铛作为未读快捷入口（「查看全部」进入消息中心）
首期广度	宽首期：五端触达矩阵 + 多系统消息源样例
跳转解析	消息只携带业务键；各端用本地路由表解析目标（不下发各端 URL）
消息与触达	一条业务事件 = 一条 Message；多通道（站内/推送/服务号）挂在同一条上
外部双 App	占位名 external-app-a / external-app-b，真名后续替换
落地架构	独立消息中枢：src/common/message-hub/ + 新原型 message-center；工作台铃铛改读中枢

3. 目标用户与核心任务

• 目标用户：OneOS 内部运营/业务人员（Web 为主）；五端与外部 App 在原型中用「端模拟器」与路由表示意。
• 核心任务：
  1. 在统一列表中看到来自多系统的待办/提醒类消息
  2. 打开详情理解上下文与通道触达状态
  3. 「去处理」按当前端解析并跳到来源办理页（或明确不可跳）

4. 范围

4.1 本轮做

• 统一 Message 模型、通道触达态、本地 RouteRule 与 resolve()
• 新原型 message-center：筛选、列表、详情、端模拟器、去处理
• 工作台/外壳铃铛对接同一中枢（旧 notices 迁移或适配）
• 五端 × 多系统种子与路由表样例（含外部 App A/B 占位）
• .spec 路由规则全文 + AutoPRD / 导航登记（实现轮）

4.2 本轮不做

• 真实推送 SDK、厂商通道、微信服务号模板下发
• 跨端已读强一致、服务端已读同步
• 外部 App 真唤端 / Universal Link 联调
• 车辆中台真实事件流接入（仅占位样例）
• 独立移动端/鸿蒙原生 UI 工程

5. 架构

业务系统(OneOS / vehicle-mid / other / external)
        │  产生业务事件（原型内为种子写入）
        ▼
┌───────────────────┐
│  message-hub      │  Message 池 · ChannelDelivery · RouteRule · resolve()
└─────────┬─────────┘
          │
    ┌─────┴─────┐
    ▼           ▼
消息中心页    顶栏铃铛 / 外壳 bridge
(完整 IA)     (未读摘要 + 快捷)
    │
    ▼
resolve(client) → 原型内导航 / 深链示意 / 不可跳提示

5.1 目录约定

路径	职责
src/common/message-hub/	类型、种子、路由表、resolve、读写状态（localStorage 可选用）
src/prototypes/message-center/	消息中心主 UI
src/prototypes/message-center/.spec/	路由规则、通道矩阵、验收
src/common/oneos-app-shell/	铃铛桥升级为 Message 摘要同步（兼容旧字段可选）
src/prototypes/oneos-web-workbench-new/	铃铛数据源改为中枢

6. 数据模型

6.1 Message

字段	说明
id	稳定 ID
sourceSystem	oneos | vehicle-mid | other-system | external
bizType	如 approval.arrive、urge.remind、contract.expire、fault.overdue、order.action
bizId	来源业务主键
title / summary / detail	展示文案
priority	如 normal / high（催办类可 high）
createdAt	ISO 时间
readAt	可选；本地已读
audience	角色/用户占位（原型可按角色过滤，对齐现工作台习惯）
channels	ChannelDelivery[]

6.2 ChannelDelivery

字段	说明
client	web | ios | android | harmony | wechat_oa
status	pending | sent | failed | skipped（原型模拟）
updatedAt	可选

说明：通道状态表示「是否对该端做过触达尝试」的演示态，不是跳转 URL。

6.3 RouteRule

字段	说明
sourceSystem	与 Message 一致
bizType	与 Message 一致
client	目标端
targetTemplate	URI 模板，支持 {bizId} 等占位
externalApp	可选：external-app-a | external-app-b
label	人读说明

解析优先级

1. 精确匹配 sourceSystem + bizType + client
2. 同系统同 bizType 的 fallback（如 harmony → android 模板，若配置了 fallback）
3. 无规则 → 不跳转，UI 明确提示「当前端暂无可跳转目标」

禁止：根据标题猜路径；无规则时静默跳首页。

7. 交互与闭环

7.1 铃铛

• 展示未读数与最近 N 条
• 点击单条：标已读并打开详情卡片（含「去处理」）；不在列表行上直接跳转，避免未看清上下文就离开
• 「查看全部」→ /prototypes/message-center

7.2 消息中心页

• 左：筛选（全部/未读/已读、系统源、业务类型）+ 端模拟器（切换 client，影响解析预览与去处理）
• 右：列表 + 详情（正文、通道触达态、解析预览、去处理）

7.3 去处理

1. 标记已读（本地）
2. resolve(message, simulatedClient)
3. 命中且为 Web 原型 path → 站内导航（直链或外壳 ONEOS_SHELL_NAV）
4. 命中且为外部/原生 scheme → 展示示意面板（将打开哪一 App/URI），不真唤端
5. 未命中 → Toast/详情内错误态，文案固定可验收

8. 种子与路由样例（宽首期）

消息源至少覆盖：

• oneos：审批到达、催办、合同/证照到期、账单、系统通知（从现有工作台 notices 映射迁入）
• vehicle-mid：故障逾期、车辆状态事件各 ≥1
• other-system：通用接入槽 ≥1
• external：跳转 App A、App B 的操作类各 ≥1

五端：每条关键 bizType 在路由表中为 web/ios/android/harmony/wechat_oa 提供模板或显式 skipped 说明（如纯 Web 办理类在 wechat_oa 可 skipped + 文案）。

9. 视觉与设计基底

沿用现有 OneOS Web 管理端语言（工作台、vm 列表习惯、外壳顶栏铃铛），不另起营销风或新主题。实现前对照项目 UI 规范；复杂判定写入 .spec。

10. 验收重点

1. 消息中心可按系统源/已读态筛选，列表与详情一致
2. 端模拟器切换后，同一条消息的解析预览随路由表变化
3. 「去处理」仅在命中规则时跳转；未命中有明确提示
4. 外部 App A/B 仅示意，不真唤端
5. 铃铛未读数与中枢一致；「查看全部」进入消息中心
6. 旧工作台通知种子可在中枢中看到对应映射条目
7. 规格中路由优先级表与代码 resolve() 行为一致

11. 风险与后续

• 真名替换 external-app-a/b 时只改路由表与文案，不改模型
• 接真 API 时 Message 写入改为服务端，客户端仍只持业务键 + 本地/下发的路由表副本
• 跨端已读、推送回执可作为下一阶段，不阻塞本轮原型

12. 决策快照（对齐记录）

问题	用户选择
交付深度	规格 + Web 消息中心原型
与铃铛关系	独立消息中心 + 铃铛快捷
首期广度	宽（五端 + 多系统）
跳转方式	业务键 + 本地路由表（由「服务端多 URL」改为此案）
消息与推送	一条事件多通道同一条消息
外部 App	占位 A/B
架构	独立 message-hub + message-center 原型