补充项目列表重新分析前后端实施计划

2026-03-27 14:14:49 +08:00
parent d931ac185d
commit 2c793eaed6
2 changed files with 428 additions and 0 deletions
--- a/docs/plans/backend/2026-03-27-project-list-reanalyze-confirm-refresh-backend-implementation.md
+++ b/docs/plans/backend/2026-03-27-project-list-reanalyze-confirm-refresh-backend-implementation.md
@@ -0,0 +1,200 @@
+# Project List Reanalyze Confirm Refresh Backend Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 确认“项目列表重新分析增加确认弹窗并成功后刷新列表”这一需求无需后端源码改造，只复用现有项目标签重算与风险人数刷新链路，并留下验证与实施记录。
+
+**Architecture:** 本轮需求发生在前端页面交互层，后端只需要继续提供现有 `/ccdi/project/tags/rebuild` 提交能力，以及重算完成后的既有结果刷新链路。实施上不新增 controller、service、mapper 或 SQL，而是聚焦现有接口边界核对、关键单测回归和文档留痕，避免误把纯前端需求扩展成后端补丁工程。
+
+**Tech Stack:** Java 21, Spring Boot 3, JUnit 5, Maven, ripgrep, Markdown 文档
+
+---
+
+## 文件结构与职责
+
+**新增文件**
+
+- `docs/tests/records/2026-03-27-project-list-reanalyze-confirm-refresh-backend-verification.md`
+  记录本次后端边界核对、执行命令与回归结果。
+- `docs/reports/implementation/2026-03-27-project-list-reanalyze-confirm-refresh-backend-record.md`
+  沉淀“后端无需改造”的实施结论与影响范围。
+
+**核对文件**
+
+- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiBankTagController.java`
+  确认 `/ccdi/project/tags/rebuild` 入口继续复用。
+- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiBankTagServiceImpl.java`
+  确认手动重算后仍会触发结果刷新。
+- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/ProjectBankTagRebuildCoordinator.java`
+  确认同一项目重复提交保护仍由后端承接。
+- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/ICcdiProjectOverviewService.java`
+  确认风险人数刷新能力继续存在。
+
+**回归测试**
+
+- `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/ProjectBankTagRebuildCoordinatorTest.java`
+- `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiBankTagServiceRiskCountRefreshTest.java`
+
+**参考文件**
+
+- `docs/design/2026-03-27-project-list-reanalyze-confirm-refresh-design.md`
+- `ruoyi-ui/src/views/ccdiProject/index.vue`
+
+## Task 1: 核对后端边界仍完全满足本轮需求
+
+**Files:**
+- Review: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiBankTagController.java`
+- Review: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiBankTagServiceImpl.java`
+- Review: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/ProjectBankTagRebuildCoordinator.java`
+- Review: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/ICcdiProjectOverviewService.java`
+
+- [ ] **Step 1: 用检索命令确认关键链路位置**
+
+Run:
+
+```bash
+rg -n "tags/rebuild|submitManual|rebuildProject|refreshOverviewEmployeeResults|当前项目标签正在重算中" ccdi-project/src/main/java
+```
+
+Expected:
+
+- 能看到 controller 入口、手动提交协调器、项目重算主链路和风险人数刷新调用
+
+- [ ] **Step 2: 人工确认本轮不需要新增后端能力**
+
+核对结论需要覆盖：
+
+```text
+1. 重新分析的实际接口仍是 POST /ccdi/project/tags/rebuild
+2. 重复提交保护仍由后端协调器负责
+3. 重算完成后的风险人数刷新仍由现有服务链路负责
+4. 本轮只新增前端确认交互，不需要后端新增“确认”语义接口
+```
+
+- [ ] **Step 3: 若边界不满足则停止，不要补丁式扩后端**
+
+若发现异常：
+
+- 不要新增“重新分析确认”专用接口
+- 不要新增冗余的刷新人数接口
+- 先回到设计文档重新确认需求边界
+
+## Task 2: 运行关键回归，证明现有后端链路仍可复用
+
+**Files:**
+- Test: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/ProjectBankTagRebuildCoordinatorTest.java`
+- Test: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiBankTagServiceRiskCountRefreshTest.java`
+
+- [ ] **Step 1: 运行聚焦回归测试**
+
+Run:
+
+```bash
+mvn test -pl ccdi-project -Dtest=ProjectBankTagRebuildCoordinatorTest,CcdiBankTagServiceRiskCountRefreshTest
+```
+
+Expected:
+
+- `PASS`
+
+- [ ] **Step 2: 如果失败，先判断是否与本轮前端交互需求无关**
+
+处理原则：
+
+- 若失败与既有后端链路本身无关，先记录现象，不要顺手改后端
+- 若失败说明现有重算或刷新链路确有缺口，再回到设计阶段补后端方案
+
+- [ ] **Step 3: 确认本轮无需后端源码改动**
+
+Run:
+
+```bash
+git diff --name-only -- ccdi-project ruoyi-admin ruoyi-common ruoyi-framework ruoyi-system
+```
+
+Expected:
+
+- 无输出
+- 或仅出现经确认必须修正文档引用时涉及的文档文件，不应出现后端源码改动
+
+## Task 3: 补后端验证记录与实施记录
+
+**Files:**
+- Create: `docs/tests/records/2026-03-27-project-list-reanalyze-confirm-refresh-backend-verification.md`
+- Create: `docs/reports/implementation/2026-03-27-project-list-reanalyze-confirm-refresh-backend-record.md`
+
+- [ ] **Step 1: 新增后端验证记录**
+
+在 `docs/tests/records/2026-03-27-project-list-reanalyze-confirm-refresh-backend-verification.md` 记录：
+
+```markdown
+# 项目列表重新分析确认刷新后端验证记录
+
+## 检查目标
+- 确认项目标签重算接口与结果刷新链路已满足本轮需求
+
+## 执行命令
+- rg -n "tags/rebuild|submitManual|rebuildProject|refreshOverviewEmployeeResults|当前项目标签正在重算中" ccdi-project/src/main/java
+- mvn test -pl ccdi-project -Dtest=ProjectBankTagRebuildCoordinatorTest,CcdiBankTagServiceRiskCountRefreshTest
+
+## 验证结论
+- 后端现有链路可直接复用
+- 本轮无需新增接口、服务、SQL
+```
+
+- [ ] **Step 2: 新增后端实施记录**
+
+在 `docs/reports/implementation/2026-03-27-project-list-reanalyze-confirm-refresh-backend-record.md` 记录：
+
+```markdown
+# 项目列表重新分析确认刷新后端实施记录
+
+## 结论
+- 本次需求仅新增前端确认交互
+- 后端继续复用 /ccdi/project/tags/rebuild
+- 项目重算完成后的风险人数刷新链路保持不变
+- 后端源码与数据库均无需改动
+
+## 核查范围
+- CcdiBankTagController
+- ProjectBankTagRebuildCoordinator
+- CcdiBankTagServiceImpl
+- ICcdiProjectOverviewService
+
+## 验证
+- rg 检索关键链路
+- Maven 聚焦回归测试
+```
+
+- [ ] **Step 3: 暂存前确认仅新增记录文档**
+
+Run:
+
+```bash
+git status --short
+```
+
+Expected:
+
+- 仅出现本任务新增的后端验证记录和实施记录
+- 若发现无关文件已暂存，先移出暂存区
+
+- [ ] **Step 4: 提交后端记录文档**
+
+Run:
+
+```bash
+git add docs/tests/records/2026-03-27-project-list-reanalyze-confirm-refresh-backend-verification.md docs/reports/implementation/2026-03-27-project-list-reanalyze-confirm-refresh-backend-record.md
+git commit -m "补充项目列表重新分析后端验证记录"
+```
+
+Expected:
+
+- 提交成功，且不包含无关源码文件
+
+## Done When
+
+- 已确认 `/ccdi/project/tags/rebuild` 与现有风险人数刷新链路足以支撑本轮需求
+- 已通过聚焦回归测试证明无需补后端旁路能力
+- 后端源码、SQL、数据库均未因本轮前端交互需求发生改动
+- 已补齐后端验证记录和实施记录
--- a/docs/plans/frontend/2026-03-27-project-list-reanalyze-confirm-refresh-frontend-implementation.md
+++ b/docs/plans/frontend/2026-03-27-project-list-reanalyze-confirm-refresh-frontend-implementation.md
@@ -0,0 +1,228 @@
+# Project List Reanalyze Confirm Refresh Frontend Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 为项目列表中的“重新分析”按钮补充确认弹窗，并在确认后沿用现有接口调用、成功提示和列表刷新链路。
+
+**Architecture:** 本次仅调整 `ruoyi-ui/src/views/ccdiProject/index.vue` 的页面级交互，不下沉确认逻辑到 `ProjectTable.vue`，保持表格组件继续只负责事件透传。实现上先用源码契约测试锁定“先确认、后请求、取消不提交、成功后刷新”的行为，再做最小代码改动，并补实施记录。仓库约定不启用 subagent，执行时直接使用 `superpowers:executing-plans`，且前端直接在当前分支开发。
+
+**Tech Stack:** Vue 2, Element UI, RuoYi `this.$modal`, Node.js 源码契约测试, Markdown 文档
+
+---
+
+## 文件结构与职责
+
+**修改文件**
+
+- `ruoyi-ui/src/views/ccdiProject/index.vue`
+  在现有 `handleReAnalyze(row)` 中补确认弹窗，并确保 loading 只在确认后进入，取消确认时直接返回。
+- `ruoyi-ui/tests/unit/project-list-reanalyze-flow.test.js`
+  追加确认弹窗、取消分支和“确认后再 loading”的源码契约断言。
+
+**新增文件**
+
+- `docs/reports/implementation/2026-03-27-project-list-reanalyze-confirm-refresh-frontend-record.md`
+  记录本次前端实施内容、验证命令与结果。
+
+**参考文件**
+
+- `docs/design/2026-03-27-project-list-reanalyze-confirm-refresh-design.md`
+- `ruoyi-ui/src/plugins/modal.js`
+- `ruoyi-ui/src/views/ccdiProject/components/ProjectTable.vue`
+- `ruoyi-ui/tests/unit/project-list-reanalyze-api.test.js`
+
+## Task 1: 先锁定“先确认、后提交”的交互契约
+
+**Files:**
+- Modify: `ruoyi-ui/tests/unit/project-list-reanalyze-flow.test.js`
+- Test: `ruoyi-ui/src/views/ccdiProject/index.vue`
+- Review: `ruoyi-ui/src/plugins/modal.js`
+
+- [ ] **Step 1: 在现有流程测试中补目标断言**
+
+在 `ruoyi-ui/tests/unit/project-list-reanalyze-flow.test.js` 中保留现有接口调用、成功提示和刷新断言，再新增以下确认弹窗契约：
+
+```javascript
+assert(
+  pageSource.includes("await this.$modal.confirm("),
+  "重新分析前应先弹出确认框"
+);
+
+assert(
+  pageSource.includes("确认对项目“${row.projectName}”重新分析吗？重新分析将重新计算项目标签。"),
+  "确认弹窗文案应覆盖项目名称和重新计算标签提醒"
+);
+
+assert(
+  pageSource.includes('confirmError === "cancel"') ||
+    pageSource.includes("confirmError === 'cancel'"),
+  "取消确认时应直接结束，不继续提交"
+);
+
+assert(
+  /await this\.\$modal\.confirm\([\s\S]*?this\.\$set\(this\.reAnalyzeLoadingMap,\s*projectKey,\s*true\)/.test(pageSource),
+  "只有确认后才允许进入按钮 loading"
+);
+```
+
+- [ ] **Step 2: 运行测试，确认新契约先失败**
+
+Run:
+
+```bash
+node ruoyi-ui/tests/unit/project-list-reanalyze-flow.test.js
+```
+
+Expected:
+
+- `FAIL`，因为当前代码还没有确认弹窗与取消分支。
+
+## Task 2: 以最小改动补确认弹窗并保留现有刷新链路
+
+**Files:**
+- Modify: `ruoyi-ui/src/views/ccdiProject/index.vue`
+- Test: `ruoyi-ui/tests/unit/project-list-reanalyze-flow.test.js`
+- Test: `ruoyi-ui/tests/unit/project-list-reanalyze-api.test.js`
+
+- [ ] **Step 1: 在请求前加入确认弹窗**
+
+在 `handleReAnalyze(row)` 的重复提交判断后、loading 设置前加入确认逻辑，推荐使用现有全局弹窗能力：
+
+```javascript
+try {
+  await this.$modal.confirm(
+    `确认对项目“${row.projectName}”重新分析吗？重新分析将重新计算项目标签。`
+  )
+} catch (confirmError) {
+  if (confirmError === "cancel" || confirmError === "close") {
+    return
+  }
+  throw confirmError
+}
+```
+
+- [ ] **Step 2: 保证 loading 只在确认后进入**
+
+保持现有 `reAnalyzeLoadingMap` 结构不变，但将：
+
+```javascript
+this.$set(this.reAnalyzeLoadingMap, projectKey, true)
+```
+
+放在确认通过之后，避免点击“取消”时按钮闪动为提交态。
+
+- [ ] **Step 3: 保留现有真实接口、成功提示和列表刷新**
+
+确认后仍然沿用当前实现：
+
+```javascript
+await rebuildProjectTags({ projectId: row.projectId })
+this.$modal.msgSuccess("已开始重新分析")
+this.getList()
+```
+
+失败分支继续保留：
+
+```javascript
+const message = error && error.message ? error.message : "重新分析失败，请稍后重试"
+this.$modal.msgError(message)
+```
+
+- [ ] **Step 4: 运行前端契约测试确认通过**
+
+Run:
+
+```bash
+node ruoyi-ui/tests/unit/project-list-reanalyze-flow.test.js
+node ruoyi-ui/tests/unit/project-list-reanalyze-api.test.js
+```
+
+Expected:
+
+- 两个测试均 `PASS`
+
+- [ ] **Step 5: 手工检视关键实现没有偏离最短路径**
+
+Run:
+
+```bash
+rg -n "handleReAnalyze|\\$modal.confirm|rebuildProjectTags|msgSuccess|getList\\(" ruoyi-ui/src/views/ccdiProject/index.vue
+```
+
+Expected:
+
+- 能清晰看到“先 confirm、后请求、成功后刷新”的单链路实现
+- 不应新增额外 helper、轮询、局部数据补丁更新
+
+- [ ] **Step 6: 提交前端功能改动**
+
+Run:
+
+```bash
+git add ruoyi-ui/src/views/ccdiProject/index.vue ruoyi-ui/tests/unit/project-list-reanalyze-flow.test.js
+git commit -m "补充项目列表重新分析确认交互"
+```
+
+Expected:
+
+- 提交成功，且提交信息为中文
+
+## Task 3: 补前端实施记录
+
+**Files:**
+- Create: `docs/reports/implementation/2026-03-27-project-list-reanalyze-confirm-refresh-frontend-record.md`
+
+- [ ] **Step 1: 新增前端实施记录文档**
+
+记录至少以下内容：
+
+```markdown
+# 项目列表重新分析确认刷新前端实施记录
+
+## 本次改动
+- 为项目列表“重新分析”按钮增加确认弹窗
+- 点击确认后才调用项目标签重打标接口
+- 调用成功后继续刷新项目列表和顶部状态统计
+
+## 影响文件
+- ruoyi-ui/src/views/ccdiProject/index.vue
+- ruoyi-ui/tests/unit/project-list-reanalyze-flow.test.js
+
+## 验证
+- node ruoyi-ui/tests/unit/project-list-reanalyze-flow.test.js
+- node ruoyi-ui/tests/unit/project-list-reanalyze-api.test.js
+```
+
+- [ ] **Step 2: 复核暂存区只包含本次前端相关文件**
+
+Run:
+
+```bash
+git status --short
+```
+
+Expected:
+
+- 暂存区仅包含本任务相关源码、测试和实施记录
+- 若出现无关文件已暂存，先移出暂存区
+
+- [ ] **Step 3: 提交前端实施记录**
+
+Run:
+
+```bash
+git add docs/reports/implementation/2026-03-27-project-list-reanalyze-confirm-refresh-frontend-record.md
+git commit -m "补充项目列表重新分析前端实施记录"
+```
+
+Expected:
+
+- 提交成功，且不夹带无关文件
+
+## Done When
+
+- 点击项目列表“重新分析”时会先出现确认弹窗
+- 用户取消确认时不会发请求、不会进入 loading
+- 用户确认后仍然调用现有 `/ccdi/project/tags/rebuild`
+- 成功提示仍为“已开始重新分析”，且会刷新列表和状态统计
+- 已补齐前端源码契约测试与实施记录