8.0 KiB
8.0 KiB
Context
员工信息维护是纪检初核系统的核心基础功能。系统需要管理银行内部员工的基础信息及其亲属关系，以便在进行纪检初核工作时能够快速查询相关人员信息。
约束条件：
- 必须遵循若依框架的代码规范
- 必须使用项目已定义的命名规范（模块前缀
ccdi_） - 必须支持 Excel 导入导出功能
- 亲属信息需要与员工信息关联管理
相关方：
- 纪检人员：查询员工及亲属信息
- 系统管理员：批量导入员工数据
- 人事部门：维护员工基础信息
Goals / Non-Goals
Goals
- 提供完整的员工信息 CRUD 接口
- 支持员工亲属信息的关联管理（一对多关系）
- 支持 Excel 批量导入导出，导入时可同时导入亲属信息
- 遵循现有代码模式（参考
ccdi_intermediary_blacklist模块）
Non-Goals
- 不涉及前端页面的实现（本次仅实现后端接口）
- 不涉及员工组织架构的复杂层级管理
- 不涉及员工权限、角色管理（使用若依现有系统）
- 不涉及亲属关系的高级查询功能
Decisions
1. 数据模型设计
决策：使用两张表存储员工和亲属信息
ccdi_employee (员工主表)
├── employee_id (主键)
├── name (姓名)
├── teller_no (柜员号, UNIQUE)
├── org_no (所属机构号)
├── id_card (身份证号, UNIQUE)
├── phone (电话)
├── hire_date (入职时间)
├── status (状态: 0=在职, 1=离职)
└── 审计字段 (create_by, create_time, update_by, update_time)
ccdi_employee_relative (员工亲属表)
├── relative_id (主键)
├── employee_id (外键 → ccdi_employee.employee_id)
├── relative_name (亲属姓名)
├── relative_id_card (亲属身份证号)
├── relative_phone (亲属手机号)
├── relationship (与员工关系)
└── 审计字段
理由：
- 符合数据库范式设计，避免数据冗余
- 支持一对多关系（一个员工可以有多个亲属）
- 便于查询和维护
替代方案考虑：
- 方案2：将亲属信息存储为 JSON 字段
- 优点：单表存储，查询简单
- 缺点：无法对亲属信息建索引，不支持复杂查询
- 拒绝原因：未来可能需要按亲属信息查询
2. 亲属信息维护方式
决策：在员工的新增/编辑接口中同时支持亲属信息
POST /dpc/employee
{
"name": "张三",
"tellerNo": "001",
"orgNo": "1001",
"idCard": "110101199001011234",
"phone": "13800138000",
"hireDate": "2020-01-01",
"relatives": [
{
"relativeName": "李四",
"relativeIdCard": "110101199001011235",
"relativePhone": "13800138001",
"relationship": "配偶"
}
]
}
理由：
- 减少接口数量，简化前端调用
- 保证员工与亲属信息的原子性操作
- 符合业务场景（新增员工时同时录入亲属信息）
3. Excel 导入格式
决策：使用多 Sheet 导入方式
Sheet1: 员工信息
| 姓名 | 柜员号 | 所属机构号 | 身份证号 | 电话 | 入职时间 |
|------|--------|------------|----------|------|----------|
| 张三 | 001 | 1001 | ... | ... | 2020-01-01 |
Sheet2: 亲属信息 (可选)
| 员工身份证号 | 亲属姓名 | 亲属身份证号 | 亲属手机号 | 与员工关系 |
|--------------|----------|--------------|------------|------------|
| 110101... | 李四 | 110101... | 138... | 配偶 |
理由：
- 清晰分离员工和亲属数据
- 支持仅导入员工信息（亲属信息为可选）
- 通过员工身份证号关联两张表
替代方案考虑：
- 方案2：单 Sheet 导入，亲属信息嵌套在员工行中
- 缺点：格式复杂，Excel 难以编辑
- 拒绝原因：用户体验差
4. 字典数据
决策：使用字典管理"与员工关系"字段和"员工状态"字段
字典类型: ccdi_relative_relationship
字典数据: 配偶、父亲、母亲、子女、兄弟姐妹、其他
字典类型: ccdi_employee_status
字典数据: 在职(0)、离职(1)
理由：
- 符合若依框架设计模式
- 便于后续扩展关系类型
- 统一管理枚举值
5. 数据库约束
决策：柜员号和身份证号添加唯一约束
UNIQUE KEY `uk_teller_no` (`teller_no`),
UNIQUE KEY `uk_id_card` (`id_card`)
理由：
- 柜员号是员工的唯一标识，不允许重复
- 身份证号具有唯一性，不允许重复
- 防止数据重复和业务逻辑错误
6. 命名规范
决策：遵循项目规范
- 表名:
ccdi_employee,ccdi_employee_relative - 实体类:
CcdiEmployee,CcdiEmployeeRelative - Controller:
CcdiEmployeeController - 权限标识:
dpc:employee:* - 所有实体类、DTO、VO 类统一使用 @Data 注解
理由：
- 与现有
ccdi_intermediary_blacklist模块保持一致 - 符合项目编码规范
- @Data 注解自动生成 getter/setter，代码简洁
7. MyBatis Plus 使用策略
决策：区分简单 CRUD 和复杂查询的实现方式
简单 CRUD 操作（使用 MyBatis Plus 方法）：
- BaseMapper 提供的方法：
insert,deleteById,deleteByIds,updateById,selectById,selectList,selectCount - 条件构造器：
QueryWrapper,LambdaQueryWrapper用于简单条件查询 - 适用场景：单表增删改查、简单条件筛选
复杂查询操作（使用 XML 映射）：
- 多表关联查询（员工 + 亲属信息）
- 复杂条件组合查询
- 需要自定义结果映射的查询
- 适用场景：关联查询、复杂业务查询
示例：
// 简单查询 - 使用 MyBatis Plus
employeeMapper.selectById(id);
employeeMapper.selectList(new LambdaQueryWrapper<CcdiEmployee>()
.eq(CcdiEmployee::getTellerNo, tellerNo));
// 复杂查询 - 使用 XML
EmployeeWithRelativesVO selectEmployeeWithRelatives(Long id);
理由：
- 简单 CRUD 使用 MyBatis Plus 减少代码量，提高开发效率
- 复杂查询使用 XML 保持 SQL 可读性和可维护性
- 符合项目技术规范（MyBatis Plus 3.5.10，Spring Boot 3 适配版）
Risks / Trade-offs
风险1: Excel 导入时亲属数据关联失败
风险描述: 导入员工和亲属信息时，若员工身份证号填写错误，亲属信息无法关联。
缓解措施:
- 导入时进行数据校验
- 提供详细的导入错误报告
- 支持"仅导入员工"模式，亲属信息可后续补录
风险2: 亲属信息数据量过大
风险描述: 某些员工可能有大量亲属记录，影响查询性能。
缓解措施:
- 建立适当的数据库索引
- 列表查询时默认不返回亲属详情
- 提供单独的亲属查询接口
权衡: 简化 vs 完整性
- 当前方案: 使用两表设计，支持完整的一对多关系
- 简化方案: 将亲属信息存储为 JSON
- 选择: 当前方案，因为纪检场景可能需要按亲属信息查询
Migration Plan
后端部署步骤
- 执行数据库脚本，创建表和字典数据
- 部署后端代码
- （前端开发阶段）配置菜单和权限数据
回滚计划
- 从数据库中删除新增的表和字典数据
- 移除后端代码部署
前端开发注意事项
- 开发前端页面时需同步在
sys_menu表中插入菜单及权限数据 - 菜单路径：信息维护 → 员工信息管理
- 权限标识：
dpc:employee:list,dpc:employee:query,dpc:employee:add,dpc:employee:edit,dpc:employee:remove,dpc:employee:export,dpc:employee:import
Open Questions
-
亲属关系是否需要支持多层级？ (如：亲属的亲属)
- 当前决策: 否，仅支持员工的直接亲属
-
导入时是否需要支持"更新已有员工"模式？
- 当前决策: 是，通过柜员号或身份证号判断
-
员工离职后如何处理？- 已确认: 增加状态字段（0=在职, 1=离职）
-
身份证号和柜员号是否需要唯一性约束？- 已确认: 两者都需要唯一约束