补充结果总览卡片结构合并实施计划

2026-03-27 14:44:10 +08:00
parent 3ea227141d
commit d914c93e93
3 changed files with 463 additions and 0 deletions
--- a/docs/plans/backend/2026-03-27-results-overview-card-merge-backend-implementation.md
+++ b/docs/plans/backend/2026-03-27-results-overview-card-merge-backend-implementation.md
@@ -0,0 +1,135 @@
+# Results Overview Card Merge Backend Implementation Plan
+
+> **For agentic workers:** REQUIRED: This repo forbids subagents, so use superpowers:executing-plans in the current session. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 验证“结果总览卡片结构合并”仅为前端展示层调整，现有结果总览后端接口、字段和查询口径已足以支撑本轮需求，不新增接口、不扩字段、不改 SQL，并补齐后端边界与验证留痕。
+
+**Architecture:** 本轮需求只涉及 `PreliminaryCheck.vue` 顶部结构合并和区块标题统一，后端默认不做源码开发。执行时仅围绕 `CcdiProjectOverviewController + ICcdiProjectOverviewService + CcdiProjectOverviewServiceImpl + CcdiProjectOverviewMapper.xml` 的现有结果总览链路做边界确认与回归验证，确认 `dashboard`、`risk-people`、`risk-models/cards` 与现有风险明细查询数据已能直接支撑新布局；若验证通过，只沉淀“后端无需改造”的实施记录与验证记录。
+
+**Tech Stack:** Java 21, Spring Boot 3, MyBatis XML, Maven, JUnit 5
+
+---
+
+### Task 1: 确认现有结果总览后端契约足以支撑本轮前端合并
+
+**Files:**
+- Verify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiProjectOverviewController.java`
+- Verify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/ICcdiProjectOverviewService.java`
+- Verify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectOverviewServiceImpl.java`
+- Verify: `ccdi-project/src/main/resources/mapper/ccdi/project/CcdiProjectOverviewMapper.xml`
+- Test: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/controller/CcdiProjectOverviewControllerTest.java`
+- Test: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectOverviewServiceImplTest.java`
+
+- [ ] **Step 1: Review the backend boundary**
+
+人工核对以下边界仍成立：
+
+- `GET /ccdi/project/overview/dashboard` 继续提供顶部 5 个统计项数据
+- `GET /ccdi/project/overview/risk-people` 继续提供风险人员列表数据
+- `GET /ccdi/project/overview/risk-models/cards` 继续提供风险模型卡片数据
+- 前端只是把顶部两个区块改为同一卡片展示，不需要新增“风险总览壳层”专用字段
+- 现有 `riskLevel`、`riskLevelType`、`modelCount` 等字段语义无需调整
+
+- [ ] **Step 2: Run the focused backend contract tests**
+
+Run:
+
+```bash
+mvn test -pl ccdi-project -Dtest=CcdiProjectOverviewControllerTest,CcdiProjectOverviewServiceImplTest
+```
+
+Expected:
+
+- `PASS`
+
+- [ ] **Step 3: If any test fails, stop and reassess**
+
+若失败：
+
+- 不要直接新增接口、字段或补丁式查询
+- 先确认失败是否与本轮纯前端结构合并直接相关
+- 若确实发现后端契约缺口，停止执行并回到设计阶段补充后端方案
+
+- [ ] **Step 4: Re-run the same tests after analysis**
+
+Run:
+
+```bash
+mvn test -pl ccdi-project -Dtest=CcdiProjectOverviewControllerTest,CcdiProjectOverviewServiceImplTest
+```
+
+Expected:
+
+- `PASS`
+
+- [ ] **Step 5: Commit**
+
+```bash
+# 本任务若无代码或文档改动，不产生提交。
+```
+
+### Task 2: 做结果总览后端回归并沉淀“无需改造”记录
+
+**Files:**
+- Test: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/controller/CcdiProjectOverviewControllerContractTest.java`
+- Test: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapperSqlTest.java`
+- Test: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapperRiskModelCardsTest.java`
+- Create: `docs/tests/records/2026-03-27-results-overview-card-merge-backend-verification.md`
+- Create: `docs/reports/implementation/2026-03-27-results-overview-card-merge-backend-record.md`
+
+- [ ] **Step 1: Run backend regression**
+
+Run:
+
+```bash
+mvn test -pl ccdi-project -Dtest=CcdiProjectOverviewControllerContractTest,CcdiProjectOverviewMapperSqlTest,CcdiProjectOverviewMapperRiskModelCardsTest
+```
+
+Expected:
+
+- 全部 `PASS`
+- 能确认结果总览查询仍基于现有员工结果表与既有 SQL 口径
+
+- [ ] **Step 2: Write the verification record**
+
+在 `docs/tests/records/2026-03-27-results-overview-card-merge-backend-verification.md` 记录：
+
+- 执行命令
+- 执行日期
+- 测试结果
+- 结论：现有结果总览后端契约足以支撑本轮卡片结构合并，后端无需扩展
+
+- [ ] **Step 3: Write the implementation record**
+
+在 `docs/reports/implementation/2026-03-27-results-overview-card-merge-backend-record.md` 记录：
+
+- 本轮后端不改源码
+- 维持的接口边界
+- 维持的结果总览字段口径
+- 回归验证结果
+
+- [ ] **Step 4: Confirm no backend source files were modified**
+
+Run:
+
+```bash
+git diff --name-only -- ccdi-project ruoyi-admin ruoyi-common ruoyi-framework ruoyi-system
+```
+
+Expected:
+
+- 无输出，或仅出现与当前后端稳定性直接相关且经确认必须修复的文件
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add docs/tests/records/2026-03-27-results-overview-card-merge-backend-verification.md docs/reports/implementation/2026-03-27-results-overview-card-merge-backend-record.md
+git commit -m "补充结果总览卡片合并后端边界记录"
+```
+
+## Done When
+
+- 已确认现有结果总览后端接口足以支撑前端卡片结构合并
+- 未引入任何与需求无关的后端补丁式改动
+- 已留下后端验证记录与实施记录
+- 后端执行结论明确为“无需改造”
--- a/docs/plans/frontend/2026-03-27-results-overview-card-merge-frontend-implementation.md
+++ b/docs/plans/frontend/2026-03-27-results-overview-card-merge-frontend-implementation.md
@@ -0,0 +1,298 @@
+# Results Overview Card Merge Frontend Implementation Plan
+
+> **For agentic workers:** REQUIRED: This repo forbids subagents, so use superpowers:executing-plans in the current session. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 将结果总览页顶部的 `风险仪表盘` 与 `风险人员总览` 合并为一个 `风险总览` 大卡片，并将后续两个主区块标题统一为 `风险模型` 与 `风险明细`，同时补齐统计卡片标题与小图标展示。
+
+**Architecture:** 保持 `PreliminaryCheck.vue` 作为结果总览唯一入口，不新增接口、不重组数据装配。实现只收敛在 `PreliminaryCheck.vue`、`OverviewStats.vue`、`RiskPeopleSection.vue`、`RiskModelSection.vue`、`RiskDetailSection.vue` 五个前端组件与对应静态断言测试中，按“TDD 锁结构 -> 合并总览卡片 -> 统一区块标题 -> 聚焦回归与文档留痕”的顺序推进。
+
+**Tech Stack:** Vue 2, Element UI, SCSS, Node.js
+
+---
+
+### Task 1: 锁定结果总览卡片合并与标题统一契约
+
+**Files:**
+- Modify: `ruoyi-ui/tests/unit/preliminary-check-layout.test.js`
+- Modify: `ruoyi-ui/tests/unit/preliminary-check-summary-and-people.test.js`
+- Modify: `ruoyi-ui/tests/unit/preliminary-check-summary-visuals.test.js`
+- Modify: `ruoyi-ui/tests/unit/preliminary-check-overview-spacing.test.js`
+- Modify: `ruoyi-ui/tests/unit/preliminary-check-model-and-detail.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+更新现有静态断言，锁定以下契约：
+
+- `PreliminaryCheck.vue` 中存在统一的 `风险总览` 容器，例如 `risk-overview-card`
+- `OverviewStats` 与 `RiskPeopleSection` 继续存在，但被收进同一个总览容器
+- `OverviewStats.vue` 不再包含 `风险仪表盘`、`风险总体数据概览` 文案
+- `RiskPeopleSection.vue` 不再把 `风险人员总览` 作为独立大卡片标题
+- mock 数据中的最后一个统计卡片文案改为 `无预警人数`
+- `RiskModelSection.vue` 顶层标题改为 `风险模型`
+- `RiskDetailSection.vue` 顶层标题改为 `风险明细`
+
+示例断言片段：
+
+```js
+assert(entry.includes("risk-overview-card"), "结果总览页缺少统一风险总览容器");
+assert(entry.includes("风险总览"), "结果总览页缺少风险总览标题");
+assert(!stats.includes("风险仪表盘"), "统计区不应继续保留风险仪表盘标题");
+assert(mockSource.includes('label: "无预警人数"'), "最后一个统计项应为无预警人数");
+assert(model.includes("风险模型"), "第二张主卡片标题应为风险模型");
+assert(detail.includes("风险明细"), "第三张主卡片标题应为风险明细");
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+cd ruoyi-ui
+node tests/unit/preliminary-check-layout.test.js
+node tests/unit/preliminary-check-summary-and-people.test.js
+node tests/unit/preliminary-check-summary-visuals.test.js
+node tests/unit/preliminary-check-overview-spacing.test.js
+node tests/unit/preliminary-check-model-and-detail.test.js
+```
+
+Expected:
+
+- `FAIL`
+- 原因是当前页面仍保留 `风险仪表盘` 独立壳层与旧区块标题
+
+- [ ] **Step 3: Commit the contract update**
+
+```bash
+git add ruoyi-ui/tests/unit/preliminary-check-layout.test.js ruoyi-ui/tests/unit/preliminary-check-summary-and-people.test.js ruoyi-ui/tests/unit/preliminary-check-summary-visuals.test.js ruoyi-ui/tests/unit/preliminary-check-overview-spacing.test.js ruoyi-ui/tests/unit/preliminary-check-model-and-detail.test.js
+git commit -m "锁定结果总览卡片合并结构断言"
+```
+
+### Task 2: 合并风险总览卡片并收掉重复壳层
+
+**Files:**
+- Modify: `ruoyi-ui/src/views/ccdiProject/components/detail/PreliminaryCheck.vue`
+- Modify: `ruoyi-ui/src/views/ccdiProject/components/detail/OverviewStats.vue`
+- Modify: `ruoyi-ui/src/views/ccdiProject/components/detail/RiskPeopleSection.vue`
+- Modify: `ruoyi-ui/src/views/ccdiProject/components/detail/preliminaryCheck.mock.js`
+
+- [ ] **Step 1: Implement the merged overview shell**
+
+在 `PreliminaryCheck.vue` 中：
+
+- 新增统一的 `风险总览` 外层卡片结构
+- 先渲染统计区，再渲染风险人员区
+- 保持 `currentData.summary`、`currentData.riskPeople` 的传参与现有事件绑定不变
+
+在 `OverviewStats.vue` 中：
+
+- 去掉独立 `section-card`、旧标题组和旧副标题
+- 只保留统计卡片栅格内容
+- 保留每个统计项的 `icon`、`label`、`value` 与 `tone` 绑定
+
+在 `RiskPeopleSection.vue` 中：
+
+- 去掉自身独立白卡壳层
+- 保留导出按钮、表格字段、查看详情事件与风险标签逻辑
+- 不重做现有表格列与数据语义
+
+在 `preliminaryCheck.mock.js` 中：
+
+- 将最后一个统计项文案改为 `无预警人数`
+- 保持 5 个统计项顺序不变
+
+- [ ] **Step 2: Run focused tests**
+
+Run:
+
+```bash
+cd ruoyi-ui
+node tests/unit/preliminary-check-layout.test.js
+node tests/unit/preliminary-check-summary-and-people.test.js
+node tests/unit/preliminary-check-summary-visuals.test.js
+node tests/unit/preliminary-check-overview-spacing.test.js
+node tests/unit/preliminary-check-states.test.js
+```
+
+Expected:
+
+- `PASS`
+
+- [ ] **Step 3: If any test fails, fix only within the merged overview scope**
+
+修正原则：
+
+- 不新增接口或额外数据装配
+- 不把 `OverviewStats` 与 `RiskPeopleSection` 合并成单个大组件
+- 不引入设计文档之外的新区块或新交互
+
+- [ ] **Step 4: Re-run the same focused tests**
+
+Run:
+
+```bash
+cd ruoyi-ui
+node tests/unit/preliminary-check-layout.test.js
+node tests/unit/preliminary-check-summary-and-people.test.js
+node tests/unit/preliminary-check-summary-visuals.test.js
+node tests/unit/preliminary-check-overview-spacing.test.js
+node tests/unit/preliminary-check-states.test.js
+```
+
+Expected:
+
+- `PASS`
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add ruoyi-ui/src/views/ccdiProject/components/detail/PreliminaryCheck.vue ruoyi-ui/src/views/ccdiProject/components/detail/OverviewStats.vue ruoyi-ui/src/views/ccdiProject/components/detail/RiskPeopleSection.vue ruoyi-ui/src/views/ccdiProject/components/detail/preliminaryCheck.mock.js
+git commit -m "合并结果总览顶部风险总览卡片"
+```
+
+### Task 3: 统一风险模型与风险明细主卡片标题
+
+**Files:**
+- Modify: `ruoyi-ui/src/views/ccdiProject/components/detail/RiskModelSection.vue`
+- Modify: `ruoyi-ui/src/views/ccdiProject/components/detail/RiskDetailSection.vue`
+- Modify: `ruoyi-ui/tests/unit/preliminary-check-model-and-detail.test.js`
+
+- [ ] **Step 1: Implement title normalization**
+
+在 `RiskModelSection.vue` 中：
+
+- 将第一块主标题改为 `风险模型`
+- 下面的子标题与内容区块保持现有语义，不扩功能
+
+在 `RiskDetailSection.vue` 中：
+
+- 将第一块主标题改为 `风险明细`
+- 下面的两张子表格块保持现有语义、导出按钮和展示逻辑
+
+- [ ] **Step 2: Run title-related tests**
+
+Run:
+
+```bash
+cd ruoyi-ui
+node tests/unit/preliminary-check-model-and-detail.test.js
+node tests/unit/preliminary-check-summary-and-people.test.js
+```
+
+Expected:
+
+- `PASS`
+
+- [ ] **Step 3: Verify no unintended model/detail behavior changed**
+
+额外人工核对以下内容仍成立：
+
+- 风险模型区的卡片筛选、任意触发 / 同时触发切换、分页与查看详情入口仍在
+- 风险明细区的两张表仍保留现有字段、金额格式与操作列
+
+- [ ] **Step 4: Re-run model/detail regression**
+
+Run:
+
+```bash
+cd ruoyi-ui
+node tests/unit/preliminary-check-model-and-detail.test.js
+node tests/unit/preliminary-check-model-card-grid.test.js
+node tests/unit/preliminary-check-model-filters.test.js
+node tests/unit/preliminary-check-model-linkage-flow.test.js
+node tests/unit/preliminary-check-project-analysis-entry.test.js
+```
+
+Expected:
+
+- `PASS`
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add ruoyi-ui/src/views/ccdiProject/components/detail/RiskModelSection.vue ruoyi-ui/src/views/ccdiProject/components/detail/RiskDetailSection.vue ruoyi-ui/tests/unit/preliminary-check-model-and-detail.test.js
+git commit -m "统一结果总览模型与明细区块标题"
+```
+
+### Task 4: 做前端回归并补充实施记录
+
+**Files:**
+- Create: `docs/reports/implementation/2026-03-27-results-overview-card-merge-frontend-record.md`
+- Create: `docs/tests/records/2026-03-27-results-overview-card-merge-frontend-verification.md`
+- Verify: `docs/design/2026-03-27-results-overview-card-merge-design.md`
+
+- [ ] **Step 1: Run the focused frontend regression suite**
+
+Run:
+
+```bash
+cd ruoyi-ui
+node tests/unit/preliminary-check-layout.test.js
+node tests/unit/preliminary-check-summary-and-people.test.js
+node tests/unit/preliminary-check-summary-visuals.test.js
+node tests/unit/preliminary-check-overview-spacing.test.js
+node tests/unit/preliminary-check-model-and-detail.test.js
+node tests/unit/preliminary-check-model-card-grid.test.js
+node tests/unit/preliminary-check-model-filters.test.js
+node tests/unit/preliminary-check-model-linkage-flow.test.js
+node tests/unit/preliminary-check-project-analysis-entry.test.js
+node tests/unit/preliminary-check-states.test.js
+npm run build:prod
+```
+
+Expected:
+
+- 所有 `node` 静态断言 `PASS`
+- `npm run build:prod` 成功完成
+
+- [ ] **Step 2: Optional manual page check**
+
+如需人工验证，再执行：
+
+```bash
+cd ruoyi-ui
+npm run dev
+```
+
+人工检查：
+
+- 首屏顶部只保留一个 `风险总览` 大卡片
+- 统计小卡片显示图标、标题、数值
+- 第二张主卡片标题为 `风险模型`
+- 第三张主卡片标题为 `风险明细`
+
+验证结束后必须主动停止前端进程，避免端口残留。
+
+- [ ] **Step 3: Write the verification record**
+
+在 `docs/tests/records/2026-03-27-results-overview-card-merge-frontend-verification.md` 记录：
+
+- 执行命令
+- 执行日期
+- 是否进行了 `npm run dev` 人工检查
+- 如启动了前端进程，何时停止、如何停止
+- 最终验证结论
+
+- [ ] **Step 4: Write the implementation record**
+
+在 `docs/reports/implementation/2026-03-27-results-overview-card-merge-frontend-record.md` 记录：
+
+- 合并 `风险仪表盘` 与 `风险人员总览` 的实现方式
+- 统计卡片标题与小图标补齐方式
+- `风险模型`、`风险明细` 标题统一情况
+- 本轮未改动的边界说明
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add docs/reports/implementation/2026-03-27-results-overview-card-merge-frontend-record.md docs/tests/records/2026-03-27-results-overview-card-merge-frontend-verification.md
+git commit -m "补充结果总览卡片合并前端实施记录"
+```
+
+## Done When
+
+- 顶部 `风险仪表盘` 与 `风险人员总览` 已合并为单个 `风险总览` 主卡片
+- 5 个统计卡片均显示标题与小图标，最后一个指标文案为 `无预警人数`
+- 第二个主卡片标题为 `风险模型`
+- 第三个主卡片标题为 `风险明细`
+- 现有数据装配、导出、查看详情、模型联动与风险明细展示行为未被破坏
+- 已留下前端实施记录与验证记录
--- a/docs/reports/implementation/2026-03-27-results-overview-card-merge-plan-record.md
+++ b/docs/reports/implementation/2026-03-27-results-overview-card-merge-plan-record.md
@@ -0,0 +1,30 @@
+# 结果总览卡片结构合并实施计划记录
+
+## 变更概述
+
+- 基于已确认的结果总览卡片结构合并设计文档，新增前端实施计划 1 份。
+- 基于已确认的结果总览卡片结构合并设计文档，新增后端实施计划 1 份。
+- 本轮计划明确聚焦：合并 `风险仪表盘` 与 `风险人员总览`、补齐统计卡片标题与小图标、统一 `风险模型` 与 `风险明细` 区块标题。
+- 本轮仅沉淀实施计划，尚未进入代码实现阶段。
+
+## 新增文件
+
+- `docs/plans/frontend/2026-03-27-results-overview-card-merge-frontend-implementation.md`
+- `docs/plans/backend/2026-03-27-results-overview-card-merge-backend-implementation.md`
+
+## 计划结论
+
+- 前端实施计划聚焦：
+  - 锁定统一 `风险总览` 大卡片结构断言
+  - 合并顶部统计区与风险人员区
+  - 统一 `风险模型`、`风险明细` 主卡片标题
+  - 做前端回归、构建验证与实施记录沉淀
+- 后端实施计划聚焦：
+  - 复核现有结果总览接口、字段和查询口径已足以支撑本轮前端改造
+  - 不新增接口、不扩字段、不改 SQL
+  - 补充后端验证记录与“无需改造”实施记录
+
+## 说明
+
+- 本次按仓库规范，将实施计划分别落到 `docs/plans/frontend/` 与 `docs/plans/backend/`。
+- 由于仓库约定不启用 subagent，后续执行阶段应在当前会话按计划顺序推进。