@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/skills/meritdata-platform-data-access/references/inbound/sync-contracts.md

@@ -0,0 +1,225 @@
+# 外部系统同步契约选型（sync-contracts）
+
+> **目的**：合并自研发版 `meritdata-platform-masterdata-sync`（L3-C 单点 API 待建项 v2.4.0），按"集成方向"作为 data-access 的 inbound 子分支。
+> **场景**：HR/ERP/LDAP 系统的组织/人员/角色/资源/授权数据向 MeritData Cloud 推送。
+> **来源**：研发 + 石油 22-modules `merit-cloud-masterdata-sync`。
+
+---
+
+## 一、两种通道选型
+
+### 1.1 REST vs WebService 决策表
+
+| 维度 | REST（HTTP/JSON） | WebService（SOAP/XML） |
+|------|-------------------|------------------------|
+| **典型外部系统** | HR SaaS、ERP 新版、IAM | 老 HR、传统 ERP、银行核心、国企 LDAP |
+| **协议** | HTTP + JSON | SOAP 1.1/1.2 + WSDL + XML |
+| **认证** | OAuth2 / API Key / JWT | WS-Security + X.509 证书 |
+| **并发** | 高（HTTP/2）| 低（XML 解析重）|
+| **调试** | curl / Postman 简单 | SoapUI / XMLSpy |
+| **安全风险** | token 泄露 / 中间人 | XXE / DTD / 外部实体 / SOAP 反序列化 |
+| **审计** | HTTP header + body | SOAPAction + XML body |
+
+### 1.2 选型流程
+
+```
+Step 1：外部系统是否提供 REST API？
+   ├─ 是 → 用 REST（首选）
+   └─ 否（仅 SOAP/WSDL）→ Step 2
+
+Step 2：是否需要 WS-Security？
+   ├─ 是 → WebService + 证书
+   └─ 否 → WebService（HTTP Basic）
+
+Step 3：认证 + 反序列化 + 审计如何做？
+   → 见 inbound/adapter-pattern.md + inbound/xml-security.md
+```
+
+---
+
+## 二、REST 通道契约
+
+### 2.1 标准路径
+
+```
+POST /api/cloud-data-sync/{bizType}
+Content-Type: application/json
+Authorization: Bearer {token}
+
+# 业务类型 bizType
+org          同步组织
+user         同步人员
+role         同步角色
+position     同步职务
+resource     同步资源
+authorization 同步授权
+```
+
+### 2.2 请求体（canonical）
+
+```json
+{
+  "sourceSystem": "HR_SYSTEM",
+  "batchNo": "HR20260908150000",
+  "operation": "UPSERT",   // UPSERT / DELETE
+  "items": [
+    {
+      "bizKey": "ORG-001",
+      "payload": {
+        "orgCode": "ORG-001",
+        "orgName": "总部",
+        "parentCode": null,
+        "sortNo": 1
+      }
+    }
+  ]
+}
+```
+
+### 2.3 响应体
+
+```json
+{
+  "code": 200,
+  "batchNo": "HR20260908150000",
+  "successCount": 95,
+  "failureCount": 5,
+  "failures": [
+    {
+      "bizKey": "USER-2001",
+      "phase": "VALIDATE",
+      "errorCode": "ERR_PARENT_ORG_NOT_FOUND",
+      "message": "父组织 ORG-999 不存在"
+    }
+  ],
+  "replayable": true
+}
+```
+
+---
+
+## 三、WebService 通道契约
+
+### 3.1 WSDL 关键点
+
+```xml
+<definitions name="MasterDataSync"
+  targetNamespace="http://cloud.meritdata.com/sync"
+  xmlns:tns="http://cloud.meritdata.com/sync">
+  
+  <types>
+    <xsd:element name="SyncRequest">
+      <xsd:complexType>
+        <xsd:sequence>
+          <xsd:element name="sourceSystem" type="xsd:string"/>
+          <xsd:element name="batchNo" type="xsd:string"/>
+          <xsd:element name="items" type="tns:SyncItem" minOccurs="0" maxOccurs="unbounded"/>
+        </xsd:sequence>
+      </xsd:complexType>
+    </xsd:element>
+  </types>
+  
+  <message name="SyncRequestMessage">
+    <part name="parameters" element="tns:SyncRequest"/>
+  </message>
+  
+  <portType name="MasterDataSyncPort">
+    <operation name="syncOrg">
+      <input message="tns:SyncRequestMessage"/>
+      <output message="tns:SyncResponseMessage"/>
+    </operation>
+  </portType>
+</definitions>
+```
+
+### 3.2 SOAP 请求示例
+
+```xml
+<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
+                  xmlns:sync="http://cloud.meritdata.com/sync">
+  <soapenv:Header>
+    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
+      <wsse:UsernameToken>
+        <wsse:Username>HR_SYSTEM</wsse:Username>
+        <wsse:Password Type="...#PasswordDigest">...</wsse:Password>
+      </wsse:UsernameToken>
+    </wsse:Security>
+  </soapenv:Header>
+  
+  <soapenv:Body>
+    <sync:SyncRequest>
+      <sync:sourceSystem>HR_SYSTEM</sync:sourceSystem>
+      <sync:batchNo>HR20260908150000</sync:batchNo>
+      <sync:items>
+        <sync:bizKey>ORG-001</sync:bizKey>
+        <sync:payload>...</sync:payload>
+      </sync:items>
+    </sync:SyncRequest>
+  </soapenv:Body>
+</soapenv:Envelope>
+```
+
+### 3.3 禁用清单（WebService 必读）
+
+| 禁止 | 理由 |
+|------|------|
+| ❌ 字符串拼接 XML | 注入风险 |
+| ❌ 启用 DTD | XXE 攻击 |
+| ❌ 解析外部实体 | 读取本地文件 / SSRF |
+| ❌ 使用 XInclude | 注入风险 |
+| ❌ 关闭 SOAPAction 校验 | 攻击者可改路由 |
+
+---
+
+## 四、认证编目
+
+| 通道 | 认证 | 配置位置 |
+|------|------|---------|
+| REST | OAuth2 client_credentials | nacos `meritdata.cloud.masterdata-sync.rest.token-url` |
+| REST | API Key（Header X-API-Key）| nacos `meritdata.cloud.masterdata-sync.rest.api-key` |
+| WebService | WS-Security UsernameToken | nacos `meritdata.cloud.masterdata-sync.ws.username` + `.password` |
+| WebService | X.509 证书 | nacos `meritdata.cloud.masterdata-sync.ws.cert-path` |
+
+> 详细配置规范 → 见 `meritdata-platform-nacos-config/references/configuration-properties.md`
+
+---
+
+## 五、与 outbound 的差异
+
+| 维度 | outbound（Feign）| inbound（REST/WS） |
+|------|------------------|---------------------|
+| 触发起源 | 二开业务代码 | 外部系统 |
+| 协议 | HTTP + JSON | HTTP/JSON 或 SOAP/XML |
+| 幂等 | 业务键 upsert | 批次号 + 业务键幂等 |
+| 失败处理 | 重试即可 | 阶段状态 + 可重放 |
+| 审计 | 可选 | **必须**（外部数据写平台）|
+| 安全 | OAuth token | XML 安全 + 业务键验证 |
+
+---
+
+## 六、典型集成清单
+
+| 集成源 | 通道 | bizType | 同步顺序 |
+|--------|------|---------|----------|
+| HR 系统（员工/组织）| REST 或 WS | org + position + user | 组织 → 职务 → 人员 |
+| IAM（统一身份）| REST | user + role + authorization | 组织 → 角色 → 人员 → 资源 → 授权 |
+| ERP 主数据 | WS | org + resource | 组织 → 资源 |
+| LDAP 目录 | REST | user | 人员（依赖组织已同步）|
+| 财务系统 | REST | resource + authorization | 资源 → 授权 |
+
+---
+
+## 七、与 playbook/cloud-dev 的协作
+
+| 场景 | 协作 skill |
+|------|----------|
+| WebService 通道（认证编目）| `meritdata-platform-platform-config/references/basic-config-api.md` |
+| 二开主动调平台（outbound）| 本 skill 的 outbound/ |
+| Feign 批量装配 | `references/outbound/batch-assembly.md` |
+| 平台 DTO 字段 | `references/outbound/dto-catalog.md` |
+
+---
+
+**最后更新**：2026-09-08（v2.5.0 P1-A 合并自 masterdata-sync）
+**来源**：石油/研发 `merit-cloud-masterdata-sync` 22-modules + module.md
+**整合位置**：`meritdata-platform-data-access/references/inbound/sync-contracts.md`

package/skills/meritdata-platform-data-access/references/inbound/xml-security.md

@@ -0,0 +1,411 @@
+# XML 安全（xml-security）
+
+> **目的**：WebService（SOAP/XML）通道的 XXE / DTD / 外部实体 / SOAPAction 防护。
+> **场景**：解析来自 HR/ERP/银行的 SOAP 请求。
+> **来源**：研发/石油 `merit-cloud-masterdata-sync` 22-modules + security-rules §五。
+
+---
+
+## 一、为什么 XML 安全是 P0
+
+### 1.1 攻击面
+
+WebService 默认解析器支持 DTD + 外部实体 → 一旦启用 = **RCE / 文件读取 / SSRF**。
+
+| 攻击 | 影响 |
+|------|------|
+| XXE (XML External Entity) | 读取服务器任意文件、SSRF |
+| DTD Recursion | DoS（XML 炸弹）|
+| SOAP 反序列化 | RCE |
+| XPath 注入 | 越权访问 |
+| XML 签名绕过 | 完整性失效 |
+
+### 1.2 历史教训
+
+2017 年 OWASP Top 10 把 XXE 列为 A4（XML External Entities）。2018 年后多数语言默认禁用，但仍要主动验证。
+
+---
+
+## 二、5 条铁律（MUST DO）
+
+### 2.1 禁用 DTD
+
+```java
+// ✅ 正确：禁用 DTD
+SAXParserFactory factory = SAXParserFactory.newInstance();
+factory.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
+SAXParser parser = factory.newSAXParser();
+```
+
+```java
+// ❌ 错误：允许 DTD
+SAXParserFactory factory = SAXParserFactory.newInstance();
+// 默认支持 DTD → XXE 风险
+```
+
+### 2.2 禁用外部实体
+
+```java
+// ✅ 正确：禁用外部实体
+DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
+dbf.setFeature("http://xml.org/sax/features/external-general-entities", false);
+dbf.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
+dbf.setFeature("http://apache.org/xml/features/nonvalidating/load-external-dtd", false);
+dbf.setXIncludeAware(false);
+dbf.setExpandEntityReferences(false);
+```
+
+### 2.3 限制解析大小（防 DoS）
+
+```java
+// ✅ 正确：限制 XML 大小
+SAXParserFactory factory = SAXParserFactory.newInstance();
+factory.setFeature("http://javax.xml.XMLConstants/feature/secure-processing", true);
+
+// 限制实体扩展次数
+XMLReader xmlReader = XMLReaderFactory.createXMLReader();
+xmlReader.setFeature("http://apache.org/xml/features/max-entity-expansion", 100);
+
+// 限制最大元素深度
+SAXParser parser = factory.newSAXParser();
+parser.setProperty("http://www.sax.org/xml/properties/depth-limit", 100);
+```
+
+### 2.4 禁用 SOAPAction 攻击
+
+```java
+// ✅ 正确：验证 SOAPAction 白名单
+public void handleSoapRequest(HttpServletRequest request) {
+    String soapAction = request.getHeader("SOAPAction");
+    List<String> allowedActions = Arrays.asList(
+        "syncOrg", "syncUser", "syncRole", "syncPosition", "syncResource", "syncAuthorization"
+    );
+
+    if (!allowedActions.contains(soapAction)) {
+        throw new SoapActionDeniedException("SOAPAction 不在白名单：" + soapAction);
+    }
+}
+```
+
+### 2.5 不使用字符串拼接 XML
+
+```java
+// ❌ 错误：字符串拼接
+String xml = "<user><name>" + userInput + "</name></user>";
+
+// ✅ 正确：使用安全序列化器（Jackson XML / JAXB）
+String xml = xmlMapper.writeValueAsString(user);
+```
+
+---
+
+## 三、解析器配置模板
+
+### 3.1 SAX 解析（流式，适合大文件）
+
+```java
+public class SecureXmlParser {
+
+    public static SAXParser createSecureSAXParser() throws Exception {
+        SAXParserFactory factory = SAXParserFactory.newInstance();
+
+        // 禁用 DTD
+        factory.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
+
+        // 禁用外部实体
+        factory.setFeature("http://xml.org/sax/features/external-general-entities", false);
+        factory.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
+        factory.setFeature("http://apache.org/xml/features/nonvalidating/load-external-dtd", false);
+
+        // 限制实体扩展
+        factory.setFeature("http://javax.xml.XMLConstants/feature/secure-processing", true);
+
+        // 不解析外部 XInclude
+        factory.setXIncludeAware(false);
+
+        return factory.newSAXParser();
+    }
+}
+```
+
+### 3.2 DOM 解析（树模型，适合小文档）
+
+```java
+public static DocumentBuilder createSecureDocumentBuilder() throws Exception {
+    DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
+
+    // 同 SAX 全部安全配置
+    dbf.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
+    dbf.setFeature("http://xml.org/sax/features/external-general-entities", false);
+    dbf.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
+    dbf.setFeature("http://apache.org/xml/features/nonvalidating/load-external-dtd", false);
+    dbf.setFeature("http://javax.xml.XMLConstants/feature/secure-processing", true);
+    dbf.setXIncludeAware(false);
+    dbf.setExpandEntityReferences(false);
+
+    return dbf.newDocumentBuilder();
+}
+```
+
+### 3.3 JAXB 反序列化（对象绑定）
+
+```java
+// ✅ 正确：使用带安全配置的 Unmarshaller
+public class SecureJaxbContext {
+
+    public static <T> T parseXml(InputStream xml, Class<T> clazz) throws Exception {
+        // 1. 先用安全解析器解析为 Document
+        DocumentBuilder db = SecureXmlParser.createSecureDocumentBuilder();
+        Document doc = db.parse(xml);
+
+        // 2. 再用 JAXB 转对象
+        JAXBContext context = JAXBContext.newInstance(clazz);
+        Unmarshaller unmarshaller = context.createUnmarshaller();
+        return unmarshaller.unmarshal(doc, clazz).getValue();
+    }
+}
+```
+
+### 3.4 Spring WebService 配置
+
+```java
+@Configuration
+public class WebServiceSecurityConfig {
+
+    @Bean
+    public SaajSoapMessageFactory messageFactory() {
+        SaajSoapMessageFactory factory = new SaajSoapMessageFactory();
+        factory.setSoapVersion(SoapVersion.SOAP_12);
+
+        // 禁用外部实体
+        Map<String, Object> properties = new HashMap<>();
+        properties.put("javax.xml.soap.SOAPConnectionFactory",
+            "com.sun.xml.messaging.saaj.client.p2p.HttpSOAPConnectionFactory");
+        properties.put("com.sun.xml.internal.ws.disableExternalEntityProcessing", "true");
+
+        factory.setMessageProperties(properties);
+        return factory;
+    }
+}
+```
+
+---
+
+## 四、典型攻击与防御
+
+### 4.1 XXE 读取文件
+
+**攻击 payload**：
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE foo [
+  <!ENTITY xxe SYSTEM "file:///etc/passwd">
+]>
+<sync:SyncRequest>
+  <sync:sourceSystem>&xxe;</sync:sourceSystem>
+  ...
+</sync:SyncRequest>
+```
+
+**防护**：禁用外部实体 → entity 不解析 → `&xxe;` 变为普通字符串。
+
+### 4.2 XXE SSRF
+
+**攻击 payload**：
+
+```xml
+<!ENTITY xxe SYSTEM "http://internal-server/admin">
+```
+
+**防护**：同 4.1，禁用外部实体。
+
+### 4.3 XML 炸弹（DoS）
+
+**攻击 payload**：
+
+```xml
+<?xml version="1.0"?>
+<!DOCTYPE lolz [
+  <!ENTITY lol "lol">
+  <!ENTITY lol2 "&lol;&lol;&lol;&lol;&lol;">
+  <!ENTITY lol3 "&lol2;&lol2;&lol2;&lol2;&lol2;">
+  ...
+]>
+<lolz>&lol3;</lolz>
+```
+
+**防护**：限制实体扩展次数 + 限制 XML 大小。
+
+### 4.4 SOAPAction 攻击
+
+**攻击**：把 `SOAPAction: syncUser` 改为 `SOAPAction: deleteAllUsers`，路由到错误操作。
+
+**防护**：白名单验证 SOAPAction。
+
+### 4.5 XPath 注入
+
+**攻击**：业务字段含 `' or '1'='1`，XPath 查询被注入。
+
+**防护**：参数化 XPath 查询 + 输入校验。
+
+---
+
+## 五、Jackson XML 输出安全
+
+### 5.1 配置
+
+```java
+XmlMapper xmlMapper = new XmlMapper();
+
+// 禁用外部实体（默认已禁用，但显式声明）
+xmlMapper.getFactory().setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
+
+// 不输出 XML 声明中的 standalone="yes"
+xmlMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
+```
+
+### 5.2 不输出敏感字段
+
+```java
+@JsonIgnoreProperties({"password", "secretKey"})
+public class SyncRequest {
+    private String sourceSystem;
+    private String batchNo;
+    private List<SyncItem> items;
+}
+```
+
+---
+
+## 六、安全配置清单
+
+| 配置项 | 推荐值 | 理由 |
+|--------|--------|------|
+| `disallow-doctype-decl` | `true` | 防 DTD |
+| `external-general-entities` | `false` | 防 XXE |
+| `external-parameter-entities` | `false` | 防 XXE |
+| `load-external-dtd` | `false` | 防 XXE |
+| `secure-processing` | `true` | 通用加固 |
+| `XIncludeAware` | `false` | 防 XInclude |
+| `expandEntityReferences` | `false` | 防实体扩展 |
+| `max-entity-expansion` | `100` | 防 DoS |
+| `depth-limit` | `100` | 防嵌套炸弹 |
+| XML 最大大小 | `10MB` | 防 DoS |
+
+---
+
+## 七、安全审计
+
+### 7.1 检测清单
+
+```bash
+# 检测是否启用了 DTD
+grep -rn "setFeature.*disallow-doctype-decl" src/main/java/
+  └── 必须存在 true 配置
+
+# 检测外部实体
+grep -rn "external-general-entities" src/main/java/
+  └── 必须存在 false 配置
+
+# 检测字符串拼接 XML
+grep -rn 'String.*"<.*\${.*}"' src/main/java/
+  └── 应该为空（仅生成代码用，业务代码禁用）
+```
+
+### 7.2 CI 集成
+
+```yaml
+# .gitlab-ci.yml
+check-xml-security:
+  script:
+    - bash tools/check-xxe-config.sh src/main/java/
+  allow_failure: false
+```
+
+---
+
+## 八、与其他 skill 的协作
+
+| 安全维度 | 协作 skill |
+|---------|----------|
+| SQL 注入（PreparedStatement）| `security-rules.md §一` |
+| 敏感信息脱敏 | `security-rules.md §三` |
+| 文件路径穿越 | `security-rules.md §五` |
+| 错误信息泄露 | `security-rules.md §六` |
+| 二开业务数据 | `data-classification/references/hibernate-filter.md` |
+
+---
+
+## 九、典型场景示例
+
+### 9.1 Spring WS 安全配置
+
+```java
+@Endpoint
+public class MasterDataSyncEndpoint {
+
+    @PayloadRoot(namespace = "http://cloud.meritdata.com/sync",
+                 localPart = "SyncRequest")
+    @ResponsePayload
+    public SyncResponse sync(@RequestPayload SyncRequest request) {
+        // 1. 业务键幂等
+        if (batchStateRepo.existsByBatchNo(request.getBatchNo())) {
+            return SyncResponse.duplicate(request.getBatchNo());
+        }
+
+        // 2. 转换（用安全 JAXB 反序列化）
+        // (已在上游拦截器中用安全解析器)
+
+        // 3. 执行业务
+        // ...
+
+        return SyncResponse.success(request.getBatchNo());
+    }
+}
+```
+
+### 9.2 拦截器层安全检查
+
+```java
+@Component
+public class SoapSecurityInterceptor extends EndpointInterceptorAdapter {
+
+    @Override
+    public boolean handleRequest(MessageContext messageContext, Object endpoint) {
+        SoapMessage message = (SoapMessage) messageContext.getRequest();
+
+        // 1. 验证 SOAPAction 白名单
+        String action = message.getSoapAction();
+        if (!ALLOWED_ACTIONS.contains(action)) {
+            throw new SoapActionDeniedException(action);
+        }
+
+        // 2. 验证消息大小
+        if (message.getPayload().getByteArray().length > MAX_SIZE) {
+            throw new MessageTooLargeException();
+        }
+
+        return true;
+    }
+}
+```
+
+---
+
+## 十、常见错误
+
+| 错误 | 后果 | 正确做法 |
+|------|------|---------|
+| 用 DocumentBuilderFactory.newInstance() 默认配置 | XXE 漏洞 | 显式禁用 DTD + 外部实体 |
+| 字符串拼接 XML | XML 注入 | JAXB / Jackson XML |
+| 不限制 XML 大小 | DoS | max-entity-expansion + 大小限制 |
+| SOAPAction 不校验 | 路由到错误操作 | 白名单 |
+| XPath 拼接 | XPath 注入 | 参数化查询 |
+| 异常信息泄露物理路径 | 信息泄露 | 统一错误处理 |
+
+---
+
+**最后更新**：2026-09-08（v2.5.0 P1-A 合并自 masterdata-sync）
+**来源**：石油/研发 `merit-cloud-masterdata-sync` 22-modules + security-rules §五
+**整合位置**：`meritdata-platform-data-access/references/inbound/xml-security.md`