leaudit-platform-backend/docs/交叉评查/新项目交叉评查详细业务逻辑定稿.md

新项目交叉评查详细业务逻辑定稿

目标：把新项目交叉评查的业务逻辑收敛成一份“可直接指导实现”的定稿，重点避免实现阶段把任务状态、评分语义、权限边界、版本逻辑和完成条件做错。

1. 定位

交叉评查在新项目中必须被视为：

• 一层独立的“协作复核业务”
• 建立在 leaudit 已有文档、评查运行、规则结果之上
• 不负责重新生成底层规则结果
• 只负责任务协作、提案、投票、完成确认和展示分数叠加

因此，交叉评查不是评查引擎的一部分，而是评查结果之上的二次协作层。

2. 核心业务对象

新项目中交叉评查至少包含五类核心对象：

2.1 任务

任务是交叉评查的协作容器，负责绑定：

• 一组参与人
• 一组主要负责人
• 一批文档
• 一个文档类型语义
• 一个任务状态

任务是交叉评查权限判断的顶层边界。

2.2 任务成员

任务成员分为两类：

• participant：普通参与人
• principal：主要负责人

另有一个特殊角色：

• assigner：任务创建者

实现上建议：

• assigner 保存在任务主表
• participant/principal 保存在成员表

2.3 任务文档

任务文档表示：

• 哪些文档进入了交叉评查任务
• 每个文档在该任务内的完成状态

注意：

• 任务文档状态是“任务内状态”
• 不等于文档全局状态
• 不等于底层评查运行状态

2.4 提案

提案表示：

• 某个参与人针对某个“规则结果”提出的分数调整建议

提案的本质是：

• 绑定到具体 rule_result
• 以“增量分值”表达加分或扣分

2.5 投票

投票表示：

• 任务成员对某条提案的同意或反对

投票只作用于提案状态流转，不直接改文档状态。

3. 不可搞错的几个真相源

实现阶段最容易尴尬的就是“到底哪张表是真相源”。

这里必须定死：

3.1 文档真相源

• leaudit_documents

3.2 文档文件与版本真相源

• leaudit_document_files
• leaudit_documents.versionGroupKey
• leaudit_documents.versionNo
• leaudit_documents.previousVersionId
• leaudit_documents.rootVersionId
• leaudit_documents.isLatestVersion

3.3 机器评查结果真相源

• leaudit_rule_results

3.4 人工审核覆盖真相源

• leaudit_review_point_audits

3.5 交叉评查协作真相源

• leaudit_cross_review_tasks
• leaudit_cross_review_task_members
• leaudit_cross_review_task_documents
• leaudit_cross_review_proposals
• leaudit_cross_review_votes

4. 明确禁止的实现方式

以下做法不要再用：

4.1 不要直接修改 leaudit_rule_results 原始分数

原因：

• 会污染机器评查原始结果
• 会让重新跑批、调试、审计对账变得混乱

4.2 不要把交叉评查完成状态写回文档全局状态

原因：

• 交叉评查完成只是任务内完成
• 同一文档可能同时出现在多个任务或多个业务视角下

4.3 不要靠前端自行拼表判断权限

原因：

• 字段口径容易漂移
• 任务成员、负责人和创建者语义容易搞混
• 前端无法作为权限真相源

4.4 不要再用“同名同类型猜版本”作为主逻辑

原因：

• 新平台已经有正式版本字段
• 同名同类型只能作为兼容或兜底

5. 任务业务逻辑定稿

5.1 创建任务

输入

• 文档 ID 列表
• 参与人 ID 列表
• 主要负责人 ID 列表
• 任务名称
• 任务类型
• 文档类型信息

必须规则

1. assigner_id 必须自动加入任务成员集合
2. 成员列表必须去重
3. 主要负责人必须同时是任务成员
4. 所有文档必须真实存在
5. 所有文档必须可被当前用户纳入交叉评查
6. 初始状态必须是 in_progress

输出

• 任务主记录
• 任务成员记录
• 任务文档记录

注意

• 创建任务不等于重新跑评查
• 默认不触发新的机器评查
• 如果文档上传接口内包含自动评查，是上传链路行为，不是任务创建行为

5.2 任务列表

任务列表只返回当前用户参与的任务。

当前用户可见任务的判定

用户满足以下任一条件即可见：

• 是 assigner
• 是成员表里的 participant
• 是成员表里的 principal

返回字段必须稳定

• task_id
• task_name
• task_status
• doc_type
• task_type
• task_created_at
• progress
• total_documents
• evaluation_region

进度定义

progress = 已完成任务文档数 / 任务文档总数 * 100

这里的“已完成”只看：

• leaudit_cross_review_task_documents.audit_status

不看：

• leaudit_documents.audit_status
• leaudit_audit_runs.status
• leaudit_rule_results

5.3 任务状态

任务状态建议保留三态：

• pending
• in_progress
• completed

但如果当前产品没有明确“待启动”态，实际上可以只使用：

• in_progress
• completed

状态流转规则

• 创建任务 -> in_progress
• 所有任务内文档完成 -> completed
• 只要还有未完成文档 -> 保持 in_progress

禁止的隐式流转

不要因为：

• 提案全部投完
• 文档所有规则点都看过
• 有人上传了附件

就自动把任务置完成。

任务完成只能由“所有任务内文档被确认完成”推导出来。

6. 任务文档业务逻辑定稿

6.1 文档进入任务

文档进入任务只有两种方式：

• 创建任务时挂入
• 向已有任务追加文档

文档进入任务后默认状态

• audit_status = 0

即：

• 新纳入任务的文档，默认都还未完成交叉评查

6.2 文档完成的真正含义

任务内文档“完成”表示：

• 负责人或创建者确认：该文档在这个任务内的交叉评查工作结束

它不表示：

• 文档机器评查已完成
• 所有人都看过
• 所有提案都被通过
• 文档在全局业务上彻底完结

6.3 谁可以确认文档完成

只有：

• 任务创建者 assigner
• 主要负责人 principal

普通 participant 不可确认完成。

6.4 确认完成前的业务建议

建议在后端允许确认前做提醒型校验，而不是强阻断：

• 文档下是否还有 pending 提案
• 是否存在未投票成员

推荐策略：

• 默认允许负责人确认完成
• 如果仍有 pending 提案，返回告警信息给前端二次确认

这样更贴近真实业务，不会因为个别滞后投票把流程卡死。

7. 提案业务逻辑定稿

7.1 提案的最小绑定单位

提案必须绑定到：

• 一个任务
• 一个文档
• 一个规则结果 rule_result_id

不要只绑定：

• 文档 + 评查点名称
• 文档 + 规则名

因为这些都不够稳定。

7.2 谁可以提案

只有该任务成员可以提案。

必须满足

1. 用户是任务成员
2. 文档属于该任务
3. rule_result_id 属于该文档
4. 当前提案目标不是已删除/无效结果

7.3 提案唯一性规则

建议规则：

• 同一用户对同一任务下同一文档的同一 rule_result_id
• 同时只能存在一条“有效提案”

有效提案指：

• pending
• approved
• rejected

如果需要允许历史重提，建议前提是：

• 原提案已 cancelled
• 或被软删

7.4 提案分值规则

必须禁止

• 0 分提案

必须校验

1. 当前分值已为 0 时，不允许继续扣分
2. 当前分值已达该规则满分时，不允许继续加分
3. 提案增量应用后，理论结果不能越界

边界是：

• 最低 0
• 最高该规则满分

7.5 提案创建后的自动动作

提案创建成功后：

1. 自动写入一条提案人 agree 投票
2. 立刻触发提案状态判定

8. 投票业务逻辑定稿

8.1 谁可以投票

只有该任务成员可以投票。

额外限制

• 非成员不能投
• 已删除提案不能投
• 已结束提案不能投

8.2 提案人能否投票

建议保留老逻辑：

• 提案创建后自动算提案人一票同意

这意味着：

• 提案人不需要再手动投一次
• 后续若要改票，只能通过显式撤销/重投逻辑支持

8.3 投票值

推荐只保留：

• agree
• disagree

“取消投票”不作为状态值保存，而是：

• 将该投票软删

8.4 一人一票

同一提案、同一成员：

• 同一时刻只能存在一条有效投票

如重复投票：

• 覆盖旧投票类型

9. 提案状态机定稿

提案状态建议固定为：

• pending
• approved
• rejected
• cancelled

9.1 创建后的初始状态

• pending

9.2 通过规则

设任务有效成员数为 n

通过阈值：

• threshold = floor(n / 2) + 1

若：

• agree >= threshold

则：

• proposal.status = approved

9.3 否决规则

若：

• disagree >= threshold

则：

• proposal.status = rejected

9.4 提前否决规则

若：

• 即使所有剩余未投票者都改投同意，agree 也达不到 threshold

则：

• proposal.status = rejected

9.5 撤销规则

只有提案人可撤销，且只允许撤销：

• pending

撤销后：

• status = cancelled
• 同时软删或停用关联投票

9.6 提案终态不可再操作

对于：

• approved
• rejected
• cancelled

不允许再继续投票或修改状态。

10. 分数语义定稿

这是实现中最容易“做着做着又回到老系统”的地方，必须说清楚。

10.1 三层分数

新项目详情页涉及三层分数：

机器分

来自：

• leaudit_rule_results

含义：

• 规则执行后机器给出的原始结果分值

人工审核分

来自：

• leaudit_review_point_audits

含义：

• 人工对规则结果的覆盖性判断

交叉评查调整分

来自：

• 所有已通过的 leaudit_cross_review_proposals

含义：

• 协作层加减分累计值

10.2 推荐最终展示分数计算

建议按以下顺序：

1. 先计算基础分 baseScore
2. 再叠加交叉评查增量 crossDelta
3. 再做边界裁剪

baseScore 计算建议

若存在人工审核覆盖：

• 按人工审核后的通过/不通过结果计算基础分

否则：

• 按机器结果计算基础分

crossDelta

取该 rule_result_id 下所有：

• status = approved
• deleted_at is null

提案的 proposed_score_delta 累加值

finalScore

finalScore = clamp(baseScore + crossDelta, 0, ruleMaxScore)

10.3 绝对禁止

不要：

• 直接更新 leaudit_rule_results.score
• 直接把聚合后的最终分落回机器结果表

11. 详情页聚合逻辑定稿

当前详情页主入口已经是：

• DocumentServiceImpl.GetReviewPoints()

这条主链路可以保留。

11.1 详情页返回内容应包含

• 规则点列表
• 单点机器分
• 单点人工审核覆盖结果
• 单点最终展示分
• 交叉评查提案列表
• 文档级统计信息

11.2 提案列表读取规则

提案列表优先从：

• leaudit_cross_review_proposals

读取。

如果需要历史兼容，可短期允许：

• 新表优先
• 旧 cross_scoring_proposals 兜底

但这必须是过渡方案，不是长期方案。

11.3 文档总分统计

文档总分建议由每个规则点的最终展示分累加得到。

即：

• 总分不是单独存储字段
• 而是聚合计算结果

12. 版本归纳逻辑定稿

12.1 主规则

任务文档列表必须优先基于：

• versionGroupKey

归组。

当前版本判定

优先使用：

• isLatestVersion = true

历史版本排序

按：

• versionNo desc

或时间倒序

12.2 兜底规则

只有在极端兼容场景下，才允许用：

• normalizedName + typeId

做辅助兜底。

12.3 追加附件后的语义

追加附件如果产生新文档，则该新文档：

• 应进入同一版本链
• 自动挂到当前任务
• 默认 audit_status = 0

原因：

• 新版本进入任务后，需要重新做交叉评查确认

13. 权限逻辑定稿

13.1 权限判断分两层

第一层：RBAC 权限点

例如：

• cross_review:task:read
• cross_review:task:create
• cross_review:proposal:create
• cross_review:proposal:vote
• cross_review:document:complete

第二层：业务归属校验

例如：

• 是否是该任务成员
• 是否是负责人
• 文档是否属于该任务
• 规则结果是否属于该文档

两层都通过，才允许操作。

13.2 读权限

用户可读某任务，当且仅当：

• 是 assigner
• 或是任务成员

13.3 写权限

创建提案

• 任务成员即可

投票

• 任务成员即可

撤销提案

• 仅提案人

确认文档完成

• 仅 assigner 或 principal

上传任务文档 / 追加附件

• 建议仅 assigner 或 principal

14. 实施时的接口行为定稿

14.1 后端必须兜住这些错误

• 文档不存在
• 文档不属于任务
• 规则结果不属于文档
• 用户不是任务成员
• 用户不是负责人
• 提案重复
• 提案已结束
• 分值越界

14.2 后端返回建议

每个关键接口尽量返回：

• success
• message
• 必要结果对象
• 必要告警信息

例如确认完成时可以带：

• has_pending_proposals
• pending_proposal_count
• has_pending_votes

15. 推荐开发顺序

为了避免做到一半逻辑漂移，建议严格按以下顺序：

第一步

先落表结构和状态定义。

第二步

实现 service 层纯业务逻辑：

• 任务
• 提案
• 投票
• 完成确认

第三步

实现 controller 接口。

第四步

把详情页聚合接到新提案表。

第五步

再做上传、附件、版本链整合。

16. 最终一句话定稿

新项目交叉评查的正确实现方式应该是：

• 用 leaudit_* 作为文档与评查结果底座
• 用 leaudit_cross_review_* 承接协作层
• 用聚合计算得到最终展示分
• 用任务内状态管理完成进度
• 用后端统一收口权限和状态流转

只要这五点不偏，整体实现就不会跑歪。