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

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

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

@@ -1,352 +0,0 @@
-# 同步后对账（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`