ccdi/docs/design/2026-03-24-project-list-reanalyze-design.md

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

背景

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

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

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

• 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 封装、列表按钮接线、单元测试与回归验证