添加文档

人力资源数据推送.md

@@ -0,0 +1,215 @@
+# 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 |
+
+---
+