ccdi/doc/requirements/designs/2026-02-09-employee-table-rename-to-base-staff.md

员工信息表重命名设计文档

创建日期: 2026-02-09 作者: Claude 版本: 1.0

---

1. 概述

1.1 变更目的

将员工信息表 ccdi_employee 重命名为 ccdi_base_staff，并同步更新所有相关的 Java 类名、字段名和权限字符，保持代码命名的一致性和可读性。

1.2 变更范围

• 数据库: 表名、字段名、索引
• 后端: Entity、DTO、VO、Mapper、Service、Controller
• 前端: API 调用、页面组件、权限指令
• 权限: 菜单权限、按钮权限

1.3 环境说明

• 开发环境，无生产数据
• 无需数据迁移
• 变更风险可控

---

2. 数据库变更

2.1 表名变更

-- 表重命名（已完成）
RENAME TABLE ccdi_employee TO ccdi_base_staff;

2.2 字段变更

原字段名	新字段名	类型	说明
employee_id	staff_id	BIGINT(20)	主键，员工ID
teller_no	删除	VARCHAR(50)	柜员号字段已移除

2.3 保持不变的字段

以下字段保持不变：

• name VARCHAR(100) - 姓名
• dept_id BIGINT(20) - 所属部门ID
• id_card VARCHAR(18) - 身份证号
• phone VARCHAR(11) - 电话
• hire_date DATE - 入职时间
• status CHAR(1) - 状态
• create_by, create_time, update_by, update_time - 审计字段

2.4 索引变更

• 主键索引：PRIMARY KEY (staff_id)
• 普通索引：idx_dept_id, idx_status
• 删除 uk_teller_no 唯一索引（已随字段删除）

---

3. 后端代码变更

3.1 Entity 层

类名变更:

CcdiEmployee.java → CcdiBaseStaff.java

字段变更:

// 主键字段
private Long employeeId;  →  private Long staffId;

// 删除字段
- private String tellerNo;

// @TableName 注解
@TableName("ccdi_employee")  →  @TableName("ccdi_base_staff")

// @TableId 注解
@TableId(type = IdType.INPUT)  // 保持不变

3.2 DTO/VO 层

所有 DTO/VO 类需要同步重命名：

原类名	新类名
CcdiEmployeeAddDTO	CcdiBaseStaffAddDTO
CcdiEmployeeEditDTO	CcdiBaseStaffEditDTO
CcdiEmployeeQueryDTO	CcdiBaseStaffQueryDTO
CcdiEmployeeVO	CcdiBaseStaffVO
CcdiEmployeeExcel	CcdiBaseStaffExcel

字段变更：

• employeeId → staffId
• 删除 tellerNo

3.3 Mapper 层

接口变更:

CcdiEmployeeMapper.java → CcdiBaseStaffMapper.java

XML 文件变更:

CcdiEmployeeMapper.xml → CcdiBaseStaffMapper.xml

SQL 语句更新:

<!-- 所有 SQL 中的字段名更新 -->
employee_id  →  staff_id
teller_no    →  删除相关查询和条件

<!-- ResultMap 更新 -->
<id property="employeeId" column="employee_id"/>
  →
<id property="staffId" column="staff_id"/>

3.4 Service 层

接口和实现类变更:

ICcdiEmployeeService.java       →  ICcdiBaseStaffService.java
CcdiEmployeeServiceImpl.java    →  CcdiBaseStaffServiceImpl.java
ICcdiEmployeeImportService.java →  ICcdiBaseStaffImportService.java
CcdiEmployeeImportServiceImpl  →  CcdiBaseStaffImportServiceImpl

方法参数和返回值类型同步更新。

3.5 Controller 层

类名变更:

CcdiEmployeeController.java → CcdiBaseStaffController.java

API 路径变更:

// 所有接口路径更新
@PreAuthorize("@ss.hasPermi('ccdi:employee:list')")   →  @PreAuthorize("@ss.hasPermi('ccdi:baseStaff:list')")
@RequestMapping("/ccdi/employee")  →  @RequestMapping("/ccdi/baseStaff")

接口端点:

• GET /ccdi/baseStaff/list - 列表查询
• GET /ccdi/baseStaff/{staffId} - 详情查询
• POST /ccdi/baseStaff - 新增
• PUT /ccdi/baseStaff - 修改
• DELETE /ccdi/baseStaff/{staffIds} - 删除
• POST /ccdi/baseStaff/importData - 导入
• POST /ccdi/baseStaff/export - 导出

---

4. 前端代码变更

4.1 API 层

文件更新:

// API 请求路径更新
url: '/ccdi/employee/list'  →  url: '/ccdi/baseStaff/list'

// 字段名更新
employeeId  →  staffId
tellerNo   →  删除相关引用

4.2 页面组件

组件文件:

• 员工管理页面组件重命名
• 所有数据绑定的字段名更新
• 表单验证规则更新
• 表格列定义更新

字段映射:

// 数据绑定
employeeId  →  staffId
tellerNo   →  删除

// 表格列 prop
:prop="'employeeId'"  →  :prop="'staffId'"

4.3 路由配置

如需更新路由路径：

{
  path: 'baseStaff',
  component: () => import('@/views/ccdi/baseStaff/index')
}

---

5. 权限字符变更

5.1 后端权限注解

所有 @PreAuthorize 注解中的权限字符需要更新：

原权限字符	新权限字符
ccdi:employee:list	ccdi:baseStaff:list
ccdi:employee:query	ccdi:baseStaff:query
ccdi:employee:add	ccdi:baseStaff:add
ccdi:employee:edit	ccdi:baseStaff:edit
ccdi:employee:remove	ccdi:baseStaff:remove
ccdi:employee:export	ccdi:baseStaff:export
ccdi:employee:import	ccdi:baseStaff:import

5.2 前端权限指令

所有权限指令更新：

<!-- 示例 -->
v-hasPermi="['ccdi:employee:add']"  →  v-hasPermi="['ccdi:baseStaff:add']"

5.3 数据库菜单权限表

需要在 sys_menu 表中更新：

• 菜单权限标识：ccdi:employee:list → ccdi:baseStaff:list
• 按钮权限：ccdi:employee:add/edit/remove/export/import → ccdi:baseStaff:add/edit/remove/export/import

---

6. 测试验证方案

6.1 后端接口测试

使用测试脚本验证所有 API 端点：

1. 基础 CRUD 测试

   • 列表查询：验证分页、筛选功能
   • 详情查询：验证 staffId 参数
   • 新增功能：验证字段必填项
   • 修改功能：验证更新操作
   • 删除功能：验证批量删除

2. 字段验证测试

   • staffId 字段正常返回
   • tellerNo 字段不存在

3. 权限测试

   • 不同角色访问接口验证权限控制
   • 验证权限字符生效

6.2 前端功能测试

1. 页面功能

   • 列表页面正常加载
   • 搜索筛选功能正常
   • 新增/编辑对话框正常
   • 删除确认功能正常
   • 分页功能正常

2. 导入导出测试

   • Excel 模板下载（字段为 staffId）
   • 数据导入功能
   • 数据导出功能

3. 权限测试

   • 按钮显示/隐藏根据权限控制
   • 无权限时提示正确

6.3 数据库验证

-- 验证表结构
DESC ccdi_base_staff;

-- 验证主键
SHOW INDEX FROM ccdi_base_staff WHERE Key_name = 'PRIMARY';

-- 验证数据量
SELECT COUNT(*) FROM ccdi_base_staff;

---

7. 实施步骤

7.1 后端实施顺序

1. 更新 Entity 层（CcdiBaseStaff）
2. 更新 DTO/VO 层
3. 更新 Mapper 层（接口和 XML）
4. 更新 Service 层（接口和实现）
5. 更新 Controller 层（包括权限字符）
6. 编译验证

7.2 前端实施顺序

1. 更新 API 层
2. 更新页面组件
3. 更新路由配置（如有）
4. 更新权限指令
5. 本地运行验证

7.3 数据库同步

1. 更新菜单权限表（sys_menu）
2. 验证表结构和索引
3. 验证权限配置

---

8. 回滚方案

如需回滚，执行以下步骤：

1. 数据库回滚

   RENAME TABLE ccdi_base_staff TO ccdi_employee;
   -- 恢复 teller_no 字段（如有需要）
   

2. 代码回滚

   • 使用 Git 回退到变更前的提交
   • 或手动恢复所有类名和字段名

3. 权限回滚

   • 恢复 sys_menu 表中的权限字符

---

9. 附录

9.1 影响文件清单

后端 Java 文件（约 25 个）:

• Entity: CcdiEmployee.java
• DTO/VO: AddDTO, EditDTO, QueryDTO, VO, Excel
• Mapper: CcdiEmployeeMapper.java/xml
• Service: ICcdiEmployeeService, ServiceImpl
• ImportService: ICcdiEmployeeImportService, ImportServiceImpl
• Controller: CcdiEmployeeController

前端文件:

• API: ccdiEmployee.js
• Views: 员工管理相关组件
• Router: 路由配置（如有）

SQL 文件（约 6 个）:

• dpc_employee.sql
• fix_charset.sql
• migration/employee_org_no_to_dept_id.sql
• modify_employee_id_to_teller_no.sql
• 等相关脚本

9.2 关键注意事项

1. 字段删除: teller_no 字段已删除，需确认无其他代码引用
2. 主键变更: employee_id → staff_id，需注意自增策略变化
3. 权限同步: 确保数据库菜单表与代码权限字符一致
4. 测试覆盖: 全面测试导入导出功能的字段映射

---

文档状态: 已完成 审核状态: 待审核