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

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

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