74 行
9.2 KiB
Markdown
74 行
9.2 KiB
Markdown
# 采购与资产详情独立路由化
|
||
|
||
## Goal
|
||
|
||
把采购、资产两个已有业务台账从“列表页用 `?id=` 填充详情态”迁移为“列表查找、独立详情处理”，让记录可深链、筛选可恢复、返回可预测；资产新建使用独立创建路由，避免把完整长表单重新塞回台账列表。
|
||
|
||
## Confirmed Facts
|
||
|
||
- 报销、项目和审批任务已有独立详情路由与安全 `state.from` 返回约定，可作为仓库内成熟模式。
|
||
- 采购、资产都已有完整详情/编辑能力，并以列表页 `?id=`、本地 selected ID 和 searchParams 双向同步驱动；本任务是搬迁既有信息结构，不重做业务详情。
|
||
- 采购“新建采购”会先创建草稿并取得实体 ID，因此创建成功后可直接进入 `/purchase-requests/:purchaseRequestId`，不需要采购新建路由。
|
||
- 资产“新增资产”在提交前只有本地长表单、没有实体 ID；历史任务已确认“新建资产卡片进入独立创建视图”，本轮采用 `/assets/new`。
|
||
- 两个列表的筛选目前主要存在组件本地 state；拆出详情后若不把可恢复筛选写入 URL，返回列表会丢失用户上下文。
|
||
- 两页都已使用 `useUnsavedChangesGuard`，路由迁移必须保留取消离开与确认离开的既有语义。
|
||
- 项目详情、全局搜索和 PC 通知仍存在旧采购/资产入口：项目详情生成采购 `?id=`，全局搜索依赖服务端 `href`，PC 通知生成未被页面消费的 `highlight`。
|
||
- 现有采购/资产 E2E 和人工 witness 多处直接访问 `?id=`，需要兼容重定向并同步结构化路由证据。
|
||
- 合同没有 selected ID 或详情态，属于从零建设详情页；已拆到 `08-05-contract-detail-workspace`。
|
||
- 完整差旅已冻结；付款批次和请假继续保持既有页面边界，均不纳入本任务。
|
||
|
||
## Scope
|
||
|
||
- 仅迁移采购、资产两个已有 `?id=` 详情态到独立实体详情路由，并新增资产独立创建路由 `/assets/new`。
|
||
- 包含列表纯化、可恢复筛选 URL 化、详情/创建页拆分、旧链接兼容、现有前端关联入口更新、权限 guard、返回/深链和未保存保护。
|
||
- 资产列表保留现有资产分类管理等列表级工具；“纯列表”指不再承载某条资产或采购记录的详情/编辑工作区。
|
||
- 不新建合同详情信息结构，不恢复差旅，不改付款批次或请假页面。
|
||
|
||
## Requirements
|
||
|
||
- R1：`/purchase-requests` 与 `/assets` 只承载标题、创建入口、可恢复筛选、列表/卡片、分页或现有列表级工具，不渲染单条记录详情工作区。
|
||
- R2：采购详情固定为 `/purchase-requests/:purchaseRequestId`，资产详情固定为 `/assets/:assetId`；均支持直接打开、刷新、复制链接和正确页面元数据。
|
||
- R3：资产创建固定为 `/assets/new`，仅 `asset.manage` 可访问；创建成功后替换为新资产详情路由，浏览器返回不得重新进入已提交的创建表单。
|
||
- R4：采购状态、范围、供应商、公司、成本中心、页码，以及资产搜索、状态、类型、敏感级别、分类、公司、成本中心、归属人和范围等可恢复筛选以 URL 为事实源；无效值回落到安全默认，不扩大数据范围。
|
||
- R5：只搬迁现有详情、编辑、附件、审计、状态动作、资产流转和权限显隐，不新增合同式信息结构或改变业务能力。
|
||
- R6：从列表或资产创建页进入详情时保留经过校验的返回来源；从项目、全局搜索和通知等现有入口进入详情时使用新 URL。浏览器后退沿历史返回，显式返回在无安全来源时回到对应模块列表。
|
||
- R7：路由离开、显式返回、浏览器后退或跳转其他记录时存在未保存修改，必须沿用现有 dirty-form 保护；取消后保留当前 URL、记录与输入。
|
||
- R8：旧 `/purchase-requests?id=<id>`、`/assets?id=<id>` 使用 replace 进入新详情路由，并把移除 `id` 后的安全列表查询保留为返回来源；空 ID 不触发详情，无效/无权限 ID 不泄露记录摘要。
|
||
- R9：详情 403/404 使用统一自然中文安全错误态，仅说明“记录可能不存在或无权查看”并提供返回列表入口，不区分可用于资源枚举的敏感细节。
|
||
- R10：新列表、详情和创建路由沿用现有权限与服务端数据范围；资产 `/assets/new` 使用比资产列表更窄的 `asset.manage` guard，不得把列表可见权限误当创建权限。
|
||
- R11：采购创建成功、采购/资产列表行、项目关联、全局搜索结果解析、PC 通知解析和受影响测试改用统一的采购/资产详情路径构造；`client/src` 不再新增业务性的采购/资产 `?id=` 或 `highlight` 详情链接，兼容入口除外。
|
||
- R12：合同、差旅、付款、请假明确排除，不做顺手重构；移动采购详情保持现状，资产 PC 新路由在移动工作台偏好环境中仍安全回落到既有移动资产扫码页。
|
||
|
||
## Acceptance Criteria
|
||
|
||
- [x] `/purchase-requests` 与 `/assets` 首屏均为列表态，且不请求单条记录详情；资产分类管理等现有列表级工具仍可用。
|
||
- [x] `/purchase-requests/:purchaseRequestId` 与 `/assets/:assetId` 可直接访问、刷新和复制，页面标题、导航激活、权限 guard 与安全错误态正确。
|
||
- [ ] `/assets/new` 展示现有资产创建表单，非 `asset.manage` 用户不能直接访问；创建成功后 URL 变为 `/assets/:assetId`，返回不会回到已提交表单。— PAUSED：路由、权限与静态优先级已在 Chromium 通过；真实创建成功与历史栈因既有本地数据库列缺失未执行。
|
||
- [x] 采购和资产的全部可恢复列表筛选可由 URL 还原；列表进入详情再返回时筛选、范围和采购页码保持一致，筛选变更不会污染浏览器返回历史。
|
||
- [x] 旧 `?id=` 链接 replace 到对应新详情路由，返回时不丢失移除 `id` 后的安全筛选；空 ID 留在列表，无效或无权限 ID 不出现空白、错误对象或敏感摘要。
|
||
- [ ] 编辑、附件、状态动作、审计、资产流转和确认能力与迁移前等价，未保存保护覆盖详情返回、创建取消、浏览器后退和跨路由离开。— PAUSED：mock 路由与未保存保护已通过；真实采购附件/状态及资产流转等价回归受本地数据库缺口阻塞。
|
||
- [ ] 采购创建成功直接进入新详情；项目关联、全局搜索和 PC 通知中的采购/资产记录均进入新详情 URL，不再依赖未消费的 `highlight`。— PAUSED：项目、搜索与通知入口已验证；真实采购创建成功链路受本地数据库缺口阻塞。
|
||
- [x] `/assets/new` 不被动态资产详情路由当成 `assetId`，详情路由不加载完整列表，列表路由不加载详情。
|
||
- [x] 移动采购详情路由不回退；移动工作台偏好环境访问资产列表、详情或创建 URL 时继续进入既有 `/mobile/assets/scan`，不新增移动资产详情能力。
|
||
- [x] 合同、差旅、付款和请假代码不因本任务发生功能性修改；后端 endpoint、payload、权限/数据逻辑和数据库均不改变。
|
||
- [ ] 聚焦 Playwright 覆盖列表进入、筛选深链、详情刷新、返回恢复、旧链兼容、资产创建、无权限/不存在、dirty-form 取消与确认，以及项目/搜索/通知入口。— PAUSED：29 项 mock Chromium 回归已通过；真实资产创建和完整业务链仍受本地数据库缺口阻塞。
|
||
- [ ] `cd client && npm run typecheck && npm run build`、相关现有 E2E、任务校验与 Trellis 门禁通过。— PAUSED：类型、构建、mock E2E 与全部治理门禁已通过；`procurement-flow`、`assets-flow` 和真实权限直连用例未能在当前本地数据库执行。
|
||
|
||
## Out of Scope
|
||
|
||
- 合同详情页或合同文件能力。
|
||
- 差旅、付款批次、请假详情路由。
|
||
- 采购独立新建路由；采购继续先创建草稿再进入详情。
|
||
- 新移动资产详情页、移动资产创建页或移动导航重写。
|
||
- 后端 API endpoint/payload、状态机、权限模型、数据库 schema 或真实数据迁移。
|
||
- 模块冻结、一级导航调整、功能下线、详情信息架构重做或视觉换肤。
|
||
|
||
## Test Plan
|
||
|
||
- `cd client && npm run typecheck && npm run build`
|
||
- 聚焦 Playwright 覆盖采购/资产筛选 URL、列表进入详情、深链刷新、显式返回与浏览器后退、旧 `?id=` replace、无权限/不存在和 dirty-form 取消/确认。
|
||
- 覆盖 `/assets/new` 的权限、未保存取消、创建成功 replace、`new` 静态路由优先级，以及采购创建成功后的详情导航。
|
||
- 更新并运行 `procurement-flow.spec.ts`、`assets-flow.spec.ts`、`r103-cross-page-ui-consistency.spec.ts`、`pc-detail-mobile-visual-wave3.spec.ts`、`global-search.spec.ts`、通知链接与移动路由受影响用例；必要时增加聚焦路由合同 spec。
|
||
- 用代码搜索确认 `client/src` 中业务入口不再产生采购/资产 `?id=` 或 `highlight` 详情链接，只保留明确命名的兼容解析逻辑。
|
||
- 运行 `python3 ./.trellis/scripts/task.py validate 08-05-business-detail-routing`、`node scripts/qa/check-process-contract.mjs --baseline --json`、`node scripts/qa/audit-docs.mjs --check-registry`、`node scripts/qa/check-trellis-governance.mjs` 和 `git diff --check`。
|