新增 AutoRDO 需求清洗工作台与消息中枢，迭代 OneOS V2 设计规范及租赁合同/工作台/车辆等原型，同步云效技能与导航注册；并归档一批 legacy 原型快照。

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-28 15:50:35 +08:00
parent b14425da5a
commit 5d51a6bf7a
1393 changed files with 488042 additions and 10046 deletions
--- a/docs/superpowers/plans/2026-07-22-message-hub.md
+++ b/docs/superpowers/plans/2026-07-22-message-hub.md
@@ -0,0 +1,548 @@
+# Message Hub 实施计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 落地统一消息中枢（模型 + 本地路由表 + Web 消息中心原型），并让工作台/外壳铃铛读同一中枢。
+
+**Architecture:** `src/common/message-hub/` 持有 Message、ChannelDelivery、RouteRule 与 `resolve()`；新原型 `message-center` 提供筛选/列表/详情/端模拟器/去处理；工作台与 `notice-bridge` 通过适配层映射为铃铛摘要。真推送与真唤端不做。
+
+**Tech Stack:** React + TypeScript（现有 Axhub Make 原型）、Vitest（`resolve` 单测）、localStorage（可选已读）、现有 `oneos-app-shell` 铃铛 UI。
+
+**Spec:** [docs/superpowers/specs/2026-07-22-message-hub-design.md](../specs/2026-07-22-message-hub-design.md)
+
+---
+
+## 文件结构（锁定）
+
+| 路径 | 职责 |
+|------|------|
+| `src/common/message-hub/types.ts` | Message / Channel / RouteRule 类型 |
+| `src/common/message-hub/routes.ts` | 五端 × 多系统路由表常量 |
+| `src/common/message-hub/resolve.ts` | `resolveMessageTarget()` |
+| `src/common/message-hub/resolve.test.ts` | 路由优先级与失败态单测 |
+| `src/common/message-hub/seed.ts` | 宽首期种子消息（含旧 notices 映射） |
+| `src/common/message-hub/store.ts` | 读列表、标已读、未读数（内存 + localStorage） |
+| `src/common/message-hub/shell-adapter.ts` | Message → `ShellNoticeItem` |
+| `src/common/message-hub/index.ts` | 公共导出 |
+| `src/prototypes/message-center/index.tsx` | 原型入口 |
+| `src/prototypes/message-center/MessageCenterApp.tsx` | 主 UI |
+| `src/prototypes/message-center/styles/index.css` | 样式 |
+| `src/prototypes/message-center/annotation-source.json` | 标注目录 |
+| `src/prototypes/message-center/.spec/route-resolve.md` | 路由判定全文 |
+| `src/prototypes/message-center/.spec/requirements-prd.md` | AutoPRD |
+| `src/resources/prd/message-center-autoprd.md` | PRD 副本 |
+| 修改 `oneos-app-shell/ShellNoticeCenter.tsx` | 「查看全部」→ 消息中心；详情优先于行内直跳 |
+| 修改 `oneos-web-workbench-new` | 铃铛数据改读 message-hub |
+| 修改 `nav-menu.json` | 增加「消息中心」菜单项 |
+
+---
+
+### Task 1: message-hub 类型 + resolve + 单测
+
+**Files:**
+- Create: `src/common/message-hub/types.ts`
+- Create: `src/common/message-hub/resolve.ts`
+- Create: `src/common/message-hub/resolve.test.ts`
+- Create: `src/common/message-hub/index.ts`（先导出类型与 resolve）
+
+- [ ] **Step 1: 写入类型**
+
+```ts
+// src/common/message-hub/types.ts
+export type SourceSystem = 'oneos' | 'vehicle-mid' | 'other-system' | 'external';
+export type MessageClient = 'web' | 'ios' | 'android' | 'harmony' | 'wechat_oa';
+export type ChannelStatus = 'pending' | 'sent' | 'failed' | 'skipped';
+export type MessagePriority = 'normal' | 'high';
+export type ExternalAppId = 'external-app-a' | 'external-app-b';
+
+export type ChannelDelivery = {
+  client: MessageClient;
+  status: ChannelStatus;
+  updatedAt?: string;
+};
+
+export type HubMessage = {
+  id: string;
+  sourceSystem: SourceSystem;
+  bizType: string;
+  bizId: string;
+  title: string;
+  summary: string;
+  detail: string;
+  priority: MessagePriority;
+  createdAt: string;
+  readAt?: string;
+  /** 角色占位；空数组表示全员可见 */
+  audienceRoleIds: string[];
+  channels: ChannelDelivery[];
+  /** 展示用业务标签，如「交车任务」 */
+  bizTag: string;
+};
+
+export type RouteRule = {
+  sourceSystem: SourceSystem;
+  bizType: string;
+  client: MessageClient;
+  targetTemplate: string;
+  label: string;
+  externalApp?: ExternalAppId;
+  /** 精确未命中时，再试该 client（如 harmony → android） */
+  fallbackClient?: MessageClient;
+};
+
+export type ResolveOk = {
+  ok: true;
+  uri: string;
+  label: string;
+  externalApp?: ExternalAppId;
+  rule: RouteRule;
+};
+
+export type ResolveFail = {
+  ok: false;
+  reason: 'no_rule';
+  message: '当前端暂无可跳转目标';
+};
+
+export type ResolveResult = ResolveOk | ResolveFail;
+```
+
+- [ ] **Step 2: 写失败单测（先不实现 resolve 逻辑体）**
+
+```ts
+// src/common/message-hub/resolve.test.ts
+import { describe, expect, it } from 'vitest';
+import { resolveMessageTarget } from './resolve';
+import type { HubMessage, RouteRule } from './types';
+
+const baseMsg: HubMessage = {
+  id: 'm1',
+  sourceSystem: 'oneos',
+  bizType: 'approval.arrive',
+  bizId: 'AP-1',
+  title: '待审',
+  summary: '',
+  detail: '详情',
+  priority: 'normal',
+  createdAt: '2026-07-22T10:00:00+08:00',
+  audienceRoleIds: [],
+  channels: [],
+  bizTag: '租赁合同',
+};
+
+describe('resolveMessageTarget', () => {
+  it('精确匹配 web 规则', () => {
+    const rules: RouteRule[] = [
+      {
+        sourceSystem: 'oneos',
+        bizType: 'approval.arrive',
+        client: 'web',
+        targetTemplate: '/prototypes/oneos-web-approval-todo?id={bizId}',
+        label: '审批待办',
+      },
+    ];
+    const r = resolveMessageTarget(baseMsg, 'web', rules);
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.uri).toBe('/prototypes/oneos-web-approval-todo?id=AP-1');
+  });
+
+  it('harmony 可 fallback 到 android', () => {
+    const rules: RouteRule[] = [
+      {
+        sourceSystem: 'oneos',
+        bizType: 'approval.arrive',
+        client: 'android',
+        targetTemplate: 'oneos://approval/{bizId}',
+        label: '安卓审批',
+        fallbackClient: undefined,
+      },
+      {
+        sourceSystem: 'oneos',
+        bizType: 'approval.arrive',
+        client: 'harmony',
+        targetTemplate: '',
+        label: '鸿蒙走安卓模板',
+        fallbackClient: 'android',
+      },
+    ];
+    // 实现约定：harmony 行若 targetTemplate 为空且带 fallbackClient，则用 fallback 的模板
+    const r = resolveMessageTarget(baseMsg, 'harmony', rules);
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.uri).toBe('oneos://approval/AP-1');
+  });
+
+  it('无规则返回固定文案', () => {
+    const r = resolveMessageTarget(baseMsg, 'wechat_oa', []);
+    expect(r).toEqual({
+      ok: false,
+      reason: 'no_rule',
+      message: '当前端暂无可跳转目标',
+    });
+  });
+
+  it('带 externalApp', () => {
+    const msg = { ...baseMsg, sourceSystem: 'external' as const, bizType: 'order.action', bizId: 'O-9' };
+    const rules: RouteRule[] = [
+      {
+        sourceSystem: 'external',
+        bizType: 'order.action',
+        client: 'web',
+        targetTemplate: 'ext-app-a://order/{bizId}',
+        label: '外部 App A 订单',
+        externalApp: 'external-app-a',
+      },
+    ];
+    const r = resolveMessageTarget(msg, 'web', rules);
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.uri).toBe('ext-app-a://order/O-9');
+      expect(r.externalApp).toBe('external-app-a');
+    }
+  });
+});
+```
+
+- [ ] **Step 3: 跑测确认失败**
+
+Run: `npx vitest --run src/common/message-hub/resolve.test.ts`  
+Expected: FAIL（模块不存在或函数未导出）
+
+- [ ] **Step 4: 实现 resolve**
+
+```ts
+// src/common/message-hub/resolve.ts
+import type { HubMessage, MessageClient, ResolveResult, RouteRule } from './types';
+
+function fillTemplate(template: string, msg: HubMessage): string {
+  return template
+    .replaceAll('{bizId}', encodeURIComponent(msg.bizId))
+    .replaceAll('{id}', encodeURIComponent(msg.id));
+}
+
+function findRule(
+  rules: RouteRule[],
+  sourceSystem: HubMessage['sourceSystem'],
+  bizType: string,
+  client: MessageClient,
+): RouteRule | undefined {
+  return rules.find(
+    (r) => r.sourceSystem === sourceSystem && r.bizType === bizType && r.client === client,
+  );
+}
+
+export function resolveMessageTarget(
+  msg: HubMessage,
+  client: MessageClient,
+  rules: RouteRule[],
+): ResolveResult {
+  const primary = findRule(rules, msg.sourceSystem, msg.bizType, client);
+  if (primary) {
+    const useFallback =
+      (!primary.targetTemplate || primary.targetTemplate.trim() === '') && primary.fallbackClient;
+    if (useFallback && primary.fallbackClient) {
+      const fb = findRule(rules, msg.sourceSystem, msg.bizType, primary.fallbackClient);
+      if (fb?.targetTemplate) {
+        return {
+          ok: true,
+          uri: fillTemplate(fb.targetTemplate, msg),
+          label: primary.label || fb.label,
+          externalApp: fb.externalApp ?? primary.externalApp,
+          rule: fb,
+        };
+      }
+    }
+    if (primary.targetTemplate?.trim()) {
+      return {
+        ok: true,
+        uri: fillTemplate(primary.targetTemplate, msg),
+        label: primary.label,
+        externalApp: primary.externalApp,
+        rule: primary,
+      };
+    }
+  }
+  return { ok: false, reason: 'no_rule', message: '当前端暂无可跳转目标' };
+}
+```
+
+- [ ] **Step 5: 跑测通过**
+
+Run: `npx vitest --run src/common/message-hub/resolve.test.ts`  
+Expected: PASS（4 tests）
+
+- [ ] **Step 6: Commit**（仅当用户要求提交时执行）
+
+```bash
+git add src/common/message-hub/
+git commit -m "$(cat <<'EOF'
+feat(message-hub): add types and resolve() with vitest coverage
+
+EOF
+)"
+```
+
+---
+
+### Task 2: 路由表 + 种子消息
+
+**Files:**
+- Create: `src/common/message-hub/routes.ts`
+- Create: `src/common/message-hub/seed.ts`
+- Modify: `src/common/message-hub/index.ts`
+
+- [ ] **Step 1: 写入 `ROUTE_RULES`**
+
+至少覆盖（每个 listed bizType 需含 web/ios/android/harmony/wechat_oa 五行；wechat 无办理页可用空 template + 不配 fallback，使 resolve 失败并在 UI 显示 skipped 通道态）：
+
+| sourceSystem | bizType | web 目标示例 |
+|--------------|---------|--------------|
+| oneos | approval.arrive | `/prototypes/oneos-web-approval-todo?id={bizId}` |
+| oneos | urge.remind | `/prototypes/oneos-web-ops`（可带 query） |
+| oneos | contract.expire | `/prototypes/customer-management` |
+| oneos | license.expire | `/prototypes/customer-management` |
+| oneos | bill.ready | `/prototypes/lease-business-ledger` |
+| oneos | h2.balance | `/prototypes/payment-records` |
+| oneos | system.release | （无跳转或打开版本说明占位 path） |
+| vehicle-mid | fault.overdue | `/prototypes/vehicle-fault-handling#page=detail&id={bizId}` |
+| vehicle-mid | vehicle.status | `/prototypes/vehicle-management` |
+| other-system | generic.notice | `/prototypes/message-center`（仅详情，无外跳也可失败） |
+| external | order.action | `ext-app-a://order/{bizId}` + `externalApp: external-app-a` |
+| external | settle.action | `ext-app-b://settle/{bizId}` + `externalApp: external-app-b` |
+
+harmony 行：`targetTemplate: ''`, `fallbackClient: 'android'`。  
+ios/android：`oneos://…` / `oneos-android://…` 占位 scheme。  
+wechat_oa：对可 H5 办理的给 `https://oa.example.com/...` 占位；纯 PC 办理给空 template。
+
+- [ ] **Step 2: 写入 `SEED_MESSAGES`**
+
+映射旧 `SEED_NOTICES`（保留原 id 如 `n-1`、`RELEASE_NOTICE_ID` 便于对照）+ 新增 vehicle-mid / other-system / external 各至少规格要求条数。  
+`audienceRoleIds` 对齐原 `roleIds`；无角色限制用 `[]`。  
+`channels`：web=sent，移动三端=sent 或 pending，wechat_oa 按样例 sent/skipped。
+
+- [ ] **Step 3: 导出**
+
+```ts
+// index.ts
+export * from './types';
+export * from './resolve';
+export { ROUTE_RULES } from './routes';
+export { SEED_MESSAGES } from './seed';
+```
+
+- [ ] **Step 4: 用真实 ROUTE_RULES 补一条集成断言（可选放 resolve.test）**
+
+```ts
+import { ROUTE_RULES } from './routes';
+import { SEED_MESSAGES } from './seed';
+
+it('种子 approval 在 web 可解析', () => {
+  const msg = SEED_MESSAGES.find((m) => m.bizType === 'approval.arrive');
+  expect(msg).toBeTruthy();
+  const r = resolveMessageTarget(msg!, 'web', ROUTE_RULES);
+  expect(r.ok).toBe(true);
+});
+```
+
+Run: `npx vitest --run src/common/message-hub/resolve.test.ts` → PASS
+
+- [ ] **Step 5: Commit**（用户要求时）
+
+```bash
+git add src/common/message-hub/
+git commit -m "$(cat <<'EOF'
+feat(message-hub): add route table and wide-scope seed messages
+
+EOF
+)"
+```
+
+---
+
+### Task 3: store + shell 适配
+
+**Files:**
+- Create: `src/common/message-hub/store.ts`
+- Create: `src/common/message-hub/shell-adapter.ts`
+- Modify: `src/common/message-hub/index.ts`
+
+- [ ] **Step 1: store**
+
+```ts
+// 要点
+const STORAGE_KEY = 'oneos.message-hub.readAt.v1';
+// loadSeed(): HubMessage[] — 合并 SEED 与 localStorage 中的 readAt
+// markRead(id): void
+// unreadCount(messages, roleId?): number
+// listForRole(messages, roleId?): HubMessage[]
+// sort: 未读优先 → priority high → createdAt desc
+```
+
+- [ ] **Step 2: shell-adapter**
+
+```ts
+import type { ShellNoticeItem } from '../oneos-app-shell/notice-bridge';
+import type { HubMessage } from './types';
+import { resolveMessageTarget } from './resolve';
+import { ROUTE_RULES } from './routes';
+
+export function toShellNoticeItem(msg: HubMessage): ShellNoticeItem {
+  const web = resolveMessageTarget(msg, 'web', ROUTE_RULES);
+  return {
+    id: msg.id,
+    type: msg.priority === 'high' && msg.bizType.startsWith('urge') ? '催办提醒' : msg.bizTag,
+    bizTag: msg.bizTag,
+    title: msg.title,
+    summary: msg.summary,
+    detail: msg.detail,
+    time: msg.createdAt.replace('T', ' ').slice(0, 16),
+    read: !!msg.readAt,
+    href: web.ok && web.uri.startsWith('/') ? web.uri : undefined,
+    taskId: msg.bizId,
+  };
+}
+```
+
+注意：铃铛点击按规格**只打开详情、不在行上直跳**；`href` 仍可供详情内「去处理」使用。`type === '催办提醒'` 用于外壳排序/标签，adapter 对 `urge.remind` 必须输出 `'催办提醒'`。
+
+- [ ] **Step 3: 导出 store / adapter**
+
+- [ ] **Step 4: Commit**（用户要求时）
+
+---
+
+### Task 4: message-center 原型 UI
+
+**Files:**
+- Create: `src/prototypes/message-center/index.tsx`
+- Create: `src/prototypes/message-center/MessageCenterApp.tsx`
+- Create: `src/prototypes/message-center/styles/index.css`
+- 实现前 Read: `~/.agents/skills/ui-ux-pro-max/SKILL.md`，并跑  
+  `python3 ~/.agents/skills/ui-ux-pro-max/scripts/search.py "admin dashboard notification inbox" --design-system -p "OneOS message-center"`  
+  视觉对齐现有工作台，不用营销风。
+
+- [ ] **Step 1: 入口**
+
+```tsx
+/**
+ * @name 消息中心
+ */
+import React from 'react';
+import { PrototypeAnnotationHost } from '../../common/prototype-annotation-host';
+import annotationSource from './annotation-source.json';
+import MessageCenterApp from './MessageCenterApp';
+import './styles/index.css';
+
+export default function MessageCenterPage() {
+  return (
+    <>
+      <MessageCenterApp />
+      <PrototypeAnnotationHost source={annotationSource as any} />
+    </>
+  );
+}
+```
+
+（若项目 annotation 挂载方式与 fault-handling 不同，以同目录近期原型为准。）
+
+- [ ] **Step 2: MessageCenterApp 行为清单（必须全部有）**
+
+1. 左栏：全部/未读/已读；系统源多选或下拉；业务类型下拉；**端模拟器**五端  
+2. 右栏列表：未读点、bizTag、title、时间  
+3. 选中详情：detail、channels 触达态表、`resolve` 预览（随端模拟器变）、「去处理」  
+4. 去处理：`markRead` → resolve →  
+   - `uri` 以 `/` 开头：`window.location.href` 或外壳 `postMessage({ type: 'ONEOS_SHELL_NAV', href })`（与工作台 `protoNav` 一致）  
+   - 否则：模态「将打开 {externalApp} / {uri}」（不 `window.open` scheme）  
+   - fail：页面内固定文案「当前端暂无可跳转目标」  
+5. 触控/对比度遵循 ui-ux-pro-max；表格数字可用 tabular-nums
+
+- [ ] **Step 3: 本地预览**
+
+打开 `/prototypes/message-center`，手测：切换端模拟器预览变化；external 消息出示意模态；无 wechat 规则时提示不可跳。
+
+- [ ] **Step 4: Commit**（用户要求时）
+
+---
+
+### Task 5: 业务规格 + AutoPRD + 标注
+
+**Files:**
+- Create: `src/prototypes/message-center/.spec/route-resolve.md`（判定优先级表、前置条件、数据源、用户可见结果、种子 vs 未接 API）
+- Create: `src/prototypes/message-center/.spec/requirements-prd.md`（用户故事：起点→运作→闭环；摘要链到 route-resolve）
+- Create: `src/resources/prd/message-center-autoprd.md`（与 PRD 同步）
+- Create/Update: `annotation-source.json` 顶层 `directory.nodes` 含「产品需求说明（PRD）」全文
+
+- [ ] **Step 1: 按 oneos-autoprd 写 PRD**（产品语言，不写文件路径堆砌）
+
+- [ ] **Step 2: route-resolve.md 必须含**
+
+| 优先级 | 条件 | 结果 |
+|--------|------|------|
+| 1 | 精确 source+bizType+client 且 template 非空 | 填充 URI |
+| 2 | template 空且 fallbackClient 有对应规则 | 用 fallback URI |
+| 3 | 否则 | 不可跳转文案 |
+
+- [ ] **Step 3: 若存在脚本则运行**
+
+`node scripts/sync-annotation-directory.mjs`（或项目内同等命令）
+
+- [ ] **Step 4: Commit**（用户要求时）
+
+---
+
+### Task 6: 导航登记
+
+**Files:**
+- Modify: `src/prototypes/oneos-prototype-nav/nav-menu.json`（在「工作台」旁或系统能力区增加「消息中心」→ `prototypes/message-center`）
+- Run: `npm run nav:sync -- --prototype message-center --note "新增统一消息中心原型"`
+
+- [ ] **Step 1: 加菜单项**
+- [ ] **Step 2: nav:sync**
+- [ ] **Step 3: 刷新原型导航页确认可见**
+- [ ] **Step 4: Commit**（用户要求时）
+
+---
+
+### Task 7: 工作台铃铛 + 外壳对接中枢
+
+**Files:**
+- Modify: `src/prototypes/oneos-web-workbench-new/components/WorkbenchPage.tsx`（及 NoticePanel 数据源）
+- Modify: `src/prototypes/oneos-web-workbench-new/data/notices.ts` — 改为从 hub re-export 适配函数，或标记 deprecated 并改调用方
+- Modify: `src/common/oneos-app-shell/ShellNoticeCenter.tsx`  
+  - 列表项点击：`onOpen` 打开详情（勿直接 `onHandle`）  
+  - 「查看全部」主按钮导航到 `/prototypes/message-center`  
+- Modify: `.spec/notice-center.md` 注明数据源迁移至 message-hub  
+- Update workbench AutoPRD 中通知章节（行为变更需 sync）
+
+- [ ] **Step 1: Workbench 使用 `loadMessages` + `toShellNoticeItem` / 自有列表组件读 hub**
+- [ ] **Step 2: postNoticesSync 仍发 `ShellNoticeItem[]`（adapter 输出）**
+- [ ] **Step 3: 外壳「查看全部」→ message-center**
+- [ ] **Step 4: 手测：原型演示嵌入工作台时铃铛未读与中枢一致；查看全部进入消息中心**
+- [ ] **Step 5: Commit**（用户要求时）
+
+---
+
+### Task 8: 验收对照 + 收尾
+
+- [ ] **Step 1: 对照规格 §10 验收清单逐条勾选**
+- [ ] **Step 2: `npx vitest --run src/common/message-hub/resolve.test.ts`**
+- [ ] **Step 3: 更新设计文档状态旁注明「已实现原型」（若本轮做完）**
+- [ ] **Step 4: 停止 brainstorm companion（可选）**  
+  `/Users/sylvawong/.agents/skills/brainstorming/scripts/stop-server.sh /Users/sylvawong/oneos1.2/.superpowers/brainstorm/82675-1784712939`
+
+---
+
+## Spec 覆盖自检
+
+| 规格要求 | 任务 |
+|----------|------|
+| Message / Channel / RouteRule 模型 | Task 1–2 |
+| 本地路由 + 优先级 + 固定失败文案 | Task 1, 5 |
+| 五端 × 多系统种子与外部 A/B | Task 2 |
+| 消息中心 UI + 端模拟器 + 去处理 | Task 4 |
+| 铃铛快捷 + 查看全部 | Task 7 |
+| 独立中枢架构 | Task 1–4 |
+| .spec + AutoPRD + 标注 | Task 5 |
+| 导航登记 | Task 6 |
+| 不做真推送/真唤端 | Task 4 模态示意 |
+
+无 TBD 占位；`resolveMessageTarget` / `HubMessage` / `ROUTE_RULES` 命名全计划一致。