# 项目管理列表重新分析设计文档

## 背景

项目管理列表中的“重新分析”按钮目前只在前端弹出提示：

- 未调用任何后端接口
- 不会触发项目重新打标
- 不会触发风险人数重新计算

与此同时，后端已经具备完整的项目级银行流水重打标链路：

- `POST /ccdi/project/tags/rebuild` 可提交项目级手动重打标任务
- `CcdiBankTagServiceImpl.rebuildProject(...)` 会将项目状态切换为 `3-打标中`
- 重打标完成后会调用 `refreshOverviewEmployeeResults(projectId, operator)`
- `refreshOverviewEmployeeResults(...)` 会同步重建员工结果并刷新项目高/中/低风险人数

因此，本次问题不在于缺少后端能力，而在于列表页“重新分析”没有接入现有后端链路。

## 目标

- 让项目管理列表中的“重新分析”按钮真正触发项目级重新打标。
- 复用现有后端异步重打标流程，不新增并行实现。
- 在提交成功后立即刷新列表，让用户看到项目进入“打标中”状态。
- 由后端现有流程在重打标完成后自动刷新风险人数口径。

## 范围

### In Scope

- 项目管理列表页“重新分析”按钮接入真实接口
- 新增前端 API 封装，调用现有 `/ccdi/project/tags/rebuild`
- 按钮提交态控制，防止重复点击
- 成功提示、失败提示与列表刷新
- 前端单元测试补充

### Out of Scope

- 不新增新的后端控制器或服务接口
- 不新增轮询、进度条、消息推送、WebSocket
- 不调整重打标规则、结果口径或人数计算逻辑
- 不变更“重新分析”按钮的显示状态范围

## 现状分析

### 前端现状

`ruoyi-ui/src/views/ccdiProject/index.vue` 中的 `handleReAnalyze(row)` 当前仅执行：

- `console.log("重新分析:", row)`
- `this.$modal.msgSuccess("正在重新分析项目: " + row.projectName)`

这意味着：

- 前端提示与实际业务状态不一致
- 列表不会刷新为“打标中”
- 风险人数也不会发生任何变化

### 后端现状

后端已有现成能力可直接复用：

1. `CcdiBankTagController.rebuild(...)`
   - 接收 `projectId` 和可选 `modelCode`
   - 当前支持项目维度全量重打标
2. `ProjectBankTagRebuildCoordinator.submitManual(...)`
   - 对同一项目做运行中校验，避免重复提交
3. `CcdiBankTagServiceImpl.rebuildProject(...)`
   - 将项目状态更新为 `3-打标中`
   - 清理旧标签结果并重新执行规则
   - 成功后调用 `refreshOverviewEmployeeResults(...)`
   - 最终将项目状态切换为 `1-已完成`
4. `CcdiProjectOverviewServiceImpl.refreshOverviewEmployeeResults(...)`
   - 删除并重建员工结果总览
   - 同步更新项目高风险、中风险、低风险人数

结论：

- “重新打标”和“重新计算人数”已经在同一条后端链路里闭环
- 前端只需正确提交项目级重打标请求并刷新列表

## 方案选择

本次采用“前端直接复用现有项目重打标接口”的方案。

### 推荐方案

列表页点击“重新分析”时：

1. 调用 `POST /ccdi/project/tags/rebuild`
2. 请求体只传 `projectId`
3. 不传 `modelCode`，表示按项目维度执行全量重打标
4. 成功后提示“已开始重新分析”
5. 立即刷新列表，让项目状态显示为“打标中”

### 不采用的方案

#### 方案一：新增“重新分析”专用后端接口

不采用原因：

- 与现有重打标接口能力重复
- 只是多包一层语义，不增加业务价值
- 会扩大后端改动面与测试面

#### 方案二：前端额外补调“人数刷新”接口

不采用原因：

- 重打标成功后已自动调用 `refreshOverviewEmployeeResults(...)`
- 再补调会造成重复刷新，甚至可能引入时序问题

## 详细设计

## 1. 前端 API 设计

在 `ruoyi-ui/src/api/ccdiProject.js` 中新增项目重分析接口封装。

请求设计：

- URL：`/ccdi/project/tags/rebuild`
- Method：`POST`
- Body：`{ projectId }`

说明：

- 本次不新增新的 API 文件
- 继续收口在现有 `ccdiProject.js`
- 与项目管理列表页调用场景保持就近维护

## 2. 列表页交互设计

`ruoyi-ui/src/views/ccdiProject/index.vue` 中的 `handleReAnalyze(row)` 改为真实提交逻辑。

执行顺序：

1. 判断当前项目是否正在提交“重新分析”
2. 调用项目重分析接口
3. 成功后提示“已开始重新分析”
4. 立即调用 `getList()` 刷新列表
5. 刷新后项目状态由后端返回的 `3-打标中` 驱动展示

本次不新增确认弹窗，保持最短路径实现。

## 3. 按钮提交态设计

为避免用户连续点击同一项目的“重新分析”按钮，需要增加按钮级提交态控制。

推荐方式：

- 在列表页维护一个按 `projectId` 标识的提交中状态
- 提交中的项目：
  - “重新分析”按钮显示加载态
  - 按钮不可再次点击

提交结束后：

- 无论成功还是失败，都清理该项目的提交态

这样可以避免：

- 同一用户连续点击导致重复请求
- 列表刷新前出现多次成功提示

## 4. 状态展示设计

“重新分析”按钮继续只在 `status === '1'` 时显示。

交互结果：

- 点击成功并刷新列表后，项目状态会切换为 `3-打标中`
- 由于操作列本来只在 `status === '1'` 时展示“重新分析”
- 刷新后按钮会自然消失，无需额外写隐藏逻辑

这保证了操作权限仍由现有状态判断驱动，不引入新的前端分支。

## 5. 异常处理设计

### 业务异常

对于后端明确返回的业务异常，前端直接展示后端消息，不自行改写文案。

典型场景包括：

- 当前项目标签正在重算中，请稍后再试
- 已归档项目不允许重新进入打标流程

这样可以保证页面提示与后端业务规则一致。

### 网络或未知异常

当请求失败但无明确业务文案时，前端统一提示：

- `重新分析失败，请稍后重试`

失败时不刷新列表，保持当前页面数据稳定。

## 6. 后端影响说明

本次不新增后端代码逻辑，直接复用现有链路：

- `CcdiBankTagController`
- `ProjectBankTagRebuildCoordinator`
- `CcdiBankTagServiceImpl`
- `CcdiProjectOverviewServiceImpl`

后端在本次需求中的职责已经满足：

- 手动提交流水重打标
- 校验项目是否允许进入打标
- 防止同一项目重复提交
- 重打标完成后自动刷新风险人数

因此后端实施计划将以“确认边界、补充验证说明”为主，不引入功能代码变更。

## 7. 测试设计

### 前端单元测试

至少补充以下验证：

1. 点击“重新分析”会调用真实接口，而不是只弹本地提示
2. 接口成功后会提示“已开始重新分析”
3. 接口成功后会刷新列表
4. 接口失败时展示失败提示，且不会误提示成功

### 回归验证

重点验证以下场景：

1. 已完成项目点击“重新分析”后，列表刷新为“打标中”
2. 重新进入列表或后续再次查询时，风险人数展示为重算后的结果
3. 当项目已有运行中的打标任务时，页面提示后端返回的业务异常
4. 已归档项目仍不出现“重新分析”入口

## 8. 风险与约束

- 本次列表页只做“提交并刷新”，不做结果完成态轮询，因此用户需要依赖后续刷新看到最终人数变化。
- 若后端重打标执行时间较长，用户在一次刷新后看到“打标中”属于预期行为。
- 该方案依赖现有后端重打标链路稳定可用，不单独补建旁路接口。

## 9. 文档产出要求

按仓库约定，设计确认后继续产出两份实施计划：

1. 后端实施计划：`docs/plans/backend/`
2. 前端实施计划：`docs/plans/frontend/`

其中：

- 后端实施计划明确本次以后端验证与边界说明为主
- 前端实施计划覆盖 API 封装、列表按钮接线、单元测试与回归验证