ccdi/docs/plans/frontend/2026-04-26-enterprise-auto-fill-frontend-implementation.md

# 关联业务自动补入实体库 Frontend Implementation Plan

> **执行约束:** 按当前项目 `AGENTS.md` 执行；未获得用户明确要求时不启用 subagent。Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 验证前端通过现有企业来源枚举接口展示新增 `SUPPLIER=供应商`，并在真实页面确认自动补入实体库后的展示链路可用。

**Architecture:** 本次不新增前端交互，不修改前端源码。企业来源选项由后端 `/ccdi/enum/enterpriseSource` 返回，实体库管理页与招投标详情页沿用 `getEnterpriseSourceOptions()` 展示新增来源；前端工作重点是运行真实页面验证并记录结果。

**Tech Stack:** Vue 2, Element UI, npm, nvm, Playwright.

---

## File Structure

- No source changes expected: `ruoyi-ui/src/views/ccdiEnterpriseBaseInfo/index.vue`
  - 已通过 `getEnterpriseSourceOptions()` 获取企业来源。
- No source changes expected: `ruoyi-ui/src/views/ccdiPurchaseTransaction/index.vue`
  - 企业详情弹窗已通过 `getEnterpriseSourceOptions()` 格式化企业来源。
- Create or update: `docs/reports/implementation/2026-04-26-enterprise-auto-fill-implementation.md`
  - 补充前端真实页面验证结果。
- Generated test files:
  - 如需生成导入样本，放在 `output/playwright/` 或 `output/spreadsheet/`，不提交到 git。

## Task 1: 前端源码确认

**Files:**
- Read: `ruoyi-ui/src/views/ccdiEnterpriseBaseInfo/index.vue`
- Read: `ruoyi-ui/src/views/ccdiPurchaseTransaction/index.vue`
- Read: `ruoyi-ui/src/api/ccdiEnum.js`

- [ ] **Step 1: 确认企业来源接口使用点**

Run:

```bash
rg -n "getEnterpriseSourceOptions|formatEnterpriseSource|enterpriseSourceOptions" ruoyi-ui/src/views/ccdiEnterpriseBaseInfo/index.vue ruoyi-ui/src/views/ccdiPurchaseTransaction/index.vue ruoyi-ui/src/api/ccdiEnum.js
```

Expected:

- 实体库管理页调用 `getEnterpriseSourceOptions()`
- 招投标详情企业弹窗调用 `getEnterpriseSourceOptions()`
- API 路径为 `/ccdi/enum/enterpriseSource`

- [ ] **Step 2: 确认不存在本地硬编码映射**

Expected: 未发现页面本地写死企业来源映射；如发现硬编码映射，停止实施并先修订本计划。

## Task 2: 前端启动准备

**Files:**
- Read: `ruoyi-ui/package.json`
- Use: `ruoyi-ui/.nvmrc` if present

- [ ] **Step 1: 使用 nvm 确认 Node 版本**

Run:

```bash
cd ruoyi-ui
source ~/.nvm/nvm.sh
nvm use
node -v
```

Expected: 切换到项目要求的 Node 版本。

- [ ] **Step 2: 启动前端开发服务**

Run:

```bash
cd ruoyi-ui
source ~/.nvm/nvm.sh
nvm use
npm run dev
```

Expected: 前端服务启动成功，记录实际 URL。若端口占用，按 Vite/Vue CLI 输出使用实际端口。

- [ ] **Step 3: 启动后端**

Run:

```bash
sh bin/restart_java_backend.sh
```

Expected: 后端 `62318` 可访问。

测试结束后必须关闭本次启动的前后端进程。

## Task 3: 实体库管理页面验证

**Files:**
- Verify: real page `ruoyi-ui/src/views/ccdiEnterpriseBaseInfo/index.vue`
- Do not use: prototype pages

- [ ] **Step 1: Playwright 打开真实实体库管理页面**

进入实际路由：

```text
http://localhost:8080/maintain/enterpriseBaseInfo
```

Expected: 页面正常加载。

- [ ] **Step 2: 验证企业来源下拉包含供应商**

操作：

- 打开查询区“企业来源”下拉。
- 检查存在“供应商”选项。

Expected: 下拉出现“供应商”。

- [ ] **Step 3: 验证列表/详情展示**

准备后端自动补入的一条 `ent_source=SUPPLIER` 测试企业后：

- 在实体库管理页面搜索该统一社会信用代码。
- 检查列表企业来源显示“供应商”。
- 打开详情，检查企业来源显示“供应商”，风险等级为空时显示为空值占位。

Expected: 枚举中文展示正确。

## Task 4: 招投标真实页面验证

**Files:**
- Verify: `ruoyi-ui/src/views/ccdiPurchaseTransaction/index.vue`

- [ ] **Step 1: 打开真实招投标信息维护页面**

进入实际路由，例如：

```text
http://localhost:8080/maintain/purchaseTransaction
```

Expected: 页面正常加载。

- [ ] **Step 2: 新建含供应商统一信用代码的招投标记录**

使用真实页面新增测试数据：

- 采购事项 ID 使用本轮唯一测试值。
- 供应商明细中至少一条填写供应商名称和统一信用代码。

Expected: 保存成功。

- [ ] **Step 3: 回到实体库管理验证供应商自动补入**

用供应商统一信用代码查询实体库。

Expected:

- 能查到实体库记录。
- 企业名称为供应商名称。
- 企业来源显示“供应商”。
- 风险等级为空。

- [ ] **Step 4: 清理测试数据**

删除本轮新建的招投标测试数据和自动补入的实体库测试数据。若实体库记录已有关联限制，先删除业务数据再删除实体库记录。

Expected: 页面列表回到测试前状态。

## Task 5: 导入页面验证

**Files:**
- Generated samples: `output/playwright/` or `output/spreadsheet/`

- [ ] **Step 1: 在真实页面下载导入模板**

必须从当前业务页面点击下载模板，不手工凭记忆构造表头。

Expected: 获取当前模板。

- [ ] **Step 2: 基于模板生成测试文件**

至少覆盖：

- 员工亲属实体关联：页面 `/maintain/staffEnterpriseRelation`，点击“导入”后在弹窗中点击“下载模板”，接口 `ccdi/staffEnterpriseRelation/importTemplate`，上传接口 `/ccdi/staffEnterpriseRelation/importData`，验证成功行实体自动补入 `EMP_RELATION`。
- 信贷客户实体关联：页面 `/maintain/custEnterpriseRelation`，点击“导入”后在弹窗中点击“下载模板”，接口 `ccdi/custEnterpriseRelation/importTemplate`，上传接口 `/ccdi/custEnterpriseRelation/importData`，验证成功行实体自动补入 `CREDIT_CUSTOMER`。
- 中介实体关联：页面 `/maintain/intermediary`，点击“导入中介实体关联关系”，在导入弹窗下载模板，接口 `ccdi/intermediary/importEnterpriseRelationTemplate`，上传接口 `/ccdi/intermediary/importEnterpriseRelationData`，验证成功行实体自动补入 `INTERMEDIARY` 且风险等级高风险。
- 招投标信息维护：页面 `/maintain/purchaseTransaction`，点击“导入”后在弹窗中点击“下载模板”，接口 `ccdi/purchaseTransaction/importTemplate`，上传接口 `/ccdi/purchaseTransaction/importData`，验证供应商统一信用代码自动补入 `SUPPLIER`。
- 每个页面至少包含一个混合成功失败样本，验证失败行不补实体。

Expected: 测试文件保存在 `output/playwright/` 或 `output/spreadsheet/`，不提交 git。

- [ ] **Step 3: 上传并核对导入状态**

在真实页面上传文件，核对：

- 页面提示
- 导入状态
- 失败记录弹窗
- 列表总数变化
- 实体库是否新增对应实体

Expected: 成功行补实体，失败行不补实体。

- [ ] **Step 4: 清理测试数据和任务缓存**

删除本轮成功写入的业务数据和实体库数据，清理页面本地导入任务缓存。

Expected: 页面和数据库不残留本轮测试数据。

## Task 6: 记录验证结果

**Files:**
- Modify: `docs/reports/implementation/2026-04-26-enterprise-auto-fill-implementation.md`

- [ ] **Step 1: 补充前端验证记录**

记录：

```markdown
## 前端验证
- Node 版本：
- 前端 URL：
- 后端 URL：
- 实体库企业来源“供应商”展示：
- 招投标供应商自动补入页面验证：
- 导入页面验证：
- 测试数据清理：
```

- [ ] **Step 2: 停止测试进程**

停止本次启动的前端和后端进程。

Expected: 无测试进程残留。

- [ ] **Step 3: 检查生成文件未进入 git**

Run:

```bash
git status --short
```

Expected: `output/playwright/`、`output/spreadsheet/` 下生成测试文件不在待提交范围。