@alanwang-merit/meritdata-platform-skill-package 1.0.8 → 1.0.10

package/skills/meritdata-platform-integration/references/notification-detail/11_/344/270/211/345/271/263/345/217/260/346/234/215/345/212/241-3.6/346/234/215/345/212/241/351/200/232/347/237/245-CloudFeignMessageClient.md

@@ -0,0 +1,467 @@
+---
+name: 服务通知 CloudFeignMessageClient
+source-file: 公共资产清单
+source-section: 3.6 服务通知
+keywords: [CloudFeignMessageClient, 服务通知, sendRoleMessage, sendResourceMessage, sendUserRoleMessage, sendAssignMessage, sendUserAppMessage, DynamicCloudFeignClient, CloudTenancySync, 角色变更, 资源变更, 权限分配]
+use-cases: [角色变更通知, 资源变更通知, 用户角色变更通知, 权限分配变更通知, 租户同步, 用户/组织/人员变更通知]
+related: [08, 10, 12]
+---
+
+# 服务通知 CloudFeignMessageClient
+
+> **原文章节**：`公共资产清单 → 3.6 服务通知`
+> **行号范围**：L1736–L2176
+
+## 🎯 一句话
+通过 `CloudFeignMessageClient`（5 个消息发送方法）+ `DynamicCloudFeignClient`（动态 FeignClient）+ 二开 Feign 接收接口，实现租户、组织、人员、角色、权限变更时跨服务的实时消息通知。
+
+## 📋 接口/方法清单
+
+### 3.6.1 租户同步
+
+**使用场景**：创建租户时，同步信息给二开服务
+
+#### 3.6.1.1 动态FeignClient构建
+
+完整包路径：`com.meritdata.cloud.feignclient.DynamicCloudFeignClient`
+
+方法：`getFeignClient(serviceName, type)`
+
+入参：String serviceName, Class<T> type
+
+返回：T (泛型FeignClient)
+
+使用场景：根据服务名称动态获取FeignClient，用于调用二开服务的接口
+
+**Nacos配置**：
+```properties
+meritdata.cloud.sync-tenancy-receiver: cloud-system-demo  # 二开服务名称，多个服务用逗号分隔
+```
+
+#### 3.6.1.2 租户同步发送
+
+完整包路径：`com.meritdata.cloud.system.manager.ou.tenancy.dynsync.CloudTenancySync`
+
+方法：`syncAdd(Tenancy tenancy)`
+
+入参：Tenancy tenancy
+
+返回：ResultBody<String>
+
+使用场景：当新建租户时，平台异步向已配置的二开服务发送租户同步消息
+
+**Nacos配置**：
+```properties
+meritdata.cloud.sync-tenancy-receiver: cloud-system-demo1,cloud-system-demo2  # 多个服务用逗号分隔
+```
+
+#### 3.6.1.3 租户同步接收
+
+完整包路径：`com.meritdata.cloud.system.manager.ou.tenancy.dynsync.CloudTenancySync`
+
+方法：`POST /api/tenancy/sync/add`
+
+入参：Tenancy tenancy
+
+返回：ResultBody<String>
+
+使用场景：二开服务实现租户同步接收接口，接收平台发送的租户信息
+
+**二开服务实现示例**：
+```java
+/**
+ * 二开服务实现租户同步接收接口
+ */
+@RestController
+@RequestMapping("/api/tenancy/sync")
+public class TenancySyncReceiver {
+
+    @PostMapping("/add")
+    public ResultBody<String> syncAdd(@RequestBody Tenancy tenancy) {
+        log.info("收到租户同步消息: {}", tenancy);
+        // 创建租户专属数据空间、初始化租户配置等
+        return ResultBody.success("同步成功");
+    }
+}
+```
+
+---
+
+### 3.6.2 用户权限同步
+
+**使用场景**：用户、角色、权限变更时，发送消息通知订阅的二开服务
+
+**Nacos配置**：
+```properties
+meritdata.cloud.sync-cloud-data-application-name: cloud-system-demo  # 订阅消息的二开服务名称
+```
+
+**公共消息体 MessageBody 字段说明**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| tid | String | 租户ID |
+| theme | String | 消息主题（ROLE/RESOURCE/USER_ROLE/ASSIGN） |
+| data | List | 消息数据列表（RoleMessage/ResourceMessage/RoleUserMessage/AssignMessage） |
+
+#### 3.6.2.1 发送角色变更消息
+
+完整包路径：`com.meritdata.cloud.feignclient.CloudFeignMessageClient`
+
+方法：`sendRoleMessage(MessageBody messageBody)`
+
+入参：MessageBody（data为List<RoleMessage>）
+
+返回：boolean
+
+使用场景：角色信息变更时，发送消息通知相关系统
+
+**角色消息（RoleMessage）字段说明**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | String | 角色ID |
+| deptId | String | 部门ID |
+| deptCode | String | 部门编码 |
+| code | String | 角色编码 |
+| name | String | 角色名称 |
+| type | Integer | 角色类型 |
+| application | String | 产品名称 |
+| operation | String | 操作：add新增、update更新、del删除 |
+| timeStamp | String | 时间戳 |
+
+**二开服务接收示例**：
+
+```java
+@PostMapping("/send-role-message")
+public boolean sendRoleMessage(@RequestBody MessageBody messageBody) {
+    List<RoleMessage> roleList = (List<RoleMessage>) messageBody.getData();
+    for (RoleMessage role : roleList) {
+        String operation = role.getOperation();  // add/update/del
+        String roleCode = role.getCode();
+        String roleName = role.getName();
+    }
+    return true;
+}
+```
+
+#### 3.6.2.2 发送资源变更消息
+
+方法：`sendResourceMessage(MessageBody messageBody)`
+
+入参：MessageBody（data为List<ResourceMessage>）
+
+返回：boolean
+
+使用场景：资源（菜单）信息变更时，发送消息通知相关系统
+
+**资源消息（ResourceMessage）字段说明**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | String | 资源ID |
+| parentId | String | 父资源ID |
+| type | String | 类型：0模块、1菜单、2组件、4分组 |
+| name | String | 资源名称 |
+| url | String | 菜单路由 |
+| embedUrl | String | 嵌入URL |
+| application | String | 产品名称 |
+| sort | Integer | 排序 |
+| iconPath | String | 图标路径 |
+| operation | String | 操作：add新增、update更新、del删除 |
+| timeStamp | String | 时间戳 |
+
+**二开服务接收示例**：
+
+```java
+@PostMapping("/send-resource-message")
+public boolean sendResourceMessage(@RequestBody MessageBody messageBody) {
+    List<ResourceMessage> resourceList = (List<ResourceMessage>) messageBody.getData();
+    for (ResourceMessage resource : resourceList) {
+        String operation = resource.getOperation();  // add/update/del
+        String type = resource.getType();            // 0模块/1菜单/2组件/4分组
+        String url = resource.getUrl();              // 菜单路由
+    }
+    return true;
+}
+```
+
+#### 3.6.2.3 发送用户角色变更消息
+
+方法：`sendUserRoleMessage(MessageBody messageBody)`
+
+入参：MessageBody（data为List<RoleUserMessage>）
+
+返回：boolean
+
+使用场景：用户角色分配变更时，发送消息通知相关系统
+
+**用户角色消息（RoleUserMessage）字段说明**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| userId | String | 用户ID |
+| userCode | String | 用户编码 |
+| roleCode | String | 角色编码 |
+| operation | String | 操作：add新增、del删除 |
+| timeStamp | String | 时间戳 |
+
+**二开服务接收示例**：
+
+```java
+@PostMapping("/send-user-role-message")
+public boolean sendUserRoleMessage(@RequestBody MessageBody messageBody) {
+    List<RoleUserMessage> userRoleList = (List<RoleUserMessage>) messageBody.getData();
+    for (RoleUserMessage userRole : userRoleList) {
+        String operation = userRole.getOperation();  // add/del
+        String userId = userRole.getUserId();
+        String roleCode = userRole.getRoleCode();
+    }
+    return true;
+}
+```
+
+#### 3.6.2.4 发送权限分配变更消息
+
+方法：`sendAssignMessage(MessageBody messageBody)`
+
+入参：MessageBody（data为List<AssignMessage>）
+
+返回：boolean
+
+使用场景：权限分配变更时，发送消息通知相关系统
+
+**权限分配消息（AssignMessage）字段说明**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| resourceId | String | 资源ID |
+| type | String | 授权类型：3按机构、4按角色、6按人员 |
+| code | String | 角色编码或机构编码 |
+| url | String | 菜单路由 |
+| application | String | 产品名称 |
+| operation | String | 操作：add新增、del删除 |
+| timeStamp | String | 时间戳 |
+
+**二开服务接收示例**：
+
+```java
+@PostMapping("/send-assign-message")
+public boolean sendAssignMessage(@RequestBody MessageBody messageBody) {
+    List<AssignMessage> assignList = (List<AssignMessage>) messageBody.getData();
+    for (AssignMessage assign : assignList) {
+        String operation = assign.getOperation();  // add/del
+        String type = assign.getType();            // 3按机构/4按角色/6按人员
+        String resourceId = assign.getResourceId();
+    }
+    return true;
+}
+```
+
+---
+
+### 3.6.3 服务通知二开接口
+
+**使用场景**：平台端用户、组织、人员等变更时，通知二开服务进行相应处理
+
+#### 3.6.3.1 用户新增通知
+
+完整包路径：`com.meritdata.cloud.system.manager.ou.user.controller.IUserPortalService`
+
+FeignClient接口：`POST /user-add`
+
+入参：User user
+
+返回：void
+
+**Nacos配置（二开服务）**：
+```properties
+meritdata.cloud.user-customization-extension-application-name: cloud-system-demo  # 二开服务名，平台端调用
+```
+
+**二开服务实现**：
+```java
+@PostMapping("/user-add")
+public void userAdd(@RequestBody User user) {
+    // 处理用户新增逻辑
+}
+```
+
+#### 3.6.3.2 用户编辑通知
+
+方法：`POST /user-update`
+
+入参：User user
+
+返回：void
+
+**二开服务实现**：
+```java
+@PostMapping("/user-update")
+public void userUpdate(@RequestBody User user) {
+    // 处理用户编辑逻辑
+}
+```
+
+#### 3.6.3.3 用户删除通知
+
+方法：`POST /user-remove`
+
+入参：UserListDto userListDto
+
+返回：void
+
+**二开服务实现**：
+```java
+@PostMapping("/user-remove")
+public void userRemove(@RequestBody UserListDto userListDto) {
+    // 处理用户删除逻辑
+}
+```
+
+#### 3.6.3.4 初始化密码通知
+
+方法：`POST /resetPass`
+
+入参：User user
+
+返回：void
+
+**二开服务实现**：
+```java
+@PostMapping("/resetPass")
+public void resetPass(@RequestBody User user) {
+    // 处理初始化密码逻辑
+}
+```
+
+#### 3.6.3.5 修改密码通知
+
+方法：`POST /changePass`
+
+入参：User user
+
+返回：void
+
+**二开服务实现**：
+```java
+@PostMapping("/changePass")
+public void changePass(@RequestBody User user) {
+    // 处理修改密码逻辑
+}
+```
+
+#### 3.6.3.6 组织新增通知
+
+完整包路径：`com.meritdata.cloud.system.manager.ou.org.controller.IOrgPortalService`
+
+FeignClient接口：`POST /api/ou/org/create`
+
+入参：Organization org
+
+返回：void
+
+**Nacos配置（二开服务）**：
+```properties
+meritdata.cloud.org-emp-customization-extension-application-name: cloud-system-demo  # 二开服务名
+```
+
+**二开服务实现**：
+```java
+@PostMapping("/api/ou/org/create")
+public void orgAdd(@RequestBody Organization org) {
+    // 处理组织新增逻辑
+}
+```
+
+#### 3.6.3.7 组织修改通知
+
+方法：`POST /api/ou/org/update`
+
+入参：Organization org
+
+返回：void
+
+**二开服务实现**：
+```java
+@PostMapping("/api/ou/org/update")
+public void orgUpdate(@RequestBody Organization org) {
+    // 处理组织修改逻辑
+}
+```
+
+#### 3.6.3.8 组织删除通知
+
+方法：`POST /api/ou/org/delete`
+
+入参：OrgListDto orgListDto
+
+返回：void
+
+**二开服务实现**：
+```java
+@PostMapping("/api/ou/org/delete")
+public void orgRemove(@RequestBody OrgListDto orgListDto) {
+    // 处理组织删除逻辑
+}
+```
+
+#### 3.6.3.9 人员新增通知
+
+方法：`POST /emp-add`
+
+入参：Emp emp
+
+返回：void
+
+**二开服务实现**：
+```java
+@PostMapping("/emp-add")
+public void empAdd(@RequestBody Emp emp) {
+    // 处理人员新增逻辑
+}
+```
+
+#### 3.6.3.10 人员修改通知
+
+方法：`POST /emp-update`
+
+入参：Emp emp
+
+返回：void
+
+**二开服务实现**：
+```java
+@PostMapping("/emp-update")
+public void empUpdate(@RequestBody Emp emp) {
+    // 处理人员修改逻辑
+}
+```
+
+#### 3.6.3.11 人员删除通知
+
+方法：`POST /emp-delete`
+
+入参：EmpListDto empListDto
+
+返回：void
+
+**二开服务实现**：
+```java
+@PostMapping("/emp-delete")
+public void empRemove(@RequestBody EmpListDto empListDto) {
+    // 处理人员删除逻辑
+}
+```
+
+## 💡 使用建议
+
+1. **5 大消息发送方法**：`sendRoleMessage` / `sendResourceMessage` / `sendUserRoleMessage` / `sendAssignMessage` / `sendUserAppMessage` 涵盖平台所有权限/资源变更场景。
+2. **Nacos 订阅优先**：二开服务只需在 `application-name` 注册后即可接收到所有平台变更消息，无需开发 FeignClient。
+3. **二开服务零侵入**：通过 `IUserPortalService` / `IOrgPortalService` 接收用户/组织/人员变更通知，本服务本地业务尽量在 `@PostMapping` 接收方法中处理。
+
+## 🔗 相关章节
+
+- `08_三平台服务-3.3会话信息-SessionUtils.md`（会话信息获取）
+- `10_三平台服务-3.4多系统集成+3.5数据密级.md`（多系统集成）
+- `12_四业务组件-4.1工作流BpmEngine.md`（BPM 流程）

package/skills/meritdata-platform-integration/references/org-user-sync.md

@@ -0,0 +1,121 @@
+## 前置条件
+
+**服务调用方式**: 调用目标平台组织服务提供的 WebService 或 RESTful API，无需在二开项目中引入依赖。服务名和路由以目标项目配置为准。
+
+---
+
+## WebService 同步接口
+
+**地址格式**: `{gatewayOrigin}{gatewayPrefix}/{applicationName}/ws/{serviceName}?wsdl`。先通过目标 WSDL 或网关路由核对 `{applicationName}`、`{serviceName}` 和 `gatewayPrefix`。
+
+**完整包路径**: `com.meritdata.cloud.system.manager.ou.sync.ws.impl`
+
+| 服务名 | 方法 | 参数 | 返回值 | 说明 |
+|--------|------|------|--------|------|
+| syncOrgWebService | syncOrg | XML 字符串 | "1" 成功 / "0" 失败 | 组织同步 |
+| syncUserWebService | syncUser | XML 字符串 | "1" 成功 / "0" 失败 | 人员同步 |
+| syncResourceWebService | syncResource | XML 字符串 | "1" 成功 / "0" 失败 | 资源同步 |
+| syncRoleWebService | syncRole | XML 字符串 | "1" 成功 / "0" 失败 | 角色同步 |
+| syncAssignWebService | syncAssign | XML 字符串 | "1" 成功 / "0" 失败 | 权限同步 |
+
+---
+
+## RESTful API 同步接口
+
+**基础路径**: `/webapi/ou/sync`
+
+**完整包路径**: `com.meritdata.cloud.system.manager.ou.sync.controller.WebApiSyncController`
+
+**认证方式**: 请求 Header 携带 `app-key` 和 `app-token`
+
+| 接口路径 | 方法 | 参数 | 说明 |
+|----------|------|------|------|
+| `/webapi/ou/sync/org` | POST | orgInfo (XML) | 组织同步 |
+| `/webapi/ou/sync/user` | POST | userInfo (XML) | 人员同步 |
+| `/webapi/ou/sync/resource` | POST | resourceInfo (XML) | 资源同步 |
+| `/webapi/ou/sync/role` | POST | roleInfo (XML) | 角色同步 |
+| `/webapi/ou/sync/duty` | POST | dutyInfo (XML) | 职务同步 |
+| `/webapi/ou/sync/assign` | POST | assignInfo (XML) | 权限同步 |
+
+### 调用示例
+
+```java
+// RESTful API 调用
+HttpHeaders headers = new HttpHeaders();
+headers.set("app-key", "{appKey-from-managed-config}");
+headers.set("app-token", "{appToken-from-managed-config}");
+
+// 组织同步 XML 格式
+String xmlData = "<ROOT>"
+    + "<ORG>"
+    + "<ORG_CODE>{orgCode}</ORG_CODE>"
+    + "<ORG_PARENT_CODE>{parentOrgCode}</ORG_PARENT_CODE>"
+    + "<ORG_NAME>{orgName}</ORG_NAME>"
+    + "<ORG_SIMPLENAME>{orgSimpleName}</ORG_SIMPLENAME>"
+    + "<ORG_DLEVEL>{dataSecretLevel}</ORG_DLEVEL>"
+    + "<ORG_IS_ABLE>{enabled}</ORG_IS_ABLE>"
+    + "<ORG_SORT>{sort}</ORG_SORT>"
+    + "<ORG_REMARK>{remark}</ORG_REMARK>"
+    + "</ORG>"
+    + "</ROOT>";
+
+HttpEntity<String> request = new HttpEntity<>(xmlData, headers);
+
+String endpoint = "{gatewayOrigin}{gatewayPrefix}/webapi/ou/sync/org";
+restTemplate.postForObject(endpoint, request, String.class);
+```
+
+---
+
+## XML 格式参考
+
+### 组织同步 XML 标签
+
+| 标签 | 必填 | 说明 |
+|------|------|------|
+| `<ROOT>` | 是 | 根节点 |
+| `<ORG>` | 是 | 组织节点（可包含多个） |
+| `<ORG_CODE>` | 是 | 组织编码（唯一标识） |
+| `<ORG_PARENT_CODE>` | 是 | 父组织编码 |
+| `<ORG_NAME>` | 是 | 组织名称 |
+| `<ORG_SIMPLENAME>` | 否 | 组织简称 |
+| `<ORG_DLEVEL>` | 是 | 数据密级（0-4） |
+| `<ORG_IS_ABLE>` | 是 | 是否启用（0-停用/1-启用） |
+| `<ORG_SORT>` | 否 | 排序号 |
+| `<ORG_REMARK>` | 否 | 备注说明 |
+
+### 人员同步 XML 示例
+
+```xml
+<ROOT>
+  <USER>
+    <USER_CODE>{userCode}</USER_CODE>
+    <USER_NAME>{userName}</USER_NAME>
+    <USER_ORG_CODE>{orgCode}</USER_ORG_CODE>
+    <USER_LOGINNAME>{loginName}</USER_LOGINNAME>
+    <USER_PASSWORD>{initialPassword}</USER_PASSWORD>
+    <USER_IS_ABLE>{enabled}</USER_IS_ABLE>
+  </USER>
+</ROOT>
+```
+
+---
+
+## 典型使用场景
+
+| 场景 | 推荐接口 |
+|------|----------|
+| HR 系统同步组织架构 | 组织同步 → 人员同步 |
+| 新员工入职 | 人员同步 |
+| 组织架构调整 | 组织同步 |
+| 权限系统对接 | 角色同步 → 资源同步 → 权限同步 |
+| 职务体系同步 | 职务同步 |
+
+---
+
+## 组织人员同步注意事项
+
+1. RESTful API 的 `app-key` 和 `app-token` 从受管配置读取，确保已在平台端配置。
+2. 请求体和 `Content-Type` 以目标接口契约为准；本参考仅列出 XML 结构。
+3. `{initialPassword}` 必须通过受管配置或身份系统提供，不能嵌入 XML 示例、源码或日志。
+4. 幂等语义和详细 XML 格式以《组织和人员同步》使用攻略及目标接口实现为准。