# Design：B-2b 统一报销工作台迁移 ## 1. Architecture Decision 采用“任务路由分派 + 唯一报销工作台内容合同 + PC/移动布局壳 + 三个模式适配器”。不把审批模式继续塞进现有大型详情页，也不让通用 workflow 页面继续拥有报销业务布局。 ```text /workflow/tasks/:taskId /mobile/approvals/:taskId │ │ └──── authorized task route dispatcher ┘ │ entityType=reimbursement │ ReimbursementApprovalAdapter │ ReimbursementDesktopWorkspaceShell （共享内容合同） /reimbursements/:reimbursementId │ reimbursement route selector ├─ participant + draft/rejected -> ReimbursementEditAdapter └─ otherwise authorized -> ReimbursementReadonlyAdapter │ Desktop / Mobile WorkspaceShell （共享内容合同） ``` 任务分派器通过唯一一次已授权 task detail 查询选择实体渲染器，并把同一份 query result（含受控 refetch 能力）移交给所选渲染器。它不重复查询、不渲染报销摘要、不计算报销检查、不持有审批表单状态。非报销实体继续进入现有通用详情。 ## 2. Shell Contract PC/移动布局壳都是纯组合组件，共享模型和 capability 合同，但不强求同一份 DOM，也不接收 `mode` 用于业务判断： ```ts type ReimbursementWorkspaceModel = { header: ReimbursementWorkspaceHeaderModel; evidence: ReimbursementWorkspaceEvidenceProjection; issueSummary: ReimbursementWorkspaceIssueSummary | null; timeline: ReimbursementWorkspaceTimelineModel; }; type ReimbursementWorkspaceCapabilities = { item?: ReimbursementEvidenceItemCapabilities; invoice?: ReimbursementEvidenceInvoiceCapabilities; attachment?: ReimbursementEvidenceAttachmentCapabilities; decision?: ReimbursementDecisionCapabilities; }; type ReimbursementWorkspaceShellProps = { model: ReimbursementWorkspaceModel; capabilities: ReimbursementWorkspaceCapabilities; primaryActions?: ReactNode; secondaryActions?: ReactNode; statusSummary?: ReactNode; transientFeedback?: ReactNode; }; ``` `ReimbursementDesktopWorkspaceShell` 与 `ReimbursementMobileWorkspaceShell` 可以根据数据是否存在组合区块，也可以渲染注入的 slot；两者必须保持同一业务内容顺序和语义子组件，但可分别实现 PC 右栏与移动卡片/底部安全区布局。它们不能根据角色、permission、workflow 状态、报销状态或模式推导能力，不能用 `isMobile` 业务分支互相模拟。壳内禁止 `useQuery`、`useMutation`、API client 和业务 mutation state。纯视觉展开优先使用语义 HTML；确需本地视觉状态时不得承载业务事实。 ## 3. Adapter Responsibilities ### Edit Adapter - 获取/刷新报销详情、费用类型、项目、票据候选和 participant precheck。 - 拥有表头、明细、票据、附件、提交、删除、OCR 状态与错误恢复 mutation/state。 - 将可用动作投影为 capabilities；状态或权限不允许时不注入，不让壳二次判断。 - 服务端提交/B2 结果覆盖客户端乐观判断。 ### Approval Adapter - 消费路由边界移交的 workflow task detail/query result，不为同一 task 再发一份分派查询；另行获取实时报销详情。 - 拥有 task detail 的业务解释和刷新策略、allowedActions、提交快照、处理历史、审批 mutation、退回动作内引用、材料查看、联网状态和 fail-closed。 - 常驻内容只注入证据查看和审批决策能力；引用只注入已展开的退回编辑区，编辑/关联/解绑 capability 必须不存在。 - 任务、快照、实时报销内容任一关键部分未就绪时，输出不可决策模型和原因。 ### Readonly Adapter - 只获取既有授权允许的报销详情、处理进度和材料查看能力。 - 不请求参与人专用 precheck，不持有任何业务 mutation。 - 不注入编辑、提交或 workflow 决策能力。 共享查询键、材料打开 helper、展示投影和格式化函数可以复用；适配器不能通过一个巨大 hook 返回所有模式的 mutation 再由页面隐藏。 ## 4. Information Architecture ### PC ```text 报销单号 + 状态 报销人 · 日期 · 合计 事由 ┌────────────────────────────────────┬────────────────────┐ │ 费用明细表 │ 当前节点/状态 │ │ 票据与附件（发票/补充附件分组） │ 可决策状态 │ │ 未归属恢复（仅有时） │ 异常锚点（仅有时） │ │ 异常/快照差异（仅有时） │ 审批/提交动作 │ │ 处理历史/进度 │ sticky │ └────────────────────────────────────┴────────────────────┘ ``` ### Mobile 标题/状态 → 报销人/日期/合计 → 事由 → 费用明细卡 → 票据与附件（分组）→ 未归属恢复（仅有时）→ 异常/差异（仅有时）→ 历史/进度 → 底部动作。 正常检查不生成卡片。异常模型必须带对象引用和锚点： ```ts type ReimbursementWorkspaceIssue = { key: string; target: { kind: "item" | "invoice" | "submission"; displayLabel: string }; severity: "blocking" | "review" | "info"; reason: string; impact: string; nextStep?: string; anchorId: string; }; ``` 右栏只投影非零、可定位的问题。快照缺失是 `info`，视觉低于 blocking/review；快照与实时事实一致时不生成独立差异区。 ## 5. Route and Navigation - PC `/workflow/tasks/:taskId` 与移动 `/mobile/approvals/:taskId` 保持不变，避免破坏通知、待办、刷新和深链。 - 分派期间显示统一加载骨架；不得先挂载 `WorkflowTaskDetailPage`/通用移动详情再切换报销工作台。 - `/reimbursements/:id` 继续是报销记录入口。返回目标由合法、受限的 navigation state/source helper 解析；审批工作台不再提供“返回审批详情”的自循环外链。 - 新增或重分类路由时同步 `scripts/qa/route-manifest.json`；如果只是同一路由内分派，也要为 reimbursement renderer 增加行为证据。 ## 6. Legacy Removal 最终候选删除： - `WorkflowTaskDetailPage` 的报销 DetailField、报销证据/检查区、报销右栏摘要与报销专用动作分支。 - `MobileApprovalsPage` 的报销内容、报销检查、报销离线解释和报销动作业务分支；通用列表/非报销详情可保留。 - `ReimbursementDetailPage`/`MobileReimbursementDetailPage` 中被工作台替代的旧明细表格和旧材料分组。 - 旧报销专用文案、测试 fixture 与只为休眠路径服务的 helper/import。 允许在实现过程的未提交工作区短暂双接线；业务候选提交前必须用结构测试/`rg` allowlist 证明旧分支为 0。不得保留 feature flag 双轨。 上述壳层禁用项与通用审批旧分支清零必须实现为 `scripts/qa/check-ui-design-rules.mjs` 的 error 规则，并通过既有 `--strict` 部署 preflight；单元测试只补行为和类型证据，不能替代该门禁。 ## 7. Data and Permission Contracts - 不改后端 schema。现有 reimbursement detail、workflow detail、材料预览和动作 API 保持权威。 - 提交时费用标准/预算来自 workflow context 快照；当前票据/附件来自 reimbursement detail。 - approval adapter 复用 B-2a IndexedDB 白名单投影；工作台 model/evidence 不进入 cache。 - edit adapter 继续要求参与人 + `draft/rejected` + 现有 permission；readonly/approval 不因 UI 复用获得写能力。 - 材料 URL、访问参数和原始 payload 不进入 task、日志、浏览器持久缓存或错误文案。 ## 8. Print Boundary `/reimbursements/:id/print` 继续作为专用打印/PDF 视图，允许独立的纸面布局。它不参与三模式交互工作台，不持有工作台 mutation，也不作为审批取得核心内容的入口。本轮只做回归，避免字段删除误伤打印；不迁移或重新设计打印结构。 ## 9. Rollout and Rollback - 单一独立候选上线，不新增 migration、seed、flag 或生产数据写入。 - 切换前必须完成 PC/移动三模式和非报销回归；上线后使用公网真实 bundle + 合成 API 验收，不操作真人单据。 - 回滚是完整回到 B-2a 已部署版本；不保留运行时双壳开关。 - 真实三张 rejected 单据可与开发并行，任何反馈只通过新的规划修订进入本任务，不直接现场改产品代码。 ## 10. UI/UX Basis 本任务不引入新视觉系统。采用 `ui-ux-pro-max` 对本场景适用的通用原则：一致标题层级、组合优于模式继承、异常不只靠颜色、反馈明确、触控目标至少 44×44、渐进披露避免把所有解释预先铺开。其数据库没有命中特定“审批工作台”React 模板，因此不采用不存在的模板结论，继续以项目现有组件和 `docs/产品设计规则.md` 的信息架构为基线。 ## 11. Post-deployment KISS Evidence Layout 上线真人目视反馈证明，统一工作台架构正确，但 `ReimbursementItemEvidenceList` 仍把“费用明细、所属票据、文件动作、退回引用”压进同一嵌套卡片。收尾迭代保持适配器和 capability 边界不变，把展示层拆成三个语义组件： ```text ReimbursementEvidenceSection ├─ ReimbursementExpenseItems │ ├─ desktop: ExpenseItemsTable │ └─ mobile: ExpenseItemCards ├─ ReimbursementMaterials │ ├─ invoices │ └─ supplementary attachments └─ ReimbursementReturnReferencePicker（仅退回动作展开时挂载） ``` - `ExpenseItemsTable` 与 `ExpenseItemCards` 消费同一行模型：类型、日期、说明、金额、票据数量/状态、异常摘要、稳定锚点。PC/移动可以不同 DOM，不得各自重新计算业务状态。 - 发票不再嵌套在明细 DOM 内；projection 继续保留 `linkedItemId`，由纯函数派生每行票据摘要和独立材料列表。点击问题锚点仍能定位到对应明细行或材料行。 - 文件行的文件名/整行采用语义按钮或链接作为唯一查看入口；视觉上不重复“查看原件/查看附件”。移动命中区域不小于 44px，键盘焦点和 `aria-label` 必须包含材料类型与文件名/票号。 - edit capability 映射为明细单一编辑入口和材料区维护入口；readonly/approval 不注入维护能力。未归属或阻断票据是例外，可在材料行就地显示关联恢复动作。 - `onReferenceItem` / `onReferenceInvoice` 不再传给常驻明细/材料组件；审批适配器仅在 `activeSecondaryAction === "return"` 时把异常优先的候选模型传给引用选择器。选择器只写入本地退回意见文本，不调用 API。 - “查看完整材料”是区块级批量预览能力，与单文件入口并存时必须保持次要层级；单文件打开仍沿用既有短时 URL、用途审计和失败隔离。 参考 `/home/shunli/shenzhou-business-suite` 的费用明细表、移动卡片和附件分区只用于确定信息架构。实现不依赖该项目代码，也不复制其权限、状态或样式实现。