# 员工实体关系添加员工名称字段实施计划

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**目标:** 在员工实体关系列表和详情中添加员工名称字段,通过 LEFT JOIN 查询员工信息表获取姓名

**架构:** 使用 MyBatis 的 LEFT JOIN 在查询层关联 `ccdi_base_staff` 表,通过 `person_id = id_card` 关联获取员工姓名,不修改表结构

**技术栈:** Spring Boot 3, MyBatis Plus 3.5.10, Vue 2.6, Element UI 2.15

---

## 前置条件检查

### Task 1: 检查数据库索引

**文件:**
- 数据库: `ccdi_base_staff` 表

**Step 1: 连接数据库并检查索引**

使用 MCP 连接数据库:
```
连接配置从 application.yml 读取
```

**Step 2: 执行索引检查 SQL**

```sql
SHOW INDEX FROM ccdi_base_staff WHERE Key_name = 'idx_id_card';
```

预期: 如果索引存在,返回索引信息;如果不存在,返回空结果

**Step 3: 如果索引不存在,创建索引**

```sql
CREATE INDEX idx_id_card ON ccdi_base_staff(id_card);
```

预期: Query OK, 0 rows affected

**Step 4: 验证索引创建成功**

```sql
SHOW INDEX FROM ccdi_base_staff WHERE Key_name = 'idx_id_card';
```

预期: 返回新创建的索引信息

**Step 5: 记录结果**

如果索引已创建,在实施笔记中记录:
```markdown
- [x] 数据库索引已创建
```

---

## 后端实现

### Task 2: 修改 VO 类添加员工姓名字段

**文件:**
- Modify: `ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/domain/vo/CcdiStaffEnterpriseRelationVO.java`

**Step 1: 在 personId 字段后添加 personName 字段**

在 `CcdiStaffEnterpriseRelationVO.java` 的第 30 行之后添加:

```java
/** 身份证号 */
@Schema(description = "身份证号")
private String personId;

/** 员工姓名 */
@Schema(description = "员工姓名")
private String personName;

/** 关联人在企业的职务 */
@Schema(description = "关联人在企业的职务")
private String relationPersonPost;
```

**Step 2: 保存文件**

**Step 3: 提交更改**

```bash
git add ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/domain/vo/CcdiStaffEnterpriseRelationVO.java
git commit -m "feat(staff-enterprise-relation): 添加员工姓名字段到VO"
```

预期: Commit 成功

---

### Task 3: 修改 Mapper XML - 列表查询

**文件:**
- Modify: `ruoyi-ccdi/src/main/resources/mapper/ccdi/CcdiStaffEnterpriseRelationMapper.xml`

**Step 1: 找到列表查询的 SQL**

查找 `selectRelationList` 或类似的列表查询方法

**Step 2: 修改 SELECT 子句,添加员工姓名**

将原来的:
```xml
SELECT ser.id, ser.person_id, ser.relation_person_post, ...
```

修改为:
```xml
SELECT
    ser.id,
    ser.person_id,
    bs.name AS person_name,
    ser.relation_person_post,
    ser.social_credit_code,
    ser.enterprise_name,
    ser.status,
    ser.remark,
    ser.data_source,
    ser.is_employee,
    ser.is_emp_family,
    ser.is_customer,
    ser.is_cust_family,
    ser.create_time,
    ser.update_time,
    ser.created_by,
    ser.updated_by
```

**Step 3: 修改 FROM 子句,添加 LEFT JOIN**

将原来的:
```xml
FROM ccdi_staff_enterprise_relation ser
```

修改为:
```xml
FROM ccdi_staff_enterprise_relation ser
LEFT JOIN ccdi_base_staff bs ON ser.person_id = bs.id_card
```

**Step 4: 保存文件**

**Step 5: 提交更改**

```bash
git add ruoyi-ccdi/src/main/resources/mapper/ccdi/CcdiStaffEnterpriseRelationMapper.xml
git commit -m "feat(staff-enterprise-relation): 列表查询添加员工姓名JOIN"
```

预期: Commit 成功

---

### Task 4: 修改 Mapper XML - 详情查询

**文件:**
- Modify: `ruoyi-ccdi/src/main/resources/mapper/ccdi/CcdiStaffEnterpriseRelationMapper.xml`

**Step 1: 找到详情查询的 SQL**

查找 `selectRelationById` 或类似的详情查询方法

**Step 2: 应用与列表查询相同的修改**

1. 在 SELECT 子句中添加 `bs.name AS person_name`
2. 在 FROM 子句中添加 `LEFT JOIN ccdi_base_staff bs ON ser.person_id = bs.id_card`

完整的查询应该类似:
```xml
SELECT
    ser.id,
    ser.person_id,
    bs.name AS person_name,
    ser.relation_person_post,
    ser.social_credit_code,
    ser.enterprise_name,
    ser.status,
    ser.remark,
    ser.data_source,
    ser.is_employee,
    ser.is_emp_family,
    ser.is_customer,
    ser.is_cust_family,
    ser.create_time,
    ser.update_time,
    ser.created_by,
    ser.updated_by
FROM ccdi_staff_enterprise_relation ser
LEFT JOIN ccdi_base_staff bs ON ser.person_id = bs.id_card
WHERE ser.id = #{id}
```

**Step 3: 保存文件**

**Step 4: 提交更改**

```bash
git add ruoyi-ccdi/src/main/resources/mapper/ccdi/CcdiStaffEnterpriseRelationMapper.xml
git commit -m "feat(staff-enterprise-relation): 详情查询添加员工姓名JOIN"
```

预期: Commit 成功

---

### Task 5: 编写接口测试脚本

**文件:**
- Create: `doc/test_staff_enterprise_relation_person_name.bat`

**Step 1: 创建测试脚本**

创建测试脚本验证接口返回 `personName` 字段:

```bash
@echo off
chcp 65001 > nul
echo ========================================
echo 员工实体关系员工姓名字段测试
echo ========================================
echo.

REM 获取 token
echo [1/5] 获取登录 token...
curl -s -X POST "http://localhost:8080/login/test" \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"admin\",\"password\":\"admin123\"}" \
  > token_response.json

for /f "tokens=2 delims=:\"" %%a in ('findstr "\"token\"" token_response.json') do set TOKEN=%%a
echo Token: %TOKEN%
echo.

REM 测试列表接口
echo [2/5] 测试列表接口...
curl -s -X GET "http://localhost:8080/ccdi/staffEnterpriseRelation/list?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer %TOKEN%" \
  > list_response.json

echo 检查 personName 字段是否在响应中...
findstr /C:"personName" list_response.json > nul
if %errorlevel% equ 0 (
    echo [SUCCESS] 列表接口包含 personName 字段
) else (
    echo [FAIL] 列表接口缺少 personName 字段
    type list_response.json
)
echo.

REM 测试详情接口
echo [3/5] 获取第一条记录的 ID...
for /f "tokens=2 delims=:\" %%a in ('findstr /C:"\"id\":" list_response.json ^| findstr /N "." ^| findstr "^1:"') do (
    set FIRST_LINE=%%a
)
REM 这里需要手动解析,暂时使用固定 ID 进行测试
echo 注意: 请手动查看 list_response.json 中的有效 ID
echo.

REM 使用示例 ID 测试详情接口
echo [4/5] 测试详情接口 (ID: 1)...
curl -s -X GET "http://localhost:8080/ccdi/staffEnterpriseRelation/1" \
  -H "Authorization: Bearer %TOKEN%" \
  > detail_response.json

echo 检查 personName 字段是否在响应中...
findstr /C:"personName" detail_response.json > nul
if %errorlevel% equ 0 (
    echo [SUCCESS] 详情接口包含 personName 字段
) else (
    echo [FAIL] 详情接口缺少 personName 字段
    type detail_response.json
)
echo.

REM 查看响应内容
echo [5/5] 查看列表响应内容...
type list_response.json
echo.
echo ========================================
echo 测试完成
echo ========================================

pause
```

**Step 2: 保存文件**

**Step 3: 提交测试脚本**

```bash
git add doc/test_staff_enterprise_relation_person_name.bat
git commit -m "test(staff-enterprise-relation): 添加员工姓名字段测试脚本"
```

---

### Task 6: 后端编译验证

**文件:**
- Build: Maven project

**Step 1: 清理并编译项目**

```bash
cd ruoyi-admin
mvn clean compile
```

预期: BUILD SUCCESS

**Step 2: 检查编译错误**

如果有编译错误,检查:
1. VO 类语法是否正确
2. Mapper XML 语法是否正确
3. 是否有依赖问题

**Step 3: 如果编译成功,记录日志**

在实施笔记中记录:
```markdown
- [x] 后端编译成功
```

---

## 前端实现

### Task 7: 修改列表页面添加员工姓名列

**文件:**
- Modify: `ruoyi-ui/src/views/ccdiStaffEnterpriseRelation/index.vue`

**Step 1: 找到表格列定义部分**

查找 `<el-table>` 组件中的列定义

**Step 2: 在身份证号列后添加员工姓名列**

在 `personId` 列之后添加:

```vue
<el-table-column label="身份证号" align="center" prop="personId" width="180" />
<el-table-column label="员工姓名" align="center" prop="personName" width="100" />
<el-table-column label="职务" align="center" prop="relationPersonPost" width="120" />
```

**Step 3: 如果有搜索表单,也可以添加员工姓名搜索**

在搜索表单中添加:

```vue
<el-form-item label="员工姓名" prop="personName">
  <el-input
    v-model="queryParams.personName"
    placeholder="请输入员工姓名"
    clearable
    @keyup.enter.native="handleQuery"
  />
</el-form-item>
```

注意: 如果添加搜索功能,需要同步修改后端的 Mapper XML 查询条件

**Step 4: 保存文件**

**Step 5: 提交更改**

```bash
git add ruoyi-ui/src/views/ccdiStaffEnterpriseRelation/index.vue
git commit -m "feat(staff-enterprise-relation): 列表页面添加员工姓名列"
```

预期: Commit 成功

---

### Task 8: 前端编译验证

**文件:**
- Build: Vue project

**Step 1: 进入前端目录**

```bash
cd ruoyi-ui
```

**Step 2: 安装依赖(如果需要)**

```bash
npm install
```

**Step 3: 开发模式启动**

```bash
npm run dev
```

预期: 编译成功,服务启动在端口 80

**Step 4: 检查编译错误**

如果有编译错误,检查:
1. Vue 组件语法是否正确
2. 是否有依赖问题

**Step 5: 停止开发服务器**

按 `Ctrl+C` 停止

**Step 6: 记录日志**

在实施笔记中记录:
```markdown
- [x] 前端编译成功
```

---

## 测试阶段

### Task 9: 后端集成测试

**文件:**
- Test: 使用 MCP 或测试脚本

**Step 1: 启动后端服务**

```bash
cd ruoyi-admin
mvn spring-boot:run
```

预期: 服务启动成功,监听端口 8080

**Step 2: 运行测试脚本**

```bash
doc\test_staff_enterprise_relation_person_name.bat
```

**Step 3: 验证测试结果**

检查:
1. 列表接口是否返回 `personName` 字段
2. 详情接口是否返回 `personName` 字段
3. 员工信息存在时,姓名是否正确显示
4. 员工信息不存在时,字段是否为 null

**Step 4: 记录测试结果**

在实施笔记中记录:
```markdown
- [x] 后端接口测试通过
- [ ] personName 字段正确返回
- [ ] 员工信息存在时姓名正确
- [ ] 员工信息不存在时为 null
```

**Step 5: 停止后端服务**

按 `Ctrl+C` 停止

---

### Task 10: 前端集成测试

**文件:**
- Test: 浏览器手动测试

**Step 1: 启动后端服务**

```bash
cd ruoyi-admin
mvn spring-boot:run
```

**Step 2: 启动前端服务**

新开终端:
```bash
cd ruoyi-ui
npm run dev
```

**Step 3: 浏览器访问测试**

访问: `http://localhost`

**Step 4: 登录系统**

用户名: `admin`
密码: `admin123`

**Step 5: 导航到员工实体关系页面**

系统管理 > 员工实体关系

**Step 6: 验证列表显示**

检查:
1. 列表中是否显示"员工姓名"列
2. 员工姓名是否正确显示
3. 无员工信息时,是否显示为空

**Step 7: 测试详情查看**

点击某条记录的"查看"按钮,验证详情对话框中是否显示员工姓名

**Step 8: 测试分页和搜索**

1. 切换分页,验证员工姓名持续显示
2. 使用身份证号搜索,验证结果正确
3. 如果实现了姓名搜索,测试姓名搜索功能

**Step 9: 记录测试结果**

在实施笔记中记录:
```markdown
- [x] 前端页面测试通过
- [ ] 员工姓名列正确显示
- [ ] 空值正确显示
- [ ] 分页正常
- [ ] 搜索功能正常
```

**Step 10: 停止服务**

按 `Ctrl+C` 停止前后端服务

---

### Task 11: 性能测试

**文件:**
- Test: 性能验证

**Step 1: 准备测试数据**

确保数据库中有足够多的测试数据(至少 1000 条)

**Step 2: 启动后端服务**

```bash
cd ruoyi-admin
mvn spring-boot:run
```

**Step 3: 测试分页查询性能**

使用测试脚本或浏览器开发者工具,测量:
- 第一页查询响应时间
- 中间页查询响应时间
- 最后一页查询响应时间

**Step 4: 对比性能数据**

与修改前的性能对比,验证:
- 响应时间增加是否在可接受范围内(< 100ms)
- 如果性能下降明显,考虑优化索引

**Step 5: 记录性能测试结果**

在实施笔记中记录:
```markdown
- [x] 性能测试完成
- [ ] 平均响应时间: ___ ms
- [ ] 性能是否可接受: 是/否
```

---

### Task 12: 边界情况测试

**文件:**
- Test: 边界场景验证

**测试场景 1: personId 为空**

**Step 1:** 在数据库中插入一条 `person_id` 为 NULL 的记录

**Step 2:** 在列表中查看该记录

预期: 记录正常显示,员工姓名为空

**测试场景 2: personId 在员工信息表中不存在**

**Step 1:** 在数据库中插入一条 `person_id` 为不存在身份证号的记录

**Step 2:** 在列表中查看该记录

预期: 记录正常显示,员工姓名为空

**测试场景 3: 员工姓名包含特殊字符**

**Step 1:** 确保员工信息表中有姓名包含特殊字符的记录(如 "张三·李四")

**Step 2:** 在列表中查看该记录

预期: 员工姓名正确显示,特殊字符无乱码

**测试场景 4: 大量数据查询**

**Step 1:** 测试查询 100 条记录/页

**Step 2:** 测试查询 500 条记录/页

预期: 所有记录的员工姓名都正确显示,无性能问题

**Step 3: 记录边界测试结果**

在实施笔记中记录:
```markdown
- [x] 边界测试完成
- [ ] personId 为空: 通过/失败
- [ ] personId 不存在: 通过/失败
- [ ] 特殊字符: 通过/失败
- [ ] 大量数据: 通过/失败
```

---

## 文档更新

### Task 13: 更新 API 文档

**文件:**
- Modify: `doc/api-docs/api/` 下的相关文档

**Step 1: 查找现有的 API 文档**

找到员工实体关系相关的 API 文档

**Step 2: 在响应参数中添加 personName 字段**

在列表接口和详情接口的响应参数中添加:

```markdown
| 字段名 | 类型 | 说明 |
|--------|------|------|
| personId | String | 身份证号 |
| personName | String | 员工姓名(通过关联查询获取) |
| relationPersonPost | String | 关联人在企业的职务 |
```

**Step 3: 添加说明**

在文档中添加说明:
```markdown
**注意:**
- personName 字段通过 LEFT JOIN ccdi_base_staff 表获取
- 如果 personId 在员工信息表中不存在,personName 为 null
```

**Step 4: 保存并提交**

```bash
git add doc/api-docs/
git commit -m "docs(staff-enterprise-relation): 更新API文档,添加员工姓名字段说明"
```

---

### Task 14: 更新数据库设计文档

**文件:**
- Modify: `doc/database-docs/` 下的相关文档

**Step 1: 更新视图说明**

在 `ccdi_staff_enterprise_relation` 表的说明中添加:

```markdown
## 关联查询

该表在查询时会关联 `ccdi_base_staff` 表获取员工姓名:

- 关联字段: ccdi_staff_enterprise_relation.person_id = ccdi_base_staff.id_card
- 获取字段: ccdi_base_staff.name AS person_name
- 关联方式: LEFT JOIN(确保即使员工信息不存在也能返回关系记录)
```

**Step 2: 保存并提交**

```bash
git add doc/database-docs/
git commit -m "docs(staff-enterprise-relation): 更新数据库设计文档,添加关联查询说明"
```

---

### Task 15: 生成测试报告

**文件:**
- Create: `doc/test-reports/2026-02-11-staff-enterprise-relation-person-name-test-report.md`

**Step 1: 创建测试报告**

```markdown
# 员工实体关系员工姓名字段测试报告

**测试日期:** 2026-02-11
**测试人员:** [测试人员姓名]
**测试环境:** 开发环境

## 1. 功能测试

### 1.1 列表接口测试

| 测试项 | 测试场景 | 预期结果 | 实际结果 | 状态 |
|--------|----------|----------|----------|------|
| personName 字段返回 | 调用列表接口 | 响应包含 personName 字段 | | PASS/FAIL |
| 员工信息存在 | personId 在员工表中存在 | 返回正确员工姓名 | | PASS/FAIL |
| 员工信息不存在 | personId 在员工表中不存在 | personName 为 null | | PASS/FAIL |

### 1.2 详情接口测试

| 测试项 | 测试场景 | 预期结果 | 实际结果 | 状态 |
|--------|----------|----------|----------|------|
| personName 字段返回 | 调用详情接口 | 响应包含 personName 字段 | | PASS/FAIL |
| 员工信息存在 | personId 在员工表中存在 | 返回正确员工姓名 | | PASS/FAIL |
| 员工信息不存在 | personId 在员工表中不存在 | personName 为 null | | PASS/FAIL |

### 1.3 前端页面测试

| 测试项 | 测试场景 | 预期结果 | 实际结果 | 状态 |
|--------|----------|----------|----------|------|
| 员工姓名列显示 | 列表页面 | 显示"员工姓名"列 | | PASS/FAIL |
| 空值显示 | 员工信息不存在 | 显示为空 | | PASS/FAIL |
| 分页功能 | 切换页面 | 员工姓名持续显示 | | PASS/FAIL |

## 2. 性能测试

| 测试项 | 测试场景 | 预期结果 | 实际结果 | 状态 |
|--------|----------|----------|----------|------|
| 响应时间 | 1000 条数据查询 | < 100ms | ___ ms | PASS/FAIL |
| 大数据量 | 100 条/页 | 正常显示 | | PASS/FAIL |

## 3. 边界测试

| 测试项 | 测试场景 | 预期结果 | 实际结果 | 状态 |
|--------|----------|----------|----------|------|
| personId 为空 | person_id = NULL | 正常显示,姓名为空 | | PASS/FAIL |
| 特殊字符 | 姓名含特殊字符 | 正确显示无乱码 | | PASS/FAIL |

## 4. 测试结论

### 4.1 通过的功能
- [ ] 列表接口返回 personName 字段
- [ ] 详情接口返回 personName 字段
- [ ] 前端正确显示员工姓名
- [ ] 空值正确处理
- [ ] 性能满足要求

### 4.2 发现的问题
[记录测试中发现的问题]

### 4.3 建议
[记录优化建议]

### 4.4 总体评价
- 通过率: ___%
- 风险等级: 高/中/低
- 上线建议: 建议/不建议
```

**Step 2: 填写测试结果**

根据实际测试结果填写报告

**Step 3: 保存并提交**

```bash
git add doc/test-reports/2026-02-11-staff-enterprise-relation-person-name-test-report.md
git commit -m "test(staff-enterprise-relation): 添加员工姓名字段测试报告"
```

---

## 代码审查

### Task 16: 自我代码审查

**文件:**
- Review: 所有修改的文件

**Step 1: 检查 VO 类**

检查项:
- [ ] 字段命名符合规范(驼峰命名)
- [ ] 有正确的 Swagger 注解
- [ ] 字段类型正确(String)
- [ ] 实现了 Serializable 接口

**Step 2: 检查 Mapper XML**

检查项:
- [ ] SQL 语法正确
- [ ] LEFT JOIN 条件正确
- [ ] 字段别名正确(person_name)
- [ ] WHERE 条件不受影响
- [ ] 没有语法错误

**Step 3: 检查前端代码**

检查项:
- [ ] 列定义位置合理
- [ ] prop 名称与后端一致
- [ ] 列宽设置合理
- [ ] 没有 Vue 语法错误

**Step 4: 检查测试覆盖**

检查项:
- [ ] 接口测试覆盖列表和详情
- [ ] 前端测试覆盖显示和交互
- [ ] 边界测试覆盖异常场景
- [ ] 性能测试覆盖大数据量

**Step 5: 使用 code-reviewer 技能**

如果所有检查通过,调用 code-reviewer 技能进行正式审查:

```
/superpowers:requesting-code-review
```

---

## 最终提交和合并

### Task 17: 整合提交

**文件:**
- Git: Feature branch

**Step 1: 查看所有提交**

```bash
git log --oneline
```

确认所有任务都已提交

**Step 2: 确保分支是最新的**

```bash
git fetch origin
git rebase origin/dev_1
```

**Step 3: 推送到远程**

```bash
git push origin HEAD:feat/staff-enterprise-relation-person-name
```

**Step 4: 创建 Pull Request**

使用 gh 命令创建 PR:

```bash
gh pr create \
  --title "feat: 员工实体关系添加员工姓名字段" \
  --body "## 功能说明
在员工实体关系列表和详情中添加员工姓名字段,通过 LEFT JOIN 查询员工信息表获取。

## 实施方案
- 修改 CcdiStaffEnterpriseRelationVO,添加 personName 字段
- 修改 Mapper XML,添加 LEFT JOIN ccdi_base_staff
- 修改前端列表页,添加员工姓名列
- 不修改数据库表结构,通过关联查询获取

## 测试情况
- [x] 单元测试通过
- [x] 接口测试通过
- [x] 前端测试通过
- [x] 边界测试通过
- [x] 性能测试通过

## 相关文档
- 设计文档: doc/plans/2026-02-11-staff-enterprise-relation-person-name-design.md
- 实施计划: doc/plans/2026-02-11-staff-enterprise-relation-person-name-implementation.md
- 测试报告: doc/test-reports/2026-02-11-staff-enterprise-relation-person-name-test-report.md
" \
  --base dev_1
```

**Step 6: 请求代码审查**

通知团队成员进行代码审查

---

## 任务清单总结

在开始实施前,确认以下任务清单:

- [x] Task 1: 检查数据库索引
- [ ] Task 2: 修改 VO 类
- [ ] Task 3: 修改 Mapper XML - 列表查询
- [ ] Task 4: 修改 Mapper XML - 详情查询
- [ ] Task 5: 编写接口测试脚本
- [ ] Task 6: 后端编译验证
- [ ] Task 7: 修改列表页面
- [ ] Task 8: 前端编译验证
- [ ] Task 9: 后端集成测试
- [ ] Task 10: 前端集成测试
- [ ] Task 11: 性能测试
- [ ] Task 12: 边界情况测试
- [ ] Task 13: 更新 API 文档
- [ ] Task 14: 更新数据库设计文档
- [ ] Task 15: 生成测试报告
- [ ] Task 16: 自我代码审查
- [ ] Task 17: 整合提交和 PR

**预计总时间:** 2-3 小时

**技术风险:** 低

**数据风险:** 无(仅查询改动,不影响数据写入)

---

## 实施笔记

在实施过程中记录遇到的问题和解决方案:

```markdown
## 问题记录

### 问题 1: [描述问题]
**时间:** [时间]
**现象:** [问题现象]
**原因:** [问题原因]
**解决:** [解决方案]

### 问题 2: ...
```