补充项目管理列表重新分析设计文档
This commit is contained in:
252
docs/design/2026-03-24-project-list-reanalyze-design.md
Normal file
252
docs/design/2026-03-24-project-list-reanalyze-design.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# 项目管理列表重新分析设计文档
|
||||
|
||||
## 背景
|
||||
|
||||
项目管理列表中的“重新分析”按钮目前只在前端弹出提示：
|
||||
|
||||
- 未调用任何后端接口
|
||||
- 不会触发项目重新打标
|
||||
- 不会触发风险人数重新计算
|
||||
|
||||
与此同时，后端已经具备完整的项目级银行流水重打标链路：
|
||||
|
||||
- `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 封装、列表按钮接线、单元测试与回归验证
|
||||
@@ -0,0 +1,20 @@
|
||||
# 2026-03-24 项目管理列表重新分析设计文档记录
|
||||
|
||||
## 本次产出
|
||||
|
||||
- 新增设计文档 `docs/design/2026-03-24-project-list-reanalyze-design.md`
|
||||
- 明确列表页“重新分析”复用现有项目级重打标接口，不新增后端并行实现
|
||||
|
||||
## 关键确认结论
|
||||
|
||||
- 列表页“重新分析”按钮只对已完成项目显示，范围不变
|
||||
- 点击后直接调用 `/ccdi/project/tags/rebuild`，只传 `projectId`
|
||||
- 提交成功后提示“已开始重新分析”并立即刷新列表
|
||||
- 风险人数重算复用后端现有 `refreshOverviewEmployeeResults(...)` 链路
|
||||
- 本次不新增轮询、进度条、消息推送
|
||||
|
||||
## 后续动作
|
||||
|
||||
- 待用户审阅设计文档后，继续输出前端与后端实施计划
|
||||
- 后端实施计划以边界确认和验证说明为主
|
||||
- 前端实施计划覆盖按钮接线、提交态控制、提示文案与单测补充
|
||||
Reference in New Issue
Block a user