leaudit-platform-frontend/docs/cross-checking-v3-migration-status.md

交叉评查 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 迁移：

• 创建任务
• 任务列表
• 文档列表
• 详情展示
• 提案投票
• 完成评查
• 已有任务补传文档

剩余工作主要集中在“追加附件”这条旧边支能力，以及后续兼容代码清理。