wkc/ccdi

Fork 0

Files

wkc e1a1083c21 docs(staff-enterprise-relation): 标记Task 1为已完成

2026-02-11 14:32:51 +08:00

21 KiB

Raw Blame History

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

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

SHOW INDEX FROM ccdi_base_staff WHERE Key_name = 'idx_id_card';

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

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

CREATE INDEX idx_id_card ON ccdi_base_staff(id_card);

预期: Query OK, 0 rows affected

Step 4: 验证索引创建成功

SHOW INDEX FROM ccdi_base_staff WHERE Key_name = 'idx_id_card';

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

Step 5: 记录结果

如果索引已创建,在实施笔记中记录:

- [x] 数据库索引已创建

后端实现

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

文件:

Modify: ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/domain/vo/CcdiStaffEnterpriseRelationVO.java

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

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

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

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

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

Step 2: 保存文件

Step 3: 提交更改

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 子句,添加员工姓名

将原来的:

SELECT ser.id, ser.person_id, ser.relation_person_post, ...

修改为:

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

将原来的:

FROM ccdi_staff_enterprise_relation ser

修改为:

FROM ccdi_staff_enterprise_relation ser
LEFT JOIN ccdi_base_staff bs ON ser.person_id = bs.id_card

Step 4: 保存文件

Step 5: 提交更改

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: 应用与列表查询相同的修改

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

完整的查询应该类似:

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: 提交更改

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 字段:

@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: 提交测试脚本

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

Task 6: 后端编译验证

文件:

Build: Maven project

Step 1: 清理并编译项目

cd ruoyi-admin
mvn clean compile

预期: BUILD SUCCESS

Step 2: 检查编译错误

如果有编译错误,检查:

VO 类语法是否正确
Mapper XML 语法是否正确
是否有依赖问题

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

在实施笔记中记录:

- [x] 后端编译成功

前端实现

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

文件:

Modify: ruoyi-ui/src/views/ccdiStaffEnterpriseRelation/index.vue

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

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

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

在 personId 列之后添加:

<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: 如果有搜索表单,也可以添加员工姓名搜索

在搜索表单中添加:

<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: 提交更改

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

预期: Commit 成功

Task 8: 前端编译验证

文件:

Build: Vue project

Step 1: 进入前端目录

cd ruoyi-ui

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

npm install

Step 3: 开发模式启动

npm run dev

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

Step 4: 检查编译错误

如果有编译错误,检查:

Vue 组件语法是否正确
是否有依赖问题

Step 5: 停止开发服务器

按 Ctrl+C 停止

Step 6: 记录日志

在实施笔记中记录:

- [x] 前端编译成功

测试阶段

Task 9: 后端集成测试

文件:

Test: 使用 MCP 或测试脚本

Step 1: 启动后端服务

cd ruoyi-admin
mvn spring-boot:run

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

Step 2: 运行测试脚本

doc\test_staff_enterprise_relation_person_name.bat

Step 3: 验证测试结果

检查:

列表接口是否返回 personName 字段
详情接口是否返回 personName 字段
员工信息存在时,姓名是否正确显示
员工信息不存在时,字段是否为 null

Step 4: 记录测试结果

在实施笔记中记录:

- [x] 后端接口测试通过
- [ ] personName 字段正确返回
- [ ] 员工信息存在时姓名正确
- [ ] 员工信息不存在时为 null

Step 5: 停止后端服务

按 Ctrl+C 停止

Task 10: 前端集成测试

文件:

Test: 浏览器手动测试

Step 1: 启动后端服务

cd ruoyi-admin
mvn spring-boot:run

Step 2: 启动前端服务

新开终端:

cd ruoyi-ui
npm run dev

Step 3: 浏览器访问测试

访问: http://localhost

Step 4: 登录系统

用户名: admin 密码: admin123

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

系统管理 > 员工实体关系

Step 6: 验证列表显示

检查:

列表中是否显示"员工姓名"列
员工姓名是否正确显示
无员工信息时,是否显示为空

Step 7: 测试详情查看

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

Step 8: 测试分页和搜索

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

Step 9: 记录测试结果

在实施笔记中记录:

- [x] 前端页面测试通过
- [ ] 员工姓名列正确显示
- [ ] 空值正确显示
- [ ] 分页正常
- [ ] 搜索功能正常

Step 10: 停止服务

按 Ctrl+C 停止前后端服务

Task 11: 性能测试

文件:

Test: 性能验证

Step 1: 准备测试数据

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

Step 2: 启动后端服务

cd ruoyi-admin
mvn spring-boot:run

Step 3: 测试分页查询性能

使用测试脚本或浏览器开发者工具,测量:

第一页查询响应时间
中间页查询响应时间
最后一页查询响应时间

Step 4: 对比性能数据

与修改前的性能对比,验证:

响应时间增加是否在可接受范围内(< 100ms)
如果性能下降明显,考虑优化索引

Step 5: 记录性能测试结果

在实施笔记中记录:

- [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: 记录边界测试结果

在实施笔记中记录:

- [x] 边界测试完成
- [ ] personId 为空: 通过/失败
- [ ] personId 不存在: 通过/失败
- [ ] 特殊字符: 通过/失败
- [ ] 大量数据: 通过/失败

文档更新

Task 13: 更新 API 文档

文件:

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

Step 1: 查找现有的 API 文档

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

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

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

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

Step 3: 添加说明

在文档中添加说明:

**注意:**
- personName 字段通过 LEFT JOIN ccdi_base_staff 表获取
- 如果 personId 在员工信息表中不存在,personName 为 null

Step 4: 保存并提交

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 表的说明中添加:

## 关联查询

该表在查询时会关联 `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: 保存并提交

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: 创建测试报告

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

**测试日期:** 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: 保存并提交

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: 查看所有提交

git log --oneline

确认所有任务都已提交

Step 2: 确保分支是最新的

git fetch origin
git rebase origin/dev_1

Step 3: 推送到远程

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

Step 4: 创建 Pull Request

使用 gh 命令创建 PR:

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: 请求代码审查

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

任务清单总结

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

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 小时

技术风险: 低

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

实施笔记

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

## 问题记录

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

### 问题 2: ...

21 KiB Raw Blame History

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

前置条件检查

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: 整合提交

任务清单总结

实施笔记

21 KiB

Raw Blame History