ccdi/docs/plans/frontend/2026-03-24-special-check-family-asset-liability-frontend-implementation.md

# Special Check Family Asset Liability 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:** 保持 `SpecialCheck.vue` 作为专项排查页入口，不新增路由或平行页面。前端拆成“主容器 + 专项核查列表区块 + 行内展开详情”三层结构，列表接口与详情接口分开请求，样式沿用结果总览已有卡片、表格、标签和空态语言。

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

---

### Task 1: 补专项核查 API 封装

**Files:**
- Create: `ruoyi-ui/src/api/ccdi/projectSpecialCheck.js`
- Test: `ruoyi-ui/tests/unit/special-check-family-asset-liability-api.test.js`

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

新增接口契约静态断言，锁定以下方法与路径：

- `getFamilyAssetLiabilityList`
- `getFamilyAssetLiabilityDetail`
- `/ccdi/project/special-check/family-asset-liability/list`
- `/ccdi/project/special-check/family-asset-liability/detail`

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

Run:

```bash
cd ruoyi-ui
node tests/unit/special-check-family-asset-liability-api.test.js
```

Expected:

- `FAIL`

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

在 API 模块中新增：

- `getFamilyAssetLiabilityList(projectId)`
- `getFamilyAssetLiabilityDetail(projectId, staffIdCard)`

要求：

- 统一使用 `@/utils/request`
- 详情接口透传 `projectId` 与 `staffIdCard`
- 不和 `projectOverview.js` 混写

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

Run:

```bash
cd ruoyi-ui
node tests/unit/special-check-family-asset-liability-api.test.js
```

Expected:

- `PASS`

- [ ] **Step 5: Commit**

```bash
git add ruoyi-ui/src/api/ccdi/projectSpecialCheck.js ruoyi-ui/tests/unit/special-check-family-asset-liability-api.test.js
git commit -m "补充专项核查家庭资产负债前端接口"
```

### Task 2: 将 SpecialCheck.vue 从占位页升级为页面主容器

**Files:**
- Modify: `ruoyi-ui/src/views/ccdiProject/components/detail/SpecialCheck.vue`
- Create: `ruoyi-ui/src/views/ccdiProject/components/detail/specialCheck.mock.js`
- Test: `ruoyi-ui/tests/unit/special-check-layout.test.js`
- Test: `ruoyi-ui/tests/unit/special-check-states.test.js`

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

补页面主容器静态断言，锁定以下内容：

- `SpecialCheck.vue` 不再渲染“功能开发中...”
- 页面包含专项核查卡片标题“员工家庭资产负债专项核查”
- 页面保留 `loading / empty / loaded` 三态结构

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

Run:

```bash
cd ruoyi-ui
node tests/unit/special-check-layout.test.js
node tests/unit/special-check-states.test.js
```

Expected:

- `FAIL`

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

在 `SpecialCheck.vue` 中：

- 引入真实列表接口
- 维持页面级 `loading / empty / loaded` 状态
- 页面主卡片采用与结果总览一致的白卡结构
- `specialCheck.mock.js` 仅保留空态和骨架所需结构，不额外扩展伪业务数据

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

Run:

```bash
cd ruoyi-ui
node tests/unit/special-check-layout.test.js
node tests/unit/special-check-states.test.js
```

Expected:

- `PASS`

- [ ] **Step 5: Commit**

```bash
git add ruoyi-ui/src/views/ccdiProject/components/detail/SpecialCheck.vue ruoyi-ui/src/views/ccdiProject/components/detail/specialCheck.mock.js ruoyi-ui/tests/unit/special-check-layout.test.js ruoyi-ui/tests/unit/special-check-states.test.js
git commit -m "升级专项排查页主容器"
```

### Task 3: 实现员工家庭核查列表与风险标签

**Files:**
- Create: `ruoyi-ui/src/views/ccdiProject/components/detail/FamilyAssetLiabilitySection.vue`
- Test: `ruoyi-ui/tests/unit/special-check-family-table.test.js`
- Test: `ruoyi-ui/tests/unit/special-check-risk-tag.test.js`

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

新增区块组件静态断言，锁定：

- 列表字段包含姓名、身份证号、所属部门、家庭总年收入、家庭总资产、家庭总负债、风险情况、操作
- 风险情况使用标签展示
- 操作列文案为“查看详情”

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

Run:

```bash
cd ruoyi-ui
node tests/unit/special-check-family-table.test.js
node tests/unit/special-check-risk-tag.test.js
```

Expected:

- `FAIL`

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

在 `FamilyAssetLiabilitySection.vue` 中：

- 接收列表数据与加载状态
- 使用 `el-table` 渲染员工家庭核查列表
- 风险标签颜色与结果总览现有标签语义保持一致
- 金额统一格式化为元或万元显示，前后一致即可，不增加额外切换控件

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

Run:

```bash
cd ruoyi-ui
node tests/unit/special-check-family-table.test.js
node tests/unit/special-check-risk-tag.test.js
```

Expected:

- `PASS`

- [ ] **Step 5: Commit**

```bash
git add ruoyi-ui/src/views/ccdiProject/components/detail/FamilyAssetLiabilitySection.vue ruoyi-ui/tests/unit/special-check-family-table.test.js ruoyi-ui/tests/unit/special-check-risk-tag.test.js
git commit -m "补充专项核查家庭资产负债列表展示"
```

### Task 4: 实现行内展开详情与按需查询

**Files:**
- Create: `ruoyi-ui/src/views/ccdiProject/components/detail/FamilyAssetLiabilityDetail.vue`
- Modify: `ruoyi-ui/src/views/ccdiProject/components/detail/FamilyAssetLiabilitySection.vue`
- Test: `ruoyi-ui/tests/unit/special-check-detail-expand.test.js`
- Test: `ruoyi-ui/tests/unit/special-check-detail-layout.test.js`

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

新增详情展开断言，锁定：

- 点击“查看详情”后在当前行内展开
- 不出现弹窗、抽屉或路由跳转
- 详情固定分为收入、资产、负债三组
- 资产和负债明细均以表格或列表形式展开

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

Run:

```bash
cd ruoyi-ui
node tests/unit/special-check-detail-expand.test.js
node tests/unit/special-check-detail-layout.test.js
```

Expected:

- `FAIL`

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

在 `FamilyAssetLiabilitySection.vue` 中：

- 管理当前展开员工 `expandedStaffIdCard`
- 首次展开时调用详情接口
- 再次点击同一行时收起
- 切换项目 `projectId` 时清空展开状态和详情缓存

在 `FamilyAssetLiabilityDetail.vue` 中：

- 展示收入明细、本人与配偶小计
- 展示资产合计与资产明细列表
- 展示负债合计与负债明细列表
- 对空明细显示局部空态，不额外跳页

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

Run:

```bash
cd ruoyi-ui
node tests/unit/special-check-detail-expand.test.js
node tests/unit/special-check-detail-layout.test.js
```

Expected:

- `PASS`

- [ ] **Step 5: Commit**

```bash
git add ruoyi-ui/src/views/ccdiProject/components/detail/FamilyAssetLiabilityDetail.vue ruoyi-ui/src/views/ccdiProject/components/detail/FamilyAssetLiabilitySection.vue ruoyi-ui/tests/unit/special-check-detail-expand.test.js ruoyi-ui/tests/unit/special-check-detail-layout.test.js
git commit -m "补充专项核查家庭资产负债详情展开"
```

### Task 5: 对齐结果总览视觉并补记录

**Files:**
- Modify: `ruoyi-ui/src/views/ccdiProject/components/detail/SpecialCheck.vue`
- Modify: `ruoyi-ui/src/views/ccdiProject/components/detail/FamilyAssetLiabilitySection.vue`
- Modify: `ruoyi-ui/src/views/ccdiProject/components/detail/FamilyAssetLiabilityDetail.vue`
- Test: `ruoyi-ui/tests/unit/special-check-visual-alignment.test.js`
- Create: `docs/reports/implementation/2026-03-24-special-check-family-asset-liability-frontend-record.md`
- Create: `docs/tests/records/2026-03-24-special-check-family-asset-liability-frontend-verification.md`

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

新增样式/结构静态断言，锁定：

- 使用结果总览同类白卡容器结构
- 标题、副标题、表格头、风险标签与页面留白节奏统一
- 页面不再出现占位图标与“功能开发中...”文案

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

Run:

```bash
cd ruoyi-ui
node tests/unit/special-check-visual-alignment.test.js
```

Expected:

- `FAIL`

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

收口样式与文档：

- 对齐结果总览现有 `section-card / block-header / el-table` 风格
- 保持桌面端阅读密度稳定
- 确认空态、加载态、异常态都在当前卡片内解决
- 写前端实施记录与验证记录

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

Run:

```bash
cd ruoyi-ui
node tests/unit/special-check-family-asset-liability-api.test.js
node tests/unit/special-check-layout.test.js
node tests/unit/special-check-states.test.js
node tests/unit/special-check-family-table.test.js
node tests/unit/special-check-risk-tag.test.js
node tests/unit/special-check-detail-expand.test.js
node tests/unit/special-check-detail-layout.test.js
node tests/unit/special-check-visual-alignment.test.js
```

Expected:

- `PASS`

将执行命令与结果记录到 `docs/tests/records/2026-03-24-special-check-family-asset-liability-frontend-verification.md`。

- [ ] **Step 5: Commit**

```bash
git add ruoyi-ui/src/views/ccdiProject/components/detail/SpecialCheck.vue ruoyi-ui/src/views/ccdiProject/components/detail/FamilyAssetLiabilitySection.vue ruoyi-ui/src/views/ccdiProject/components/detail/FamilyAssetLiabilityDetail.vue docs/reports/implementation/2026-03-24-special-check-family-asset-liability-frontend-record.md docs/tests/records/2026-03-24-special-check-family-asset-liability-frontend-verification.md ruoyi-ui/tests/unit/special-check-visual-alignment.test.js
git commit -m "完成专项核查家庭资产负债前端实现"
```