feat: migrate cross checking ui to v3 flow

2026-05-07 18:15:40 +08:00
parent a14a1f0ee1
commit add399e126
7 changed files with 786 additions and 333 deletions
@@ -0,0 +1,179 @@
+# 交叉评查 v3 迁移收口说明
+
+## 当前主链路状态
+
+目前交叉评查的主流程已经切到新版本链路：
+
+1. 创建任务页先上传文档，再调用 `POST /api/v3/cross-review/tasks` 创建任务
+2. 任务列表走 `POST /api/v3/cross-review/tasks/query`
+3. 任务文档列表走 `GET /api/v3/cross-review/tasks/{taskId}/documents`
+4. 交叉评查详情页使用新版评查详情页外壳
+5. 提案、投票、待投票检查走 `v3 cross-review` 接口
+6. 完成评查走 `POST /api/v3/cross-review/tasks/{taskId}/documents/{documentId}/complete`
+
+## 本次已完成的前端收口
+
+### 1. 创建任务
+
+文件：
+
+- `app/routes/cross-checking.upload.tsx`
+- `app/api/cross-checking/cross-files-upload.ts`
+
+现状：
+
+- 不再把“上传文件 + 自动分配任务”作为主链路
+- 改为先上传文档，再使用上传成功返回的 `documentId` 创建任务
+- 创建任务请求体已经对齐后端 `v3` DTO：
+  - `taskName`
+  - `taskType`
+  - `docTypeId`
+  - `docTypeCode`
+  - `memberUserIds`
+  - `principalUserIds`
+  - `documentIds`
+
+### 2. 任务页
+
+文件：
+
+- `app/api/cross-checking/cross-files.ts`
+- `app/routes/cross-checking._index.tsx`
+
+现状：
+
+- 任务列表、统计、文档列表均已接新接口
+- 返回任务页后仍保留 `openModal + taskId + taskName` 的 reopen 机制
+
+### 3. 详情页
+
+文件：
+
+- `app/routes/cross-checking.result.tsx`
+- `app/components/reviews/ReviewTabs.tsx`
+
+现状：
+
+- 页面外壳切到新版评查详情页
+- 优先复用新版预览、tab、文件信息组件
+- 交叉评查特有的提案面板仍保留，作为业务差异层
+
+### 4. 提案与投票
+
+文件：
+
+- `app/api/cross-checking/cross-file-result.ts`
+
+现状：
+
+- 已切到以下新接口：
+  - `POST /api/v3/cross-review/proposals`
+  - `POST /api/v3/cross-review/proposals/{proposalId}/votes`
+  - `DELETE /api/v3/cross-review/proposals/{proposalId}`
+  - `GET /api/v3/cross-review/documents/{documentId}/proposals`
+  - `GET /api/v3/cross-review/documents/{documentId}/pending-votes`
+
+## 边支能力迁移状态
+
+结合最新后端实现，交叉评查的边支能力里，“向已有任务补传文档”也已经切到新版本链路。
+
+### 1. 向已有任务补传文档
+
+文件：
+
+- `app/api/cross-checking/cross-files-upload.ts`
+
+接口：
+
+- `POST /api/v3/cross-review/tasks/{taskId}/documents/upload`
+
+调用位置：
+
+- `app/components/cross-checking/DocumentListModal.tsx`
+
+当前实现：
+
+- 前端改为直接上传 `file`
+- 后端不再走旧 `cross_review` 边支上传逻辑
+- 改为复用 `leaudit` 文档上传与抽取链路，再把新文档挂到交叉评查任务下
+- 上传成功后任务状态会回到 `in_progress`
+
+说明：
+
+- 这条能力已经不再依赖旧版 `v2 cross_review upload_documents`
+- 文档抽取、后续评查点生成与新版主链路保持一致
+
+## 仍保留旧接口的支链路
+
+以下能力当前仍是旧接口，尚未迁到 `v3`：
+
+### 1. 任务文档追加附件
+
+文件：
+
+- `app/api/cross-checking/cross-files.ts`
+
+接口：
+
+- `POST /api/v2/cross_review/tasks/{task_id}/documents/{document_id}/append_attachments`
+
+调用位置：
+
+- `app/components/cross-checking/DocumentListModal.tsx`
+
+说明：
+
+- 该能力主要服务合同场景的版本追加
+- 当前仍可继续保留旧接口，等后端 `v3` 能力明确后再迁
+
+### 2. 合同模板上传
+
+文件：
+
+- `app/api/cross-checking/cross-files.ts`
+
+接口：
+
+- 复用上传服务 `/upload_contract_template`
+
+调用位置：
+
+- `app/components/cross-checking/DocumentListModal.tsx`
+
+说明：
+
+- 该能力不属于 `cross-review` 专属接口，暂不要求迁到 `v3 cross-review`
+
+## 建议的后续迁移优先级
+
+### P1
+
+- 追加附件：`appendTaskDocumentAttachments()`
+
+原因：
+
+- 业务价值高，但更多是合同场景增强功能
+- 可以在主链路稳定后迁
+
+### P2
+
+- 历史兼容 helper 清理
+- 旧注释、旧命名继续清理
+
+原因：
+
+- 不影响业务，但能减少后续误接老接口的概率
+
+## 当前结论
+
+可以认为交叉评查的核心业务链路已经完成 `v3` 迁移：
+
+- 创建任务
+- 任务列表
+- 文档列表
+- 详情展示
+- 提案投票
+- 完成评查
+- 已有任务补传文档
+
+剩余工作主要集中在“追加附件”这条旧边支能力，以及后续兼容代码清理。