feat: migrate cross review to v3 leaudit flow
This commit is contained in:
wren
@@ -0,0 +1,562 @@
|
||||
# 新项目交叉评查实现方案设计稿
|
||||
|
||||
> 目标：基于 `leaudit-platform` 当前代码结构，给出交叉评查在新项目中的推荐实现方案，并明确数据模型、接口设计、目录落点、迁移顺序与实施边界。
|
||||
|
||||
## 1. 背景判断
|
||||
|
||||
结合当前仓库代码可以确认：
|
||||
|
||||
- 前端交叉评查页面已经存在于 `new_doc_review`
|
||||
- RBAC 路由中已经存在 `/cross-checking`
|
||||
- 新平台文档与评查底座已经切到 `leaudit_*`
|
||||
- 但交叉评查协作层仍未完整迁入 `fastapi_modules/fastapi_leaudit`
|
||||
|
||||
当前现状更接近：
|
||||
|
||||
- 页面壳子是新的
|
||||
- 文档与评查引擎底座是新的
|
||||
- 交叉评查业务逻辑仍然大量沿用老系统思维和老接口口径
|
||||
|
||||
因此，交叉评查在新项目中的核心任务，不是“新做一个页面”，而是把“协作复核层”从老系统迁到新平台。
|
||||
|
||||
## 2. 总体设计原则
|
||||
|
||||
推荐遵循以下原则：
|
||||
|
||||
### 2.1 交叉评查是协作层，不是评查引擎层
|
||||
|
||||
交叉评查不负责：
|
||||
|
||||
- OCR
|
||||
- 文本抽取
|
||||
- 规则执行
|
||||
- 原始机器评查结果生成
|
||||
|
||||
交叉评查只负责：
|
||||
|
||||
- 任务
|
||||
- 参与人
|
||||
- 文档挂载
|
||||
- 提案
|
||||
- 投票
|
||||
- 完成确认
|
||||
- 结果展示叠加
|
||||
|
||||
### 2.2 原始评查结果尽量不可变
|
||||
|
||||
不建议像老系统那样把通过提案直接回写到旧 `evaluation_results.final_score`。
|
||||
|
||||
新平台里更合理的方式是：
|
||||
|
||||
- `leaudit_rule_results` 保留机器评查真相
|
||||
- `leaudit_review_point_audits` 保留人工审核覆盖
|
||||
- `leaudit_cross_review_proposals` 保留交叉评查加减分提案
|
||||
- 页面展示时动态聚合出最终展示分数
|
||||
|
||||
### 2.3 交叉评查单独建模，不污染 LeAudit 核心表
|
||||
|
||||
推荐新增专属表：
|
||||
|
||||
- `leaudit_cross_review_tasks`
|
||||
- `leaudit_cross_review_task_members`
|
||||
- `leaudit_cross_review_task_documents`
|
||||
- `leaudit_cross_review_proposals`
|
||||
- `leaudit_cross_review_votes`
|
||||
|
||||
### 2.4 版本归纳使用新平台版本能力
|
||||
|
||||
不要继续使用老系统“同名 + 同类型推断版本”的方案作为主路径。
|
||||
|
||||
新平台已有：
|
||||
|
||||
- `leaudit_documents.versionGroupKey`
|
||||
- `leaudit_documents.versionNo`
|
||||
- `leaudit_documents.previousVersionId`
|
||||
- `leaudit_documents.rootVersionId`
|
||||
- `leaudit_documents.isLatestVersion`
|
||||
|
||||
交叉评查列表应优先基于这些字段实现版本归纳。
|
||||
|
||||
### 2.5 权限必须后端收口
|
||||
|
||||
前端可以决定是否显示按钮，但最终权限校验必须在后端 service 层完成。
|
||||
|
||||
不能继续依赖前端自己拼 PostgREST 查询判断权限。
|
||||
|
||||
## 3. 新项目里可直接复用的基础能力
|
||||
|
||||
## 3.1 文档主链路
|
||||
|
||||
现有能力：
|
||||
|
||||
- 上传文档：`fastapi_modules/fastapi_leaudit/controllers/documentController.py`
|
||||
- 文档服务：`fastapi_modules/fastapi_leaudit/services/impl/documentServiceImpl.py`
|
||||
- 文档主表：`fastapi_modules/fastapi_leaudit/models/leauditDocument.py`
|
||||
- 文档文件表：`fastapi_modules/fastapi_leaudit/models/leauditDocumentFile.py`
|
||||
|
||||
可复用点：
|
||||
|
||||
- 文档上传
|
||||
- OSS 存储
|
||||
- 文档版本管理
|
||||
- 附件追加
|
||||
- 文档详情读取
|
||||
|
||||
## 3.2 评查运行与结果主链路
|
||||
|
||||
现有能力：
|
||||
|
||||
- 评查运行主表：`fastapi_modules/fastapi_leaudit/models/leauditAuditRun.py`
|
||||
- 评查运行控制器：`fastapi_modules/fastapi_leaudit/controllers/auditController.py`
|
||||
- 评查详情聚合：`DocumentServiceImpl.GetReviewPoints()`
|
||||
|
||||
可复用点：
|
||||
|
||||
- 评查运行追踪
|
||||
- 详情页规则结果聚合
|
||||
- 人工审核结果叠加
|
||||
|
||||
## 3.3 详情页结果聚合
|
||||
|
||||
现有 VO：
|
||||
|
||||
- `fastapi_modules/fastapi_leaudit/domian/vo/reviewPointVo.py`
|
||||
|
||||
现有能力：
|
||||
|
||||
- `ReviewPointsAggregateVO`
|
||||
- `scoring_proposals`
|
||||
- `ReviewPointResultVO.finalScore`
|
||||
- `ReviewPointResultVO.machineScore`
|
||||
|
||||
这意味着：
|
||||
|
||||
- 详情页主结构已经可承载交叉评查提案数据
|
||||
- 只需把“提案来源”和“最终分数计算方式”替换为新模型
|
||||
|
||||
## 4. 目标架构
|
||||
|
||||
推荐架构分成两层：
|
||||
|
||||
### 4.1 LeAudit 评查结果层
|
||||
|
||||
职责：
|
||||
|
||||
- 文档上传
|
||||
- 规则执行
|
||||
- 机器评查结果生成
|
||||
- 人工审核覆盖记录
|
||||
|
||||
主要表：
|
||||
|
||||
- `leaudit_documents`
|
||||
- `leaudit_document_files`
|
||||
- `leaudit_audit_runs`
|
||||
- `leaudit_rule_results`
|
||||
- `leaudit_review_point_audits`
|
||||
|
||||
### 4.2 Cross Review 协作层
|
||||
|
||||
职责：
|
||||
|
||||
- 交叉评查任务
|
||||
- 成员管理
|
||||
- 任务文档挂载
|
||||
- 加减分提案
|
||||
- 投票
|
||||
- 文档完成确认
|
||||
- 协作态进度管理
|
||||
|
||||
主要表：
|
||||
|
||||
- `leaudit_cross_review_tasks`
|
||||
- `leaudit_cross_review_task_members`
|
||||
- `leaudit_cross_review_task_documents`
|
||||
- `leaudit_cross_review_proposals`
|
||||
- `leaudit_cross_review_votes`
|
||||
|
||||
## 5. 新数据模型设计
|
||||
|
||||
## 5.1 `leaudit_cross_review_tasks`
|
||||
|
||||
任务主表。
|
||||
|
||||
建议字段：
|
||||
|
||||
- `id`
|
||||
- `task_name`
|
||||
- `task_type`
|
||||
- `doc_type_id`
|
||||
- `doc_type_code`
|
||||
- `assigner_id`
|
||||
- `status`
|
||||
- `created_at`
|
||||
- `updated_at`
|
||||
- `deleted_at`
|
||||
|
||||
说明：
|
||||
|
||||
- `status` 建议值：`pending`、`in_progress`、`completed`
|
||||
- `doc_type_id` 可用于快速关联新平台文档类型
|
||||
- `doc_type_code` 用于兼容前端和历史口径
|
||||
|
||||
## 5.2 `leaudit_cross_review_task_members`
|
||||
|
||||
任务成员表。
|
||||
|
||||
建议字段：
|
||||
|
||||
- `id`
|
||||
- `task_id`
|
||||
- `user_id`
|
||||
- `member_role`
|
||||
- `created_at`
|
||||
- `updated_at`
|
||||
- `deleted_at`
|
||||
|
||||
说明：
|
||||
|
||||
- `member_role` 建议值：`participant`、`principal`
|
||||
- 任务创建者不建议仅放数组，应显式保存在任务主表 `assigner_id`
|
||||
|
||||
## 5.3 `leaudit_cross_review_task_documents`
|
||||
|
||||
任务文档表。
|
||||
|
||||
建议字段：
|
||||
|
||||
- `id`
|
||||
- `task_id`
|
||||
- `document_id`
|
||||
- `audit_status`
|
||||
- `created_at`
|
||||
- `updated_at`
|
||||
- `deleted_at`
|
||||
|
||||
说明：
|
||||
|
||||
- `audit_status=0` 表示未完成
|
||||
- `audit_status=1` 表示已确认完成
|
||||
- 这是任务内状态，不是文档全局状态
|
||||
|
||||
## 5.4 `leaudit_cross_review_proposals`
|
||||
|
||||
提案表。
|
||||
|
||||
建议字段：
|
||||
|
||||
- `id`
|
||||
- `task_id`
|
||||
- `document_id`
|
||||
- `rule_result_id`
|
||||
- `proposer_id`
|
||||
- `proposed_score_delta`
|
||||
- `reason`
|
||||
- `status`
|
||||
- `created_at`
|
||||
- `updated_at`
|
||||
- `deleted_at`
|
||||
|
||||
说明：
|
||||
|
||||
- `rule_result_id` 应关联 `leaudit_rule_results.id`
|
||||
- `proposed_score_delta` 使用增量值，正数加分，负数扣分
|
||||
- `status` 建议值：`pending`、`approved`、`rejected`、`cancelled`
|
||||
|
||||
## 5.5 `leaudit_cross_review_votes`
|
||||
|
||||
投票表。
|
||||
|
||||
建议字段：
|
||||
|
||||
- `id`
|
||||
- `proposal_id`
|
||||
- `voter_id`
|
||||
- `vote_type`
|
||||
- `created_at`
|
||||
- `updated_at`
|
||||
- `deleted_at`
|
||||
|
||||
说明：
|
||||
|
||||
- `vote_type` 建议值：`agree`、`disagree`
|
||||
- `cancel` 建议用软删除表示，不必单独存为最终值
|
||||
|
||||
## 6. 关键业务规则如何映射到新平台
|
||||
|
||||
## 6.1 创建任务
|
||||
|
||||
目标保留的老规则：
|
||||
|
||||
- 创建者强制加入任务成员
|
||||
- 可指定普通参与人和主要负责人
|
||||
- 任务创建时可同时挂一批文档
|
||||
|
||||
新实现建议：
|
||||
|
||||
- 创建任务时先写 `leaudit_cross_review_tasks`
|
||||
- 再写 `leaudit_cross_review_task_members`
|
||||
- 再写 `leaudit_cross_review_task_documents`
|
||||
|
||||
## 6.2 文档访问校验
|
||||
|
||||
目标保留的老规则：
|
||||
|
||||
- 只有任务成员才能看任务文档
|
||||
- 提案必须绑定任务内文档
|
||||
|
||||
新实现建议：
|
||||
|
||||
- 不再让前端自己查 `cross_task_document_mapping`
|
||||
- 提供统一后端方法：
|
||||
- `CheckTaskMember(taskId, userId)`
|
||||
- `CheckTaskDocument(taskId, documentId)`
|
||||
- `CheckTaskDocumentRuleResult(documentId, ruleResultId)`
|
||||
|
||||
## 6.3 提案创建
|
||||
|
||||
目标保留的老规则：
|
||||
|
||||
- 必须是任务参与者
|
||||
- 同一用户不能对同一评查点重复创建有效提案
|
||||
- 不允许 0 分提案
|
||||
- 当前分数为 0 时不能继续扣
|
||||
- 当前已满分时不能继续加
|
||||
|
||||
新实现建议：
|
||||
|
||||
- 通过 `rule_result_id` 读取对应规则结果
|
||||
- 计算当前展示分数
|
||||
- 校验是否还能继续加减
|
||||
- 写入 `leaudit_cross_review_proposals`
|
||||
- 自动插入一条提案人同意票
|
||||
|
||||
## 6.4 投票与状态流转
|
||||
|
||||
目标保留的老规则：
|
||||
|
||||
- 采用绝对多数制
|
||||
- 阈值为 `floor(n / 2) + 1`
|
||||
|
||||
新实现建议：
|
||||
|
||||
- `n` 基于 `leaudit_cross_review_task_members` 统计活跃成员
|
||||
- 同意达到阈值 -> `approved`
|
||||
- 反对达到阈值 -> `rejected`
|
||||
- 剩余票全部同意也无法通过 -> `rejected`
|
||||
|
||||
## 6.5 文档完成确认
|
||||
|
||||
目标保留的老规则：
|
||||
|
||||
- 只有创建者或负责人可确认
|
||||
- 文档完成改的是任务内状态
|
||||
- 全部文档完成后任务才完成
|
||||
|
||||
新实现建议：
|
||||
|
||||
- 确认文档完成时更新 `leaudit_cross_review_task_documents.audit_status`
|
||||
- 若同任务下所有未删除文档都为完成，则更新 `leaudit_cross_review_tasks.status = completed`
|
||||
|
||||
## 6.6 分数计算
|
||||
|
||||
这是新实现里最重要的变化。
|
||||
|
||||
### 不建议
|
||||
|
||||
- 直接更新 `leaudit_rule_results.score`
|
||||
- 直接写回机器结果源字段
|
||||
|
||||
### 建议
|
||||
|
||||
按聚合方式计算展示分数：
|
||||
|
||||
- `machineScore`：来自 `leaudit_rule_results`
|
||||
- `auditOverride`：来自 `leaudit_review_point_audits`
|
||||
- `crossReviewDelta`：来自所有已通过的 `leaudit_cross_review_proposals`
|
||||
- `finalScore`：在详情页聚合阶段动态计算
|
||||
|
||||
建议公式：
|
||||
|
||||
1. 先根据机器结果与人工审核确定基础结果
|
||||
2. 基础结果换算出基础得分
|
||||
3. 加上 `approved` 提案累计增量
|
||||
4. 最终再做上下限裁剪：
|
||||
- 不低于 0
|
||||
- 不高于规则满分
|
||||
|
||||
## 7. 详情页如何接入新实现
|
||||
|
||||
当前详情页主入口已经存在：
|
||||
|
||||
- `fastapi_modules/fastapi_leaudit/controllers/documentController.py`
|
||||
- `GET /v3/review-points/{DocumentId}`
|
||||
|
||||
建议做法：
|
||||
|
||||
### 7.1 保留 `GetReviewPoints()` 作为主入口
|
||||
|
||||
这样前端详情页无需大改。
|
||||
|
||||
### 7.2 修改 `_loadScoringProposals()`
|
||||
|
||||
当前只是兼容读取旧 `cross_scoring_proposals`。
|
||||
|
||||
建议改为：
|
||||
|
||||
- 优先读取 `leaudit_cross_review_proposals`
|
||||
- 若尚未迁移完成，可保留旧表兼容兜底一段时间
|
||||
|
||||
### 7.3 修改评查点聚合逻辑
|
||||
|
||||
在 `_loadReviewPointResults()` 或其上层聚合逻辑中：
|
||||
|
||||
- 读取单点所有已批准提案的分值增量
|
||||
- 计算 `finalScore`
|
||||
- 继续把提案列表放入 `scoring_proposals`
|
||||
|
||||
### 7.4 前端详情页不用重构为新的页面协议
|
||||
|
||||
保持 `ReviewPointsAggregateVO` 不变或小幅扩展即可。
|
||||
|
||||
## 8. 任务列表和任务文档列表如何实现
|
||||
|
||||
## 8.1 任务列表
|
||||
|
||||
返回建议字段：
|
||||
|
||||
- `task_id`
|
||||
- `task_name`
|
||||
- `task_status`
|
||||
- `doc_type`
|
||||
- `task_type`
|
||||
- `task_created_at`
|
||||
- `progress`
|
||||
- `total_documents`
|
||||
- `evaluation_region`
|
||||
|
||||
实现来源：
|
||||
|
||||
- 任务主表
|
||||
- 成员表
|
||||
- 任务文档表
|
||||
|
||||
## 8.2 任务文档列表
|
||||
|
||||
建议按以下逻辑组织：
|
||||
|
||||
1. 先取任务绑定文档
|
||||
2. 通过 `leaudit_documents.versionGroupKey` 做版本归组
|
||||
3. 当前版本优先取 `isLatestVersion = true`
|
||||
4. 统计信息来自 `leaudit_rule_results`
|
||||
5. 最终展示分数叠加 `approved` 提案增量
|
||||
|
||||
## 8.3 不建议继续使用旧版“同名同类型猜版本”
|
||||
|
||||
因为新平台已经有更稳定的版本链字段，不必再依赖脆弱的文件名规则。
|
||||
|
||||
## 9. 上传与追加附件的实现建议
|
||||
|
||||
## 9.1 推荐长期方案
|
||||
|
||||
采用“文档系统”和“交叉评查系统”解耦：
|
||||
|
||||
1. 先用通用文档接口上传
|
||||
2. 拿到 `documentId`
|
||||
3. 再把文档挂入交叉任务
|
||||
|
||||
优点：
|
||||
|
||||
- 复用现有 `DocumentServiceImpl.Upload`
|
||||
- 文档生命周期统一
|
||||
- 附件处理逻辑不重复
|
||||
|
||||
## 9.2 推荐短期兼容方案
|
||||
|
||||
为兼容当前前端，可先提供聚合接口：
|
||||
|
||||
- `UploadAndCreateTask`
|
||||
- `UploadDocumentsToTask`
|
||||
- `AppendTaskDocumentAttachments`
|
||||
|
||||
这些接口内部再调用：
|
||||
|
||||
- `DocumentService.Upload`
|
||||
- `DocumentService.AppendAttachments`
|
||||
|
||||
这样前端先不需要大改。
|
||||
|
||||
## 10. 权限设计
|
||||
|
||||
建议保留现有 RBAC 权限点：
|
||||
|
||||
- `cross_review:task:read`
|
||||
- `cross_review:task:create`
|
||||
- `cross_review:progress:view`
|
||||
- `cross_review:proposal:create`
|
||||
- `cross_review:proposal:read`
|
||||
- `cross_review:proposal:delete`
|
||||
- `cross_review:proposal:vote`
|
||||
- `cross_review:document:complete`
|
||||
|
||||
同时叠加业务层权限判断：
|
||||
|
||||
- 是否任务成员
|
||||
- 是否创建者
|
||||
- 是否主要负责人
|
||||
- 文档是否属于任务
|
||||
- 评查点结果是否属于该文档
|
||||
|
||||
## 11. 推荐实施顺序
|
||||
|
||||
### 第一阶段：先建协作层表和后端接口
|
||||
|
||||
目标：
|
||||
|
||||
- 新建 `leaudit_cross_review_*` 表
|
||||
- 新建 `CrossReviewController / Service / DTO / VO`
|
||||
- 打通任务、提案、投票、完成确认
|
||||
|
||||
### 第二阶段：详情页切新提案逻辑
|
||||
|
||||
目标：
|
||||
|
||||
- `GetReviewPoints()` 改读新提案表
|
||||
- 动态计算最终分数
|
||||
- 详情页不再依赖旧 `cross_scoring_proposals`
|
||||
|
||||
### 第三阶段：任务文档列表切新版本底座
|
||||
|
||||
目标：
|
||||
|
||||
- 改用 `leaudit_documents` 版本字段归组
|
||||
- 任务内分数与统计改读新平台结果
|
||||
|
||||
### 第四阶段：前端路径和历史兼容收口
|
||||
|
||||
目标：
|
||||
|
||||
- 逐步下线 `/admin/v2/cross_review/*` 历史兼容口径
|
||||
- 清理前端直查旧表逻辑
|
||||
- 清理旧 `cross_*` 兼容读取
|
||||
|
||||
## 12. 风险与注意事项
|
||||
|
||||
### 12.1 最大风险：最终分数语义变化
|
||||
|
||||
如果继续沿用老系统“直接回写”的做法，会污染新平台结果底座。
|
||||
|
||||
建议统一改为聚合展示分数。
|
||||
|
||||
### 12.2 第二风险：前端隐式依赖旧接口字段
|
||||
|
||||
当前 `new_doc_review/app/api/cross-checking/*` 里仍存在很多历史字段名和旧路径假设。
|
||||
|
||||
新后端第一期最好兼容这些字段，避免前端同步改动过大。
|
||||
|
||||
### 12.3 第三风险：权限校验分散
|
||||
|
||||
当前部分前端仍尝试自行查表判断权限。
|
||||
|
||||
迁移时应尽快把权限判断收敛到后端。
|
||||
|
||||
Reference in New Issue
Block a user