feat: migrate cross review to v3 leaudit flow

2026-05-07 18:18:59 +08:00
parent 35e0c45c42
commit 1c84209f38
23 changed files with 5172 additions and 39 deletions
@@ -0,0 +1,450 @@
+# 新项目交叉评查新表结构与接口清单
+
+> 目标：给出交叉评查在新平台中的建议表结构、接口清单以及代码文件落点，便于直接拆任务实施。
+
+## 1. 推荐新增表
+
+## 1.1 `leaudit_cross_review_tasks`
+
+用途：
+
+- 交叉评查任务主表
+
+建议字段：
+
+```sql
+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`
+
+用途：
+
+- 任务参与人和负责人关系表
+
+建议字段：
+
+```sql
+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`
+
+用途：
+
+- 任务绑定文档
+
+建议字段：
+
+```sql
+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`
+
+用途：
+
+- 交叉评查加减分提案
+
+建议字段：
+
+```sql
+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`
+
+用途：
+
+- 提案投票
+
+建议字段：
+
+```sql
+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`
+
+用途：
+
+- 创建交叉评查任务
+
+请求体建议：
+
+```json
+{
+  "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`
+
+用途：
+
+- 创建提案
+
+请求体建议：
+
+```json
+{
+  "task_id": 1,
+  "document_id": 101,
+  "rule_result_id": 10001,
+  "proposed_score_delta": -5,
+  "reason": "该点应扣 5 分"
+}
+```
+
+### `POST /api/v2/cross_review/proposals/{proposalId}/votes`
+
+用途：
+
+- 对提案投票
+
+请求体建议：
+
+```json
+{
+  "vote_type": "agree"
+}
+```
+
+### `DELETE /api/v2/cross_review/proposals/{proposalId}`
+
+用途：
+
+- 撤销提案
+
+### `POST /api/v2/cross_review/proposals/document`
+
+用途：
+
+- 获取某文档的提案列表
+
+请求体建议：
+
+```json
+{
+  "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：清理旧兼容
+
+- 清理旧表直查
+- 清理前端旧路径
+- 清理旧逻辑兜底
+