ccdi/docs/plans/frontend/2026-03-19-results-overview-risk-api-frontend-implementation.md

# Results Overview Risk API 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:** 将结果总览页面中的风险仪表盘、风险人员总览、中高风险人员 TOP10 从本地 mock 数据切换为真实后端接口数据。

**Architecture:** 保持 `PreliminaryCheck.vue` 作为结果总览页面入口，不改造当前 4 区块布局，只在前端增加结果总览 API 封装、页面数据拉取与 3 个区块的真实数据映射。风险模型区和风险明细区继续使用现有 mock 或原状，不额外扩展接口范围。

**Tech Stack:** Vue 2, Element UI, Axios (`@/utils/request`), Node.js, npm

---

### Task 1: 新增结果总览 API 封装

**Files:**
- Create: `ruoyi-ui/src/api/ccdi/projectOverview.js`
- Test: `ruoyi-ui/tests/unit/project-overview-api.test.js`

- [ ] **Step 1: Write the failing test**

新增静态断言脚本，锁定 3 个接口方法：

```js
const assert = require("assert");
const fs = require("fs");
const path = require("path");

const source = fs.readFileSync(
  path.resolve(__dirname, "../../src/api/ccdi/projectOverview.js"),
  "utf8"
);

[
  "getOverviewDashboard",
  "getOverviewRiskPeople",
  "getOverviewTopRiskPeople",
  "/ccdi/project/overview/dashboard",
  "/ccdi/project/overview/risk-people",
  "/ccdi/project/overview/top-risk-people",
].forEach((token) => assert(source.includes(token), token));
```

- [ ] **Step 2: Run test to verify it fails**

Run:

```bash
cd ruoyi-ui
node tests/unit/project-overview-api.test.js
```

Expected:

- `FAIL`

- [ ] **Step 3: Write minimal implementation**

创建 API 文件：

```js
import request from "@/utils/request";

export function getOverviewDashboard(projectId) {
  return request({ url: "/ccdi/project/overview/dashboard", method: "get", params: { projectId } });
}
```

同理补齐另外两个接口。

- [ ] **Step 4: Run test to verify it passes**

Run:

```bash
cd ruoyi-ui
node tests/unit/project-overview-api.test.js
```

Expected:

- `PASS`

- [ ] **Step 5: Commit**

```bash
git add ruoyi-ui/src/api/ccdi/projectOverview.js ruoyi-ui/tests/unit/project-overview-api.test.js
git commit -m "新增结果总览风险接口前端封装"
```

### Task 2: 在 PreliminaryCheck 页面接入 3 个真实接口

**Files:**
- Modify: `ruoyi-ui/src/views/ccdiProject/components/detail/PreliminaryCheck.vue`
- Modify: `ruoyi-ui/src/views/ccdiProject/components/detail/preliminaryCheck.mock.js`
- Test: `ruoyi-ui/tests/unit/preliminary-check-api-integration.test.js`

- [ ] **Step 1: Write the failing test**

新增静态断言脚本，锁定页面必须引入真实 API：

```js
const assert = require("assert");
const fs = require("fs");
const path = require("path");

const source = fs.readFileSync(
  path.resolve(__dirname, "../../src/views/ccdiProject/components/detail/PreliminaryCheck.vue"),
  "utf8"
);

[
  "getOverviewDashboard",
  "getOverviewRiskPeople",
  "getOverviewTopRiskPeople",
  "loadOverviewData",
  "Promise.all",
].forEach((token) => assert(source.includes(token), token));
```

- [ ] **Step 2: Run test to verify it fails**

Run:

```bash
cd ruoyi-ui
node tests/unit/preliminary-check-api-integration.test.js
```

Expected:

- `FAIL`

- [ ] **Step 3: Write minimal implementation**

在 `PreliminaryCheck.vue` 中：

1. 引入 3 个 API 方法
2. 新增 `loadOverviewData`
3. 在页面进入或 `projectId` 变化时并发拉取 3 个接口
4. 将返回结果合并到页面数据：

```js
this.realData = {
  ...this.mockData,
  summary: dashboardData,
  riskPeople: {
    overviewList: riskPeopleData.overviewList || [],
    topRiskList: topRiskPeopleData.topRiskList || [],
  },
};
```

5. 保留现有 `loading / empty / loaded` 状态

本任务只替换这 3 块数据，不动风险模型区和风险明细区。

- [ ] **Step 4: Run test to verify it passes**

Run:

```bash
cd ruoyi-ui
node tests/unit/preliminary-check-api-integration.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/preliminaryCheck.mock.js ruoyi-ui/tests/unit/preliminary-check-api-integration.test.js
git commit -m "接入结果总览风险真实接口"
```

### Task 3: 校准风险人员区字段映射与空态

**Files:**
- Modify: `ruoyi-ui/src/views/ccdiProject/components/detail/RiskPeopleSection.vue`
- Test: `ruoyi-ui/tests/unit/preliminary-check-risk-people-binding.test.js`

- [ ] **Step 1: Write the failing test**

新增静态断言脚本，锁定字段映射仍与当前页面结构兼容：

```js
const assert = require("assert");
const fs = require("fs");
const path = require("path");

const source = fs.readFileSync(
  path.resolve(__dirname, "../../src/views/ccdiProject/components/detail/RiskPeopleSection.vue"),
  "utf8"
);

[
  "sectionData.overviewList",
  "sectionData.topRiskList",
  "riskCount",
  "riskPoint",
  "modelCount",
  "riskLevelType",
].forEach((token) => assert(source.includes(token), token));
```

- [ ] **Step 2: Run test to verify it fails**

Run:

```bash
cd ruoyi-ui
node tests/unit/preliminary-check-risk-people-binding.test.js
```

Expected:

- 若字段被改乱或误删则 `FAIL`

- [ ] **Step 3: Write minimal implementation**

实施要求：

1. 保持现有表格列不重排
2. 若接口返回空数组，表格自然展示 Element 空态
3. `riskLevelType` 不在组件内重新判断，直接使用后端返回值
4. `actionLabel` 缺失时仍回退为 `查看详情`

- [ ] **Step 4: Run test to verify it passes**

Run:

```bash
cd ruoyi-ui
node tests/unit/preliminary-check-risk-people-binding.test.js
```

Expected:

- `PASS`

- [ ] **Step 5: Commit**

```bash
git add ruoyi-ui/src/views/ccdiProject/components/detail/RiskPeopleSection.vue ruoyi-ui/tests/unit/preliminary-check-risk-people-binding.test.js
git commit -m "校准结果总览风险人员区字段映射"
```

### Task 4: 补充前端验证记录与实施记录

**Files:**
- Create: `docs/tests/records/2026-03-19-results-overview-risk-api-frontend-verification.md`
- Create: `docs/reports/implementation/2026-03-19-results-overview-risk-api-frontend-implementation.md`

- [ ] **Step 1: Write the failing record skeleton**

先创建验证记录模板：

```md
# 结果总览风险接口前端验证记录

## 验证范围
- API 封装
- 结果总览页面并发取数
- 风险人员区字段映射
```

- [ ] **Step 2: Run frontend verification commands**

Run:

```bash
cd ruoyi-ui
node tests/unit/project-overview-api.test.js
node tests/unit/preliminary-check-api-integration.test.js
node tests/unit/preliminary-check-risk-people-binding.test.js
npm run build:prod
```

Expected:

- 3 个脚本 `PASS`
- 构建成功

- [ ] **Step 3: Write minimal implementation record**

实施记录至少包含：

- 新增结果总览 API 封装
- 页面接入 3 个真实接口
- 风险模型区和风险明细区本轮保持不变

- [ ] **Step 4: Re-run record review**

Run:

```bash
sed -n '1,220p' docs/tests/records/2026-03-19-results-overview-risk-api-frontend-verification.md
sed -n '1,220p' docs/reports/implementation/2026-03-19-results-overview-risk-api-frontend-implementation.md
```

Expected:

- 两份文档都能覆盖本次前端接入范围和验证方法

- [ ] **Step 5: Commit**

```bash
git add docs/tests/records/2026-03-19-results-overview-risk-api-frontend-verification.md docs/reports/implementation/2026-03-19-results-overview-risk-api-frontend-implementation.md
git commit -m "补充结果总览风险接口前端记录"
```