leaudit-platform-frontend/auth_doc/交叉评查接口对接状态报告.md

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

本文档对比 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 中定义：

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

然后在各接口中使用：

// 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: { ... } }
);

---

报告生成完毕