ccdi/docs/plans/frontend/2026-04-17-intermediary-library-refactor-frontend-implementation.md

# 中介库主从结构改造前端实施计划

> **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/ccdiIntermediary/` 作为唯一页面入口，不新增一级菜单和独立平行页面。首页搜索与表格改成统一口径，新增只新增中介本人；中介详情改成维护容器，内部承载中介本人信息、亲属列表、关联机构列表；亲属和机构关系通过独立编辑弹窗维护。

**Tech Stack:** Vue 2, Element UI, JavaScript, npm, nvm, Markdown

---

## 文件结构与职责

**设计与参考**

- `docs/design/2026-04-17-intermediary-library-refactor-design.md`
  本次前端实施的设计基线。

**前端 API**

- `ruoyi-ui/src/api/ccdiIntermediary.js`
  继续作为中介综合库 API 文件，补亲属与机构关系子资源接口，并收敛旧机构中介接口。

**页面主文件**

- `ruoyi-ui/src/views/ccdiIntermediary/index.vue`
  负责搜索、统一列表、三类记录分流、新增链路和详情联动。

**页面组件**

- `ruoyi-ui/src/views/ccdiIntermediary/components/SearchForm.vue`
  改为新搜索字段与提示文案。
- `ruoyi-ui/src/views/ccdiIntermediary/components/DataTable.vue`
  改为固定五列表头和按 `recordType` 分流操作按钮。
- `ruoyi-ui/src/views/ccdiIntermediary/components/DetailDialog.vue`
  从只读详情改为“中介详情维护容器”。
- `ruoyi-ui/src/views/ccdiIntermediary/components/EditDialog.vue`
  收敛为中介本人新增 / 编辑弹窗，去掉旧机构中介表单。
- `ruoyi-ui/src/views/ccdiIntermediary/components/RelativeEditDialog.vue`
  新增亲属编辑弹窗。
- `ruoyi-ui/src/views/ccdiIntermediary/components/EnterpriseRelationEditDialog.vue`
  新增关联机构关系编辑弹窗。

**依赖参考**

- `ruoyi-ui/src/views/ccdiStaffFmyRelation/index.vue`
  参考亲属类表单字段与关系展示。
- `ruoyi-ui/src/views/ccdiCustEnterpriseRelation/index.vue`
  参考关系类表单和列表交互。
- `ruoyi-ui/src/views/ccdiBaseStaff/index.vue`
  参考统一页内搜索、分页与基础弹窗写法。

## 实施任务

### Task 1: 收敛 API 文件为三类记录统一链路

**Files:**

- Modify: `ruoyi-ui/src/api/ccdiIntermediary.js`

- [ ] **Step 1: 先梳理旧 API 的调用位置**

Run: `rg -n "addEntityIntermediary|getEntityIntermediary|updateEntityIntermediary" ruoyi-ui/src/views/ccdiIntermediary -S`
Expected: 明确哪些旧机构中介方法会被移除或替换。

- [ ] **Step 2: 保留中介本人接口并调整命名语义**

保留：

```js
listIntermediary(query)
getPersonIntermediary(bizId)
addPersonIntermediary(data)
updatePersonIntermediary(data)
```

- [ ] **Step 3: 新增亲属接口**

补充：

```js
listIntermediaryRelatives(bizId)
getIntermediaryRelative(relativeBizId)
addIntermediaryRelative(bizId, data)
updateIntermediaryRelative(data)
delIntermediaryRelative(relativeBizId)
```

- [ ] **Step 4: 新增机构关系接口**

补充：

```js
listIntermediaryEnterpriseRelations(bizId)
getIntermediaryEnterpriseRelation(id)
addIntermediaryEnterpriseRelation(bizId, data)
updateIntermediaryEnterpriseRelation(data)
delIntermediaryEnterpriseRelation(id)
```

- [ ] **Step 5: 删除前端对旧机构中介 CRUD 的直接依赖**

Expected: 不再调用旧 `/ccdi/intermediary/entity` 新增 / 修改接口。

- [ ] **Step 6: 提交 API 调整**

```bash
git add ruoyi-ui/src/api/ccdiIntermediary.js
git commit -m "feat: 调整中介综合库前端接口"
```

### Task 2: 改造搜索表单和首页查询参数

**Files:**

- Modify: `ruoyi-ui/src/views/ccdiIntermediary/index.vue`
- Modify: `ruoyi-ui/src/views/ccdiIntermediary/components/SearchForm.vue`

- [ ] **Step 1: 先写页面数据结构变更**

将 `queryParams` 收敛为：

```js
{
  pageNum: 1,
  pageSize: 10,
  name: null,
  certificateNo: null,
  recordType: null,
  relatedIntermediaryKeyword: null
}
```

- [ ] **Step 2: 修改搜索表单字段**

搜索区固定为：

```vue
名称
证件号
记录类型
关联中介信息
```

- [ ] **Step 3: 为“关联中介信息”补提示文案**

文案示例：

```vue
placeholder="请输入关联中介姓名或证件号"
```

- [ ] **Step 4: 移除旧“中介类型”搜索**

Expected: 页面上不再出现“个人 / 机构”并列筛选语义。

- [ ] **Step 5: 运行本地 lint 前自查**

Expected: 查询参数和表单字段命名完全一致，没有遗留旧字段。

- [ ] **Step 6: 提交搜索区改造**

```bash
git add ruoyi-ui/src/views/ccdiIntermediary/index.vue ruoyi-ui/src/views/ccdiIntermediary/components/SearchForm.vue
git commit -m "feat: 调整中介综合库搜索条件"
```

### Task 3: 改造统一列表与三类记录操作分流

**Files:**

- Modify: `ruoyi-ui/src/views/ccdiIntermediary/components/DataTable.vue`
- Modify: `ruoyi-ui/src/views/ccdiIntermediary/index.vue`

- [ ] **Step 1: 先写出列表固定列结构**

表格列固定为：

```vue
名称
证件号
关联中介姓名
关联关系
创建时间
操作
```

- [ ] **Step 2: 让表格读取统一字段**

统一使用：

```js
row.name
row.certificateNo
row.relatedIntermediaryName
row.relationText
row.createTime
```

- [ ] **Step 3: 按 `recordType` 渲染操作按钮**

逻辑示例：

```js
if (row.recordType === 'INTERMEDIARY') { ... }
if (row.recordType === 'RELATIVE') { ... }
if (row.recordType === 'ENTERPRISE_RELATION') { ... }
```

- [ ] **Step 4: 在 `index.vue` 中改造 `handleDetail` / `handleUpdate` / `handleDelete`**

Expected: 三类记录进入不同弹窗和不同删除接口。

- [ ] **Step 5: 删除对旧机构中介详情弹窗的依赖**

Expected: 首页不再把机构主档当作中介主记录。

- [ ] **Step 6: 提交列表分流改造**

```bash
git add ruoyi-ui/src/views/ccdiIntermediary/components/DataTable.vue ruoyi-ui/src/views/ccdiIntermediary/index.vue
git commit -m "feat: 改造中介综合库统一列表"
```

### Task 4: 收敛中介本人编辑弹窗

**Files:**

- Modify: `ruoyi-ui/src/views/ccdiIntermediary/components/EditDialog.vue`
- Modify: `ruoyi-ui/src/views/ccdiIntermediary/index.vue`

- [ ] **Step 1: 删除旧“个人 / 机构二选一”入口**

Expected: 新增按钮点击后直接打开中介本人表单，不再先选类型。

- [ ] **Step 2: 删除旧机构中介表单片段**

Expected: `EditDialog.vue` 仅保留中介本人字段。

- [ ] **Step 3: 在提交前固定前端口径**

前端不让用户选择：

```js
form.personSubType = '本人'
form.relatedNumId = null
```

- [ ] **Step 4: 保存成功后自动进入中介详情维护页**

在 `index.vue` 中串起：

```js
await addPersonIntermediary(data)
await openDetailByBizId(...)
```

- [ ] **Step 5: 自查编辑态**

Expected: 修改中介本人时仍可正常加载详情和更新，但不允许切换为亲属语义。

- [ ] **Step 6: 提交中介本人弹窗改造**

```bash
git add ruoyi-ui/src/views/ccdiIntermediary/components/EditDialog.vue ruoyi-ui/src/views/ccdiIntermediary/index.vue
git commit -m "feat: 收敛中介本人编辑弹窗"
```

### Task 5: 新增亲属编辑弹窗

**Files:**

- Create: `ruoyi-ui/src/views/ccdiIntermediary/components/RelativeEditDialog.vue`
- Modify: `ruoyi-ui/src/views/ccdiIntermediary/index.vue`
- Reference: `ruoyi-ui/src/views/ccdiStaffFmyRelation/index.vue`

- [ ] **Step 1: 新建亲属弹窗组件骨架**

最小 props：

```js
visible
title
form
relationTypeOptions
certTypeOptions
ownerName
```

- [ ] **Step 2: 布置亲属字段**

至少包含：

```vue
姓名
证件号
证件类型
性别
手机号码
联系地址
亲属关系(personSubType)
备注
所属中介姓名(只读)
```

- [ ] **Step 3: 禁止选择“本人”**

Expected: 亲属关系选项中过滤掉 `本人`。

- [ ] **Step 4: 在 `index.vue` 中接入新增 / 编辑 / 删除亲属流程**

Expected: 首页点亲属记录可直接编辑；详情页也可新增亲属。

- [ ] **Step 5: 保存成功后刷新首页和详情内亲属列表**

Expected: 无需手工刷新页面。

- [ ] **Step 6: 提交亲属弹窗链路**

```bash
git add ruoyi-ui/src/views/ccdiIntermediary/components/RelativeEditDialog.vue ruoyi-ui/src/views/ccdiIntermediary/index.vue
git commit -m "feat: 新增中介亲属编辑弹窗"
```

### Task 6: 新增机构关系编辑弹窗

**Files:**

- Create: `ruoyi-ui/src/views/ccdiIntermediary/components/EnterpriseRelationEditDialog.vue`
- Modify: `ruoyi-ui/src/views/ccdiIntermediary/index.vue`
- Reference: `ruoyi-ui/src/views/ccdiCustEnterpriseRelation/index.vue`

- [ ] **Step 1: 新建机构关系弹窗组件骨架**

最小 props：

```js
visible
title
form
ownerName
```

- [ ] **Step 2: 布置机构关系字段**

固定字段为：

```vue
统一社会信用代码
关联角色/职务(relationPersonPost)
备注
所属中介姓名(只读)
```

- [ ] **Step 3: 只做关系维护，不出现机构主档字段**

Expected: 不出现企业性质、法定代表人等机构主档表单项。

- [ ] **Step 4: 在 `index.vue` 中接入新增 / 编辑 / 删除机构关系流程**

Expected: 首页点机构关系记录可直接编辑；详情页也可新增关系。

- [ ] **Step 5: 保存成功后刷新首页和详情内机构关系列表**

Expected: 新增关系后首页能查到该条记录。

- [ ] **Step 6: 提交机构关系弹窗链路**

```bash
git add ruoyi-ui/src/views/ccdiIntermediary/components/EnterpriseRelationEditDialog.vue ruoyi-ui/src/views/ccdiIntermediary/index.vue
git commit -m "feat: 新增中介机构关系编辑弹窗"
```

### Task 7: 将详情弹窗改为中介详情维护容器

**Files:**

- Modify: `ruoyi-ui/src/views/ccdiIntermediary/components/DetailDialog.vue`
- Modify: `ruoyi-ui/src/views/ccdiIntermediary/index.vue`

- [ ] **Step 1: 先定义详情容器需要的数据结构**

至少包括：

```js
personDetail
relativeList
enterpriseRelationList
```

- [ ] **Step 2: 将详情弹窗改为三个分区**

分区固定为：

```vue
中介基本信息
亲属信息
关联机构信息
```

- [ ] **Step 3: 在亲属分区增加“新增亲属 / 编辑 / 删除”**

Expected: 用户在中介详情中即可维护名下亲属。

- [ ] **Step 4: 在机构关系分区增加“新增关联机构 / 编辑 / 删除”**

Expected: 用户在中介详情中即可维护名下机构关系。

- [ ] **Step 5: 让首页新增成功后自动打开该详情容器**

Expected: 完整符合“先建中介，再在下面维护”的流程。

- [ ] **Step 6: 提交详情维护容器改造**

```bash
git add ruoyi-ui/src/views/ccdiIntermediary/components/DetailDialog.vue ruoyi-ui/src/views/ccdiIntermediary/index.vue
git commit -m "feat: 改造中介详情维护容器"
```

### Task 8: 执行前端构建验证

**Files:**

- Modify: `docs/plans/frontend/2026-04-17-intermediary-library-refactor-frontend-implementation.md`
  在执行阶段补充真实验证结果。

- [ ] **Step 1: 使用 nvm 切换前端 Node 版本**

Run: `cd /Users/wkc/Desktop/ccdi/ccdi/ruoyi-ui && source ~/.nvm/nvm.sh && nvm use 14.21.3`
Expected: 输出 `Now using node v14.21.3`

- [ ] **Step 2: 执行生产构建**

Run: `cd /Users/wkc/Desktop/ccdi/ccdi/ruoyi-ui && source ~/.nvm/nvm.sh && nvm use 14.21.3 && npm run build:prod`
Expected: 构建成功，无语法错误和模块缺失错误。

- [ ] **Step 3: 如需联调，启动前端后手工验证关键链路**

Run: `cd /Users/wkc/Desktop/ccdi/ccdi/ruoyi-ui && source ~/.nvm/nvm.sh && nvm use 14.21.3 && npm run dev`
Expected: 页面可打开，退出后主动结束进程。

- [ ] **Step 4: 记录真实执行结果**

Expected: 文档中补充实际命令与结果，不写假数据。

- [ ] **Step 5: 提交验证结果**

```bash
git add docs/plans/frontend/2026-04-17-intermediary-library-refactor-frontend-implementation.md
git commit -m "docs: 更新中介库前端实施计划执行结果"
```

## 验证命令

```bash
cd /Users/wkc/Desktop/ccdi/ccdi/ruoyi-ui
source ~/.nvm/nvm.sh && nvm use 14.21.3
npm run build:prod
```

## 完成标准

- 首页搜索字段调整为名称、证件号、记录类型、关联中介信息
- 首页列表固定展示名称、证件号、关联中介姓名、关联关系、创建时间
- 新增按钮只新增中介本人，不再新增机构中介主记录
- 首页能同时展示中介本人、亲属、机构关系三类记录
- 首页点击亲属或机构关系记录可直接进入各自编辑弹窗
- 中介详情支持维护中介本人、亲属列表、机构关系列表
- 前端已使用 `nvm` 指定 Node 版本并完成构建验证