leaudit-platform-backend/docs/交叉评查/新项目交叉评查新表结构与接口清单.md

新项目交叉评查新表结构与接口清单

目标：给出交叉评查在新平台中的建议表结构、接口清单以及代码文件落点，便于直接拆任务实施。

1. 推荐新增表

1.1 leaudit_cross_review_tasks

用途：

• 交叉评查任务主表

建议字段：

id bigint primary key,
task_name varchar(255) not null,
task_type varchar(32) not null,
doc_type_id bigint null,
doc_type_code varchar(64) null,
assigner_id bigint not null,
status varchar(32) not null default 'in_progress',
created_at timestamptz not null default now(),
updated_at timestamptz not null default now(),
deleted_at timestamptz null

建议索引：

• idx_lcrt_assigner_id
• idx_lcrt_status
• idx_lcrt_doc_type_id

1.2 leaudit_cross_review_task_members

用途：

• 任务参与人和负责人关系表

建议字段：

id bigint primary key,
task_id bigint not null,
user_id bigint not null,
member_role varchar(32) not null,
created_at timestamptz not null default now(),
updated_at timestamptz not null default now(),
deleted_at timestamptz null

约束建议：

• 唯一约束：(task_id, user_id, deleted_at is null) 语义上唯一

建议索引：

• idx_lcrtm_task_id
• idx_lcrtm_user_id
• idx_lcrtm_role

1.3 leaudit_cross_review_task_documents

用途：

• 任务绑定文档

建议字段：

id bigint primary key,
task_id bigint not null,
document_id bigint not null,
audit_status integer not null default 0,
created_at timestamptz not null default now(),
updated_at timestamptz not null default now(),
deleted_at timestamptz null

说明：

• audit_status=0 未完成
• audit_status=1 已完成

建议索引：

• idx_lcrtd_task_id
• idx_lcrtd_document_id
• idx_lcrtd_task_status

1.4 leaudit_cross_review_proposals

用途：

• 交叉评查加减分提案

建议字段：

id bigint primary key,
task_id bigint not null,
document_id bigint not null,
rule_result_id bigint not null,
proposer_id bigint not null,
proposed_score_delta numeric(10,2) not null,
reason text not null,
status varchar(32) not null default 'pending',
created_at timestamptz not null default now(),
updated_at timestamptz not null default now(),
deleted_at timestamptz null

建议索引：

• idx_lcrp_task_id
• idx_lcrp_document_id
• idx_lcrp_rule_result_id
• idx_lcrp_proposer_id
• idx_lcrp_status

业务唯一性建议：

• 同一用户对同一 document_id + rule_result_id 同时只能存在一条有效提案

1.5 leaudit_cross_review_votes

用途：

• 提案投票

建议字段：

id bigint primary key,
proposal_id bigint not null,
voter_id bigint not null,
vote_type varchar(16) not null,
created_at timestamptz not null default now(),
updated_at timestamptz not null default now(),
deleted_at timestamptz null

建议索引：

• idx_lcrv_proposal_id
• idx_lcrv_voter_id

业务唯一性建议：

• 同一提案、同一用户仅保留一条有效投票

2. 推荐后端文件落点

2.1 Models

建议新增：

• fastapi_modules/fastapi_leaudit/models/leauditCrossReviewTask.py
• fastapi_modules/fastapi_leaudit/models/leauditCrossReviewTaskMember.py
• fastapi_modules/fastapi_leaudit/models/leauditCrossReviewTaskDocument.py
• fastapi_modules/fastapi_leaudit/models/leauditCrossReviewProposal.py
• fastapi_modules/fastapi_leaudit/models/leauditCrossReviewVote.py

2.2 DTO

建议新增：

• fastapi_modules/fastapi_leaudit/domian/Dto/crossReviewDto.py

建议包含：

• CrossReviewTaskCreateDTO
• CrossReviewProposalCreateDTO
• CrossReviewVoteDTO
• CrossReviewTaskDocumentQueryDTO

2.3 VO

建议新增：

• fastapi_modules/fastapi_leaudit/domian/vo/crossReviewVo.py

建议包含：

• CrossReviewTaskItemVO
• CrossReviewTaskPageVO
• CrossReviewTaskDocumentVO
• CrossReviewTaskDocumentPageVO
• CrossReviewProposalVO
• CrossReviewProposalPageVO
• CrossReviewPermissionVO
• CrossReviewCompleteVO

2.4 Service

建议新增：

• fastapi_modules/fastapi_leaudit/services/crossReviewService.py
• fastapi_modules/fastapi_leaudit/services/impl/crossReviewServiceImpl.py

2.5 Controller

建议新增：

• fastapi_modules/fastapi_leaudit/controllers/crossReviewController.py

3. 推荐服务接口

建议在 crossReviewService.py 中定义以下能力：

• CreateTask(...)
• GetUserTasks(...)
• GetTaskDocuments(...)
• CanConfirmTaskDocument(...)
• CompleteTaskDocument(...)
• CreateProposal(...)
• VoteProposal(...)
• CancelProposal(...)
• GetDocumentProposals(...)
• GetPendingProposalDetails(...)
• CheckPendingVotesByDocument(...)
• UploadDocumentsToTask(...)
• AppendTaskDocumentAttachments(...)
• LoadApprovedProposalDeltas(...)

4. 推荐接口清单

4.1 任务接口

POST /api/v2/cross_review/tasks

用途：

• 创建交叉评查任务

请求体建议：

{
  "document_ids": [101, 102],
  "user_ids": [11, 12],
  "principal_user_ids": [21],
  "task_name": "市局间交叉评查-合同类",
  "doc_type_id": 3,
  "doc_type_code": "XZCF",
  "task_type": "CITY"
}

POST /api/v2/cross_review/tasks/user_tasks

用途：

• 获取当前用户参与的任务列表

GET /api/v2/cross_review/tasks/{taskId}/documents

用途：

• 获取任务下文档列表
• 支持版本归纳

查询参数建议：

• page
• page_size
• keyword

GET /api/v2/cross_review/tasks/{taskId}/can-confirm

用途：

• 检查当前用户是否能确认文档评查完成

POST /api/v2/cross_review/tasks/{taskId}/documents/{documentId}/complete

用途：

• 确认任务内文档完成

POST /api/v2/cross_review/tasks/{taskId}/upload_documents

用途：

• 向已有任务追加新文档

POST /api/v2/cross_review/tasks/{taskId}/documents/{documentId}/append_attachments

用途：

• 给任务文档追加附件并生成新版本

4.2 提案接口

POST /api/v2/cross_review/proposals

用途：

• 创建提案

请求体建议：

{
  "task_id": 1,
  "document_id": 101,
  "rule_result_id": 10001,
  "proposed_score_delta": -5,
  "reason": "该点应扣 5 分"
}

POST /api/v2/cross_review/proposals/{proposalId}/votes

用途：

• 对提案投票

请求体建议：

{
  "vote_type": "agree"
}

DELETE /api/v2/cross_review/proposals/{proposalId}

用途：

• 撤销提案

POST /api/v2/cross_review/proposals/document

用途：

• 获取某文档的提案列表

请求体建议：

{
  "document_id": 101,
  "page": 1,
  "page_size": 10
}

POST /api/v2/cross_review/proposals/details

用途：

• 获取当前用户待处理提案列表

POST /api/v2/cross_review/proposals/document/check_pending_votes

用途：

• 检查某文档是否仍有提案未完成投票

5. 与现有 DocumentServiceImpl 的衔接点

5.1 详情页提案列表

当前衔接点：

• DocumentServiceImpl._loadScoringProposals()

建议：

• 改成读 leaudit_cross_review_proposals
• 后续移除对旧 cross_scoring_proposals 的直接依赖

5.2 最终得分计算

当前衔接点：

• DocumentServiceImpl._loadReviewPointResults()

建议：

• 增加按 rule_result_id 聚合已通过提案分数的逻辑
• 返回前写入 ReviewPointResultVO.finalScore

5.3 文档上传与附件追加

建议复用：

• DocumentServiceImpl.Upload()
• DocumentServiceImpl.AppendAttachments()

交叉评查只负责：

• 上传后把文档挂入任务
• 维护任务内状态和版本展示

6. 建议前端改造策略

6.1 第一阶段

前端尽量少改，只调整 API 基址和字段映射。

重点文件：

• new_doc_review/app/api/cross-checking/cross-files.ts
• new_doc_review/app/api/cross-checking/cross-file-result.ts
• new_doc_review/app/api/cross-checking/cross-files-upload.ts

6.2 第二阶段

逐步清理这些旧依赖：

• 前端直接查 cross_examination_tasks
• 前端直接查 cross_task_document_mapping
• 前端假设旧路径 /admin/cross_review/*

7. 推荐实施拆解

P0：表结构与模型

• 建新表
• 建模型
• 建基础迁移

P1：任务与提案接口

• 创建任务
• 任务列表
• 文档列表
• 提案创建
• 投票
• 完成确认

P2：详情页聚合接入

• GetReviewPoints() 改接新提案表
• 动态计算最终分数

P3：上传与版本链闭环

• 任务上传文档
• 追加附件
• 版本归纳改用 versionGroupKey

P4：清理旧兼容

• 清理旧表直查
• 清理前端旧路径
• 清理旧逻辑兜底