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

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

@@ -1,248 +0,0 @@
-# 导入导出典型场景（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/references/idempotency.md

@@ -1,203 +0,0 @@
-# 幂等设计（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)