zcloud_gbs_human_user/人力资源数据推送.md

# zcloud_gbs_human_user 项目文档

## 1. 项目概述

**项目名称**：zcloud_gbs_human_user（人力资源用户管理）

**项目简介**：本项目是 GBS 人力资源用户管理模块，负责管理与第三方人资系统对接的人员和部门数据同步。主要功能包括：从第三方接口同步全量人员/部门数据、部门对比同步。
预留出人员增删改查接口，只需要**秦港股份**的部门及人员数据，并同步到本系统。

**数据参考**：
- 人员数据及结构 ---> GBS-人资推送部门人员数据.zip ----> 人资人员缓存.json
- 部门数据及结构 ---> GBS-人资推送部门人员数据.zip ----> 人资对接json.txt

**开发平台**：新租户，新账号
- 账号：renliziyuanbu
- 密码：Aa@12345678
- 新建了个应用人力资源进行测试。用户管理暂时不用

**应用名称**：`jjb-saas-zcloud-human-user`

**网关路由**：`humanUser`


---

## 2. 项目结构

```
zcloud_gbs_human_user/
├── start/                    # 启动模块
├── web-adapter/              # 适配层（Controller/Facade/Job）
├── web-app/                  # 应用层（Service/Exe）
├── web-client/               # 接口契约（ServiceI/DTO）
├── web-domain/               # 领域层（Model/Gateway）
└── web-infrastructure/       # 基础设施层（GatewayImpl/Mapper/Repository）
```

---

## 3. 模块职责说明

### 3.1 start（启动模块）

**职责**：项目入口，Spring Boot 启动类及配置文件管理。

| 文件 | 说明 |
|------|------|
| `Application.java` | 启动类，配置包扫描 `com.zcloud` 和 `com.jjb`，Mapper 扫描指向 `persistence.mapper` |
| `resources/bootstrap.yml` | 配置文件导入（nacos-prod.yml、sdk-prod.yml、swagger.yml） |
| `resources/nacos-prod.yml` | Nacos 连接配置（地址、命名空间、shared-configs） |
| `resources/sdk-prod.yml` | SDK 网关路由配置 |
| `resources/swagger.yml` | Swagger 文档配置 |
| `resources/nacos/*.yml` | 共享配置文件（数据库、Redis、日志、MQ 等） |
| `target/templates/risk.html` | 前端静态页面模板 |

### 3.2 web-client（接口契约模块）

**职责**：定义对外接口契约和传输对象，不包含业务逻辑。

| 目录/文件 | 说明 |
|-----------|------|
| `api/HumanUserServiceI.java` | 服务接口（增删改查） |
| `dto/HumanUserAddCmd.java` | 新增人员命令 |
| `dto/HumanUserUpdateCmd.java` | 更新人员命令 |
| `dto/HumanUserRemoveCmd.java` | 删除命令 |
| `dto/HumanUserPageQry.java` | 分页查询参数 |
| `dto/HumanUserListQry.java` | 列表查询参数 |
| `dto/clientobject/HumanUserCO.java` | 返回客户端对象 |

### 3.3 web-adapter（适配层）

**职责**：接收外部请求，协议适配和参数转换。

| 目录/文件 | 说明 |
|-----------|------|
| `web/HumanUserController.java` | HTTP 控制器，提供同步任务手动触发接口 |
| `plan/HumanUserSyncJob.java` | 人员同步定时任务 |
| `plan/HumanDeptSyncJob.java` | 部门同步定时任务 |
| `plan/HumanUserDeptCompareSyncJob.java` | 部门对比同步定时任务 |

**HTTP 接口**：

| 接口路径 | 方法 | 说明 |
|----------|------|------|
| `/humanUser/user/asyncSyncHumanUser` | POST | 手动触发人员同步 |
| `/humanUser/user/asyncSyncHumanDept` | POST | 手动触发部门同步 |
| `/humanUser/user/asyncSyncDeptCompare` | POST | 手动触发部门对比同步 |

### 3.4 web-app（应用层）

**职责**：业务编排，协调各领域组件完成具体业务。

#### 3.4.1 Service 实现

| 文件 | 说明 |
|------|------|
| `service/HumanUserServiceImpl.java` | 实现 `HumanUserServiceI`，将增删改委托给对应 Exe |
| `service/AsyncSyncService.java` | 异步同步服务，使用 `@Async("syncTaskExecutor")` 线程池 |

#### 3.4.2 Command/Exe 执行器

| 文件 | 说明 |
|------|------|
| `command/HumanUserAddExe.java` | 新增人员，通过 Dubbo 调用 `UserFacade.add` |
| `command/HumanUserUpdateExe.java` | 更新人员，通过 Dubbo 调用 `UserFacade.update` |
| `command/HumanUserRemoveExe.java` | 删除人员，通过 Dubbo 调用 `UserFacade.delete` |
| `command/query/HumanUserQueryExe.java` | 查询执行器 |

#### 3.4.3 同步执行器（核心业务）

| 文件 | 说明 |
|------|------|
| `command/HumanUserSyncExe.java` | **人员数据同步**：从第三方接口获取全量人员数据，按公司/部门过滤后同步到底座用户中心 |
| `command/HumanDeptSyncExe.java` | **部门数据同步**：从第三方数据中提取部门树，递归同步到本系统 |
| `command/HumanUserDeptCompareSyncExe.java` | **部门对比同步**：对比统一用户管理与变动记录表的部门信息，记录差异 |

### 3.5 web-domain（领域层）

**职责**：定义领域模型、Gateway 接口。

| 文件 | 说明 |
|------|------|
| `domain/model/HumanUserE.java` | 人资用户实体，包含 `initFromJson()` 从第三方 JSON 初始化 |
| `domain/model/HumanUserRecordE.java` | 人资每日变动记录实体 |
| `domain/gateway/HumanUserGateway.java` | 人资用户数据访问接口（list/getById/add/update/remove） |
| `domain/gateway/HumanUserRecordGateway.java` | 人资变动记录数据访问接口 |

### 3.6 web-infrastructure（基础设施层）

**职责**：实现 Gateway 接口，数据库访问。

| 目录/文件 | 说明 |
|-----------|------|
| `gatewayimpl/HumanUserGatewayImpl.java` | HumanUserGateway 实现，通过 Repository 持久化 |
| `gatewayimpl/HumanUserRecordGatewayImpl.java` | HumanUserRecordGateway 实现 |
| `resources/mapper/HumanUserMapper.xml` | human_user 表 MyBatis 映射 |
| `resources/mapper/HumanUserRecordMapper.xml` | human_user_record 表 MyBatis 映射 |
| `resources/TableCreationDDL.sql` | 建表 DDL |

---

## 4. 数据库内容

### 4.1 jjb-saas-zcloud-human-user 数据库

### 4.2 human_user（人资用户表）

**索引**：`idx_employee_phone (employee_name, phone_number)`

### 4.3 human_user_record（人资每日变动记录表）


## 5. 核心业务流程

### 5.1 人员数据同步流程（HumanUserSyncExe）

```
第三方接口 (http://192.168.10.56:8090)
    ↓ 获取全量人员数据
过滤 TARGET_CORP_NAME = "秦港股份"
    ↓
按id_card_number字段查询 human_user 表
    ↓
├─ 已存在且部门变更 → 更新部门 + 记录变动
├─ 已存在且部门未变 → 跳过
├─ 未存在于 human_user，但统一用户已存在 → 保存 human_user 记录
└─ 完全不存在 → 创建底座账号 + 保存 human_user + 记录变动
```

**关键配置**：
- 目标公司：`秦皇岛港股份有限公司`
- 第三方过滤公司：`秦港股份`
- 第三方接口：`http://192.168.10.56:8090`

### 5.2 部门数据同步流程（HumanDeptSyncExe）

```
第三方接口
    ↓ 解析部门树
递归查找目标公司 "秦皇岛港股份有限公司"
    ↓
根据父部门ID + 部门名称判断是否存在
    ↓
├─ 已存在 → 使用已有ID继续同步子部门
└─ 不存在 → 创建新部门 + 使用新ID继续同步子部门
```

### 5.3 部门对比同步流程（HumanUserDeptCompareSyncExe）

```
查询统一用户管理用户列表
    ↓
查询 human_user_record 变动记录
    ↓ 构建 userId → deptName 映射
对比两者的部门信息
    ↓
发现差异 → 记录变动到 human_user_record
```

---

## 6. 依赖关系

### 6.1 外部 Dubbo 服务依赖

| Dubbo Reference | 说明 | 来源 |
|-----------------|------|------|
| `UserFacade` | 底座用户服务 | jjb-saas-system-client |
| `RoleFacade` | 底座角色服务 | jjb-saas-system-client |
| `ZcloudUserFacade` | 统一用户服务 | zcloud_gbscommon |
| `ZcloudDepartmentFacade` | 统一部门服务 | zcloud_gbscommon |
| `ZcloudCorpFacade` | 统一企业服务 | zcloud_gbscommon |

---