npm - @alanwang-merit/meritdata-platform-skill-package - Versions diffs - 1.0.10 → 1.0.12 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (631) hide show

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

@@ -1,317 +0,0 @@
-# 典型 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 DELETED Viewed

@@ -1,60 +0,0 @@
-# 调度（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 DELETED Viewed

@@ -1,286 +0,0 @@
-# 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 DELETED Viewed

@@ -1,42 +0,0 @@
----
-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)