189 行
12 KiB
Markdown
189 行
12 KiB
Markdown
# 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` 的费用明细表、移动卡片和附件分区只用于确定信息架构。实现不依赖该项目代码，也不复制其权限、状态或样式实现。
|