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

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

## 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：清理旧兼容

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