194 lines
8.2 KiB
Markdown
194 lines
8.2 KiB
Markdown
# 消息中枢（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 原型 |
|