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

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

@@ -0,0 +1,248 @@
+# 导入导出典型场景（scenarios）
+
+> 常见场景的实现参考。
+
+---
+
+## 1. 人员批量导入
+
+### 1.1 模板字段
+
+| 字段 | 必填 | 校验 |
+|------|------|------|
+| 工号 | 是 | 唯一 + 长度 1-32 |
+| 姓名 | 是 | 长度 1-64 |
+| 手机号 | 是 | 正则校验 |
+| 邮箱 | 否 | 邮箱格式 |
+| 部门编码 | 是 | 必须在平台存在 |
+| 岗位 | 否 | - |
+| 入职日期 | 是 | 日期格式 |
+
+### 1.2 实现
+
+```java
+@Data
+public class UserImportVO {
+    @ExcelProperty("工号")
+    @NotBlank
+    private String code;
+
+    @ExcelProperty("姓名")
+    @NotBlank
+    private String name;
+
+    @ExcelProperty("手机号")
+    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式错误")
+    private String phone;
+
+    @ExcelProperty("部门编码")
+    @NotBlank
+    private String deptCode;
+
+    @ExcelProperty("入职日期")
+    @DateTimeFormat("yyyy-MM-dd")
+    private LocalDate entryDate;
+}
+
+@JobHandler("userImportJob")
+public class UserImportJob extends IJobHandler {
+
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+        ImportParam p = JSON.parseObject(param, ImportParam.class);
+        String fileUrl = p.getFileUrl();
+
+        // 异步处理（大文件）
+        asyncImportService.importUsers(fileUrl, p.getTaskId());
+        return new ReturnT<>("导入任务已启动：" + p.getTaskId());
+    }
+}
+```
+
+---
+
+## 2. 订单导出（带筛选条件）
+
+### 2.1 场景
+
+用户在前端选择时间范围 + 状态，导出订单列表。
+
+### 2.2 实现
+
+```java
+@GetMapping("/export")
+public void exportOrders(@SpringQueryMap OrderQuery query, HttpServletResponse response) throws IOException {
+    // 1. 设置响应头
+    prepareExcelResponse(response, "采购订单");
+
+    // 2. 流式写入（避免大数据量 OOM）
+    try (ExcelWriter excelWriter = EasyExcel.write(response.getOutputStream(), OrderExportVO.class).build()) {
+        WriteSheet writeSheet = EasyExcel.writerSheet("订单列表").build();
+
+        // 3. 分页查询 + 分批写入
+        int page = 1;
+        while (true) {
+            Page<OrderExportVO> pageData = orderService.pageForExport(query, page, 1000);
+            if (pageData.isEmpty()) break;
+
+            excelWriter.write(pageData.getRecords(), writeSheet);
+
+            if (!pageData.hasNext()) break;
+            page++;
+        }
+    }
+}
+```
+
+### 2.3 性能优化
+
+- 流式写入（不一次性查询全部）
+- 分批查询 + 分批写入
+- 异步导出（特别大数据量）→ 用户下载文件而不是同步返回
+
+---
+
+## 3. 字典导入
+
+### 3.1 模板字段
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| 字典类型 | 是 | 必须是已存在的 type |
+| 字典编码 | 是 | 同 type 下唯一 |
+| 字典名称 | 是 | - |
+| 父编码 | 否 | 用于树形字典 |
+| 排序 | 否 | 默认 0 |
+
+### 3.2 实现
+
+```java
+@JobHandler("dictImportJob")
+public class DictImportJob extends IJobHandler {
+    @Override
+    public ReturnT<String> execute(String param) throws Exception {
+        DictImportParam p = JSON.parseObject(param, DictImportParam.class);
+
+        // 1. 读 Excel
+        List<DictImportVO> dataList = readExcel(p.getFileUrl(), DictImportVO.class);
+
+        // 2. 校验（按 type 分组校验唯一性）
+        Map<String, List<DictImportVO>> grouped = dataList.stream()
+            .collect(Collectors.groupingBy(DictImportVO::getType));
+
+        for (Map.Entry<String, List<DictImportVO>> entry : grouped.entrySet()) {
+            String type = entry.getKey();
+            List<DictImportVO> items = entry.getValue();
+
+            // 同 type 下 code 唯一
+            Set<String> codeSet = new HashSet<>();
+            for (DictImportVO item : items) {
+                if (!codeSet.add(item.getCode())) {
+                    throw new BizException(type + " 下存在重复编码：" + item.getCode());
+                }
+            }
+        }
+
+        // 3. 批量 upsert（幂等）
+        lookupService.batchUpsert(dataList);
+
+        return new ReturnT<>("导入 " + dataList.size() + " 条字典");
+    }
+}
+```
+
+---
+
+## 4. 大数据量导出（百万级）
+
+### 4.1 场景
+
+订单表 500 万条，用户要导出。
+
+### 4.2 同步方案（不推荐）
+
+```java
+@GetMapping("/export-all")
+public void exportAll(HttpServletResponse response) throws IOException {
+    List<OrderExportVO> all = orderRepository.findAllForExport();  // ❌ 500 万条 → OOM
+    EasyExcel.write(response.getOutputStream(), OrderExportVO.class).sheet().doWrite(all);
+}
+```
+
+**问题**：内存溢出 / 请求超时。
+
+### 4.3 异步方案（推荐）
+
+```
+Controller → 提交导出任务 → 立即返回 taskId
+Worker → 后台分批查询 + 写入临时文件 → 上传到 OSS → 通知用户
+```
+
+**实现**：
+
+```java
+@PostMapping("/export-async")
+public ApiResponse<String> exportAsync(@RequestBody OrderQuery query) {
+    String taskId = exportTaskService.submit(query);
+    return ApiResponse.success("导出任务已提交：" + taskId);
+}
+
+@Service
+public class ExportTaskService {
+
+    @Async("exportExecutor")
+    public String submit(OrderQuery query) {
+        String taskId = UUID.randomUUID().toString();
+
+        // 1. 写临时文件
+        Path tempFile = Files.createTempFile("export-", ".xlsx");
+
+        try (ExcelWriter writer = EasyExcel.write(tempFile.toString(), OrderExportVO.class).build()) {
+            WriteSheet sheet = EasyExcel.writerSheet("订单列表").build();
+
+            int page = 1;
+            while (true) {
+                Page<OrderExportVO> pageData = orderService.pageForExport(query, page, 5000);
+                if (pageData.isEmpty()) break;
+
+                writer.write(pageData.getRecords(), sheet);
+
+                if (!pageData.hasNext()) break;
+                page++;
+            }
+        }
+
+        // 2. 上传 OSS
+        String url = ossClient.upload(tempFile);
+
+        // 3. 保存任务结果
+        exportTaskRepository.save(new ExportTask(taskId, url, ExportTaskStatus.COMPLETED));
+
+        // 4. 通知用户
+        notificationService.sendToCurrentUser("导出完成：" + url);
+
+        return taskId;
+    }
+}
+```
+
+---
+
+## 5. ❌ 反模式汇总
+
+| 反模式 | 后果 |
+|--------|------|
+| 一次性读全部数据 | OOM |
+| 同步处理大文件 | 请求超时 |
+| 不校验直接入库 | 脏数据 |
+| 错误就中断 | 部分成功部分失败，无法回滚 |
+| 不收集错误行 | 用户无法修正 |
+| 循环单条查关联 | N+1 性能差 |
+
+---
+
+## 6. 关联阅读
+
+- [excel-guide.md](excel-guide.md) — EasyExcel 接入
+- [async-and-validate.md](async-and-validate.md) — 异步处理与校验
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-job/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: meritdata-platform-job
+description: |
+  任务调度（XXL-JOB）。注册 JobHandler、配置 cron、调度中心接入、幂等设计、失败重试、分布式锁、Job 间依赖。
+  触发场景：新二开模块需要定时任务；HR 数据同步；报表生成；清理任务。
+  何时不用：实时业务逻辑 → 用 code-spec；事件驱动 → L3 消息中心（待建）。
+metadata:
+  version: "1.0.0"
+  author: petroleum+rd
+  source: petroleum+rd
+  date_added: "2026-09-07"
+  last_modified: "2026-09-07"
+  risk: medium
+  layer: L2
+  sub-layer: L2-C
+  stack: java
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# 任务调度（job）
+
+## 触发
+- 新二开模块需要定时执行（每天/每小时/每分钟）
+- HR 数据同步 / 报表生成 / 数据清理
+- 需要分布式锁防止并发执行
+- 需要 Job 间依赖（A 完成后触发 B）
+
+## 不触发
+- 实时业务逻辑（同步处理）→ 用 `meritdata-platform-code-spec`
+- 事件驱动（消息队列）→ L3 消息中心（待建）
+- 业务流程触发 → 用 `meritdata-platform-bpm`
+
+## 前置约束
+- 定时任务**必须幂等**（多次执行结果一致）
+- 失败必须显式上抛，**禁止** `catch + log + continue`（详见铁律 §八.3）
+- Feign 调用遵守 `meritdata-platform-integration` 批量装配规则
+
+## 路由
+- XXL-JOB 接入 + JobHandler 写法 → [references/xxl-job-guide.md](references/xxl-job-guide.md)
+- 幂等设计 + 分布式锁 → [references/idempotency.md](references/idempotency.md)
+- 典型场景（HR 同步/清理） → [references/scenarios.md](references/scenarios.md)

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

@@ -0,0 +1,203 @@
+# 幂等设计（idempotency）
+
+> **铁律**：定时任务**必须幂等**（多次执行结果一致）。重试、并发、跨日补跑都不会产生脏数据。
+
+---
+
+## 1. 幂等的本质
+
+```
+执行 1 次：N 条数据
+执行 N 次：还是 N 条数据（数量一致、内容一致）
+```
+
+---
+
+## 2. 实现方案
+
+### 2.1 方案 1：唯一键去重（推荐）
+
+利用数据库唯一约束，业务键重复时**不抛错**，**跳过或更新**。
+
+```java
+// ✅ 正确：upsert 模式
+@Transactional
+public void syncUser(HrUser hrUser) {
+    User existing = userRepository.findByCode(hrUser.getCode()).orElse(null);
+    if (existing == null) {
+        // 新增
+        User newUser = convertToUser(hrUser);
+        userRepository.save(newUser);
+    } else if (hrUser.getUpdateTime().isAfter(existing.getUpdateTime())) {
+        // 更新（HR 比本地新）
+        updateUser(existing, hrUser);
+        userRepository.save(existing);
+    }
+    // 否则：本地比 HR 新，跳过（防止回退）
+}
+```
+
+### 2.2 方案 2：状态机去重
+
+记录每个业务的"是否已处理"标志位。
+
+```sql
+CREATE TABLE t_hr_sync_log (
+  id              BIGINT PRIMARY KEY,
+  hr_change_id    VARCHAR(64) NOT NULL,
+  processed       TINYINT DEFAULT 0,
+  process_time    DATETIME,
+  UNIQUE KEY uk_hr_change_id (hr_change_id)
+);
+```
+
+```java
+@Transactional
+public void syncChange(HrChange change) {
+    // 1. 先插日志（依赖唯一约束）
+    try {
+        syncLogRepository.save(new SyncLog(change.getId()));
+    } catch (DuplicateKeyException e) {
+        // 已处理过，跳过
+        return;
+    }
+
+    // 2. 执行业务逻辑
+    applyChange(change);
+
+    // 3. 标记处理完成
+    syncLogRepository.markProcessed(change.getId());
+}
+```
+
+### 2.3 方案 3：版本号去重
+
+业务表带 `version` 字段，更新时校验版本。
+
+```java
+@Transactional
+public void syncOrder(Order newOrder) {
+    Order existing = orderRepository.findByNo(newOrder.getNo()).orElse(null);
+    if (existing == null) {
+        newOrder.setVersion(1);
+        orderRepository.save(newOrder);
+    } else if (newOrder.getVersion() > existing.getVersion()) {
+        existing.setStatus(newOrder.getStatus());
+        existing.setVersion(newOrder.getVersion());
+        // ...
+        orderRepository.save(existing);
+    }
+    // 否则：旧版本，跳过
+}
+```
+
+### 2.4 方案 4：分布式锁（单实例执行）
+
+```java
+@JobHandler("criticalJob")
+public class CriticalJob extends IJobHandler {
+    @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;
+    }
+}
+```
+
+**注意**：分布式锁只能保证"同一时刻只有一个执行"，不能保证"多次执行结果一致"。
+
+---
+
+## 3. 按场景选方案
+
+| 场景 | 推荐方案 |
+|------|---------|
+| HR 数据同步 | 方案 1（upsert）+ 方案 2（处理日志）|
+| 支付回调 | 方案 2（状态机 + notify_id）|
+| 订单同步 | 方案 3（版本号）|
+| 单实例定时清理 | 方案 4（分布式锁）|
+| 报表生成 | 方案 1（覆盖写）|
+
+---
+
+## 4. ❌ 反模式
+
+### 4.1 ❌ 不做任何去重
+
+```java
+// ❌ 错：重复执行会产生重复数据
+@Override
+public ReturnT<String> execute(String param) {
+    List<HrUser> users = hrClient.getUsers();
+    for (HrUser user : users) {
+        userRepository.save(convertToUser(user));
+    }
+    return SUCCESS;
+}
+```
+
+重试一次就重复一份数据。
+
+### 4.2 ❌ 只靠分布式锁
+
+```java
+// ❌ 错：锁只能保证"不并发"，不能保证"不重处理"
+RLock lock = redissonClient.getLock("job:userSync");
+// 加锁
+syncUsers();
+```
+
+如果上次执行到一半崩溃（锁过期），下次重新执行仍可能产生重复。
+
+### 4.3 ❌ 用 `delete + insert` 模拟 upsert
+
+```java
+// ❌ 错：删除后插入有间隙，期间查不到数据
+userRepository.deleteByCode(code);
+userRepository.save(newUser);
+```
+
+✅ 用 `INSERT ... ON DUPLICATE KEY UPDATE`（MySQL）或 `MERGE`（Oracle）。
+
+### 4.4 ❌ 时间窗口去重
+
+```java
+// ❌ 错：用时间窗口判断
+if (user.getCreateTime().isAfter(lastHour)) {
+    userRepository.save(user);
+}
+```
+
+时间窗口不准确（网络延迟、时区、时钟漂移），应该用业务 ID 去重。
+
+---
+
+## 5. 测试用例
+
+每个幂等 Job 必须包含以下回归用例：
+
+| 用例 | 场景 | 期望 |
+|------|------|------|
+| 正常执行 | 第一次跑 | N 条数据 |
+| 重复执行 | 立刻再跑 | 还是 N 条数据（数量一致）|
+| 并发执行 | 同时跑 2 次 | 加锁后只跑 1 次；或最终一致 |
+| 部分失败重试 | 前 1000 条成功，后 1000 条失败，重试 | 最终 2000 条，无重复 |
+| 跨日补跑 | 昨天失败的数据今天补跑 | 与昨天合并后无重复 |
+
+详见 `meritdata-platform-code-spec` 中"测试规范"。
+
+---
+
+## 6. 关联阅读
+
+- [xxl-job-guide.md](xxl-job-guide.md) — XXL-JOB 接入
+- [scenarios.md](scenarios.md) — 典型场景
+- [SKILL.md](../SKILL.md)