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

package/skills/meritdata-platform-data-access/references/inbound/adapter-pattern.md

@@ -0,0 +1,431 @@
+# 适配层模式（adapter-pattern）
+
+> **目的**：设计"来源 DTO → canonical payload → 平台 payload"的三层适配模式，让 N 个外部系统只需写 N 个适配器，而不是 N×M 个。
+> **场景**：HR/ERP/LDAP 等多个外部系统接入同一平台。
+> **来源**：研发/石油 `merit-cloud-masterdata-sync` 22-modules。
+
+---
+
+## 一、三层适配架构
+
+```
+┌─────────────────┐
+│   来源系统       │ HR_SYSTEM (Oracle + 自定义字段)
+│   DTO (不统一)   │
+└────────┬────────┘
+         │ 适配器 A
+         ▼
+┌─────────────────┐
+│  Canonical      │ 通用规范（与具体系统无关）
+│  Payload        │
+└────────┬────────┘
+         │ 适配器 B
+         ▼
+┌─────────────────┐
+│  平台 Payload    │ 平台 DTO（统一）
+└─────────────────┘
+```
+
+**关键优势**：
+- 新增外部系统只需写 1 个适配器（不是 M 个）
+- 平台侧适配器只写一次（所有外部系统共用）
+- 适配逻辑可单测（与平台解耦）
+
+---
+
+## 二、来源 DTO → Canonical（适配器 A）
+
+### 2.1 HR 系统原始 DTO
+
+```java
+@Data
+public class HrUserDTO {
+    private String EMP_ID;              // 工号
+    private String EMP_NAME;            // 姓名
+    private String EMAIL_ADDR;          // 邮箱
+    private String DEPT_CODE;           // 部门代码
+    private String STATUS;              // A=在职 / D=离职
+    private Date HIRE_DATE;             // 入职日期
+}
+```
+
+### 2.2 适配器 A：HR DTO → Canonical
+
+```java
+@Component
+public class HrUserToCanonicalAdapter implements CanonicalAdapter<HrUserDTO> {
+
+    @Override
+    public String getSourceSystem() {
+        return "HR_SYSTEM";
+    }
+
+    @Override
+    public String getBizType() {
+        return "user";
+    }
+
+    @Override
+    public CanonicalItem adapt(HrUserDTO hrUser) {
+        CanonicalItem item = new CanonicalItem();
+
+        // 业务键：HR 工号（稳定）
+        item.setBizKey("USER-" + hrUser.getEMP_ID());
+
+        // 父业务键：组织 bizKey
+        item.setParentBizKey("ORG-" + hrUser.getDEPT_CODE());
+
+        // 删除语义：HR 的 STATUS=D 映射为 DELETE
+        if ("D".equals(hrUser.getSTATUS())) {
+            item.setOperation(Operation.DELETE);
+        } else {
+            item.setOperation(Operation.UPSERT);
+        }
+
+        // payload：按 canonical schema 装填
+        item.setPayload(new CanonicalUserPayload()
+            .setUserCode("USER-" + hrUser.getEMP_ID())
+            .setUserName(hrUser.getEMP_NAME())
+            .setEmail(hrUser.getEMAIL_ADDR())
+            .setOrgCode("ORG-" + hrUser.getDEPT_CODE())
+            .setEnabled(!"D".equals(hrUser.getSTATUS()))
+            .setHireDate(formatDate(hrUser.getHIRE_DATE())));
+
+        return item;
+    }
+}
+```
+
+### 2.3 不同外部系统的差异化点
+
+| 维度 | HR_SYSTEM | IAM_SYSTEM | ERP_SYSTEM |
+|------|-----------|------------|-----------|
+| 业务键生成 | `USER-{工号}` | `U-{uuid}` | `EMP-{empId}` |
+| 删除语义字段 | `STATUS = 'D'` | `disabled = true` | `ACTIVE_FLAG = 'N'` |
+| 字段名映射 | `EMP_NAME → userName` | `displayName → userName` | `NAME → userName` |
+
+---
+
+## 三、Canonical → 平台 Payload（适配器 B）
+
+### 3.1 平台 DTO
+
+```java
+@Data
+public class CloudUserDTO {
+    private Long id;
+    private String userCode;
+    private String userName;
+    private String email;
+    private Long orgId;          // 平台内部组织 ID
+    private Long positionId;
+    private Boolean enabled;
+    private Boolean deleted;
+}
+```
+
+### 3.2 适配器 B：Canonical → 平台 DTO
+
+```java
+@Component
+public class CanonicalUserToCloudAdapter implements CloudAdapter<CanonicalUserPayload, CloudUserDTO> {
+
+    @Autowired
+    private OrgFeignClient orgClient;       // 平台 Feign 批量查 orgId
+
+    @Override
+    public CloudUserDTO adapt(CanonicalUserPayload canonical, BizKeyMappingCache cache) {
+        CloudUserDTO cloudUser = new CloudUserDTO();
+
+        cloudUser.setUserCode(canonical.getUserCode());
+        cloudUser.setUserName(canonical.getUserName());
+        cloudUser.setEmail(canonical.getEmail());
+        cloudUser.setEnabled(canonical.getEnabled());
+        cloudUser.setDeleted(false);
+
+        // 关键：用 bizKey → 平台内部 ID 映射
+        Long orgId = cache.getOrgId(canonical.getOrgCode());
+        if (orgId == null) {
+            throw new SyncException(
+                "ERR_ORG_NOT_SYNCED",
+                "组织 " + canonical.getOrgCode() + " 未同步，请先同步组织"
+            );
+        }
+        cloudUser.setOrgId(orgId);
+
+        return cloudUser;
+    }
+}
+```
+
+---
+
+## 四、BizKey 映射缓存
+
+### 4.1 为什么需要
+
+**bizKey 是外部系统的稳定键**，平台内部用 ID（Long）。
+
+**每次同步都要查**：
+- 人员 → 查组织的 orgId
+- 授权 → 查 userId、resourceId
+- 没有缓存 → 每次 N+1 Feign 调用
+
+### 4.2 缓存实现
+
+```java
+@Component
+public class BizKeyMappingCache {
+
+    @Autowired
+    private OrgFeignClient orgClient;
+
+    @Autowired
+    private UserFeignClient userClient;
+
+    // bizKey → platformId 缓存
+    private final Cache<String, Long> orgIdCache = Caffeine.newBuilder()
+        .maximumSize(10_000)
+        .expireAfterWrite(Duration.ofHours(1))
+        .build();
+
+    /**
+     * 同步时预热（一次 Feign 拉全量）
+     */
+    public void warmUp(String sourceSystem, String bizType) {
+        if ("org".equals(bizType)) {
+            List<OrgDTO> orgs = orgClient.listBySourceSystem(sourceSystem);
+            orgs.forEach(o -> orgIdCache.put(o.getOrgCode(), o.getId()));
+        }
+    }
+
+    /**
+     * 查询 + 缺失时回查 Feign
+     */
+    public Long getOrgId(String orgCode) {
+        Long cached = orgIdCache.getIfPresent(orgCode);
+        if (cached != null) return cached;
+
+        // 缓存未命中 → Feign 查询
+        OrgDTO org = orgClient.getByCode(orgCode);
+        if (org == null) return null;
+
+        orgIdCache.put(orgCode, org.getId());
+        return org.getId();
+    }
+}
+```
+
+### 4.3 缓存失效
+
+| 触发 | 失效策略 |
+|------|---------|
+| 同步 org 成功 | 更新对应 orgCode 缓存 |
+| 批量同步结束 | 不失效（依赖 TTL）|
+| 外部全量替换 | 全清 + 重新 warmUp |
+
+---
+
+## 五、批量同步编排
+
+### 5.1 编排器
+
+```java
+@Service
+public class MasterDataSyncOrchestrator {
+
+    @Autowired
+    private List<CanonicalAdapter> adapters;          // 所有适配器 A
+
+    @Autowired
+    private CloudAdapterRegistry adapterRegistry;     // 适配器 B 注册表
+
+    @Autowired
+    private BatchStateRepository batchStateRepo;
+
+    @Autowired
+    private BizKeyMappingCache mappingCache;
+
+    public SyncResult sync(SyncRequest request) {
+        // 1. 幂等检查（基于 batchNo）
+        if (batchStateRepo.existsByBatchNo(request.getBatchNo())) {
+            return SyncResult.duplicate(request.getBatchNo());
+        }
+
+        // 2. 选择适配器 A
+        CanonicalAdapter adapter = adapters.stream()
+            .filter(a -> a.getSourceSystem().equals(request.getSourceSystem()))
+            .findFirst()
+            .orElseThrow();
+
+        // 3. 批量转换（来源 DTO → canonical）
+        List<CanonicalItem> items = request.getSourceData().stream()
+            .map(adapter::adapt)
+            .collect(toList());
+
+        // 4. 预热映射缓存
+        mappingCache.warmUp(request.getSourceSystem(), request.getBizType());
+
+        // 5. 逐项执行（canonical → 平台）
+        SyncResult result = new SyncResult(request.getBatchNo());
+        for (CanonicalItem item : items) {
+            try {
+                CloudAdapter cloudAdapter = adapterRegistry.get(request.getBizType());
+                Object platformPayload = cloudAdapter.adapt(item.getPayload(), mappingCache);
+
+                // 6. 写入平台（Feign 或 同 JVM Service）
+                invokePlatformWrite(request.getBizType(), platformPayload);
+
+                result.incrementSuccess();
+            } catch (SyncException e) {
+                result.addFailure(item.getBizKey(), e.getErrorCode(), e.getMessage());
+                if (e.isPermanent()) {
+                    // 永久错误 → 不重试
+                }
+            }
+        }
+
+        // 7. 保存批次状态
+        batchStateRepo.save(BatchState.from(result));
+
+        // 8. 返回
+        return result;
+    }
+}
+```
+
+### 5.2 阶段状态保存
+
+```java
+@Data
+@Entity
+@Table(name = "T_SYNC_BATCH_STATE")
+public class BatchState {
+    private String batchNo;
+    private String sourceSystem;
+    private String bizType;
+    private BatchStatus status;        // RUNNING / SUCCESS / PARTIAL / RECONCILE_FAILED
+    private Integer totalCount;
+    private Integer successCount;
+    private Integer failureCount;
+    private String failuresJson;       // 失败明细 JSON
+    private LocalDateTime createTime;
+    private LocalDateTime updateTime;
+}
+```
+
+---
+
+## 六、重试与可重放
+
+### 6.1 重试规则
+
+| 错误类型 | 是否重试 | 退避策略 |
+|---------|---------|---------|
+| 临时错误（网络/超时）| ✅ | 指数退避（2s, 4s, 8s, 16s, 32s）|
+| 业务错误（数据校验失败）| ❌ 永久错误 | 直接进入人工队列 |
+| 幂等错误（重复执行）| ❌ | 跳过（基于 batchNo）|
+| 安全错误（认证失败）| ❌ | 报警 + 人工 |
+
+### 6.2 重试实现
+
+```java
+@Retryable(
+    value = {TransientException.class},
+    maxAttempts = 5,
+    backoff = @Backoff(delay = 2000, multiplier = 2, maxDelay = 32000)
+)
+public SyncResult syncWithRetry(SyncRequest request) {
+    return orchestrator.sync(request);
+}
+```
+
+### 6.3 重放
+
+```java
+@Service
+public class BatchReplayService {
+
+    /**
+     * 用同一 batchNo 重放（不影响已成功项）
+     */
+    public SyncResult replay(String batchNo) {
+        BatchState state = batchStateRepo.findByBatchNo(batchNo);
+        if (state == null) {
+            throw new NotFoundException("批次不存在：" + batchNo);
+        }
+
+        // 仅重放失败项
+        List<FailureDetail> failures = parseFailures(state.getFailuresJson());
+        SyncRequest partialRequest = buildPartialRequest(state, failures);
+
+        return orchestrator.sync(partialRequest);
+    }
+}
+```
+
+---
+
+## 七、与安全规则协作
+
+| 安全风险 | 来源 | 防护 |
+|---------|------|------|
+| XXE 攻击 | WebService | `xml-security.md` |
+| 路径穿越 | 文件路径字段 | `security-rules.md §五` |
+| SQL 注入 | 字段拼接 | 必须用 PreparedStatement（`security-rules.md §一`）|
+| 越权访问 | 资源授权同步 | `data-classification/references/hibernate-filter.md` |
+| token 泄露 | 日志 | `security-rules.md §三` 敏感信息脱敏 |
+
+---
+
+## 八、典型场景示例
+
+### 8.1 HR 系统日终同步
+
+```
+22:00 HR 触发批量推送
+      ↓
+22:00 平台接收 batchNo = HR20260908220000
+      ↓
+22:00-22:05 适配器 A 转换 5000 条人员
+      ↓
+22:05 映射缓存预热（一次 Feign 拉所有组织）
+      ↓
+22:05-22:30 适配器 B 逐项写入
+      ↓
+22:30 返回 successCount=4950 / failureCount=50
+      ↓
+22:31 失败明细进入人工队列（业务错误：父组织不存在）
+```
+
+### 8.2 LDAP 同步人员（最小化场景）
+
+```json
+{
+  "sourceSystem": "LDAP",
+  "batchNo": "LDAP20260909080000",
+  "bizType": "user",
+  "operation": "UPSERT",
+  "items": [...]
+}
+```
+
+无需同步 org（LDAP 用户已有 orgCode 字符串，由 HR 系统同步组织）。
+
+---
+
+## 九、常见错误
+
+| 错误 | 后果 | 正确做法 |
+|------|------|---------|
+| 来源 DTO 直接转平台 DTO | N×M 适配器 | canonical 中转 |
+| 不缓存 bizKey 映射 | N+1 Feign | warmUp + TTL |
+| 不用 batchNo | 失败无法重放 | 全局唯一批次号 |
+| 不分阶段错误类型 | 临时错误永久失败 | 分类（临时/业务/安全）|
+| 全量替换不审批 | 误删数据 | FULL_REPLACE 人工审批 |
+
+---
+
+**最后更新**：2026-09-08（v2.5.0 P1-A 合并自 masterdata-sync）
+**来源**：石油/研发 `merit-cloud-masterdata-sync` 22-modules
+**整合位置**：`meritdata-platform-data-access/references/inbound/adapter-pattern.md`