7.7 KiB

Raw Blame History

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

7.7 KiB Raw Blame History Unescape Escape