285 lines
9.4 KiB
Markdown
285 lines
9.4 KiB
Markdown
# 员工亲属关系信息维护功能设计文档
|
||
|
||
## 一、需求概述
|
||
|
||
开发一个员工亲属关系信息维护的页面，功能包括新增、修改、删除、模板下载、文件导入异步新增。完全按照采购交易管理和招聘信息功能的后端业务处理逻辑和前端UI交互进行开发，交互细节保持完全一致。
|
||
|
||
## 二、功能规格
|
||
|
||
### 2.1 数据模型
|
||
|
||
**数据表**：`ccdi_staff_fmy_relation`
|
||
|
||
**主键设计**：
|
||
- 使用自增 `id` 作为主键
|
||
- 建立唯一索引：`UNIQUE KEY uk_person_cert (person_id, relation_cert_no)`
|
||
- 确保同一员工不会重复添加同一亲属
|
||
|
||
**核心字段**：
|
||
- `id` - 主键（BIGINT自增）
|
||
- `person_id` - 员工身份证号（关联ccdi_base_staff表）
|
||
- `relation_type` - 关系类型（字典：配偶、父亲、母亲、儿子、女儿、祖父、祖母、外祖父、外祖母、兄弟姐妹）
|
||
- `relation_name` - 关系人姓名
|
||
- `gender` - 性别（M:男 F:女 O:其他）
|
||
- `birth_date` - 出生日期
|
||
- `relation_cert_type` - 证件类型（下拉：身份证、护照、军官证等）
|
||
- `relation_cert_no` - 证件号码
|
||
- `mobile_phone1` - 手机号码1
|
||
- `mobile_phone2` - 手机号码2
|
||
- `wechat_no1` - 微信名称1
|
||
- `wechat_no2` - 微信名称2
|
||
- `wechat_no3` - 微信名称3
|
||
- `contact_address` - 详细联系地址
|
||
- `relation_desc` - 关系详细描述
|
||
- `status` - 状态（0-无效、1-有效）
|
||
- `effective_date` - 关系生效日期
|
||
- `invalid_date` - 关系失效日期
|
||
- `remark` - 备注信息
|
||
- `data_source` - 数据来源
|
||
- `is_emp_family` - 是否是员工的家庭关系（后台维护，不显示）
|
||
- `is_cust_family` - 是否是信贷客户的家庭关系（后台维护，不显示）
|
||
|
||
**必填字段**：
|
||
- 员工身份证号、关系类型、关系人姓名、证件类型、证件号码、状态
|
||
|
||
### 2.2 数据验证规则
|
||
|
||
1. **person_id存在性校验**：必须在ccdi_base_staff表中存在
|
||
2. **唯一性校验**：person_id + relation_cert_no 组合唯一
|
||
3. **身份证号格式校验**：18位身份证号格式
|
||
4. **手机号格式校验**：11位手机号码格式（可选）
|
||
|
||
### 2.3 模块命名
|
||
|
||
- **后端模块名**：`ccdi-staff-fmy-relation`
|
||
- **数据库表**：`ccdi_staff_fmy_relation`
|
||
- **前端路由**：`/ccdi/staff/fmy/relation`
|
||
- **菜单路径**：信息维护 > 员工亲属关系
|
||
- **权限标识**：`ccdi:staffFmyRelation:*`
|
||
|
||
## 三、后端设计
|
||
|
||
### 3.1 Controller层接口
|
||
|
||
**基础CRUD接口**：
|
||
- `GET /ccdi/staffFmyRelation/list` - 分页查询（5个查询条件）
|
||
- `GET /ccdi/staffFmyRelation/{id}` - 获取详情
|
||
- `POST /ccdi/staffFmyRelation` - 新增
|
||
- `PUT /ccdi/staffFmyRelation` - 修改
|
||
- `DELETE /ccdi/staffFmyRelation/{ids}` - 批量删除
|
||
- `POST /ccdi/staffFmyRelation/export` - 导出
|
||
|
||
**导入相关接口**：
|
||
- `POST /ccdi/staffFmyRelation/importTemplate` - 下载模板（带字典下拉框）
|
||
- `POST /ccdi/staffFmyRelation/importData` - 异步导入（纯新增，重复即失败）
|
||
- `GET /ccdi/staffFmyRelation/importStatus/{taskId}` - 查询导入状态
|
||
- `GET /ccdi/staffFmyRelation/importFailures/{taskId}` - 查询导入失败记录（分页）
|
||
|
||
### 3.2 查询条件
|
||
|
||
列表页支持5个查询条件：
|
||
1. 员工身份证号
|
||
2. 关系人姓名
|
||
3. 关系类型（下拉）
|
||
4. 证件号码
|
||
5. 状态（下拉：有效/无效）
|
||
|
||
### 3.3 核心业务逻辑
|
||
|
||
1. **数据验证**：新增/修改时验证person_id是否在ccdi_base_staff中存在
|
||
2. **唯一性校验**：person_id + relation_cert_no组合唯一
|
||
3. **异步导入**：使用线程池处理，导入结果存入Redis，前端轮询状态
|
||
4. **纯新增模式**：导入时不更新已存在的记录，直接标记为失败
|
||
|
||
### 3.4 代码结构
|
||
|
||
```
|
||
ruoyi-ccdi/
|
||
├── controller/
|
||
│ └── CcdiStaffFmyRelationController.java
|
||
├── domain/
|
||
│ ├── CcdiStaffFmyRelation.java # 实体类
|
||
│ ├── dto/
|
||
│ │ ├── CcdiStaffFmyRelationAddDTO.java
|
||
│ │ ├── CcdiStaffFmyRelationEditDTO.java
|
||
│ │ └── CcdiStaffFmyRelationQueryDTO.java
|
||
│ ├── vo/
|
||
│ │ ├── CcdiStaffFmyRelationVO.java
|
||
│ │ └── StaffFmyRelationImportFailureVO.java
|
||
│ └── excel/
|
||
│ └── CcdiStaffFmyRelationExcel.java
|
||
├── mapper/
|
||
│ └── CcdiStaffFmyRelationMapper.java
|
||
└── service/
|
||
├── ICcdiStaffFmyRelationService.java
|
||
├── ICcdiStaffFmyRelationImportService.java
|
||
├── impl/
|
||
│ ├── CcdiStaffFmyRelationServiceImpl.java
|
||
│ └── CcdiStaffFmyRelationImportServiceImpl.java
|
||
```
|
||
|
||
## 四、前端设计
|
||
|
||
### 4.1 列表页布局
|
||
|
||
**顶部查询区**（5个查询条件）：
|
||
- 员工身份证号、关系人姓名、关系类型（下拉）、证件号码、状态（下拉）
|
||
|
||
**操作按钮**：
|
||
- 新增、导出、导入、模板下载、删除（批量）
|
||
|
||
**表格列**：
|
||
- 员工身份证号、关系类型、关系人姓名、性别、证件类型、证件号码、手机号码1、状态、创建时间
|
||
- 操作列：修改、删除
|
||
|
||
### 4.2 新增/修改对话框
|
||
|
||
分组两列布局，不折叠：
|
||
|
||
**第一组 - 基本信息**（两列）：
|
||
- 员工身份证号*、关系类型*（下拉）、关系人姓名*、性别（下拉）、出生日期、证件类型*（下拉）、证件号码*（带格式校验）
|
||
|
||
**第二组 - 联系方式**（两列）：
|
||
- 手机号码1、手机号码2、微信名称1、微信名称2、微信名称3、联系地址
|
||
|
||
**第三组 - 其他信息**（两列）：
|
||
- 关系详细描述、状态*（默认有效）、生效日期、失效日期、备注
|
||
|
||
### 4.3 导入功能交互
|
||
|
||
完全参照招聘信息的导入流程：
|
||
1. 点击"导入"按钮 → 选择Excel文件
|
||
2. 立即返回taskId → 弹出"导入任务已提交"提示
|
||
3. 自动轮询importStatus接口 → 显示进度条
|
||
4. 完成后显示导入摘要（成功数、失败数）
|
||
5. 失败记录可点击查看详情（分页表格）
|
||
|
||
### 4.4 前端代码结构
|
||
|
||
```
|
||
ruoyi-ui/src/
|
||
├── api/
|
||
│ └── ccdi/
|
||
│ └── staffFmyRelation.js
|
||
└── views/
|
||
└── ccdiStaffFmyRelation/
|
||
└── index.vue
|
||
```
|
||
|
||
## 五、数据字典
|
||
|
||
### 5.1 关系类型字典
|
||
|
||
**字典类型**：`ccdi_relation_type`
|
||
|
||
**字典值**：
|
||
- 配偶
|
||
- 父亲
|
||
- 母亲
|
||
- 儿子
|
||
- 女儿
|
||
- 祖父
|
||
- 祖母
|
||
- 外祖父
|
||
- 外祖母
|
||
- 兄弟姐妹
|
||
|
||
### 5.2 证件类型字典
|
||
|
||
**字典类型**：`ccdi_cert_type`（新建或复用）
|
||
|
||
**字典值**：
|
||
- 身份证
|
||
- 护照
|
||
- 军官证
|
||
- 其他
|
||
|
||
### 5.3 性别字典
|
||
|
||
**字典类型**：`sys_user_sex`（复用）
|
||
|
||
**字典值**：
|
||
- 男（M）
|
||
- 女（F）
|
||
- 其他（O）
|
||
|
||
## 六、与参考代码的校验对照
|
||
|
||
### 6.1 必须保持一致的关键点
|
||
|
||
**1. Controller接口结构**：
|
||
- 接口路径、参数命名、返回值格式与CcdiPurchaseTransactionController完全一致
|
||
- 使用MyBatis Plus的Page进行分页
|
||
- 使用@PreAuthorize注解进行权限控制
|
||
- 使用@Operation注解标注Swagger文档
|
||
|
||
**2. 异步导入流程**：
|
||
- importData接口立即返回taskId
|
||
- 使用ImportResultVO封装返回结果
|
||
- importStatus接口返回ImportStatusVO
|
||
- importFailures接口支持分页查询失败记录
|
||
|
||
**3. 前端UI交互**：
|
||
- 导入对话框自动轮询importStatus接口
|
||
- 进度条显示导入进度
|
||
- 完成后显示导入摘要
|
||
- 失败记录以可展开的表格形式展示
|
||
|
||
**4. Excel模板**：
|
||
- 使用@DictDropdown注解为字典字段添加下拉框
|
||
- 字段顺序与表单一致
|
||
- 必填字段标注红色星号
|
||
|
||
### 6.2 实现后校验清单
|
||
|
||
创建实施方案后，需要对照采购交易管理代码逐项校验：
|
||
- [ ] Controller接口签名是否一致
|
||
- [ ] Service层方法命名是否一致
|
||
- [ ] DTO/VO类的命名和字段是否一致
|
||
- [ ] 前端API调用方式是否一致
|
||
- [ ] 前端页面布局和交互流程是否一致
|
||
- [ ] 导入功能的状态轮询机制是否一致
|
||
- [ ] 导入失败记录的展示方式是否一致
|
||
|
||
## 七、实施步骤
|
||
|
||
### 阶段1：数据库和字典准备
|
||
1. 确认数据库表 `ccdi_staff_fmy_relation` 已存在（或创建）
|
||
2. 添加唯一索引：`uk_person_cert (person_id, relation_cert_no)`
|
||
3. 创建数据字典：`ccdi_relation_type`（10种关系类型）
|
||
4. 配置菜单：信息维护 > 员工亲属关系
|
||
|
||
### 阶段2：后端开发
|
||
1. 生成实体类、Mapper、Service、Controller基础代码
|
||
2. 创建VO/DTO类（参照采购交易的结构）
|
||
3. 实现Excel导入导出类（添加@DictDropdown注解）
|
||
4. 实现Service层业务逻辑（含唯一性校验、person_id存在性校验）
|
||
5. 实现异步导入Service（使用线程池+Redis）
|
||
6. 实现Controller层接口
|
||
7. 配置Swagger注解
|
||
|
||
### 阶段3：前端开发
|
||
1. 创建API文件 `staffFmyRelation.js`（参照purchaseTransaction.js）
|
||
2. 创建Vue页面 `index.vue`（参照purchase交易的布局）
|
||
3. 实现列表页（查询、表格、分页）
|
||
4. 实现新增/修改对话框（分组两列布局）
|
||
5. 实现导入功能（含轮询、进度条、失败记录展示）
|
||
|
||
### 阶段4：测试和校验
|
||
1. 编写测试脚本（使用admin/admin123获取token）
|
||
2. 测试CRUD功能
|
||
3. 测试Excel导入导出
|
||
4. 与采购交易代码对照校验（使用校验清单）
|
||
5. 生成API文档
|
||
|
||
## 八、文档输出
|
||
|
||
- 设计文档：`doc/plans/2026-02-09-ccdi-staff-fmy-relation-design.md`
|
||
- API文档：`doc/api/ccdi_staff_fmy_relation_api.md`
|
||
|
||
## 九、参考文档
|
||
|
||
- 采购交易管理：`CcdiPurchaseTransactionController.java`
|
||
- 招聘信息管理：`CcdiStaffRecruitmentController.java`
|
||
- 前端参考：`ruoyi-ui/src/views/ccdiPurchaseTransaction/index.vue`
|