# 新项目交叉评查详细业务逻辑定稿 > 目标：把新项目交叉评查的业务逻辑收敛成一份“可直接指导实现”的定稿，重点避免实现阶段把任务状态、评分语义、权限边界、版本逻辑和完成条件做错。 ## 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_*` 承接协作层 - 用聚合计算得到最终展示分 - 用任务内状态管理完成进度 - 用后端统一收口权限和状态流转 只要这五点不偏，整体实现就不会跑歪。