ai-engineering-init 1.1.0

package/.codex/skills/leniu-java-report-query-param/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: leniu-java-report-query-param
+description: |
+  leniu-tengyun-core / leniu-yunshitang 项目报表查询入参规范。当创建报表Controller接口的查询入参Param类时使用此skill。
+
+  触发场景：
+  - 创建报表查询入参Param类（分页、时间范围、组织筛选）
+  - 设计报表接口的基类继承结构
+  - 配置导出列开关（exportColumns）
+  - 报表查询参数标准化
+
+  适用项目：
+  - leniu-tengyun-core：/Users/xujiajun/Developer/gongsi_proj/leniu-api/leniu-tengyun-core
+  - leniu-yunshitang：/Users/xujiajun/Developer/gongsi_proj/leniu-api/leniu-tengyun/leniu-yunshitang
+
+  触发词：leniu-报表查询、leniu-Param类、leniu-查询入参、leniu-分页参数、leniu-时间范围、leniu-ReportBaseParam、leniu-exportCols、net.xnzn、leniu-yunshitang
+---
+
+# leniu-tengyun-core 报表查询入参规范
+
+## 项目特征
+
+| 特征 | 说明 |
+|------|------|
+| **包名前缀** | `net.xnzn.core.*` |
+| **JDK 版本** | 21 |
+| **请求封装** | `LeRequest<T>` |
+| **分页参数** | `PageDTO` |
+| **基类** | `ReportBaseParam` |
+| **校验框架** | Jakarta Validation |
+
+## 核心结构
+
+### 1. Controller层接收入参
+
+```java
+import com.pig4cloud.pigx.common.core.util.LeRequest;
+
+@PostMapping("/page")
+public ReportBaseTotalVO<XxxVO> pageXxxSummary(@RequestBody LeRequest<XxxParam> request) {
+    XxxParam param = request.getContent();
+    return xxxService.pageSummary(param);
+}
+```
+
+### 2. Param类基类继承
+
+报表查询Param类**必须继承** `ReportBaseParam`：
+
+```java
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import net.xnzn.core.common.page.PageDTO;
+import net.xnzn.core.common.param.ReportBaseParam;
+
+import java.time.LocalDate;
+import java.util.List;
+
+@Data
+@EqualsAndHashCode(callSuper = true)
+@ApiModel(value = "XXX查询入参")
+public class XxxParam extends ReportBaseParam {
+
+    @ApiModelProperty("关键字")
+    private String keyword;
+
+    @ApiModelProperty("状态")
+    private Integer status;
+}
+```
+
+### 3. ReportBaseParam 提供的通用字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| `page` | `PageDTO` | 分页参数 |
+| `startDate` | `LocalDate` | 开始时间 |
+| `endDate` | `LocalDate` | 结束时间 |
+| `exportCols` | `List<String>` | 需要导出的列 |
+| `sumType` | `Integer` | 汇总类型 |
+| `sumDimension` | `Integer` | 统计维度 |
+
+## 常用查询字段模式
+
+### 时间范围查询
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+@ApiModel("订单报表查询参数")
+public class OrderReportParam extends ReportBaseParam {
+
+    // 基类已有 startDate, endDate
+
+    @ApiModelProperty("开始时间（精确到秒）")
+    private LocalDateTime startTime;
+
+    @ApiModelProperty("结束时间（精确到秒）")
+    private LocalDateTime endTime;
+}
+```
+
+### 组织筛选
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+@ApiModel("组织报表查询参数")
+public class OrgReportParam extends ReportBaseParam {
+
+    @ApiModelProperty("组织ID")
+    private Long orgId;
+
+    @ApiModelProperty("组织ID列表")
+    private List<Long> orgIds;
+
+    @ApiModelProperty("食堂ID")
+    private Long canteenId;
+
+    @ApiModelProperty("食堂ID列表")
+    private List<Long> canteenIds;
+}
+```
+
+### 餐次筛选
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+@ApiModel("餐次报表查询参数")
+public class MealtimeReportParam extends ReportBaseParam {
+
+    @ApiModelProperty("餐次类型列表")
+    private List<Integer> mealtimeTypes;
+
+    @ApiModelProperty("是否只查正餐")
+    private Boolean onlyMainMeal;
+}
+```
+
+### 金额范围
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+@ApiModel("金额报表查询参数")
+public class AmountReportParam extends ReportBaseParam {
+
+    @ApiModelProperty("最小金额（分）")
+    private Long minAmount;
+
+    @ApiModelProperty("最大金额（分）")
+    private Long maxAmount;
+}
+```
+
+## PageDTO 结构
+
+```java
+@Data
+@ApiModel("分页参数")
+public class PageDTO {
+
+    @ApiModelProperty("当前页码")
+    private Integer current = 1;
+
+    @ApiModelProperty("每页条数")
+    private Integer size = 10;
+
+    @ApiModelProperty("是否查询总数")
+    private Boolean ifCount = true;
+
+    @ApiModelProperty("页数为0时的处理")
+    private Boolean ifPageSizeZero = false;
+}
+```
+
+## 完整示例
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+@ApiModel("销售报表查询参数")
+public class SalesReportParam extends ReportBaseParam {
+
+    @ApiModelProperty(value = "关键字")
+    private String keyword;
+
+    @ApiModelProperty(value = "组织ID列表")
+    private List<Long> orgIds;
+
+    @ApiModelProperty(value = "食堂ID列表")
+    private List<Long> canteenIds;
+
+    @ApiModelProperty(value = "餐次类型列表")
+    private List<Integer> mealtimeTypes;
+
+    @ApiModelProperty(value = "支付方式列表")
+    private List<Integer> payTypes;
+
+    @ApiModelProperty(value = "最小金额（分）")
+    private Long minAmount;
+
+    @ApiModelProperty(value = "最大金额（分）")
+    private Long maxAmount;
+
+    @ApiModelProperty(value = "是否查询合计行")
+    private Boolean ifQueryTotal = true;
+}
+```
+
+## 两层继承结构（实际生产代码模式）
+
+报表 Param 存在两层继承结构，以订单分析报表为例：
+
+```
+ReportAnalysisParam（大类基类：订单分析类报表通用字段）
+    └── ReportAnalysisTurnoverParam（具体报表 Param，加业务字段）
+```
+
+### ReportAnalysisParam（中间基类）
+
+```java
+import lombok.Data;
+import net.xnzn.core.common.page.PageDTO;
+
+import java.time.LocalDate;
+import java.util.List;
+
+@Data
+public class ReportAnalysisParam {
+
+    /** 分页参数 */
+    private PageDTO page;
+
+    /** 开始日期 */
+    private LocalDate startDate;
+
+    /** 结束日期 */
+    private LocalDate endDate;
+
+    /** 日期维度：1=按月 2=按日 */
+    private Integer dateType;
+
+    /** 食堂摊位ID列表（多选） */
+    private List<Long> canteenStallIds;
+}
+```
+
+### ReportAnalysisTurnoverParam（具体 Param，继承中间基类）
+
+```java
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+import java.util.List;
+
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class ReportAnalysisTurnoverParam extends ReportAnalysisParam {
+
+    /** 餐次类型（单选） */
+    private Integer mealtimeType;
+
+    /** 餐次类型列表（多选） */
+    private List<Integer> mealtimeTypeList;
+
+    /** 排序类型：1=按金额降序（默认） */
+    private Integer sortType = 1;
+
+    /** 食堂ID（单选） */
+    private Long canteenId;
+
+    /** 摊位ID（单选） */
+    private Long stallId;
+}
+```
+
+**选择继承层级的判断依据**：
+- 若报表是"订单分析"大类报表 → 继承 `ReportAnalysisParam`（含 `dateType`）
+- 若是通用报表 → 直接继承 `ReportBaseParam`（含 `page/startDate/endDate/exportCols`）
+
+## 注意事项
+
+- 报表Param类必须继承 `ReportBaseParam` 或其子类（如 `ReportAnalysisParam`）
+- 时间字段使用 `LocalDate` 或 `LocalDateTime`
+- `dateType` 字段含义：1=按月汇总，2=按日汇总
+- 金额查询参数类型与业务域保持一致：钱包/账户用 `Long`（分），订单用 `BigDecimal`（分）；见 leniu-java-amount-handling
+- 导出时通过 `exportCols` 控制导出列

package/.codex/skills/leniu-java-task/SKILL.md

@@ -0,0 +1,367 @@
+---
+name: leniu-java-task
+description: |
+  leniu-tengyun-core / leniu-yunshitang 项目定时任务规范。当编写定时任务时使用此skill，包括XXL-Job使用和任务调度规范。
+
+  触发场景：
+  - 使用XXL-Job实现分布式定时任务
+  - 编写任务处理器（@XxlJob）
+  - 商户遍历任务模式
+  - 任务并发控制和监控
+
+  适用项目：
+  - leniu-tengyun-core：/Users/xujiajun/Developer/gongsi_proj/leniu-api/leniu-tengyun-core
+  - leniu-yunshitang：/Users/xujiajun/Developer/gongsi_proj/leniu-api/leniu-tengyun/leniu-yunshitang
+
+  触发词：leniu-定时任务、leniu-XXL-Job、leniu-@XxlJob、leniu-TenantLoader、leniu-TenantContextHolder、leniu-分布式锁、net.xnzn、leniu-yunshitang
+---
+
+# leniu-tengyun-core 定时任务规范
+
+## 项目特征
+
+| 特征 | 说明 |
+|------|------|
+| **包名前缀** | `net.xnzn.core.*` |
+| **JDK 版本** | 21 |
+| **任务框架** | XXL-Job |
+| **任务注解** | `@XxlJob` |
+| **租户上下文** | `TenantContextHolder` |
+| **租户加载器** | `TenantLoader` |
+| **跨租户工具** | `Executors` |
+| **Redis工具** | `RedisUtil` |
+| **异常类** | `LeException` |
+| **国际化** | `I18n` |
+
+## 基础使用
+
+### 定时任务模板
+
+```java
+import com.xxl.job.core.handler.annotation.XxlJob;
+import net.xnzn.framework.data.tenant.TenantContextHolder;
+import net.xnzn.core.common.loader.TenantLoader;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Lazy;
+import org.springframework.stereotype.Component;
+import lombok.extern.slf4j.Slf4j;
+
+@Component
+@Slf4j
+public class DataSyncTask {
+
+    @Autowired
+    @Lazy
+    private DataSyncService dataSyncService;
+
+    /**
+     * 数据同步任务
+     */
+    @XxlJob(value = "dataSyncJob")
+    public void syncData() {
+        log.info("【定时任务】数据同步任务开始执行");
+
+        try {
+            int count = dataSyncService.sync();
+            log.info("【定时任务】数据同步任务执行完成,同步数量:{}", count);
+        } catch (Exception e) {
+            log.error("【定时任务】数据同步任务执行失败", e);
+            throw e;  // 重新抛出,XXL-Job会记录失败
+        }
+    }
+}
+```
+
+## 商户遍历模式
+
+### 模式一: 直接使用 TenantLoader（最常用）
+
+```java
+@Component
+@Slf4j
+public class AccSubTimeTask {
+
+    @Autowired
+    @Lazy
+    private TenantLoader tenantLoader;
+
+    @Autowired
+    @Lazy
+    private AccSubTimeService accSubTimeService;
+
+    /**
+     * 补贴定时发放任务
+     */
+    @XxlJob("accSubTimeSendHandle")
+    public void accSubTimeSendHandle() {
+        log.info("[补贴定时规则]定时任务,开始时间:{}", LocalDateTime.now());
+
+        // 遍历所有商户
+        tenantLoader.listTenant().forEach(merchantId -> {
+            try {
+                // 设置租户上下文
+                TenantContextHolder.setTenantId(merchantId);
+
+                // 并发控制
+                this.checkTask(merchantId);
+
+                // 执行业务逻辑
+                accSubTimeService.accSubRuleTask();
+            } catch (Exception e) {
+                log.error("[补贴定时规则]定时任务异常,商家={}", merchantId, e);
+            }
+        });
+
+        log.info("[补贴定时规则]定时任务,结束时间:{}", LocalDateTime.now());
+    }
+
+    /**
+     * 并发控制检查
+     */
+    protected void checkTask(Long tenantId) {
+        String key = "yst:task:name:" + tenantId;
+        boolean ifFirst = RedisUtil.setNx(key, LeConstants.COMMON_YES, 6);
+        if (!ifFirst) {
+            throw new LeException(I18n.getMessage("acc_operate_exits_task"));
+        }
+    }
+}
+```
+
+### 模式二: 使用 Executors 工具类
+
+```java
+import net.xnzn.framework.data.executor.Executors;
+
+@Component
+@Slf4j
+public class CouponTask {
+
+    @Autowired
+    @Lazy
+    private CouponService couponService;
+
+    /**
+     * 餐券状态自动处理
+     */
+    @XxlJob("couponStateAutoHandler")
+    public void couponStateAutoHandler() {
+        log.info("[餐券状态]定时任务开始执行");
+
+        // 使用工具类遍历商户
+        Executors.doInAllTenant(tenantId -> {
+            try {
+                TenantContextHolder.setTenantId(tenantId);
+                couponService.autoHandleState();
+            } catch (Exception e) {
+                log.error("[餐券状态]定时任务异常,商家={}", tenantId, e);
+            }
+        });
+
+        log.info("[餐券状态]定时任务执行完成");
+    }
+}
+```
+
+### 模式三: 商户遍历 + 分布式锁
+
+```java
+import org.redisson.api.RLock;
+
+@Component
+@Slf4j
+public class PayTask {
+
+    @Autowired
+    @Lazy
+    private TenantLoader tenantLoader;
+
+    private static final String LOCK_KEY_PAYING = "pay:paying:lock";
+
+    /**
+     * 处理支付中的交易记录
+     */
+    @XxlJob("payingTradeRecordHandler")
+    public void payingTradeRecordHandler() {
+        // 获取分布式锁
+        RLock lock = RedisUtil.getLock(LOCK_KEY_PAYING);
+        if (!lock.tryLock()) {
+            log.warn("[支付定时任务]上一个任务进行中");
+            return;
+        }
+
+        try {
+            log.info("[支付定时任务]处理支付中的交易开始执行");
+
+            for (Long tenantId : tenantLoader.listTenant()) {
+                try {
+                    TenantContextHolder.setTenantId(tenantId);
+                    // 处理交易记录
+                    tradeRecordService.handlePayingRecords();
+                } catch (Exception e) {
+                    log.error("[支付定时任务]商户处理异常,tenantId={}", tenantId, e);
+                }
+            }
+        } finally {
+            if (lock.isHeldByCurrentThread() && lock.isLocked()) {
+                lock.unlock();
+            }
+        }
+    }
+}
+```
+
+## 并发控制
+
+### 方式一: Redis setNx 简单锁（商户级）
+
+```java
+/**
+ * 商户级别的并发控制
+ */
+protected void checkTask(Long tenantId) {
+    String key = "yst:task:name:" + tenantId;
+    boolean ifFirst = RedisUtil.setNx(key, "1", 6);
+    if (!ifFirst) {
+        throw new LeException("任务正在执行");
+    }
+}
+```
+
+### 方式二: Redisson 分布式锁（全局级）
+
+```java
+@XxlJob("globalTaskJob")
+public void globalTask() {
+    RLock lock = RedisUtil.getLock("task:global:lock");
+    if (!lock.tryLock()) {
+        log.warn("[全局任务]上一个任务进行中,跳过");
+        return;
+    }
+
+    try {
+        doTask();
+    } finally {
+        if (lock.isHeldByCurrentThread() && lock.isLocked()) {
+            lock.unlock();
+        }
+    }
+}
+```
+
+## 任务参数
+
+### 使用任务参数
+
+```java
+import com.xxl.job.core.context.XxlJobHelper;
+
+@XxlJob("dataCleanJob")
+public void cleanData() {
+    // 获取任务参数
+    String param = XxlJobHelper.getJobParam();
+    log.info("【定时任务】数据清理任务开始执行,参数:{}", param);
+
+    try {
+        // 解析参数
+        DataCleanParam cleanParam = JacksonUtil.readValue(param, DataCleanParam.class);
+        int count = dataService.clean(cleanParam);
+        log.info("【定时任务】数据清理任务执行完成,清理数量:{}", count);
+    } catch (Exception e) {
+        log.error("【定时任务】数据清理任务执行失败", e);
+        throw e;
+    }
+}
+```
+
+## 任务分片
+
+```java
+@XxlJob("userDataSyncJob")
+public void syncUserData() {
+    // 获取分片参数
+    int shardIndex = XxlJobHelper.getShardIndex();  // 当前分片索引
+    int shardTotal = XxlJobHelper.getShardTotal();  // 总分片数
+
+    log.info("【定时任务】用户数据同步,分片:{}/{}", shardIndex, shardTotal);
+
+    // 查询当前分片的数据
+    List<User> users = userService.listBySharding(shardIndex, shardTotal);
+    // 处理数据...
+}
+```
+
+## 最佳实践
+
+### 1. 依赖注入使用 @Autowired @Lazy
+
+```java
+@Component
+@Slf4j
+public class XxxTask {
+
+    @Autowired
+    @Lazy
+    private XxxService xxxService;
+
+    @Autowired
+    @Lazy
+    private TenantLoader tenantLoader;
+}
+```
+
+### 2. 商户遍历必须设置租户上下文
+
+```java
+tenantLoader.listTenant().forEach(merchantId -> {
+    try {
+        // ⚠️ 必须设置租户上下文
+        TenantContextHolder.setTenantId(merchantId);
+        doSomething();
+    } catch (Exception e) {
+        log.error("[任务]处理异常,商家={}", merchantId, e);
+    }
+});
+```
+
+### 3. 单个商户失败不影响其他商户
+
+```java
+// ✅ 推荐
+tenantLoader.listTenant().forEach(merchantId -> {
+    try {
+        TenantContextHolder.setTenantId(merchantId);
+        doBusiness();
+    } catch (Exception e) {
+        log.error("[任务]商户处理异常", e);  // 捕获异常,继续执行
+    }
+});
+
+// ❌ 避免
+for (Long merchantId : tenantLoader.listTenant()) {
+    TenantContextHolder.setTenantId(merchantId);
+    doBusiness();  // 异常会导致后续商户无法执行
+}
+```
+
+### 4. 任务日志完整
+
+```java
+@XxlJob("dataSyncJob")
+public void syncData() {
+    log.info("[任务名称]定时任务开始执行");
+    try {
+        int count = doSync();
+        log.info("[任务名称]定时任务执行完成,数量:{}", count);
+    } catch (Exception e) {
+        log.error("[任务名称]定时任务执行失败", e);
+        throw e;
+    }
+}
+```
+
+## 注意事项
+
+- 与 `scheduled-jobs` 技能不同，本技能侧重 XXL-Job 使用规范
+- 商户遍历任务必须设置 `TenantContextHolder.setTenantId()`
+- 注意控制任务并发，避免重复执行