leaudit-platform-backend/docs/交叉评查/新项目交叉评查实现方案设计稿.md

新项目交叉评查实现方案设计稿

目标：基于 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 第三风险：权限校验分散

当前部分前端仍尝试自行查表判断权限。

迁移时应尽快把权限判断收敛到后端。