ccdi/assets/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 表名变更

```sql
-- 表重命名（已完成）
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
```

**字段变更**:

```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 语句更新**:

```xml
<!-- 所有 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 路径变更**:

```java
// 所有接口路径更新
@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 层

**文件更新**:

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

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

### 4.2 页面组件

**组件文件**:

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

**字段映射**:

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

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

### 4.3 路由配置

如需更新路由路径：

```javascript
{
  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 前端权限指令

所有权限指令更新：

```vue
<!-- 示例 -->
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 数据库验证

```sql
-- 验证表结构
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. **数据库回滚**
   ```sql
   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. **测试覆盖**: 全面测试导入导出功能的字段映射

---

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