# 交叉评查接口对接状态报告

> 本文档对比 `auth_doc/交叉评查接口文档(1).md` 中定义的10个接口与前端代码实际调用的接口情况。
>
> 生成时间：2025-12-11

---

## 一、接口总览对比

### 文档定义的10个接口

| 序号 | 方法 | 文档路径 | 接口名称 |
|------|------|----------|----------|
| 1 | `POST` | `/api/v2/cross_review/proposals` | 发起评分提案 |
| 2 | `POST` | `/api/v2/cross_review/proposals/{proposal_id}/votes` | 对提案投票 |
| 3 | `DELETE` | `/api/v2/cross_review/proposals/{proposal_id}` | 撤销评分提案 |
| 4 | `POST` | `/api/v2/cross_review/proposals/details` | 获取提案列表及详情 |
| 5 | `POST` | `/api/v2/cross_review/proposals/document` | 获取指定文档的提案列表 |
| 6 | `POST` | `/api/v2/cross_review/proposals/document/check_pending_votes` | 检查未投票用户 |
| 7 | `POST` | `/api/v2/cross_review/tasks/user_tasks` | 获取用户参与的任务列表 |
| 8 | `GET` | `/api/v2/cross_review/tasks/{task_id}/progress` | 获取评查任务进度 |
| 9 | `POST` | `/api/v2/cross_review/tasks/{task_id}/documents` | 获取任务下文档列表 |
| 10 | `POST` | `/api/v2/cross_review/tasks/{task_id}/documents/{document_id}/complete` | 确认完成文档评查 |

---

## 二、前端代码调用的接口清单

### 涉及文件

1. `app/api/cross-checking/cross-file-result.ts` - 提案/意见相关操作
2. `app/api/cross-checking/cross-files.ts` - 任务列表相关操作
3. `app/api/cross-checking/cross-files-upload.ts` - 文件上传相关操作

---

## 三、逐一对比分析

### ✅ 接口 1：发起评分提案

| 项目 | 文档定义 | 前端实现 | 状态 |
|------|----------|----------|------|
| **方法** | `POST` | `POST` | ✅ 一致 |
| **路径** | `/api/v2/cross_review/proposals` | `/admin/cross_review/proposals` | ⚠️ **差异** |
| **文件** | - | `cross-file-result.ts:139` | - |
| **函数** | - | `submitCrossCheckingOpinion()` | - |

**差异说明**：
- 前端使用 `/admin/cross_review/proposals`，缺少 `/v2` 版本号
- 文档推荐使用 `/api/v2/cross_review/proposals`

**请求参数对比**：
| 参数 | 文档要求 | 前端发送 | 状态 |
|------|----------|----------|------|
| `document_id` | int, 必填 | ✅ 发送 | ✅ |
| `evaluation_point_id` | int, 必填 | ✅ 发送 | ✅ |
| `proposed_score` | float, 必填 | ✅ 发送 | ✅ |
| `reason` | string, 必填 | ✅ 发送 | ✅ |
| `proposer_id` | int, 必填 | ✅ 发送 | ✅ |
| `evaluation_result_id` | int, 必填 | ✅ 发送 | ✅ |

---

### ✅ 接口 2：对提案投票

| 项目 | 文档定义 | 前端实现 | 状态 |
|------|----------|----------|------|
| **方法** | `POST` | `POST` | ✅ 一致 |
| **路径** | `/api/v2/cross_review/proposals/{proposal_id}/votes` | `/admin/cross_review/proposals/{opinionId}/votes` | ⚠️ **差异** |
| **文件** | - | `cross-file-result.ts:321-333` | - |
| **函数** | - | `performOpinionAction()` (agree/disagree/withdraw_vote) | - |

**差异说明**：
- 前端使用 `/admin/cross_review/proposals/{id}/votes`，缺少 `/v2` 版本号

**请求参数对比**：
| 参数 | 文档要求 | 前端发送 | 状态 |
|------|----------|----------|------|
| `vote_type` | string (agree/disagree/cancel), 必填 | ✅ 发送 | ✅ |
| `voter_id` | int, 必填 | ✅ 发送 | ✅ |

---

### ✅ 接口 3：撤销评分提案

| 项目 | 文档定义 | 前端实现 | 状态 |
|------|----------|----------|------|
| **方法** | `DELETE` | `DELETE` | ✅ 一致 |
| **路径** | `/api/v2/cross_review/proposals/{proposal_id}` | `/admin/cross_review/proposals/{opinionId}` | ⚠️ **差异** |
| **文件** | - | `cross-file-result.ts:338` | - |
| **函数** | - | `performOpinionAction()` (withdraw_opinion) | - |

**差异说明**：
- 前端使用 `/admin/cross_review/proposals/{id}`，缺少 `/v2` 版本号

---

### ❌ 接口 4：获取提案列表及详情

| 项目 | 文档定义 | 前端实现 | 状态 |
|------|----------|----------|------|
| **方法** | `POST` | - | ❌ **未实现** |
| **路径** | `/api/v2/cross_review/proposals/details` | - | - |
| **说明** | 获取当前用户需要处理的所有待投票提案列表 | - | - |

**备注**：此接口用于获取用户需要投票的待处理提案，前端目前未调用此接口。

---

### ✅ 接口 5：获取指定文档的提案列表

| 项目 | 文档定义 | 前端实现 | 状态 |
|------|----------|----------|------|
| **方法** | `POST` | `POST` | ✅ 一致 |
| **路径** | `/api/v2/cross_review/proposals/document` | `/admin/cross_review/proposals/document` | ⚠️ **差异** |
| **文件** | - | `cross-file-result.ts:199` | - |
| **函数** | - | `getCrossCheckingOpinions()` | - |

**差异说明**：
- 前端使用 `/admin/cross_review/proposals/document`，缺少 `/v2` 版本号

**请求参数对比**：
| 参数 | 文档要求 | 前端发送 | 状态 |
|------|----------|----------|------|
| `document_id` | int, 必填 | ✅ 发送 | ✅ |
| `page` | int, 选填, 默认1 | ✅ 发送 | ✅ |
| `page_size` | int, 选填, 默认10 | ✅ 发送 | ✅ |
| `user_id` | - (文档未要求) | ⚠️ 发送 | ⚠️ 多余参数 |

---

### ✅ 接口 6：检查未投票用户

| 项目 | 文档定义 | 前端实现 | 状态 |
|------|----------|----------|------|
| **方法** | `POST` | `POST` | ✅ 一致 |
| **路径** | `/api/v2/cross_review/proposals/document/check_pending_votes` | `/admin/cross_review/proposals/document/check_pending_votes` | ⚠️ **差异** |
| **文件** | - | `cross-file-result.ts:474` | - |
| **函数** | - | `checkProposalVotes()` | - |

**差异说明**：
- 前端使用 `/admin/cross_review/proposals/document/check_pending_votes`，缺少 `/v2` 版本号

**请求参数对比**：
| 参数 | 文档要求 | 前端发送 | 状态 |
|------|----------|----------|------|
| `document_id` | int, 必填 | ✅ 发送 | ✅ |

---

### ✅ 接口 7：获取用户参与的任务列表

| 项目 | 文档定义 | 前端实现 | 状态 |
|------|----------|----------|------|
| **方法** | `POST` | `POST` | ✅ 一致 |
| **路径** | `/api/v2/cross_review/tasks/user_tasks` | `/admin/v2/cross_review/tasks/user_tasks` | ✅ **正确** |
| **文件** | - | `cross-files.ts:406` | - |
| **函数** | - | `getUserTaskDocuments()` | - |

**说明**：此接口已正确使用 `/v2` 版本号路径。

**请求参数对比**：
| 参数 | 文档要求 | 前端发送 | 状态 |
|------|----------|----------|------|
| `page` | int, 选填, 默认1 | ✅ 发送 | ✅ |
| `page_size` | int, 选填, 默认10 | ✅ 发送 | ✅ |

---

### ❌ 接口 8：获取评查任务进度

| 项目 | 文档定义 | 前端实现 | 状态 |
|------|----------|----------|------|
| **方法** | `GET` | - | ❌ **未实现** |
| **路径** | `/api/v2/cross_review/tasks/{task_id}/progress` | - | - |
| **说明** | 根据任务ID获取评查进度详情 | - | - |

**备注**：前端目前通过 `getUserTaskDocuments` 接口返回的 `progress` 字段获取进度，未单独调用此接口。

---

### ✅ 接口 9：获取任务下文档列表

| 项目 | 文档定义 | 前端实现 | 状态 |
|------|----------|----------|------|
| **方法** | `POST` | `POST` | ✅ 一致 |
| **路径** | `/api/v2/cross_review/tasks/{task_id}/documents` | `/admin/v2/cross_review/tasks/{taskId}/documents` | ✅ **正确** |
| **文件** | - | `cross-files.ts:448` | - |
| **函数** | - | `getTaskDocuments()` | - |

**说明**：此接口已正确使用 `/v2` 版本号路径。

**请求参数对比**：
| 参数 | 文档要求 | 前端发送 | 状态 |
|------|----------|----------|------|
| `page` | int, 选填, 默认1 | ✅ 发送 | ✅ |
| `page_size` | int, 选填, 默认10 | ✅ 发送 | ✅ |
| `file_type_ids` | array[int], 选填 | ❌ 未发送 | ⚠️ 未使用 |
| `date_from` | string, 选填 | ❌ 未发送 | ⚠️ 未使用 |
| `date_to` | string, 选填 | ❌ 未发送 | ⚠️ 未使用 |
| `keyword` | string, 选填 | ❌ 未发送 | ⚠️ 未使用 |
| `order` | string, 选填 | ❌ 未发送 | ⚠️ 未使用 |

---

### ✅ 接口 10：确认完成文档评查

| 项目 | 文档定义 | 前端实现 | 状态 |
|------|----------|----------|------|
| **方法** | `POST` | `POST` | ✅ 一致 |
| **路径** | `/api/v2/cross_review/tasks/{task_id}/documents/{document_id}/complete` | `/admin/v2/cross_review/tasks/{task_id}/documents/{document_id}/complete` | ✅ **正确** |
| **文件** | - | `cross-file-result.ts:417` | - |
| **函数** | - | `confirmReviewResults(taskId, documentId, jwtToken)` | - |

**说明**：此接口已正确使用 `/v2` 版本号路径，并包含 `task_id` 和 `document_id` 参数。

**已于 2025-12-11 修复完成。**

---

## 四、其他前端调用但文档未定义的接口

### 1. 创建交叉评查任务 (upload相关)

| 项目 | 前端实现 |
|------|----------|
| **方法** | `POST` |
| **路径** | `/admin/cross_review/tasks/assign` |
| **文件** | `cross-files-upload.ts:316` |
| **函数** | `createCrossReviewTask()` |

**说明**：此接口用于创建交叉评查任务并分配用户，在本文档10个接口中未定义。

### 2. 上传并分配文件

| 项目 | 前端实现 |
|------|----------|
| **方法** | `POST` |
| **路径** | `${UPLOAD_URL}/cross_review/documents/upload_and_assign` |
| **文件** | `cross-files-upload.ts:233` |
| **函数** | `batchUploadAndAssignCrossCheckingFiles()` |

**说明**：此接口用于批量上传文件并分配交叉评查任务，在本文档10个接口中未定义。

### 3. PostgREST 直接查询

| 项目 | 前端实现 |
|------|----------|
| **路径** | `/api/postgrest/proxy/cross_examination_tasks` |
| **文件** | `cross-file-result.ts:93` |
| **函数** | `findIsProposer()` |

**说明**：直接通过 PostgREST 查询数据库表，未走统一的 API 接口。

### 4. PostgREST 直接查询文档类型

| 项目 | 前端实现 |
|------|----------|
| **路径** | `/api/postgrest/proxy/document_types` |
| **文件** | `cross-files.ts:529` |
| **函数** | `getCrossCheckingDocumentTypes()` |

**说明**：直接通过 PostgREST 查询数据库表获取文档类型。

---

## 五、总结

### 对接状态统计

| 状态 | 数量 | 百分比 |
|------|------|--------|
| ✅ 已正确对接 | 3 | 30% |
| ⚠️ 路径差异（缺少v2） | 5 | 50% |
| ❌ 未实现 | 2 | 20% |

### 需要修复的问题

#### 🟡 中优先级（建议修复）

1. **统一使用 `/api/v2` 或 `/admin/v2` 前缀**
   - 接口 1、2、3、5、6 使用了旧路径 `/admin/cross_review/...`
   - 建议统一改为 `/admin/v2/cross_review/...` 或 `/api/v2/cross_review/...`

#### 🟢 低优先级（可选实现）

3. **接口4：获取提案列表及详情**
   - 当前未实现，如需要在其他页面展示待投票提案列表可实现

4. **接口8：获取评查任务进度**
   - 当前通过任务列表接口获取进度，如需单独获取可实现

5. **接口9：增加筛选参数支持**
   - `getTaskDocuments()` 未支持 `file_type_ids`、`date_from`、`date_to`、`keyword`、`order` 等筛选参数

---

## 六、修复建议代码示例

### 统一路径前缀

建议在 `api-config.ts` 中定义：

```typescript
// api-config.ts
export const CROSS_REVIEW_API_PREFIX = '/admin/v2/cross_review';
```

然后在各接口中使用：

```typescript
// cross-file-result.ts
import { API_BASE_URL, CROSS_REVIEW_API_PREFIX } from '../../config/api-config';

// 使用示例
const response = await axios.post(
  `${API_BASE_URL}${CROSS_REVIEW_API_PREFIX}/proposals`,
  requestData,
  { headers: { ... } }
);
```

---

*报告生成完毕*