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

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

@@ -1,225 +0,0 @@
-# 外部系统同步契约选型（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

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