ccdi/doc/plans/2026-02-09-ccdi-staff-fmy-relation-design.md

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

一、需求概述

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