leaudit-platform-backend/docs/交叉评查/新项目交叉评查状态流转图与边界案例清单.md

# 新项目交叉评查状态流转图与边界案例清单

> 目标：把新项目交叉评查的状态流转、时序过程和高风险边界案例一次性说清，避免实现时出现“以为如此，实际上不是”的尴尬。

## 1. 为什么需要这份文档

交叉评查最容易出错的地方，不是 CRUD，而是：

- 状态什么时候变
- 谁能触发状态变更
- 分数什么时候生效
- 文档什么时候算完成
- 任务什么时候算完成
- 新版本文档进来后旧版本怎么处理

这些地方一旦实现错了，前端看起来也许还能跑，但业务上会很尴尬。

所以这份文档专门回答三类问题：

- 状态怎么流转
- 链路怎么串起来
- 边界情况怎么处理

## 2. 五类核心状态

建议在实现时，把状态拆成五套，不要混用。

### 2.1 文档处理状态

来源：

- `leaudit_documents.processing_status`
- `leaudit_audit_runs.status`

这套状态表示：

- 文档是否完成机器评查

它不表示：

- 是否完成交叉评查

### 2.2 任务状态

来源：

- `leaudit_cross_review_tasks.status`

建议值：

- `pending`
- `in_progress`
- `completed`

这套状态表示：

- 任务层面的协作进度

### 2.3 任务文档状态

来源：

- `leaudit_cross_review_task_documents.audit_status`

建议值：

- `0`：未完成
- `1`：已完成

这套状态表示：

- 某个文档在某个任务里是否被负责人确认完成

### 2.4 提案状态

来源：

- `leaudit_cross_review_proposals.status`

建议值：

- `pending`
- `approved`
- `rejected`
- `cancelled`

### 2.5 投票状态

来源：

- `leaudit_cross_review_votes.vote_type`

建议值：

- `agree`
- `disagree`

取消投票建议通过软删除表达，不额外引入 `cancel` 作为终态值。

## 3. 任务状态流转图

```text
创建任务
  |
  v
in_progress
  |
  | 所有任务文档 audit_status = 1
  v
completed
```

### 3.1 任务创建后状态

- 默认直接进入 `in_progress`

### 3.2 任务完成条件

只有当：

- 该任务下所有未删除任务文档都为 `audit_status = 1`

才允许变为：

- `completed`

### 3.3 明确不是任务完成条件的事件

以下事件都不能直接导致任务完成：

- 文档机器评查跑完
- 所有提案都投票结束
- 没有提案
- 所有人都看过详情页
- 追加了新附件

## 4. 任务文档状态流转图

```text
文档被挂入任务
  |
  v
audit_status = 0
  |
  | assigner 或 principal 确认完成
  v
audit_status = 1
```

### 4.1 进入任务默认状态

- 新挂入任务的文档默认 `audit_status = 0`

### 4.2 谁能把 `0` 改成 `1`

只有：

- `assigner`
- `principal`

普通参与人不允许确认完成。

### 4.3 新版本文档进入任务后的状态

如果文档追加附件或上传了新版本：

- 新文档进入任务后必须重新记为 `audit_status = 0`

原因：

- 新版本代表新的评查对象
- 不能继承旧版本的“已完成”

## 5. 提案状态流转图

```text
创建提案
  |
  v
pending
  | \
  |  \
  |   \ 提案人主动撤销
  |    \
  |     v
  |   cancelled
  |
  | agree 票达到阈值
  v
approved

pending
  |
  | disagree 票达到阈值
  | 或剩余票全部同意也无法通过
  v
rejected
```

### 5.1 初始状态

- 提案创建后默认 `pending`

### 5.2 通过条件

若：

- `agree >= floor(n / 2) + 1`

则：

- `approved`

其中 `n` 为任务有效成员总数。

### 5.3 否决条件

若：

- `disagree >= floor(n / 2) + 1`

则：

- `rejected`

### 5.4 提前否决条件

若：

- 即使所有剩余未投票成员都改投同意，提案也不可能过阈值

则：

- 直接 `rejected`

### 5.5 撤销条件

只有提案人可以撤销，且必须满足：

- 当前状态仍为 `pending`

撤销后：

- 提案变为 `cancelled`

### 5.6 终态不可再操作

提案一旦进入：

- `approved`
- `rejected`
- `cancelled`

即视为终态：

- 不允许再投票
- 不允许再撤销
- 不允许再改状态

## 6. 投票时序图

```text
参与人 -> CrossReviewController: POST /proposals/{id}/votes
CrossReviewController -> CrossReviewService: VoteProposal()
CrossReviewService -> DB: 校验提案存在且状态= pending
CrossReviewService -> DB: 校验当前用户是任务成员
CrossReviewService -> DB: 写入或更新投票
CrossReviewService -> DB: 重新统计 agree/disagree/remaining
CrossReviewService -> DB: 如达阈值则更新 proposal.status
CrossReviewService --> CrossReviewController: 返回 proposal_status
CrossReviewController --> 参与人: success + 最新状态
```

### 6.1 投票后必须立即判定状态

不要把“投票成功”和“状态判定”拆成异步延迟任务。

推荐：

- 每次投票后同步判定提案状态

原因：

- 前端能立刻拿到最新状态
- 避免多人并发时出现短暂假状态

## 7. 提案创建时序图

```text
参与人 -> CrossReviewController: POST /proposals
CrossReviewController -> CrossReviewService: CreateProposal()
CrossReviewService -> DB: 校验任务/文档/规则结果关系
CrossReviewService -> DB: 校验用户是否为任务成员
CrossReviewService -> DB: 校验是否重复提案
CrossReviewService -> DB: 校验分值边界
CrossReviewService -> DB: 写入 proposal(status=pending)
CrossReviewService -> DB: 自动写入 proposer agree 投票
CrossReviewService -> DB: 判定 proposal 是否已直接过阈值
CrossReviewService --> CrossReviewController: proposal + latest_status
CrossReviewController --> 参与人: success
```

### 7.1 自动同意票后的特殊情况

如果任务成员数很少，例如：

- 只有 1 人

那么提案创建后可能因为自动同意票立即通过。

这是允许的，只要符合阈值规则。

## 8. 文档完成确认时序图

```text
负责人 -> CrossReviewController: POST /tasks/{taskId}/documents/{documentId}/complete
CrossReviewController -> CrossReviewService: CompleteTaskDocument()
CrossReviewService -> DB: 校验任务存在
CrossReviewService -> DB: 校验用户是 assigner 或 principal
CrossReviewService -> DB: 校验文档属于该任务
CrossReviewService -> DB: 更新 task_document.audit_status = 1
CrossReviewService -> DB: 统计任务下是否所有文档已完成
CrossReviewService -> DB: 若是，则更新 task.status = completed
CrossReviewService --> CrossReviewController: document completed / task completed
CrossReviewController --> 负责人: success
```

### 8.1 确认完成时是否强制要求“所有提案已投完”

不建议强阻断。

建议策略：

- 后端检测是否还有 `pending` 提案或未投票成员
- 返回提示信息
- 由前端给出二次确认

原因：

- 真实业务里负责人可能需要“带风险确认”
- 如果完全强阻断，会把流程卡死

## 9. 详情页分数计算时序图

```text
前端详情页 -> DocumentController: GET /v3/review-points/{documentId}
DocumentController -> DocumentServiceImpl: GetReviewPoints()
DocumentServiceImpl -> DB: 读取 leaudit_rule_results
DocumentServiceImpl -> DB: 读取 leaudit_review_point_audits
DocumentServiceImpl -> DB: 读取 approved proposals
DocumentServiceImpl: 计算 baseScore
DocumentServiceImpl: 计算 crossDelta
DocumentServiceImpl: 计算 finalScore = clamp(baseScore + crossDelta)
DocumentServiceImpl --> DocumentController: ReviewPointsAggregateVO
DocumentController --> 前端详情页: data + stats + scoring_proposals
```

### 9.1 分数生效时点

提案只有在：

- `approved`

后，才计入 `crossDelta`。

以下状态都不计入：

- `pending`
- `rejected`
- `cancelled`

## 10. 版本链时序图

```text
用户上传新版本/追加附件
  |
  v
DocumentService 创建新 leaudit_document
  |
  v
新文档进入原 versionGroupKey
  |
  v
CrossReviewService 将新 document_id 挂入任务
  |
  v
task_document.audit_status = 0
  |
  v
任务列表按 versionGroupKey 归组展示
```

### 10.1 旧版本是否自动失效

不建议把旧版本任务记录自动删掉。

建议：

- 保留历史版本
- 页面默认展示最新版本
- 历史版本折叠展示

### 10.2 新版本是否自动继承提案

不建议继承。

原因：

- 提案是针对具体 `rule_result_id`
- 新版本会产生新的 `rule_result_id`
- 旧提案不能自动迁移到新结果上

## 11. 边界案例清单

下面这些情况，后端必须提前定好策略。

## 11.1 只有 1 个任务成员

### 情况

- 创建者自己给自己建任务，且没有别的成员

### 正确处理

- 阈值 = 1
- 提案创建后自动同意票即可直接 `approved`

### 不要出错

- 不要硬编码“至少两人才能交叉评查”

## 11.2 只有 2 个任务成员

### 情况

- A 发起提案
- A 自动同意
- B 反对

### 正确处理

- 成员数 `n=2`
- 阈值 `floor(2/2)+1 = 2`
- A 同意数 1，不足通过
- B 反对数 1，也不足否决
- 但此时无剩余票，提案已不可能达到 2 票同意
- 应直接 `rejected`

### 不要出错

- 不要把它一直挂在 `pending`

## 11.3 提案人重复点击提交

### 情况

- 网络慢，用户多次点提交

### 正确处理

- 通过唯一性规则防重
- 返回“已存在有效提案”

### 不要出错

- 不要产生两条同时有效的同目标提案

## 11.4 文档已有新版本，但旧版本已完成

### 情况

- 旧版本在任务里已确认完成
- 新版本追加进来

### 正确处理

- 新版本独立新增一条 `task_document`
- `audit_status = 0`
- 旧版本保持历史完成状态

### 不要出错

- 不要把新版本直接继承旧版本的完成状态

## 11.5 提案通过后又有人想继续改

### 情况

- 某条提案已经 `approved`
- 又有人想针对同一个规则点继续提分或扣分

### 正确处理

- 允许新建后续提案，但必须满足唯一性规则
- 即同一用户不能重复，但不同用户可继续提出新的有效提案

### 不要出错

- 不要错误地把“某点已有 approved 提案”理解成“该点以后都不能再提案”

## 11.6 文档没有任何提案

### 情况

- 任务成员只看文档，不提出任何提案

### 正确处理

- 允许负责人直接确认完成

### 不要出错

- 不要把“没有提案”当成“不能完成”

## 11.7 存在 `pending` 提案，但负责人仍要完成

### 情况

- 业务上要强行收口

### 正确处理

- 推荐允许，但返回 warning 信息

### 不要出错

- 不要一刀切强阻断，除非产品明确要求

## 11.8 文档重跑评查后，旧提案怎么办

### 情况

- 同一个文档重新触发 audit run
- 产生新 `rule_result_id`

### 正确处理建议

- 提案绑定的是具体 `rule_result_id`
- 如果是同一 document 的新 run，建议只对“当前有效 run”的结果展示可新建提案
- 旧 run 上的提案保留历史，不再作为主展示对象

### 不要出错

- 不要把旧 run 的提案直接混到新 run 的点位上

## 11.9 删除任务成员后，历史票怎么办

### 情况

- 某成员中途被移出任务

### 正确处理建议

- 历史投票保留
- 后续阈值计算以当前有效成员还是任务创建时成员为准，必须提前定死

### 推荐口径

- 阈值按“当前有效成员数”计算

### 注意

- 这个规则一旦确定，就不能前后漂移

## 12. 推荐的最终业务口径

为了避免后续实现反复改口，建议最终统一采用以下口径：

- 任务默认 `in_progress`
- 文档进入任务默认未完成
- 文档完成只能由创建者或负责人确认
- 任务完成由“所有任务文档完成”推导
- 提案默认 `pending`
- 提案自动给提案人一票同意
- 提案采用绝对多数制
- 提案通过后只影响展示层最终分，不改机器原始结果
- 版本归纳优先使用 `versionGroupKey`
- 权限由后端统一判断

## 13. 开发前最后核对清单

开始写代码前，建议逐项确认：

- 是否已经把五类状态拆开
- 是否已经明确最终分不是回写机器结果
- 是否已经明确任务完成只看任务文档状态
- 是否已经明确新版本进任务后默认未完成
- 是否已经明确提案绑定到 `rule_result_id`
- 是否已经明确提案通过阈值算法
- 是否已经明确权限是 RBAC + 业务归属双校验
- 是否已经明确详情页主入口仍可复用 `GetReviewPoints()`

如果这几项都确认过，交叉评查的实现基本就不会跑偏。