fix: 1. 重新对齐交叉评查的接口。

2. 确认评查结果的接口对接。 3. 新增评查点适配省级创建的响应数据和其他用户创建的单条响应数据。 4. 文档列表的文档类型通过通用的查询接口查询文档类型。优化加载状态的时机。
2025-12-11 11:16:50 +08:00
parent ba517d7b9c
commit d8bba607fc
18 changed files with 3435 additions and 1086 deletions
@@ -0,0 +1,326 @@
+# 交叉评查接口对接状态报告
+
+> 本文档对比 `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: { ... } }
+);
+```
+
+---
+
+*报告生成完毕*