# 员工亲属关系信息维护功能设计文档

## 一、需求概述

开发一个员工亲属关系信息维护的页面，功能包括新增、修改、删除、模板下载、文件导入异步新增。完全按照采购交易管理和招聘信息功能的后端业务处理逻辑和前端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`