@alanwang-merit/meritdata-platform-skill-package 1.0.9 → 1.0.11

package/skills/meritdata-platform-integration/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: meritdata-platform-integration
+description: 平台开放 REST/WebService 接口、网关鉴权、服务变更通知。用于外部系统接入、app-key/app-token 认证、Feign 通知接收，以及接口契约和请求路径核验。**HR/ERP/门户组织人员同步**已抽离到 `meritdata-platform-org-sync`。
+metadata:
+  version: "1.1.0"
+  author: 技术平台部门架构组
+  source: company
+  date_added: "2026-09-01"
+  last_updated: "2026-09-10"
+  risk: medium
+  allowed-tools: Read, Grep, Glob
+---
+
+## ⭐ MUST DO
+
+**网关路径按五段拆分（gatewayOrigin / gatewayPrefix / serviceName / contextPath / controllerPath），凭据必须来自受管配置，禁止在源码中硬编码 app-key / app-token。**
+
+## 触发条件 / 不适用
+
+**适用**：
+- 外部系统/HR/门户接入平台
+- app-key/app-token 认证
+- Feign 通知接收
+- XML 组织人员同步
+- 接口契约和请求路径核验
+
+**不适用**：
+- 二开库内部 Feign 调用 → `meritdata-platform-cloud-dev`
+- 后端基础设施 → `meritdata-platform-core`
+- 前端联调 → `meritdata-platform-frontend`
+
+## 主题路由
+
+| 任务 | 优先读取 |
+| --- | --- |
+| 网关路径规则、对接预检 | 本文件"网关路径规则"和"对接预检" |
+| 外部 REST API（基础配置/组织/人员/角色/数据源/密级/日程编排） | [`references/external-api.md`](references/external-api.md) |
+| 租户同步推送、权限变更消息、用户/组织/人员变更通知 | [`references/service-notification.md`](references/service-notification.md) |
+| WebService/RESTful 组织人员同步、XML 格式 | [`references/org-user-sync.md`](references/org-user-sync.md) |
+
+### 公司级研发攻略（dev-docs 整合）
+
+| 攻略 | 内容 | 入口 |
+|------|------|------|
+| **攻略09：组织人员同步（8 章）** | 组织/人员/资源菜单/角色/资源权限同步 | 🔀 已抽离到独立 skill：`meritdata-platform-org-sync` |
+
+### 公共资产清单（公司级参考资料）
+
+| 内容 | 入口 |
+|------|------|
+| 服务通知 CloudFeignMessageClient（3.6） | [`references/notification-detail/`](references/notification-detail/) |
+| 完整外部接口清单（19-49） | [`references/external-api/full/`](references/external-api/full/) |
+
+## 工作方式（Step 1/2/3/4）
+
+### Step 1：确认调用方向
+
+- 外部系统调用平台
+- 平台通知二开服务
+- 外部系统同步平台数据
+
+### Step 2：网关路径规则
+
+```
+完整请求路径 = {gatewayOrigin}{gatewayPrefix}/{serviceName}{contextPath}{controllerPath}
+```
+
+- `gatewayOrigin`：协议和主机，无路径
+- `gatewayPrefix`：如 `/gateway`
+- `serviceName`：从 `spring.application.name` 或网关路由取得
+- `contextPath`：从 `server.servlet.context-path`，未配置时为空
+- `controllerPath`：从 Controller 映射
+
+### Step 3：对接预检
+
+- 核对五段路径和 `gatewayPrefix` 没有重复
+- 核对鉴权方式和凭据来源
+- 核对请求 Content-Type、请求体和响应体
+- 资料未给出字段、Header、内容类型时，从目标 Swagger/WSDL 核验
+
+### Step 4：生成代码
+
+按主题路由读取 reference，沿用现有 Feign、HTTP 客户端、鉴权和异常处理约定。
+
+## 🚨 常见错误
+
+| 错误 | 后果 | 正确做法 |
+| --- | --- | --- |
+| 在源码硬编码 app-key | 安全漏洞 | 通过配置中心注入 |
+| 漏掉 gatewayPrefix | 请求 404 | 五段路径全部确认 |
+| Content-Type 假定 | XML/JSON 互调失败 | 目标 Swagger 核验 |
+| 写死环境地址 | 跨环境失效 | 用占位符 |
+
+## 边界
+
+- **不在本 skill 范围的**：
+  - 缓存/Nacos/日志 → `meritdata-platform-core`
+  - 实体字段 → `meritdata-platform-entities`
+  - 前端代理 → `meritdata-platform-frontend`
+  - 调度任务 → `meritdata-platform-job`
+  - BPM 通知 → `meritdata-platform-bpm`
+- **强制要求**：凭据和密钥必须来自受管配置

package/skills/meritdata-platform-integration/agents/openai.yaml

@@ -0,0 +1,33 @@
+display_name: "MeritData 平台集成"
+short_description: "平台开放 REST/WebService 接口、网关鉴权、服务通知、组织人员同步"
+default_prompt: |
+  meritdata-platform-integration 处理平台开放接口和外部集成场景。
+
+  适用场景：
+  - 外部系统/HR/门户接入平台
+  - app-key/app-token 认证
+  - Feign 通知接收（用户/组织/权限变更）
+  - XML/WebService 组织人员同步
+  - 网关路径五段规则（gatewayOrigin/gatewayPrefix/serviceName/contextPath/controllerPath）
+
+  使用方式：
+  ```
+  meritdata-platform-integration <集成需求>
+  ```
+
+  工作方式：
+  1. 确认调用方向：外部调平台 / 平台通知 / 外部同步
+  2. 核对五段路径、Content-Type、凭据来源
+  3. 按主题路由读取 references/ 中的专题 md
+  4. 沿用现有 Feign、HTTP 客户端、鉴权约定
+  5. 前端代理改动交给 meritdata-platform-frontend
+
+  3 个 references：
+  - external-api.md（外部 REST API）
+  - service-notification.md（服务通知）
+  - org-user-sync.md（XML 组织人员同步）
+
+  强制约束：
+  - 凭据必须来自受管配置（不硬编码 app-key）
+  - 不写死环境地址（用占位符）
+  - 路径格式五段必须全部验证

package/skills/{meritdata-dev-docs-file-finder/references/dev-docs → meritdata-platform-integration/references/external-api/full}/22_1.16/347/273/204/347/273/207/344/272/272/345/221/230/345/220/214/346/255/245.md

@@ -322,5 +322,5 @@ related: [10, 34]
 - 推荐同步顺序：**组织 → 角色 → 资源 → 资源权限 → 人员**，避免外键依赖报错
 
 ## 🔗 相关章节
-- [18_目录与文档说明](./18_目录与文档说明.md)
 - 同目录内其他 1.x 接口见 19/20/21
+- 目录与文档说明：见 README `49_附录-4.1-4.3返回码与版本清单.md`

package/skills/{meritdata-dev-docs-file-finder/references/dev-docs → meritdata-platform-integration/references/external-api/full}/39_3.12/346/225/260/346/215/256/346/272/220/347/273/264/346/212/244.md

@@ -9,12 +9,16 @@ related: [38_3.11基础数据.md]
 
 # 3.12 数据源维护
 
+> ⚠️ **2026-09-10 核实警告**：本章节接口路径（`/api/basic/datasource/*`）基于原始外部接口清单（2026-07-16）。源码实测发现 **`cloud-system-manage-module` 模块下不存在 `datasource` 包**——这些接口可能在后续版本中迁移到了 `cloud-system-online-app` 模块的 `TableDefController`（路径 `/datamodel/tabledef/...`）。使用前请在目标项目版本中验证。
+>
 > **原文章节**：`外部接口清单 → 3.12 数据源维护`
 > **行号范围**：L9357-L9607
 
 ## 🎯 一句话
 本章节提供数据源名称前缀生成、数据源删除以及已启用数据源列表查询接口。
 
+**⚠️ 接口路径需在目标版本核实**（见上方警告）。
+
 ## 📋 接口清单
 
 ## 3.12 数据源维护

package/skills/meritdata-platform-integration/references/external-api.md

@@ -0,0 +1,260 @@
+## 概述
+
+按网关路径规则调用：`{gatewayOrigin}{gatewayPrefix}/{serviceName}{contextPath}{controllerPath}`。`gatewayOrigin` 不含路径，`gatewayPrefix` 例如 `/gateway` 且只能出现一次。
+
+响应字段、成功条件、Header 和 `Content-Type` 以目标 Swagger 或服务实现为准；不要假定所有接口共享同一返回体。
+
+---
+
+## 1. 基础配置
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/certificate/allInfo` | POST | 获取产品基本信息 |
+| `/certificate/get-allow-left-drag` | POST | 获取是否可左侧拖动 |
+| `/certificate/get-init-pass` | POST | 获取初始化密码 |
+| `/certificate/getImage` | POST | 获取图片输出流 |
+| `/certificate/getSecretInfo` | POST | 获取平台密级信息 |
+| `/certificate/getCustomPlatform` | POST | 是否自定义平台 |
+| `/certificate/get-tag-url` | POST | 获取 tag 和 image |
+| `/certificate/get-login-link` | POST | 获取登录页超链接 |
+| `/certificate/license-info` | POST | 授权信息 |
+| `/api/send-message` | POST | 保存和发送消息 |
+| `/api/basic/message/get-page` | POST | 消息列表 |
+| `/api/basic/message/{messageId}` | POST | 消息详情 |
+| `/api/basic/message` | POST | 保存消息 |
+| `/api/basic/page` | POST | 首页框架配置 |
+| `/api/user/get-page` | POST | 按角色跳转首页 |
+
+---
+
+## 2. 组织机构
+
+### 2.1 组织维护
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/api/ou/org/create` | POST | 新增组织 |
+| `/api/ou/org/delete` | POST | 删除组织 |
+| `/api/ou/org/disable` | POST | 停用组织 |
+| `/api/ou/org/enable` | POST | 启用组织 |
+| `/api/ou/org/getAll` | POST | 获取所有组织 |
+| `/api/ou/org/get/{id}` | POST | 按 ID 查部门 |
+| `/api/ou/org/list` | POST | 组织列表 |
+| `/api/ou/org/get-by-id/{id}` | POST | 按 ID 查机构 |
+| `/api/ou/org/tree` | POST | 组织机构树 |
+| `/api/ou/org/tree/{orgId}` | POST | 按 ID 获取树 |
+
+### 2.2 人员维护
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/api/ou/emp/create` | POST | 新增人员 |
+| `/api/ou/emp/delete` | POST | 删除人员 |
+| `/api/ou/emp/transfer` | POST | 人员调动 |
+| `/api/ou/emp/get/{id}` | POST | 按 ID 查人员 |
+| `/api/ou/emp/get-emp/{empId}` | POST | 按人员 ID 查信息 |
+| `/api/ou/emp/list` | POST | 人员列表 |
+| `/api/ou/emp/getAll` | POST | 所有人员 |
+| `/api/ou/emp/get-by-role/{roleId}` | POST | 按角色查人员 |
+| `/api/ou/emp/get-by-role-code/{roleCode}` | POST | 按角色编码查人员 |
+| `/api/ou/emp/get-by-group/{groupId}` | POST | 按工作组查人员 |
+| `/api/ou/emp/get-by-org/{orgId}` | POST | 按机构查人员 |
+| `/api/ou/emp/get-by-dept/{deptId}` | POST | 按部门查人员 |
+| `/api/ou/emp/update` | POST | 人员更新 |
+
+### 2.3 角色维护
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/api/ou/role/add-role-member` | POST | 添加角色下人员 |
+| `/api/ou/role/create` | POST | 新增角色 |
+| `/api/ou/role/delete` | POST | 删除角色 |
+| `/api/ou/role/member-list` | POST | 角色下人员列表 |
+| `/api/ou/role/user-role-list` | POST | 用户角色列表 |
+| `/api/ou/role/get-by-code/{code}` | POST | 按编码查角色 ID |
+| `/api/ou/role/current-user-roles` | POST | 当前用户角色 |
+| `/api/ou/role/list` | POST | 角色列表 |
+| `/api/ou/role/sys-role-list` | POST | 系统角色列表 |
+| `/api/ou/role/get-user-by-role/{roleId}` | POST | 按角色获取用户 |
+| `/api/ou/role/delete-user-role` | POST | 删除用户角色 |
+
+### 2.4 用户维护
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/api/ou/user/check-login` | POST | 校验用户是否登录 |
+| `/api/ou/user/create` | POST | 新增用户 |
+| `/api/ou/user/delete` | POST | 删除用户 |
+| `/api/ou/user/disable` | POST | 停用用户 |
+| `/api/ou/user/enable` | POST | 启用用户 |
+| `/api/ou/user/get/{id}` | POST | 按 ID 获取用户 |
+| `/api/ou/user/get-user` | POST | 获取用户信息 |
+| `/api/ou/user/password-strength` | POST | 密码强度规则 |
+| `/api/ou/user/list` | POST | 用户列表 |
+| `/api/ou/user/getAll` | POST | 所有用户 |
+| `/api/ou/user/init-pass` | POST | 密码初始化 |
+| `/api/ou/user/change-password` | POST | 修改密码 |
+
+---
+
+## 3. 资源管理
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/api/authority/resource/get-by-role/{roleId}` | POST | 按角色获取资源 ID 集合 |
+| `/api/authority/resource/delete-by-resource` | POST | 删除资源权限 |
+| `/api/authority/resource/get-by-user/{userId}` | POST | 按用户获取资源 ID 集合 |
+| `/api/authority/resource/get-permission` | POST | 按资源查权限 |
+| `/api/authority/resource/get-user-detail` | POST | 按人授权详情 |
+| `/api/authority/resource/menu-auth` | POST | 按菜单授权 |
+| `/api/authority/resource/resource-auth` | POST | 按资源授权 |
+| `/api/authority/resource/delete-all-permission` | POST | 删除全部权限 |
+| `/api/authority/resource/auth-tree` | POST | 授权列表树 |
+| `/api/authority/resource/create` | POST | 新增资源 |
+| `/api/authority/resource/delete` | POST | 删除资源 |
+| `/api/authority/resource/list` | POST | 资源列表 |
+| `/api/authority/resource/update` | POST | 更新资源 |
+| `/api/authority/resource/query-resource-by-id` | POST | 按 ID 查资源 |
+| `/api/authority/resource/menu-tree` | POST | 用户门户菜单树 |
+| `/api/authority/resource/delete-by-code` | POST | 按扩展字段删除资源 |
+
+## 4. 数据源与服务管理
+
+### 数据源
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/api/basic/datasource/create-prefix` | POST | 创建数据源前缀 |
+| `/api/basic/datasource/delete` | POST | 删除数据源 |
+| `/api/basic/datasource/list-enabled` | POST | 获取已启用数据源列表 |
+| `/api/basic/datasource/param` | POST | 查询数据源详情 |
+| `/api/basic/datasource/sync` | POST | 同步数据源 |
+
+### 服务管理
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/api/basic/service/app-list` | POST | 应用信息列表 |
+| `/api/basic/service/create` | POST | 创建服务 |
+| `/api/basic/service/delete/{id}` | POST | 删除服务 |
+| `/api/basic/service/get/{id}` | POST | 获取服务信息 |
+| `/api/basic/service/add-permission` | POST | 添加服务权限 |
+| `/api/basic/service/remove-permission` | POST | 移除服务权限 |
+
+---
+
+## 5. 数据密级
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/api/basic/secret/get-data-secret-scope` | POST | 数据密级范围 |
+| `/api/basic/secret/get-data-secret-config` | POST | 数据密级配置 |
+| `/api/basic/secret/get-data-secret-dict` | POST | 密级数据字典 |
+
+---
+
+## 6. 日程编排
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/api/basic/schedule/check-system-schedule-status` | POST | 查询业务系统编排状态 |
+| `/taier/batchTask/create-flow-and-task` | POST | 生成业务流及任务并发布 |
+| `/schedule/thirdSystemDealScheduleJob` | POST | 调度编排立即执行 |
+
+---
+
+## 7. 人员选择器
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/api/ou/org/get-by-pid/{pid}` | POST | 按 PID 查组织机构 |
+| `/api/ou/org/get-with-roles/{orgId}` | POST | 机构下级+角色 |
+| `/api/ou/emp/get-by-org/{orgId}` | POST | 按组织查人员 |
+| `/api/ou/emp/get-by-role/{roleId}` | POST | 按角色查人员 |
+| `/api/ou/emp/get-by-ids` | POST | 按人员 ID 集合查信息 |
+| `/api/ou/org/get-with-groups/{orgId}` | POST | 机构下级+工作组 |
+
+---
+
+## 附录：错误码
+
+| 错误码 | 说明 |
+|--------|------|
+| `SYS_API_0000` | 成功 |
+| `SYS_API_999` | 参数校验失败 |
+| `SYS_API_998` | 调用接口失败 |
+| `SYS_API_997` | 附件大小不符合规范 |
+
+---
+
+## 外部接口注意事项
+
+1. 所有接口先按目标网关路由核对；不要将本清单中的路径片段视为完整地址。
+2. 组织人员同步接口（`/webapi/ou/sync/*`）的 `app-key` 和 `app-token` 从受管配置读取。
+3. 详细参数、Header、内容类型和返回体以目标 Swagger 或服务实现为准。
+4. **完整接口清单**：本文档为结构化提取，涵盖主要接口分类。完整的 17000+ 行接口目录（含请求参数、返回体示例）见根目录 `微服务外部接口清单.md`。
+
+---
+
+## ⚠️ 接口路径与拼写陷阱速查（基于 2026-09-10 源码实测）
+
+### 1. 内部 API 与外部 WebApi 前缀区分
+
+| 路径前辍 | 用途 | 适用 skill |
+|---------|------|----------|
+| `/api/...`（如 `/api/ou/org/list`）| 内部 API（前端/同 JVM 调用）| `meritdata-platform-integration` |
+| `/webapi/...`（如 `/webapi/ou/user/handset/changePass`）| **外部接口**（跨系统对接，HTTP）| 单独章节 |
+
+**陷阱**：外部接口不是 `/api/ou/user/...` 而是 `/webapi/ou/user/...`，**前辍不同**！调用时必须按实际接口前缀选择。
+
+### 2. 已知的源码拼写错误（按源码原样保留）
+
+| 错误路径 | 正确拼写应为 | 影响 |
+|---------|-----------|------|
+| `/api/authority/assign/delete-by-resouce` | `delete-by-resource`（少一个 r）| 路径段"resouce"而非"resource" |
+| `/api/authority/assign/delete-by-resouce-all` | `delete-by-resource-all` | 同上 |
+| `/api/authority/assign/delete-by-resouce-objid` | `delete-by-resource-objid` | 同上 |
+| `/api/authority/assign/aaignTreeByOrg` | `assignTreeByOrg`（aaign 而非 assign）| 方法名也拼错 |
+
+**⚠️ 重要**：skill 文档**按源码原样引用**这些路径（不自行"修正"），否则接口会 404。源码修复后才能在文档中修正。
+
+### 3. 类级别路径斜杠不一致
+
+| Controller | 类级别路径 | 备注 |
+|-----------|----------|------|
+| `OrgController` | `/api/ou/org/` | 有尾斜杠 |
+| `EmpController` | `/api/ou/emp/` | 有尾斜杠 |
+| `RoleController` | `/api/ou/role` | **无尾斜杠** |
+| `WorkGroupController` | `/api/ou/workgroup` | **无尾斜杠** |
+| `ResourceController` | `/api/authority/resource` | 无尾斜杠 |
+| `AssignController` | `/api/authority/assign` | 无尾斜杠 |
+| `LookupController` | `/api/basic/lookup` | 无尾斜杠 |
+
+Spring MVC 会规范化，但文档应准确反映源码。
+
+### 4. CRUD 方法名风格不统一
+
+| Controller | 新增方法 | 修改方法 | 删除方法 |
+|-----------|---------|---------|---------|
+| `OrgController` | `create` | `update` | `delete` |
+| `EmpController` | `create` / `create1` | `update` / `update1` | `delete` |
+| `RoleController` | `create` | `update` | `delete` |
+| `WorkGroupController` | `add`（但 URL 是 `/create`）| `edit`（URL 是 `/update`）| `remove`（URL 是 `/delete`）|
+
+**陷阱**：skill 文档若引用 `/api/ou/workgroup/save`，**不存在**——实际 URL 是 `/api/ou/workgroup/create`。
+
+### 5. 顶层 `save` 端点陷阱
+
+只有以下路径含顶层 `save`：
+- `/api/ou/org/save/nacos`（保存 Nacos 配置，**非业务保存**）
+
+其他 Controller 没有顶层 `save` 端点，新增/修改用 `create`/`update`/`add`/`edit`。
+
+### 6. 数据源维护（3.12）路径待核实
+
+⚠️ **2026-09-10 核实警告**：3.12 数据源维护接口（`/api/basic/datasource/*`）的来源是 2026-07-16 原始外部接口清单。源码实测发现 `cloud-system-manage-module` 模块下不存在 `datasource` 包——可能已迁移到 `cloud-system-online-app` 模块的 `TableDefController`（路径 `/datamodel/tabledef/...`）。
+
+**使用前必须在目标版本中验证**。详细见 `external-api/full/39_3.12数据源维护.md` 顶部警告。
+
+---

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 格式以《组织和人员同步》使用攻略及目标接口实现为准。