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

package/skills/meritdata-platform-data-access/references/inbound/canonical-payload.md

@@ -0,0 +1,313 @@
+# Canonical Payload 设计（canonical-payload）
+
+> **目的**：定义外部主数据同步的统一载荷格式（业务键 / 水位 / 批次号 / 父子依赖 / 删除语义 / 对账口径）。
+> **场景**：HR/ERP/LDAP 推送组织/人员/角色到平台。
+> **来源**：研发/石油 `merit-cloud-masterdata-sync` 22-modules canonical-payload.md。
+
+---
+
+## 一、为什么需要 Canonical Payload
+
+### 1.1 现实问题
+
+外部系统与平台的字段命名 / 数据类型 / 嵌套结构往往不同：
+
+| 维度 | HR 系统 | MeritData Cloud |
+|------|---------|-----------------|
+| 组织编码 | `ORG_CODE` (VARCHAR) | `orgCode` (String) |
+| 创建时间 | `CREATE_DATE` (Date) | `createTime` (LocalDateTime) |
+| 嵌套关系 | `DEPT_PATH` (路径字符串) | `parentOrgId` (Long) |
+| 删除语义 | `STATUS = 'D'` (软删除) | `deleted = true` (逻辑删除) |
+
+**直接转换 = 写一次改一次**（每个外部系统一套适配）。
+
+### 1.2 Canonical 解决
+
+```
+外部系统 A → canonical payload → 平台 payload
+外部系统 B ↗                     ↘ 平台 payload 2
+外部系统 C ↗                     ↘ 平台 payload 3
+```
+
+**canonical 是中立的、与具体外部系统解耦的载荷规范**——所有外部系统先转 canonical，再由平台侧转各自内部结构。
+
+---
+
+## 二、Canonical Payload 结构
+
+### 2.1 顶层结构
+
+```json
+{
+  "sourceSystem": "HR_SYSTEM",       // 来源系统标识（注册表维护）
+  "batchNo": "HR20260908150000",     // 批次号（外部系统生成，唯一）
+  "operation": "UPSERT",             // UPSERT / DELETE / FULL_REPLACE
+  "bizType": "user",                 // org / user / role / position / resource / authorization
+  "waterLevel": "2026-09-08T15:00:00Z", // 水位（外部数据时间戳）
+  "items": [ ... ]                   // 业务项列表
+}
+```
+
+### 2.2 业务项结构
+
+```json
+{
+  "bizKey": "USER-2001",             // 业务键（跨系统稳定主键）
+  "parentBizKey": "ORG-001",         // 父业务键（依赖关系）
+  "operation": "UPSERT",             // 单项操作（可覆盖顶层）
+  "payload": { ... },                // 业务数据（按 bizType 不同 schema）
+  "extFields": { ... }               // 扩展字段（平台透传）
+}
+```
+
+### 2.3 5 个 bizType 的 payload schema
+
+#### 2.3.1 组织（org）
+
+```json
+{
+  "orgCode": "ORG-001",
+  "orgName": "总部",
+  "parentCode": null,                // 父组织 bizKey
+  "sortNo": 1,
+  "orgType": "DEPT",                 // COMPANY / DEPT / TEAM
+  "enabled": true
+}
+```
+
+#### 2.3.2 人员（user）
+
+```json
+{
+  "userCode": "USER-2001",           // 业务键
+  "userName": "张三",
+  "email": "zhangsan@example.com",
+  "phone": "13812341234",
+  "orgCode": "ORG-001",              // 所属组织
+  "positionCode": "POS-DEV",         // 职务
+  "enabled": true,
+  "hireDate": "2024-03-15"
+}
+```
+
+#### 2.3.3 角色（role）
+
+```json
+{
+  "roleCode": "ROLE_ADMIN",
+  "roleName": "管理员",
+  "roleType": "GLOBAL",              // GLOBAL / ORG_SCOPED
+  "enabled": true
+}
+```
+
+#### 2.3.4 职务（position）
+
+```json
+{
+  "positionCode": "POS-DEV",
+  "positionName": "开发工程师",
+  "level": "P5",
+  "enabled": true
+}
+```
+
+#### 2.3.5 资源（resource）
+
+```json
+{
+  "resourceCode": "ORDER_CREATE",
+  "resourceName": "订单创建",
+  "resourceType": "BUTTON",          // MENU / BUTTON / API
+  "appCode": "PURCHASE",
+  "enabled": true
+}
+```
+
+#### 2.3.6 授权（authorization）
+
+```json
+{
+  "subjectType": "USER",             // USER / ROLE / ORG
+  "subjectCode": "USER-2001",        // 主体 bizKey
+  "objectType": "RESOURCE",
+  "objectCode": "ORDER_CREATE",      // 客体 bizKey
+  "effect": "ALLOW",                 // ALLOW / DENY
+  "validFrom": "2026-01-01",
+  "validTo": "2026-12-31"
+}
+```
+
+---
+
+## 三、关键字段语义
+
+### 3.1 业务键（bizKey）
+
+**bizKey 是跨系统稳定的唯一标识**，如 `ORG-001` / `USER-2001`。
+
+| 规则 | 示例 |
+|------|------|
+| ✅ 用外部系统业务编码 | `ORG-001` |
+| ✅ 用组织代码 + 流水号 | `PUR-2024-001` |
+| ❌ 用数据库主键 | `12345`（系统重建会变）|
+| ❌ 用名称 | `总部`（可能重名）|
+
+### 3.2 水位（waterLevel）
+
+**外部数据的时间戳**，用于增量同步：
+
+```json
+"waterLevel": "2026-09-08T15:00:00Z"
+```
+
+**作用**：
+- 平台记录 `lastSyncWaterLevel`（每个 sourceSystem + bizType 一条）
+- 下次同步只拉 waterLevel > lastSyncWaterLevel 的数据
+- 失败回滚后可重放（基于批次号，不依赖水位）
+
+### 3.3 批次号（batchNo）
+
+**外部系统生成的同步批次唯一标识**：
+
+```
+格式：{系统简称}{YYYYMMDDHHMMSS}{序号}
+示例：HR2026090815000001
+```
+
+**作用**：
+- 幂等键：相同 batchNo 不重复执行
+- 可重放：失败后用同一 batchNo 重试
+- 审计追溯：通过 batchNo 查日志
+
+### 3.4 删除语义
+
+| 操作 | 含义 | 平台行为 |
+|------|------|---------|
+| `UPSERT` | 不存在则插入，存在则更新 | 软删除恢复 + 更新 |
+| `DELETE` | 逻辑删除（业务键匹配）| 置 `deleted = true` |
+| `FULL_REPLACE` | 全量替换该 bizType 下所有数据 | **需人工审批**，禁用级联删除 |
+
+---
+
+## 四、同步顺序
+
+**默认顺序**（强依赖关系）：
+
+```
+组织 → 角色/职务 → 人员 → 资源 → 授权
+```
+
+**为什么这样排**：
+- 人员依赖组织（无组织 → 人员无归属）
+- 人员依赖职务（无职务 → 人员无级别）
+- 授权依赖资源（无资源 → 授权无意义）
+- 授权依赖主体（人员/角色必须先存在）
+
+**违反顺序的后果**：进入可重试失败，不创建无归属脏数据。
+
+---
+
+## 五、对账口径
+
+### 5.1 同步后对账 4 维度
+
+| 维度 | 检查方法 | 阈值 |
+|------|---------|------|
+| 数量 | 平台数量 = 外部推送数量 - 失败数 | 差异 > 0.1% 报警 |
+| 业务键 | 平台 bizKey 集合 = 外部推送 bizKey 集合 | 差异 > 0 报警 |
+| 父子关系 | 平台 parentBizKey 都存在 | 缺失父级报警 |
+| 授权集合 | 主体/客体都存在 | 缺失主体/客体报警 |
+
+### 5.2 对账失败处置
+
+```
+Step 1：标记 batchNo 状态 = RECONCILE_FAILED
+Step 2：生成对账报告（含具体差异项）
+Step 3：进入人工处置队列
+Step 4：人工决定
+        ├─ 全量回滚 → DELETE batchNo 所有项
+        ├─ 部分重放 → 选 failures 重新执行
+        └─ 接受差异 → 标记 batchNo = ACCEPTED_WITH_DIFF
+```
+
+---
+
+## 六、典型场景示例
+
+### 6.1 HR 系统推送组织 + 人员
+
+```json
+{
+  "sourceSystem": "HR_SYSTEM",
+  "batchNo": "HR20260908150000",
+  "operation": "UPSERT",
+  "bizType": "user",
+  "waterLevel": "2026-09-08T15:00:00Z",
+  "items": [
+    {
+      "bizKey": "USER-2001",
+      "parentBizKey": "ORG-001",
+      "operation": "UPSERT",
+      "payload": {
+        "userCode": "USER-2001",
+        "userName": "张三",
+        "email": "zhangsan@example.com",
+        "orgCode": "ORG-001",
+        "positionCode": "POS-DEV",
+        "enabled": true
+      }
+    }
+  ]
+}
+```
+
+### 6.2 IAM 推送角色 + 授权
+
+```json
+{
+  "sourceSystem": "IAM_SYSTEM",
+  "batchNo": "IAM20260908200000",
+  "operation": "UPSERT",
+  "bizType": "authorization",
+  "items": [
+    {
+      "bizKey": "AUTH-USER2001-RES001",
+      "subjectType": "USER",
+      "subjectCode": "USER-2001",
+      "objectType": "RESOURCE",
+      "objectCode": "ORDER_CREATE",
+      "effect": "ALLOW"
+    }
+  ]
+}
+```
+
+---
+
+## 七、与 outbound 的协作
+
+| 方向 | skill | 用途 |
+|------|-------|------|
+| inbound | 本文件 | 接收外部数据 |
+| outbound | `references/outbound/feign-guide.md` | 二开主动查询 |
+
+**典型场景**：HR 推送 user → 平台入库 → 二开用 Feign `userClient.getUser(id)` 查询。
+
+---
+
+## 八、常见错误
+
+| 错误 | 后果 | 正确做法 |
+|------|------|---------|
+| 用数据库主键做 bizKey | 系统迁移后失效 | 用业务编码 |
+| 同步顺序错误（先人后组织）| 人员无归属脏数据 | 组织 → 人员 |
+| 不带 waterLevel | 无法增量同步 | 必填 |
+| 不用 batchNo | 失败无法重放 | 必填 + 全局唯一 |
+| UPSERT 当 DELETE 用 | 数据残留 | 操作语义清晰 |
+
+---
+
+**最后更新**：2026-09-08（v2.5.0 P1-A 合并自 masterdata-sync）
+**来源**：石油/研发 `merit-cloud-masterdata-sync` canonical-payload.md
+**整合位置**：`meritdata-platform-data-access/references/inbound/canonical-payload.md`

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

@@ -0,0 +1,352 @@
+# 同步后对账（reconciliation）
+
+> **目的**：定义同步后如何对账（数量 / 业务键 / 父子关系 / 授权集合），差异处置与人工审批流程。
+> **场景**：HR/ERP/LDAP 推送完成后，验证平台数据完整性。
+> **来源**：研发/石油 `merit-cloud-masterdata-sync` acceptance.md。
+
+---
+
+## 一、为什么必须对账
+
+### 1.1 仅 HTTP 200 不算成功
+
+| 同步结果 | HTTP 状态 | 实际是否成功 |
+|---------|---------|------------|
+| 5000 条全部成功 | 200 | ✅ |
+| 部分成功 + 部分失败 | 200 | ⚠️ 需对账 |
+| 全部失败 | 200 | ❌ 看似成功实则全失败 |
+| 超时无响应 | 5xx | ❌ |
+
+**仅看 HTTP 状态码 = 盲同步**。必须对账才能确认业务完整性。
+
+### 1.2 对账的 4 个核心维度
+
+1. **数量对账**：平台入库数量 = 推送成功数量
+2. **业务键对账**：平台 bizKey 集合 = 推送 bizKey 集合
+3. **父子关系对账**：所有 parentBizKey 都存在
+4. **授权集合对账**：主体/客体都存在
+
+---
+
+## 二、对账流程
+
+### 2.1 同步完成 → 自动对账
+
+```
+Step 1：同步返回 successCount / failureCount
+Step 2：计算理论入库数 = successCount
+Step 3：从平台查实际入库数（按 batchNo）
+Step 4：比较理论 vs 实际 → 触发对账报告
+Step 5：4 维度对账
+Step 6：根据差异类型触发处置
+```
+
+### 2.2 4 维度对账实现
+
+```java
+@Service
+public class ReconciliationService {
+
+    @Autowired
+    private CloudUserRepository userRepo;
+
+    @Autowired
+    private SyncBatchRepository batchRepo;
+
+    public ReconciliationReport reconcile(String batchNo) {
+        BatchState batch = batchRepo.findByBatchNo(batchNo);
+        ReconciliationReport report = new ReconciliationReport(batchNo);
+
+        // 维度 1：数量对账
+        Long actualCount = userRepo.countByBatchNo(batchNo);
+        Long expectedCount = batch.getSuccessCount().longValue();
+        report.setCountDiff(actualCount - expectedCount);
+
+        // 维度 2：业务键对账
+        List<String> platformBizKeys = userRepo.listBizKeysByBatchNo(batchNo);
+        List<String> expectedBizKeys = batch.getSuccessBizKeys();
+        Set<String> missingInPlatform = diff(expectedBizKeys, platformBizKeys);
+        Set<String> extraInPlatform = diff(platformBizKeys, expectedBizKeys);
+        report.setMissingBizKeys(missingInPlatform);
+        report.setExtraBizKeys(extraInPlatform);
+
+        // 维度 3：父子关系对账
+        List<String> orphans = userRepo.findOrphansByBatchNo(batchNo);
+        report.setOrphans(orphans);
+
+        // 维度 4：授权集合对账（仅 authorization bizType）
+        if ("authorization".equals(batch.getBizType())) {
+            List<String> invalidAuths = authRepo.findInvalidByBatchNo(batchNo);
+            report.setInvalidAuthorizations(invalidAuths);
+        }
+
+        // 计算总体状态
+        report.setStatus(calculateStatus(report));
+        return report;
+    }
+}
+```
+
+---
+
+## 三、对账状态
+
+### 3.1 5 档状态
+
+| 状态 | 含义 | 处置 |
+|------|------|------|
+| `PASS` | 4 维度全部一致 | 标记 batchNo = ACCEPTED |
+| `PASS_WITH_DIFF` | 数量一致但有 extra/orphan | 人工 review |
+| `FAIL_RETRYABLE` | 部分失败可重放 | 自动重试或人工触发 |
+| `FAIL_REQUIRES_ROLLBACK` | 严重数据不一致 | **人工审批**回滚 |
+| `FAIL_PERMANENT` | 永久错误（业务键冲突）| 人工处置队列 |
+
+### 3.2 阈值触发
+
+| 维度 | 阈值 | 触发状态 |
+|------|------|---------|
+| 数量差异 | > 0.1% | FAIL_REQUIRES_ROLLBACK |
+| 业务键缺失 | > 0 | FAIL_REQUIRES_ROLLBACK |
+| 孤儿人员 | > 0 | FAIL_REQUIRES_ROLLBACK |
+| 无效授权 | > 0 | FAIL_REQUIRES_ROLLBACK |
+| 数量一致 + extra | 任意 | PASS_WITH_DIFF |
+
+---
+
+## 四、处置流程
+
+### 4.1 对账失败 → 人工处置队列
+
+```
+对账报告生成
+  ↓
+进入人工处置队列（含报告链接 + batchNo）
+  ↓
+人工决策（4 选 1）
+  ├─ 全量回滚（DELETE batchNo 所有项）
+  ├─ 部分重放（选 failures 重新执行）
+  ├─ 接受差异（标记 ACCEPTED_WITH_DIFF）
+  └─ 调查外部系统（联系 HR / ERP 运维）
+```
+
+### 4.2 全量回滚（最危险，必须审批）
+
+```java
+@Service
+public class BatchRollbackService {
+
+    @Transactional
+    public RollbackResult rollback(String batchNo, String approver, String reason) {
+        // 1. 强制审批检查
+        ApprovalRecord approval = approvalService.checkApproved(batchNo, approver);
+        if (!approval.isApproved()) {
+            throw new RollbackDeniedException("未审批，禁止回滚");
+        }
+
+        // 2. 查询批次下所有项
+        List<CloudUser> users = userRepo.findByBatchNo(batchNo);
+
+        // 3. 软删除
+        for (CloudUser user : users) {
+            user.setDeleted(true);
+            user.setDeleteReason("BATCH_ROLLBACK: " + batchNo);
+        }
+        userRepo.saveAll(users);
+
+        // 4. 更新批次状态
+        batchRepo.updateStatus(batchNo, BatchStatus.ROLLED_BACK);
+
+        // 5. 审计
+        auditLog.logRollback(batchNo, approver, reason, users.size());
+
+        return new RollbackResult(batchNo, users.size());
+    }
+}
+```
+
+### 4.3 全量替换必须审批
+
+| 操作 | 必须审批 |
+|------|---------|
+| `FULL_REPLACE` 操作 | ✅ 必须人工审批才能执行 |
+| DELETE 单项 | ❌ 不需要（业务删除）|
+| DELETE 超过阈值（> 10%）| ✅ 必须人工审批 |
+
+---
+
+## 五、对账报告
+
+### 5.1 报告结构
+
+```json
+{
+  "batchNo": "HR20260908220000",
+  "sourceSystem": "HR_SYSTEM",
+  "bizType": "user",
+  "syncTime": "2026-09-08T22:30:00Z",
+  "expectedCount": 5000,
+  "actualCount": 4950,
+  "status": "FAIL_REQUIRES_ROLLBACK",
+  "dimensions": {
+    "count": {
+      "expected": 5000,
+      "actual": 4950,
+      "diff": -50,
+      "threshold": "0.1%",
+      "pass": false
+    },
+    "bizKeys": {
+      "missing": ["USER-2001", "USER-3050"],
+      "extra": [],
+      "pass": false
+    },
+    "parentChild": {
+      "orphans": [],
+      "missingParents": ["ORG-999"],
+      "pass": false
+    },
+    "authorizations": null
+  },
+  "failures": [
+    {
+      "bizKey": "USER-3050",
+      "phase": "ADAPT",
+      "errorCode": "ERR_PARENT_ORG_NOT_FOUND",
+      "message": "父组织 ORG-999 不存在"
+    }
+  ],
+  "recommendation": "MANUAL_REVIEW"
+}
+```
+
+### 5.2 报告存储
+
+| 字段 | 存储位置 |
+|------|---------|
+| 报告内容 | `T_SYNC_RECONCILIATION_REPORT` 表 |
+| 失败明细 JSON | `T_SYNC_BATCH_STATE.failures_json` |
+| 处置决策 | `T_SYNC_ROLLBACK_APPROVAL` 表 |
+
+---
+
+## 六、对账调度
+
+### 6.1 触发时机
+
+| 触发 | 场景 |
+|------|------|
+| 同步完成后立即 | 实时对账 |
+| 每小时定时 | 增量对账（比对水位变化）|
+| 每日凌晨全量 | 兜底对账（避免实时漏报）|
+
+### 6.2 Job 配置（XXL-JOB）
+
+```java
+@JobHandler("syncDailyReconciliation")
+@Component
+public class DailyReconciliationJob extends IJobHandler {
+
+    @Autowired
+    private ReconciliationService reconciliation;
+
+    @Override
+    public ReturnT<String> execute(String param) {
+        // 查询昨天所有 batchNo
+        List<String> batchNos = batchRepo.findYesterdayBatches();
+
+        for (String batchNo : batchNos) {
+            ReconciliationReport report = reconciliation.reconcile(batchNo);
+
+            // 失败报警
+            if (report.getStatus() == FAIL_REQUIRES_ROLLBACK) {
+                alarmService.alert("同步对账失败：" + batchNo, report);
+            }
+        }
+
+        return SUCCESS;
+    }
+}
+```
+
+---
+
+## 七、典型场景
+
+### 7.1 全部成功
+
+```
+推送 5000 条 → success=5000 → 实际入库 5000 → 对账 PASS
+状态：ACCEPTED
+```
+
+### 7.2 临时错误 + 自动重试
+
+```
+推送 5000 → 第一轮失败 50（网络超时）→ 自动重试 → 第二轮成功 50
+最终 success=5000 → 对账 PASS
+```
+
+### 7.3 业务错误 + 部分失败
+
+```
+推送 5000 → 永久失败 50（父组织不存在）
+→ success=4950 / failure=50
+→ 对账 FAIL_RETRYABLE
+→ 报告进入人工队列
+→ 人工选择"重放 50 项失败"（先同步组织 ORG-999）
+→ 重放后 success=5000 → 对账 PASS
+```
+
+### 7.4 严重不一致
+
+```
+推送 5000 → 平台实际入库 4800（200 条孤儿被过滤）
+→ 对账 FAIL_REQUIRES_ROLLBACK
+→ 人工 review 后决定"回滚 4800"
+→ 强制审批 → DELETE 所有项
+→ 外部系统修复后重新同步
+```
+
+---
+
+## 八、与其他 skill 的协作
+
+| 场景 | 协作 skill |
+|------|----------|
+| 定时对账 | `meritdata-platform-job/references/scheduling-攻略/INDEX.md` |
+| 对账报警（消息中心）| `meritdata-platform-message-center/references/message-攻略/INDEX.md` |
+| 审计日志 | `meritdata-platform-operation-log` |
+| 强制审批工作流 | `meritdata-platform-bpm` |
+
+---
+
+## 九、验收标准（MS-01 ~ MS-08）
+
+| ID | 标准 | 自动化 |
+|----|------|:------:|
+| MS-01 | HTTP 200 但部分失败时，对账报告能识别 | ✅ |
+| MS-02 | 数量对账差异 > 0.1% 触发 FAIL_REQUIRES_ROLLBACK | ✅ |
+| MS-03 | 业务键缺失能精确到 bizKey 级别 | ✅ |
+| MS-04 | 父子关系孤儿能被识别 | ✅ |
+| MS-05 | 无效授权（主体/客体不存在）能被识别 | ✅ |
+| MS-06 | 全量回滚强制审批 | ✅ |
+| MS-07 | 部分重放只重放失败项 | ✅ |
+| MS-08 | 对账报告含 4 维度 + 处置建议 | ✅ |
+
+---
+
+## 十、常见错误
+
+| 错误 | 后果 | 正确做法 |
+|------|------|---------|
+| 不对账只看 HTTP 200 | 数据漂移不可见 | 强制对账 |
+| 不分维度对账 | 漏掉孤儿/无效授权 | 4 维度全检 |
+| 阈值过宽（> 5%）| 错过早期问题 | 0.1% 阈值 |
+| 不区分临时/永久错误 | 临时错误永久失败 | 错误分类 + 退避 |
+| 回滚不审批 | 误删数据 | 强制审批流 |
+
+---
+
+**最后更新**：2026-09-08（v2.5.0 P1-A 合并自 masterdata-sync）
+**来源**：石油/研发 `merit-cloud-masterdata-sync` acceptance.md
+**整合位置**：`meritdata-platform-data-access/references/inbound/reconciliation.md`