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

package/skills/meritdata-platform-job/references/scenarios.md

@@ -0,0 +1,317 @@
+# 典型 Job 场景（scenarios）
+
+> 常见 Job 场景的实现模板。
+
+---
+
+## 1. HR 用户同步
+
+### 1.1 全量同步（首次接入）
+
+```java
+@JobHandler("hrUserFullSyncJob")
+@Component
+public class HrUserFullSyncJob extends IJobHandler {
+
+    @Autowired
+    private HrClient hrClient;
+
+    @Autowired
+    private UserSyncService syncService;
+
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+        XxlJobLogger.log("开始全量同步 HR 用户");
+
+        int page = 1;
+        int total = 0;
+        while (true) {
+            Page<HrUser> pageData = hrClient.pageUsers(page, 500);
+            if (pageData.isEmpty()) break;
+
+            for (HrUser user : pageData.getRecords()) {
+                syncService.upsert(user);  // 幂等
+            }
+
+            total += pageData.getRecords().size();
+            XxlJobLogger.log("第 {} 页同步完成，累计 {} 条", page, total);
+            page++;
+        }
+
+        XxlJobLogger.log("全量同步完成，共 {} 条", total);
+        return new ReturnT<>(total + " 条用户已同步");
+    }
+}
+```
+
+### 1.2 增量同步（每天）
+
+```java
+@JobHandler("hrUserIncrementalSyncJob")
+@Component
+public class HrUserIncrementalSyncJob extends IJobHandler {
+
+    @Autowired
+    private SyncTimeService syncTimeService;
+
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+        LocalDateTime lastSyncTime = syncTimeService.getLastSyncTime("HR_USER");
+        LocalDateTime currentTime = LocalDateTime.now();
+
+        XxlJobLogger.log("增量同步 HR 用户，从 {} 到 {}", lastSyncTime, currentTime);
+
+        List<HrUserChange> changes = hrClient.getChanges(lastSyncTime, currentTime);
+
+        int addCount = 0, updateCount = 0, deleteCount = 0;
+        for (HrUserChange change : changes) {
+            switch (change.getAction()) {
+                case "ADD":
+                    syncService.create(change.getUser());
+                    addCount++;
+                    break;
+                case "UPDATE":
+                    syncService.update(change.getUser());  // 幂等
+                    updateCount++;
+                    break;
+                case "DELETE":
+                    syncService.disable(change.getUserId());
+                    deleteCount++;
+                    break;
+            }
+        }
+
+        syncTimeService.updateLastSyncTime("HR_USER", currentTime);
+
+        String result = String.format("新增 %d, 更新 %d, 禁用 %d", addCount, updateCount, deleteCount);
+        XxlJobLogger.log(result);
+        return new ReturnT<>(result);
+    }
+}
+```
+
+---
+
+## 2. 数据清理
+
+### 2.1 临时文件清理（每周）
+
+```java
+@JobHandler("tempFileCleanupJob")
+@Component
+public class TempFileCleanupJob extends IJobHandler {
+
+    @Value("${temp.dir}")
+    private String tempDir;
+
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+        LocalDateTime cutoff = LocalDateTime.now().minusDays(7);
+        int deletedCount = 0;
+
+        try (Stream<Path> stream = Files.walk(Paths.get(tempDir))) {
+            deletedCount = (int) stream
+                .filter(Files::isRegularFile)
+                .filter(p -> isModifiedBefore(p, cutoff))
+                .peek(p -> {
+                    try {
+                        Files.delete(p);
+                    } catch (IOException e) {
+                        log.warn("删除失败：{}", p, e);
+                    }
+                })
+                .count();
+        }
+
+        return new ReturnT<>("清理了 " + deletedCount + " 个临时文件");
+    }
+}
+```
+
+### 2.2 软删除数据清理（每月，谨慎！）
+
+```java
+@JobHandler("softDeletedDataCleanupJob")
+@Component
+public class SoftDeletedDataCleanupJob extends IJobHandler {
+
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+        // 仅清理 6 个月前的软删除数据
+        LocalDateTime cutoff = LocalDateTime.now().minusMonths(6);
+
+        int count = orderRepository.hardDeleteSoftDeletedBefore(cutoff);
+
+        // 记录审计日志（必须！）
+        auditService.record(AuditDTO.builder()
+            .action("HARD_DELETE")
+            .module("PURCHASE_ORDER")
+            .content("清理 " + cutoff + " 之前的软删除订单 " + count + " 条")
+            .build());
+
+        return new ReturnT<>("清理 " + count + " 条历史数据");
+    }
+}
+```
+
+---
+
+## 3. 报表生成
+
+### 3.1 月度统计报表（每月 1 号凌晨）
+
+```java
+@JobHandler("monthlyReportJob")
+@Component
+public class MonthlyReportJob extends IJobHandler {
+
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+        YearMonth lastMonth = YearMonth.now().minusMonths(1);
+
+        // 1. 计算报表数据
+        MonthlyReport report = reportService.calculate(lastMonth);
+
+        // 2. 持久化报表（幂等：同一月份覆盖）
+        monthlyReportRepository.save(report);
+
+        // 3. 推送通知（部门负责人）
+        notificationService.sendToDeptLeaders(report);
+
+        return new ReturnT<>(lastMonth + " 报表已生成");
+    }
+}
+```
+
+---
+
+## 4. 业务状态校验
+
+### 4.1 流程状态一致性校验
+
+```java
+@JobHandler("processStatusConsistencyJob")
+@Component
+public class ProcessStatusConsistencyJob extends IJobHandler {
+
+    @Autowired
+    private RuntimeService runtimeService;
+
+    @Autowired
+    private HistoryService historyService;
+
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+        // 1. 查所有 PENDING 状态 + 流程实例 ID 非空的订单
+        List<Order> pendingOrders = orderRepository.findByStatusAndProcessInstanceIdNotNull("PENDING");
+
+        int inconsistentCount = 0;
+        for (Order order : pendingOrders) {
+            // 2. 查流程实例
+            ProcessInstance pi = runtimeService.createProcessInstanceQuery()
+                .processInstanceId(order.getProcessInstanceId())
+                .singleResult();
+
+            if (pi == null) {
+                // 3. 流程已结束，查历史
+                HistoricProcessInstance historic = historyService.createHistoricProcessInstanceQuery()
+                    .processInstanceId(order.getProcessInstanceId())
+                    .singleResult();
+
+                if (historic != null) {
+                    // 4. 校正业务状态
+                    String correctStatus = historic.getEndActivityId().equals("approved") ? "APPROVED" : "REJECTED";
+                    if (!order.getStatus().equals(correctStatus)) {
+                        orderService.markCorrected(order.getId(), correctStatus, "Job 自动校正");
+                        inconsistentCount++;
+                    }
+                }
+            }
+        }
+
+        return new ReturnT<>("校正 " + inconsistentCount + " 条不一致数据");
+    }
+}
+```
+
+---
+
+## 5. 数据归档
+
+### 5.1 历史订单归档（每年）
+
+```java
+@JobHandler("historicalOrderArchiveJob")
+@Component
+public class HistoricalOrderArchiveJob extends IJobHandler {
+
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+        // 归档 3 年前的已完成订单到历史表
+        LocalDateTime cutoff = LocalDateTime.now().minusYears(3);
+
+        int archivedCount = archiveService.archiveCompletedOrders(cutoff);
+
+        return new ReturnT<>("归档 " + archivedCount + " 条历史订单");
+    }
+}
+```
+
+---
+
+## 6. 集成场景
+
+### 6.1 定时调 Feign 同步数据
+
+```java
+@JobHandler("externalSyncJob")
+@Component
+public class ExternalSyncJob extends IJobHandler {
+
+    @Autowired
+    private ExternalClient externalClient;
+
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+        // 1. 批量拉取（不是循环 getById）
+        List<ExternalData> dataList = externalClient.listAll();
+
+        // 2. 批量同步
+        syncService.batchUpsert(dataList);
+
+        return new ReturnT<>("同步 " + dataList.size() + " 条");
+    }
+}
+```
+
+**关键**：用 `listAll` 批量拉，不用循环 `getById`（详见 `meritdata-platform-integration` 铁律 1.2）。
+
+### 6.2 Job 间依赖（A 完成后触发 B）
+
+通过调度中心配置：
+- A Job 完成后回调 → 触发 B Job
+- 或 B Job 间隔固定时间后启动
+
+**不建议**用代码硬依赖（A 完成后直接调 B 的 service）→ 耦合严重。
+
+---
+
+## 7. ❌ 反模式
+
+| 反模式 | 后果 |
+|--------|------|
+| Job 不幂等 | 重试产生脏数据 |
+| Job 内启动线程 | 调度中心感知不到完成 |
+| Job 循环 Feign | N+1 性能差 |
+| Job 跑超长事务 | 数据库锁等待 |
+| Job 失败 catch + log | 调度中心以为成功，不告警 |
+| Job 处理 TB 级数据 | OOM / 超时 |
+| Job 写日志到本地 | 多实例日志分散，难排查 |
+
+---
+
+## 8. 关联阅读
+
+- [xxl-job-guide.md](xxl-job-guide.md) — XXL-JOB 接入
+- [idempotency.md](idempotency.md) — 幂等设计
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-job/references/scheduling-/346/224/273/347/225/245/INDEX.md

@@ -0,0 +1,60 @@
+# 调度（XXL-JOB / Taier）攻略索引
+
+> **来源**：研发版 `meritdata-platform-config-integration`（v2.3.1 拆分整合）
+> **实际内容位置**：[`meritdata-dev-docs-file-finder/references/dev-docs/攻略-10-定时调度-*.md`](../../../meritdata-dev-docs-file-finder/references/dev-docs/)
+> **策略**：**索引 + 指向**（不复制文件）——所有章节内容均在 dev-docs/ 维护。
+
+---
+
+## 一、攻略-10 总览
+
+| 项目 | 值 |
+|------|-----|
+| **攻略名** | 定时调度 |
+| **章节数** | 7 |
+| **总览入口** | [攻略-10-定时调度-00_总览.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-10-定时调度-00_总览.md) |
+| **典型场景** | 二开项目用 XXL-JOB 写定时任务；用 Taier（DolphinScheduler）做调度编排 |
+
+---
+
+## 二、章节清单
+
+| 章节 | 标题 | 路径 |
+|:-:|------|------|
+| 00 | 总览 | [攻略-10-定时调度-00_总览.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-10-定时调度-00_总览.md) |
+| 01 | 使用背景 | [攻略-10-定时调度-章节01_使用背景.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-10-定时调度-章节01_使用背景.md) |
+| 02 | 更新记录 | [攻略-10-定时调度-章节02_更新记录.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-10-定时调度-章节02_更新记录.md) |
+| 03 | 调度相关应用包 | [攻略-10-定时调度-章节03_调度相关应用包.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-10-定时调度-章节03_调度相关应用包.md) |
+| 04 | 配置项相关 | [攻略-10-定时调度-章节04_配置项相关.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-10-定时调度-章节04_配置项相关.md) |
+| 05 | 调度功能使用 | [攻略-10-定时调度-章节05_调度功能使用.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-10-定时调度-章节05_调度功能使用.md) |
+| 06 | 调度任务 API 接口 | [攻略-10-定时调度-章节06_调度任务_API_接口.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-10-定时调度-章节06_调度任务_API_接口.md) |
+| 07 | 对外调度任务 API 接口 | [攻略-10-定时调度-章节07_对外调度任务_API_接口.md](../../../meritdata-dev-docs-file-finder/references/dev-docs/攻略-10-定时调度-章节07_对外调度任务_API_接口.md) |
+
+---
+
+## 三、按场景快速匹配
+
+| 我想做什么 | 看哪个章节 |
+|-----------|----------|
+| 选 XXL-JOB 还是 Taier？| 章节01 使用背景 |
+| 添加定时任务（XXL-JOB 注解 `@XxlJob`）| 章节05 调度功能使用 |
+| 调度 API（启动/停止/查询）| 章节06 调度任务 API 接口 |
+| 对外暴露调度（其他服务调我的任务）| 章节07 对外调度任务 API 接口 |
+| 调度相关 Nacos 配置 | 章节04 配置项相关 |
+| 调度应用包结构（哪些 jar）| 章节03 调度相关应用包 |
+| 调度功能版本变更 | 章节02 更新记录 |
+
+---
+
+## 四、相关平台 API
+
+| 能力 | 类 / 接口 | 来源 |
+|------|----------|------|
+| 11 个 XXL-JOB API | `IJobApi`（add / update / remove / triggerJob / startJob / stopJob / pageList ...）| dev-docs/14_四业务组件-4.3定时任务IJobApi.md |
+| 12 个 Taier（DolphinScheduler）API | `ICloudClient`（submit / status / log / getTaskList / cancelJob / frozenTask ...）| dev-docs/13_四业务组件-4.2调度组件ICloudClient.md |
+| 调度编排 HTTP 接口 | `3.20 调度编排` | dev-docs/48_3.20调度编排.md |
+
+---
+
+**最后更新**：2026-09-08（v2.3.1 P1 补齐）
+**来源**：研发版 `meritdata-platform-config-integration` 攻略-10

package/skills/meritdata-platform-job/references/xxl-job-guide.md

@@ -0,0 +1,286 @@
+# XXL-JOB 接入指南（xxl-job-guide）
+
+> 平台使用 XXL-JOB 作为分布式任务调度框架。本指南说明 JobHandler 写法、调度配置、失败处理。
+
+---
+
+## 1. JobHandler 写法
+
+### 1.1 基本结构
+
+```java
+@JobHandler("purchaseOrderSyncJob")
+@Component
+public class PurchaseOrderSyncJob extends IJobHandler {
+
+    @Autowired
+    private OrderSyncService syncService;
+
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+        // 1. 参数解析
+        SyncParam syncParam = JSON.parseObject(param, SyncParam.class);
+
+        // 2. 业务逻辑
+        int count = syncService.sync(syncParam);
+
+        // 3. 返回结果
+        return new ReturnT<>(count + " 条订单已同步");
+    }
+}
+```
+
+### 1.2 @JobHandler 注解
+
+| 属性 | 必填 | 说明 |
+|------|------|------|
+| `value` | 是 | JobHandler 名称（调度中心用）|
+
+---
+
+## 2. 调度中心配置
+
+### 2.1 application.yml
+
+```yaml
+xxl:
+  job:
+    admin:
+      addresses: http://localhost:8080/xxl-job-admin
+    executor:
+      appname: your-2nd-service
+      address:
+      ip:
+      port: 9999
+      logpath: /data/applogs/xxl-job/jobhandler
+      logretentiondays: 30
+    accessToken: default_token
+```
+
+### 2.2 启动类加注解
+
+```java
+@SpringBootApplication
+@EnableScheduling
+public class YourApplication {
+    public static void main(String[] args) {
+        SpringApplication.run(YourApplication.class, args);
+    }
+}
+```
+
+---
+
+## 3. 调度中心新增任务
+
+| 字段 | 填写 |
+|------|------|
+| 执行器 | `your-2nd-service` |
+| JobHandler | `purchaseOrderSyncJob` |
+| 调度类型 | CRON |
+| Cron | `0 0 2 * * ?`（每天凌晨 2 点）|
+| 路由策略 | 第一个 / 轮询 / 故障转移 |
+| 阻塞处理 | 单机串行 |
+| 任务超时时间 | 60 分钟（按业务调整）|
+| 失败重试次数 | 3 |
+
+### Cron 表达式示例
+
+| 表达式 | 含义 |
+|--------|------|
+| `0 0 2 * * ?` | 每天凌晨 2 点 |
+| `0 0 */2 * * ?` | 每 2 小时 |
+| `0 0 0 ? * MON` | 每周一 0 点 |
+| `0 30 9 * * ?` | 每天 9:30 |
+| `0 0/30 9-17 * * ?` | 9-17 点每 30 分钟 |
+
+---
+
+## 4. 参数传递
+
+### 4.1 简单参数
+
+```java
+@JobHandler("simpleJob")
+@Component
+public class SimpleJob extends IJobHandler {
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+        // param = "userId=10001"
+        // 解析
+        Map<String, String> params = Splitter.on("&").withKeyValueSeparator("=").split(param);
+        String userId = params.get("userId");
+        // ...
+    }
+}
+```
+
+### 4.2 JSON 参数（推荐）
+
+```java
+@JobHandler("complexJob")
+@Component
+public class ComplexJob extends IJobHandler {
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+        SyncParam p = JSON.parseObject(param, SyncParam.class);
+        // p.startTime, p.endTime, p.batchSize
+    }
+}
+
+@Data
+public class SyncParam {
+    private LocalDateTime startTime;
+    private LocalDateTime endTime;
+    private Integer batchSize;
+}
+```
+
+调度中心参数：`{"startTime":"2026-09-01T00:00:00","endTime":"2026-09-07T00:00:00","batchSize":500}`
+
+---
+
+## 5. 日志查看
+
+### 5.1 输出日志
+
+```java
+@Override
+public ReturnT<String> execute(String param) throws Exception {
+    XxlJobLogger.log("开始同步订单");
+    int count = syncService.sync();
+    XxlJobLogger.log("已同步 {} 条", count);
+    return SUCCESS;
+}
+```
+
+### 5.2 查看位置
+
+调度中心 → 任务日志 → 选择执行记录 → 看完整日志
+
+---
+
+## 6. 失败处理
+
+### 6.1 失败告警
+
+调度中心 → 报警配置 → 配置邮件 / 钉钉 / 飞书 webhook
+
+### 6.2 ❌ 反例：catch + log + continue
+
+```java
+// ❌ 错：吞掉异常，调度中心看不到失败
+@Override
+public ReturnT<String> execute(String param) throws Exception {
+    try {
+        syncService.sync();
+    } catch (Exception e) {
+        log.error("同步失败", e);  // 只记录到本地日志
+        // 没有返回 FAIL → 调度中心认为成功
+    }
+    return SUCCESS;
+}
+
+// ✅ 正确：失败返回 FAIL，触发告警
+@Override
+public ReturnT<String> execute(String param) throws Exception {
+    try {
+        syncService.sync();
+    } catch (Exception e) {
+        log.error("同步失败", e);
+        return FAIL;  // 调度中心记录失败 + 触发重试 + 告警
+    }
+    return SUCCESS;
+}
+```
+
+### 6.3 重试策略
+
+调度中心配置"失败重试次数 = 3"时：
+- 失败后立即重试 1 次
+- 间隔 10s 重试 2 次
+- 间隔 30s 重试 3 次
+
+**关键**：重试的业务必须**幂等**（详见 [idempotency.md](idempotency.md)）。
+
+---
+
+## 7. 分布式锁
+
+### 7.1 场景
+
+多个实例部署时，同一 Job 同一时间只能一个实例执行。
+
+### 7.2 XXL-JOB 自带机制
+
+调度中心 → 任务配置 → 路由策略选 `故障转移` 或 `分片广播`
+
+### 7.3 业务级分布式锁
+
+```java
+@JobHandler("criticalJob")
+@Component
+public class CriticalJob extends IJobHandler {
+
+    @Autowired
+    private RedissonClient redissonClient;
+
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+        RLock lock = redissonClient.getLock("job:criticalJob:lock");
+        if (!lock.tryLock(0, 30, TimeUnit.MINUTES)) {
+            return new ReturnT<>(500, "其他实例正在执行");
+        }
+        try {
+            // 业务逻辑
+        } finally {
+            lock.unlock();
+        }
+        return SUCCESS;
+    }
+}
+```
+
+---
+
+## 8. ❌ 反模式
+
+### 8.1 ❌ 阻塞主线程
+
+```java
+// ❌ 错：循环内阻塞 IO
+for (Order order : orders) {
+    httpClient.send(order);  // 单条同步
+}
+```
+
+✅ 用批量接口 + 异步处理。
+
+### 8.2 ❌ Job 里启动线程
+
+```java
+// ❌ 错：Job 里启动线程 → 调度中心无法感知完成
+new Thread(() -> { ... }).start();
+```
+
+Job 应该同步执行到完成（阻塞处理策略）。
+
+### 8.3 ❌ Job 里做长事务
+
+```java
+// ❌ 错：单 Job 跑 5 分钟单事务
+@Transactional
+public ReturnT<String> execute(String param) {
+    // 10 万条数据一次事务
+}
+```
+
+✅ 分批处理，每批独立事务。
+
+---
+
+## 9. 关联阅读
+
+- [idempotency.md](idempotency.md) — 幂等设计
+- [scenarios.md](scenarios.md) — 典型场景
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-lookup-api/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: meritdata-platform-lookup-api
+description: |
+  字典 API。ILookupService 查字典 / 字典翻译 / 字典缓存 / 树形字典 / 多语言字典。
+  触发场景：业务字段是字典类型（订单状态、用户类型、证件类型）需要查字典或翻译；下拉框、单选、多选组件需要字典项。
+  何时不用：枚举（业务代码内常量）→ 用 Java enum；业务配置 → 用 Nacos。
+metadata:
+  version: "1.0.0"
+  author: petroleum+rd
+  source: petroleum+rd
+  date_added: "2026-09-07"
+  last_modified: "2026-09-07"
+  risk: low
+  layer: L3
+  sub-layer: L3-C
+  stack: java
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# 字典 API（lookup-api）
+
+## 触发
+- 业务字段是字典类型（订单状态、用户类型、证件类型）
+- 需要把字典 code 翻译成中文名（"PAID" → "已支付"）
+- 下拉框、单选组件需要字典项
+- 树形字典（行政区划、组织树）
+
+## 不触发
+- 枚举类（业务代码常量）→ 用 Java enum
+- 全局配置（开关、阈值）→ 用 Nacos
+- 业务实体表（用户、订单）→ 用 org-user-api 或业务 Feign
+
+## 前置约束
+- 字典由平台统一管理（lookup 表），二开不重复建字典表
+- 字典查询走缓存（缓存 key 见 references/cache-strategy.md）
+- 多语言字典由 i18n 字典项支持
+
+## 路由
+- 字典查询接口 + 翻译 → [references/guide.md](references/guide.md)
+- 树形字典 / 多语言 → [references/tree-and-i18n.md](references/tree-and-i18n.md)
+- 字典缓存策略 → [references/cache-strategy.md](references/cache-strategy.md)
+- [SKILL.md](../SKILL.md)