wkc/ccdi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7cc0dd30f1a404ca054534a21bf7756c87a9c6c2
ccdi/doc/plans/2026-02-11-staff-enterprise-relation-person-name-implementation.md

950 lines
21 KiB
Markdown
Raw Normal View History

docs(staff-enterprise-relation): 标记Task 1为已完成
2026-02-11 14:32:51 +08:00
# 员工实体关系添加员工名称字段实施计划
> **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: ...
```
Reference in New Issue Copy Permalink