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

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

@@ -1,431 +0,0 @@
-# 适配层模式（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`