ai-engineering-init 1.4.3 → 1.6.0

package/src/skills/leniu-java-concurrent/SKILL.md

@@ -0,0 +1,400 @@
+---
+name: leniu-java-concurrent
+description: |
+  leniu-tengyun-core / leniu-yunshitang 项目并发处理规范。当编写并发代码时使用此skill，包括线程安全、异步处理、分布式锁规范。
+
+  触发场景：
+  - 使用CompletableFuture进行异步处理
+  - 配置和使用线程池（ThreadPoolExecutor）
+  - 处理并发安全问题（Redis分布式锁、数据库唯一索引）
+  - 实现异步通知或异步日志（不等待结果）
+
+  适用项目：
+  - 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
+
+  触发词：并发、CompletableFuture、线程池、ThreadPool、并发安全、异步处理、synchronized
+---
+
+# leniu-tengyun-core 并发处理规范
+
+## 项目特征
+
+| 特征 | 说明 |
+|------|------|
+| 包名 | `net.xnzn.*` |
+| 异常类 | `LeException`（禁止使用 ServiceException） |
+| 工具类 | Hutool（CollUtil、StrUtil 等） |
+| 分布式锁 | `RedisUtil.getLock()` / `RedisUtil.setNx()` |
+| JDK | 21（支持虚拟线程，推荐使用标准线程池） |
+
+## 并行查询
+
+### 使用CompletableFuture
+
+```java
+// 并行查询多个数据源
+public XxxVO getData(Long id) {
+    // 创建异步任务
+    CompletableFuture<TypeA> futureA = CompletableFuture
+            .supplyAsync(() -> mapperA.selectById(id));
+
+    CompletableFuture<TypeB> futureB = CompletableFuture
+            .supplyAsync(() -> mapperB.selectById(id));
+
+    CompletableFuture<TypeC> futureC = CompletableFuture
+            .supplyAsync(() -> mapperC.selectById(id));
+
+    // 等待所有任务完成
+    CompletableFuture.allOf(futureA, futureB, futureC).join();
+
+    // 获取结果
+    TypeA resultA = futureA.join();
+    TypeB resultB = futureB.join();
+    TypeC resultC = futureC.join();
+
+    // 组装结果（使用 BeanUtil.copyProperties）
+    XxxVO vo = new XxxVO();
+    BeanUtil.copyProperties(resultA, vo);
+    vo.setDataB(resultB);
+    vo.setDataC(resultC);
+
+    return vo;
+}
+```
+
+### 指定线程池
+
+```java
+@Autowired
+private Executor asyncTaskExecutor;
+
+public XxxVO getData(Long id) {
+    // 使用指定的线程池
+    CompletableFuture<TypeA> futureA = CompletableFuture
+            .supplyAsync(() -> mapperA.selectById(id), asyncTaskExecutor);
+
+    CompletableFuture<TypeB> futureB = CompletableFuture
+            .supplyAsync(() -> mapperB.selectById(id), asyncTaskExecutor);
+
+    // 等待并获取结果
+    CompletableFuture.allOf(futureA, futureB).join();
+
+    TypeA resultA = futureA.join();
+    TypeB resultB = futureB.join();
+
+    return buildVO(resultA, resultB);
+}
+```
+
+### 报表模块专用线程池（yunshitangTaskExecutor）
+
+云食堂报表模块使用专项线程池，通过 `@Resource(name=...)` 按名称注入：
+
+```java
+@Service
+@Slf4j
+public class ReportSumXxxService {
+
+    // ✅ 按名称注入报表专用线程池
+    @Resource(name = "yunshitangTaskExecutor")
+    private AsyncTaskExecutor asyncTaskExecutor;
+
+    // ✅ 报表查询标准三并发模式：COUNT + LIST + TOTAL
+    public ReportBaseTotalVO<XxxVO> pageSummary(XxxParam param) {
+        // 1. 获取认证信息和数据权限
+        MgrUserAuthPO authPO = mgrAuthApi.getUserAuthPO();
+        ReportDataPermissionParam dataPermission =
+            reportDataPermissionService.getDataPermission(authPO);
+
+        // 2. 三并发：count、list、total 同时执行
+        CompletableFuture<Long> countFuture = CompletableFuture.supplyAsync(
+            () -> reportMapper.listSummary_COUNT(param, authPO, dataPermission),
+            asyncTaskExecutor
+        );
+        CompletableFuture<List<XxxVO>> listFuture = CompletableFuture.supplyAsync(() -> {
+            PageMethod.startPage(param.getPage());
+            return reportMapper.listSummary(param, authPO, dataPermission);
+        }, asyncTaskExecutor);
+        CompletableFuture<XxxVO> totalFuture = CompletableFuture.supplyAsync(
+            () -> reportMapper.getSummaryTotal(param, authPO, dataPermission),
+            asyncTaskExecutor
+        );
+
+        // 3. 等待所有任务完成
+        CompletableFuture.allOf(countFuture, listFuture, totalFuture).join();
+
+        // 4. 组装结果
+        PageVO<XxxVO> pageVO = PageVO.of(listFuture.join());
+        return new ReportBaseTotalVO<XxxVO>()
+            .setResultPage(pageVO)
+            .setTotalLine(totalFuture.join());
+    }
+}
+```
+
+**注意**：
+- `listSummary_COUNT` 为 Mapper 中专门的 COUNT 方法（命名规范：`listXxx_COUNT`）
+- `PageMethod.startPage()` 必须在 LIST Future 内部调用（同线程）
+- COUNT Future 使用 Mapper 的 COUNT 方法，不走 PageHelper
+- TOTAL Future 查询合计行，只返回数值字段
+
+## 异步执行
+
+### 不等待结果
+
+```java
+// 异步执行，不等待结果
+CompletableFuture.runAsync(() -> {
+    // 异步操作
+    logService.saveLog(log);
+}, asyncTaskExecutor);
+
+// 主线程继续执行
+return result;
+```
+
+### 异步执行并处理异常
+
+```java
+CompletableFuture.runAsync(() -> {
+    try {
+        // 异步操作
+        notificationService.send(message);
+    } catch (Exception e) {
+        log.error("异步发送通知失败", e);
+    }
+}, asyncTaskExecutor);
+```
+
+## 线程池配置
+
+### 自定义线程池
+
+```java
+@Configuration
+public class ThreadPoolConfig {
+
+    @Bean("asyncTaskExecutor")
+    public Executor asyncTaskExecutor() {
+        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
+        // 核心线程数
+        executor.setCorePoolSize(10);
+        // 最大线程数
+        executor.setMaxPoolSize(20);
+        // 队列容量
+        executor.setQueueCapacity(200);
+        // 线程名称前缀
+        executor.setThreadNamePrefix("async-task-");
+        // 拒绝策略
+        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
+        // 等待所有任务完成后关闭线程池
+        executor.setWaitForTasksToCompleteOnShutdown(true);
+        // 等待时间
+        executor.setAwaitTerminationSeconds(60);
+        executor.initialize();
+        return executor;
+    }
+}
+```
+
+## 并发安全
+
+### 使用分布式锁（Redisson）
+
+```java
+public void processOrder(Long orderId) {
+    String lockKey = "order:process:" + orderId;
+
+    // 获取Redisson分布式锁
+    RLock lock = RedisUtil.getLock(lockKey);
+    if (!lock.tryLock()) {
+        throw new LeException("订单正在处理中，请稍后重试");
+    }
+
+    try {
+        // 业务处理
+        doProcess(orderId);
+    } finally {
+        // 安全释放锁
+        if (lock.isHeldByCurrentThread() && lock.isLocked()) {
+            lock.unlock();
+        }
+    }
+}
+```
+
+### 使用Redis setNx 轻量锁
+
+```java
+public void processOnce(Long tenantId) {
+    String key = "task:process:" + tenantId;
+    // setNx：设置成功才继续执行，防重入
+    boolean ifFirst = RedisUtil.setNx(key, "1", 6);
+    if (!ifFirst) {
+        throw new LeException("任务正在执行中");
+    }
+
+    try {
+        doBusiness();
+    } finally {
+        RedisUtil.del(key);
+    }
+}
+```
+
+### 使用数据库唯一索引
+
+```java
+@Transactional(rollbackFor = Exception.class)
+public void createOrder(OrderParam param) {
+    try {
+        // 插入订单（依赖唯一索引防止重复）
+        Order order = buildOrder(param);
+        orderMapper.insert(order);
+    } catch (DuplicateKeyException e) {
+        throw new LeException("订单已存在");
+    }
+}
+```
+
+## 常见场景
+
+### 场景1：并行查询多个接口
+
+```java
+public DashboardVO getDashboard(Long userId) {
+    // 并行查询多个数据
+    CompletableFuture<OrderSummary> orderFuture = CompletableFuture
+            .supplyAsync(() -> orderService.getSummary(userId), asyncTaskExecutor);
+
+    CompletableFuture<PaymentSummary> paymentFuture = CompletableFuture
+            .supplyAsync(() -> paymentService.getSummary(userId), asyncTaskExecutor);
+
+    CompletableFuture<InventorySummary> inventoryFuture = CompletableFuture
+            .supplyAsync(() -> inventoryService.getSummary(userId), asyncTaskExecutor);
+
+    // 等待所有查询完成
+    CompletableFuture.allOf(orderFuture, paymentFuture, inventoryFuture).join();
+
+    // 组装结果
+    DashboardVO dashboard = new DashboardVO();
+    dashboard.setOrderSummary(orderFuture.join());
+    dashboard.setPaymentSummary(paymentFuture.join());
+    dashboard.setInventorySummary(inventoryFuture.join());
+
+    return dashboard;
+}
+```
+
+### 场景2：批量并行处理
+
+```java
+public void batchProcess(List<Long> ids) {
+    // 分批处理，每批100个（使用 Hutool CollUtil）
+    int batchSize = 100;
+    List<List<Long>> batches = CollUtil.split(ids, batchSize);
+
+    // 并行处理每批数据
+    List<CompletableFuture<Void>> futures = batches.stream()
+            .map(batch -> CompletableFuture.runAsync(() -> {
+                processBatch(batch);
+            }, asyncTaskExecutor))
+            .collect(Collectors.toList());
+
+    // 等待所有批次完成
+    CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
+
+    log.info("批量处理完成，总数:{}", ids.size());
+}
+
+private void processBatch(List<Long> batch) {
+    for (Long id : batch) {
+        try {
+            processOne(id);
+        } catch (Exception e) {
+            log.error("处理失败，id:{}", id, e);
+        }
+    }
+}
+```
+
+### 场景3：异步通知（不影响主流程）
+
+```java
+@Transactional(rollbackFor = Exception.class)
+public void createOrder(OrderParam param) {
+    // 创建订单
+    Order order = buildOrder(param);
+    orderMapper.insert(order);
+
+    // 异步发送通知（不影响主流程）
+    CompletableFuture.runAsync(() -> {
+        try {
+            // 发送短信
+            smsService.sendOrderCreated(order);
+            // 发送邮件
+            emailService.sendOrderCreated(order);
+        } catch (Exception e) {
+            log.error("发送通知失败，orderId:{}", order.getId(), e);
+        }
+    }, asyncTaskExecutor);
+
+    log.info("订单创建成功，orderId:{}", order.getId());
+}
+```
+
+## 最佳实践
+
+### 1. 指定线程池
+
+```java
+// ✅ 推荐：使用自定义线程池
+CompletableFuture.supplyAsync(() -> doSomething(), asyncTaskExecutor);
+
+// ❌ 避免：使用默认ForkJoinPool（可能影响其他业务）
+CompletableFuture.supplyAsync(() -> doSomething());
+```
+
+### 2. 异常处理
+
+```java
+CompletableFuture<Result> future = CompletableFuture
+        .supplyAsync(() -> {
+            try {
+                return doSomething();
+            } catch (Exception e) {
+                log.error("异步任务执行失败", e);
+                throw new CompletionException(e);
+            }
+        }, asyncTaskExecutor);
+
+// 处理异常（leniu 项目使用 LeException）
+try {
+    Result result = future.join();
+} catch (CompletionException e) {
+    log.error("获取异步结果失败", e);
+    throw new LeException("处理失败");
+}
+```
+
+### 3. 超时控制
+
+```java
+try {
+    // 设置超时时间
+    Result result = future.get(5, TimeUnit.SECONDS);
+} catch (TimeoutException e) {
+    log.error("异步任务超时", e);
+    throw new LeException("处理超时");
+}
+```
+
+## 常见错误
+
+| 错误写法 | 正确写法 | 说明 |
+|---------|---------|------|
+| `throw new ServiceException("msg")` | `throw new LeException("msg")` | leniu 项目异常类不同 |
+| `Lists.partition(ids, batchSize)` | `CollUtil.split(ids, batchSize)` | 使用 Hutool 工具类 |
+| `MapstructUtils.convert(a, B.class)` | `BeanUtil.copyProperties(a, b)` | leniu 使用 Hutool 转换 |
+| `import org.dromara.*` | `import net.xnzn.*` | 包名不同 |

package/src/skills/leniu-java-entity/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: leniu-java-entity
+description: |
+  leniu-tengyun-core 项目 Entity/VO/DTO/Param/Enum 数据类规范。
+
+  触发场景：
+  - 创建 Entity 实体类（@TableName、审计字段 crby/crtime/upby/uptime）
+  - 创建 VO/DTO/Param 数据传输对象
+  - 使用 Jakarta Validation 参数校验
+  - 创建枚举类（含国际化 I18n）
+  - Excel 导出 VO（EasyExcel）
+
+  触发词：Entity实体类、VO视图对象、DTO数据传输、Param参数类、@TableName、@TableField、审计字段、枚举类、Excel导出、Jakarta校验
+---
+
+# leniu Entity/VO/DTO 规范
+
+## 项目特征速查
+
+| 项 | 值 |
+|---|---|
+| 包名 | `net.xnzn.core.*` |
+| JDK | 21 → `jakarta.validation.*`（禁用 javax） |
+| 工具库 | Hutool（BeanUtil / CollUtil / ObjectUtil / StrUtil） |
+| 金额 | `Long`（分）或 `BigDecimal`（分），前端用 `money()` 转元 |
+| 审计字段 | crby / crtime / upby / uptime |
+| 逻辑删除 | **1=删除，2=正常**（与 RuoYi 相反） |
+| Entity 特点 | 无基类、无 Serializable |
+
+## Entity 模板（核心）
+
+```java
+@Data
+@Accessors(chain = true)
+@TableName(value = "table_name", autoResultMap = true)
+public class XxxEntity {
+
+    @TableId
+    @ApiModelProperty("主键ID")
+    private Long id;
+
+    // --- 业务字段 ---
+    @ApiModelProperty("名称")
+    private String name;
+
+    // --- 审计字段 ---
+    @ApiModelProperty("删除标识(1-删除,2-正常)")
+    private Integer delFlag;
+
+    @TableField(fill = FieldFill.INSERT)
+    private String crby;
+
+    @TableField(fill = FieldFill.INSERT)
+    private LocalDateTime crtime;
+
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    private String upby;
+
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    private LocalDateTime uptime;
+
+    // --- 静态工厂（预设默认值） ---
+    public static XxxEntity newDefaultInstance() {
+        XxxEntity e = new XxxEntity();
+        e.setDelFlag(2); // 2=正常
+        return e;
+    }
+
+    // --- 领域业务方法（可选） ---
+}
+```
+
+**要点**：
+- 无基类，审计字段直接定义
+- `@TableName` 一般带 `autoResultMap = true`；报表 Model 不带（无 BaseMapper）
+- 可含 `newDefaultInstance()` 工厂方法和领域业务方法
+
+## VO 模板
+
+```java
+@Data
+@Accessors(chain = true)
+@ApiModel("订单信息")
+public class OrderVO {
+
+    @ApiModelProperty("订单ID")
+    private Long orderId;
+
+    @ApiModelProperty("订单金额（元）")
+    private BigDecimal orderAmount;
+
+    @ApiModelProperty("创建时间")
+    private LocalDateTime crtime;
+}
+```
+
+带校验的 VO：
+
+```java
+@Data
+@Accessors(chain = true)
+@ApiModel("订单信息")
+public class OrderVO {
+
+    @NotNull(message = "用户ID不能为空")
+    @ApiModelProperty("用户ID")
+    private Long userId;
+
+    @NotNull(message = "订单金额不能为空")
+    @DecimalMin(value = "0.01", message = "订单金额必须大于0")
+    @ApiModelProperty("订单金额（元）")
+    private BigDecimal orderAmount;
+}
+```
+
+## Param 模板（分页查询）
+
+```java
+@Data
+@ApiModel("订单查询参数")
+public class OrderQueryParam implements Serializable {
+
+    @NotNull(message = "分页参数不能为空")
+    @ApiModelProperty(value = "分页参数", required = true)
+    private PageDTO page;
+
+    @ApiModelProperty("关键字")
+    private String keyword;
+
+    @ApiModelProperty("状态")
+    private Integer status;
+
+    @ApiModelProperty("开始日期")
+    private LocalDate startDate;
+
+    @ApiModelProperty("结束日期")
+    private LocalDate endDate;
+}
+```
+
+## DTO 模板
+
+```java
+@Data
+@ApiModel("订单数据传输对象")
+public class OrderDTO {
+
+    @ApiModelProperty("订单ID")
+    private Long orderId;
+
+    @ApiModelProperty("用户ID")
+    private Long userId;
+
+    @ApiModelProperty("订单状态")
+    private Integer status;
+}
+```
+
+## 枚举模板
+
+```java
+@Getter
+@AllArgsConstructor
+public enum OrderStatusEnum {
+
+    CREATED(1, "已创建"),
+    PAID(2, "已支付"),
+    COMPLETED(3, "已完成"),
+    CANCELLED(4, "已取消");
+
+    private final Integer key;
+    private final String desc;
+
+    public static OrderStatusEnum getByKey(Integer key) {
+        if (key == null) return null;
+        for (OrderStatusEnum e : values()) {
+            if (e.getKey().equals(key)) return e;
+        }
+        return null;
+    }
+
+    public static String getDescByKey(Integer key) {
+        OrderStatusEnum e = getByKey(key);
+        return e != null ? e.getDesc() : "";
+    }
+}
+```
+
+含国际化时，`desc` 用占位符 `"{order.status.created}"`，重写 `getDesc()` 调用 `I18n.getMessage(desc)`。
+
+## 时间格式化
+
+```java
+@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
+private LocalDateTime createTime;
+
+@DateTimeFormat(pattern = "yyyy-MM-dd")
+@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
+private LocalDate date;
+```
+
+## 对象转换
+
+```java
+// 单对象
+Target t = BeanUtil.copyProperties(source, Target.class);
+// 列表
+List<Target> list = BeanUtil.copyToList(sources, Target.class);
+```
+
+## 禁止项
+
+```java
+// ❌ 继承 RuoYi TenantEntity / BaseEntity
+import org.dromara.common.mybatis.core.domain.TenantEntity;
+
+// ❌ javax.validation（JDK 21 必须用 jakarta）
+import javax.validation.constraints.NotNull;
+
+// ❌ MapstructUtils（用 BeanUtil.copyProperties）
+MapstructUtils.convert(source, Target.class);
+
+// ❌ delFlag: 0=正常（leniu 是 2=正常）
+wrapper.eq(XxxEntity::getDelFlag, 0);
+
+// ❌ 错误审计字段名
+private String createBy;      // 必须 crby
+private LocalDateTime createTime; // 必须 crtime
+
+// ❌ Entity 加 tenant_id（双库物理隔离，不需要）
+```
+
+## 参考文档
+
+- 完整模板示例（Excel导出VO、报表Param等）：详见 `references/templates.md`
+- 生产代码参考：`sys-canteen/.../order/common/model/OrderInfo.java`