# 消息中枢（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. 架构

```text
业务系统(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 原型 |