leniu-dev 2.0.0

package/.cursor/skills/leniu-java-entity/references/templates.md

@@ -0,0 +1,237 @@
+# Entity/VO/DTO 完整模板参考
+
+## 生产代码参考：OrderInfo Model
+
+```java
+import com.baomidou.mybatisplus.annotation.*;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import lombok.Data;
+import lombok.experimental.Accessors;
+
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+
+/**
+ * 关键特征：
+ * 1. 无基类、无 Serializable
+ * 2. @TableName 不带 autoResultMap（报表 Mapper 无 BaseMapper）
+ * 3. 包含静态工厂方法 newDefaultInstance()
+ * 4. 包含领域业务方法（计算/重置等）
+ */
+@Data
+@Accessors(chain = true)
+@ApiModel(value = "订单信息")
+@TableName("order_info")
+public class OrderInfo {
+
+    @TableId
+    @ApiModelProperty(value = "订单ID")
+    private Long id;
+
+    @ApiModelProperty(value = "食堂ID")
+    private Long canteenId;
+
+    @ApiModelProperty(value = "用户ID")
+    private Long userId;
+
+    @ApiModelProperty(value = "应付金额（分）")
+    private BigDecimal payableAmount;
+
+    @ApiModelProperty(value = "实付金额（分）")
+    private BigDecimal realAmount;
+
+    @ApiModelProperty(value = "优惠金额（分）")
+    private BigDecimal discountsAmount;
+
+    @ApiModelProperty(value = "订单状态")
+    private Integer status;
+
+    @ApiModelProperty(value = "删除标识(1-删除,2-正常)")
+    private Integer delFlag;
+
+    @TableField(fill = FieldFill.INSERT)
+    @ApiModelProperty(value = "创建人")
+    private String crby;
+
+    @TableField(fill = FieldFill.INSERT)
+    @ApiModelProperty(value = "创建时间")
+    private LocalDateTime crtime;
+
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    @ApiModelProperty(value = "更新人")
+    private String upby;
+
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    @ApiModelProperty(value = "更新时间")
+    private LocalDateTime uptime;
+
+    public static OrderInfo newDefaultInstance() {
+        OrderInfo orderInfo = new OrderInfo();
+        orderInfo.setDelFlag(2);
+        orderInfo.setPayableAmount(BigDecimal.ZERO);
+        orderInfo.setRealAmount(BigDecimal.ZERO);
+        orderInfo.setDiscountsAmount(BigDecimal.ZERO);
+        return orderInfo;
+    }
+
+    public BigDecimal calcNeedPayAmount() {
+        return payableAmount.subtract(discountsAmount);
+    }
+
+    public void resetAmountsZero() {
+        this.payableAmount = BigDecimal.ZERO;
+        this.realAmount = BigDecimal.ZERO;
+        this.discountsAmount = BigDecimal.ZERO;
+    }
+}
+```
+
+## Excel 导出 VO
+
+```java
+import com.alibaba.excel.annotation.ExcelProperty;
+import com.alibaba.excel.annotation.write.style.ColumnWidth;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import lombok.Data;
+import lombok.experimental.Accessors;
+import net.xnzn.core.common.export.converter.CustomNumberConverter;
+
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+
+@Data
+@Accessors(chain = true)
+@ApiModel("订单信息")
+public class OrderExportVO {
+
+    @ExcelProperty(value = "订单ID", order = 1)
+    @ColumnWidth(15)
+    @ApiModelProperty("订单ID")
+    private Long orderId;
+
+    @ExcelProperty(value = "用户ID", order = 2)
+    @ColumnWidth(15)
+    @ApiModelProperty("用户ID")
+    private Long userId;
+
+    @ExcelProperty(value = "订单金额（元）", order = 3, converter = CustomNumberConverter.class)
+    @ColumnWidth(15)
+    @ApiModelProperty("订单金额（元）")
+    private BigDecimal orderAmount;
+
+    @ExcelProperty(value = "创建时间", order = 4)
+    @ColumnWidth(20)
+    @ApiModelProperty("创建时间")
+    private LocalDateTime crtime;
+}
+```
+
+## 报表 Param
+
+```java
+import com.alibaba.excel.annotation.ExcelIgnore;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import lombok.Data;
+
+import java.io.Serializable;
+import java.time.LocalDate;
+import java.util.List;
+
+@Data
+@ApiModel("订单报表查询参数")
+public class OrderReportParam implements Serializable {
+
+    @ExcelIgnore
+    @ApiModelProperty(value = "分页参数", required = true)
+    private PageDTO page;
+
+    @ExcelIgnore
+    @ApiModelProperty("关键字")
+    private String keyword;
+
+    @ApiModelProperty("开始日期")
+    private LocalDate startDate;
+
+    @ApiModelProperty("结束日期")
+    private LocalDate endDate;
+
+    @ApiModelProperty("食堂ID列表")
+    private List<Long> canteenIds;
+
+    @ApiModelProperty("状态")
+    private Integer status;
+}
+```
+
+## 含国际化的枚举
+
+```java
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import net.xnzn.core.common.i18n.I18n;
+
+@Getter
+@AllArgsConstructor
+public enum OrderStatusEnum {
+
+    CREATED(1, "{order.status.created}"),
+    PAID(2, "{order.status.paid}"),
+    COMPLETED(3, "{order.status.completed}"),
+    CANCELLED(4, "{order.status.cancelled}");
+
+    private final Integer key;
+    private final String desc;
+
+    public String getDesc() {
+        return I18n.getMessage(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() : "";
+    }
+}
+```
+
+## 常用注解速查
+
+### MyBatis-Plus
+
+| 注解 | 示例 |
+|------|------|
+| `@TableName` | `@TableName("order_table")` 或 `@TableName(value = "x", autoResultMap = true)` |
+| `@TableId` | `@TableId private Long id;` |
+| `@TableField(fill = FieldFill.INSERT)` | 插入时填充（crby, crtime） |
+| `@TableField(fill = FieldFill.INSERT_UPDATE)` | 插入+更新填充（upby, uptime） |
+| `@TableField(exist = false)` | 非数据库字段 |
+
+### Jakarta Validation
+
+| 注解 | 示例 |
+|------|------|
+| `@NotNull` | `@NotNull(message = "不能为空")` |
+| `@NotBlank` | `@NotBlank(message = "名称不能为空")` |
+| `@NotEmpty` | `@NotEmpty(message = "列表不能为空")` |
+| `@Size` | `@Size(min = 1, max = 100)` |
+| `@DecimalMin` | `@DecimalMin(value = "0.01")` |
+| `@Pattern` | `@Pattern(regexp = "^1[3-9]\\d{9}$")` |
+
+### EasyExcel
+
+| 注解 | 示例 |
+|------|------|
+| `@ExcelProperty(value = "列名", order = 1)` | 列名和顺序 |
+| `@ColumnWidth(15)` | 列宽 |
+| `@ExcelIgnore` | 忽略导出 |
+| `converter = CustomNumberConverter.class` | 金额转换器 |

package/.cursor/skills/leniu-java-logging/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: leniu-java-logging
+description: |
+  leniu-tengyun-core / leniu-yunshitang 项目日志规范。当编写日志代码时使用此 skill。
+
+  触发场景：
+  - 编写日志记录代码（@Slf4j、log.info/error/debug）
+  - 记录异常日志（含完整堆栈）
+  - 业务关键路径日志埋点（订单/支付/MQ/定时任务）
+  - 配置日志级别和 Logback
+  - 敏感信息脱敏处理
+
+  触发词：日志、@Slf4j、log.info、log.error、log.debug、日志级别、logback、日志格式、日志脱敏、异常日志
+---
+
+# leniu 日志规范
+
+## 基本规则
+
+- 使用 `@Slf4j`（Lombok），禁止直接用 Log4j/Logback API
+- 使用 `{}` 占位符，禁止字符串拼接
+- 异常对象作为 `log.error` 的**最后一个参数**（自动打印堆栈）
+- 日志用**中文**，用 `【模块名】` 前缀便于检索
+- 禁止记录密码、完整手机号等敏感信息
+
+## 日志级别选择
+
+| 级别 | 场景 | 示例 |
+|------|------|------|
+| ERROR | 系统错误、需立即处理 | 数据库异常、外部服务失败 |
+| WARN | 非预期但可处理 | 配置缺失用默认值、数据不存在 |
+| INFO | 关键业务节点 | 订单创建/支付成功、定时任务完成 |
+| DEBUG | 开发调试（生产不输出） | 查询参数、中间结果 |
+
+## 模块标识格式
+
+```java
+log.info("【订单】开始创建订单, userId:{}", userId);
+log.info("【支付】支付成功, orderId:{}, transactionId:{}", orderId, txId);
+log.info("【库存】扣减库存, productId:{}, quantity:{}", productId, qty);
+log.error("【远程调用】用户服务调用失败, userId:{}", userId, e);
+```
+
+MQ 消费用方括号：
+```java
+log.info("[xxx事件]MQ消费：开始");
+log.info("[xxx事件]MQ消费：消息消费完成");
+log.error("[xxx事件]MQ消费：处理异常", e);
+```
+
+## 异常日志（最重要）
+
+```java
+// ✅ 正确：异常 e 作为最后参数，保留完整堆栈
+try {
+    doProcess(orderId);
+} catch (Exception e) {
+    log.error("订单处理失败, orderId:{}", orderId, e);
+    throw new LeException("订单处理失败");
+}
+
+// ✅ 记录案发现场（关键参数 + 上下文）
+try {
+    updateStatus(orderId, status);
+} catch (Exception e) {
+    log.error("订单状态更新失败, orderId:{}, oldStatus:{}, newStatus:{}",
+              orderId, oldStatus, status, e);
+    throw new LeException("订单状态更新失败");
+}
+
+// ❌ 错误：只记录 message，丢失堆栈
+log.error("处理失败:{}", e.getMessage());
+```
+
+## 各层日志规范
+
+### Business/Service 层（关键业务）
+
+```java
+@Slf4j
+@Service
+public class OrderService {
+
+    @Transactional(rollbackFor = Exception.class)
+    public Long create(OrderParam param) {
+        log.info("【订单】开始创建订单, userId:{}, productId:{}",
+                 param.getUserId(), param.getProductId());
+        try {
+            Order order = buildOrder(param);
+            orderMapper.insert(order);
+            log.info("【订单】订单创建成功, orderId:{}", order.getId());
+            return order.getId();
+        } catch (Exception e) {
+            log.error("【订单】订单创建失败, param:{}", param, e);
+            throw new LeException("订单创建失败");
+        }
+    }
+}
+```
+
+### 定时任务
+
+```java
+@Slf4j
+@Component
+public class DataSyncJob {
+
+    @XxlJob("syncDataJob")
+    public void syncData() {
+        log.info("【定时任务】开始同步数据");
+        try {
+            int count = doSync();
+            log.info("【定时任务】数据同步完成, 同步数量:{}", count);
+        } catch (Exception e) {
+            log.error("【定时任务】数据同步失败", e);
+        }
+    }
+}
+```
+
+### MQ 消费者
+
+```java
+@Slf4j
+@MQMessageListener(group = "order-order-v3-xxx", topic = "order", tag = "order-v3-xxx")
+public class OrderMqListenerXxx implements MQListener<MqPayload<String>> {
+
+    @Override
+    public void onMessage(MqPayload<String> payload) {
+        log.info("[xxx事件]MQ消费：开始");
+        orderMqHandler.handleMessage(payload, OrderXxxPO.class, OrderMqHandler::handleXxx);
+    }
+}
+```
+
+### 外部调用
+
+```java
+public UserDTO getUserFromRemote(Long userId) {
+    log.info("【远程调用】开始调用用户服务, userId:{}", userId);
+    try {
+        UserDTO user = remoteUserService.getUser(userId);
+        log.info("【远程调用】用户服务调用成功, userId:{}", userId);
+        return user;
+    } catch (Exception e) {
+        log.error("【远程调用】用户服务调用失败, userId:{}", userId, e);
+        throw new LeException("用户信息获取失败");
+    }
+}
+```
+
+## 性能规则
+
+```java
+// ✅ debug 级别用条件判断或 Lambda（避免无用计算）
+if (log.isDebugEnabled()) {
+    log.debug("详细数据: {}", expensiveOperation());
+}
+
+// ✅ 批量操作：前后各一条，不在循环内打印
+log.info("开始处理订单, 数量:{}", orders.size());
+int success = 0, fail = 0;
+for (Order order : orders) {
+    try { process(order); success++; }
+    catch (Exception e) { log.error("订单处理失败, orderId:{}", order.getId(), e); fail++; }
+}
+log.info("订单处理完成, 成功:{}, 失败:{}", success, fail);
+
+// ✅ 只记录关键信息，不序列化大对象
+log.info("查询结果数量: {}", orders.size());  // ✅
+// log.info("查询结果: {}", orders);          // ❌ 大对象
+```
+
+## 敏感信息脱敏
+
+```java
+// ❌ 禁止记录：密码、完整手机号、身份证、银行卡
+log.info("用户登录, username:{}, password:{}", username, password);
+
+// ✅ 脱敏后记录
+log.info("发送验证码, mobile:{}", maskMobile(mobile)); // 138****1234
+```
+
+脱敏工具：详见 `references/data-mask.md`
+
+## Logback 配置
+
+配置文件：`core-starter/src/main/resources/logback-spring.xml`
+
+| Profile | 作用 |
+|---------|------|
+| `no_log_console` | 不输出到控制台 |
+| `no_log_file` | 不输出到文件 |
+
+```yaml
+# application.yml 日志级别
+logging:
+  level:
+    net.xnzn.core: INFO        # 项目
+    com.baomidou.mybatisplus: INFO
+    org.springframework: WARN
+```
+
+开发环境 `net.xnzn.core: DEBUG`，生产环境 `INFO` + `no_log_console`。
+
+## 禁止项
+
+```java
+// ❌ 直接用 Log4j API
+import org.apache.log4j.Logger;
+
+// ❌ 字符串拼接
+log.info("userId:" + userId + ", name:" + name);
+
+// ❌ 无意义日志
+log.info("进入方法");
+log.info("退出方法");
+
+// ❌ 英文日志（项目要求中文）
+log.info("Order created successfully");
+
+// ❌ 丢失异常堆栈
+log.error("失败:{}", e.getMessage());
+```
+
+## 参考文档
+
+- 详细场景示例（Controller/分页/远程调用）：详见 `references/logging-scenarios.md`
+- 脱敏工具方法：详见 `references/data-mask.md`

package/.cursor/skills/leniu-java-logging/references/data-mask.md

@@ -0,0 +1,46 @@
+# 日志脱敏工具方法
+
+```java
+public class DataMaskUtil {
+
+    /**
+     * 手机号脱敏：138****1234
+     */
+    public static String maskMobile(String mobile) {
+        if (StrUtil.isBlank(mobile) || mobile.length() != 11) {
+            return mobile;
+        }
+        return mobile.substring(0, 3) + "****" + mobile.substring(7);
+    }
+
+    /**
+     * 身份证脱敏：1234**********5678
+     */
+    public static String maskIdCard(String idCard) {
+        if (StrUtil.isBlank(idCard) || idCard.length() < 8) {
+            return idCard;
+        }
+        return idCard.substring(0, 4) + "**********" + idCard.substring(idCard.length() - 4);
+    }
+
+    /**
+     * 银行卡脱敏：6222************8888
+     */
+    public static String maskBankCard(String bankCard) {
+        if (StrUtil.isBlank(bankCard) || bankCard.length() < 8) {
+            return bankCard;
+        }
+        return bankCard.substring(0, 4) + "************" + bankCard.substring(bankCard.length() - 4);
+    }
+}
+```
+
+## 使用示例
+
+```java
+// ❌ 禁止
+log.info("发送验证码, mobile:{}, code:{}", mobile, code);
+
+// ✅ 正确
+log.info("发送验证码, mobile:{}", DataMaskUtil.maskMobile(mobile));
+```

package/.cursor/skills/leniu-java-logging/references/logging-scenarios.md

@@ -0,0 +1,113 @@
+# 日志场景详细示例
+
+## Controller 层日志
+
+```java
+@Slf4j
+@RequiresAuthentication
+@RestController
+@RequestMapping("/api/order")
+@Api(value = "订单管理", tags = "订单管理")
+public class OrderController {
+
+    @Autowired
+    private OrderService orderService;
+
+    @ApiOperation(value = "创建订单")
+    @PostMapping("/create")
+    public Long create(@Valid @RequestBody LeRequest<OrderParam> request) {
+        OrderParam param = request.getContent();
+        log.info("【订单】创建订单请求, userId:{}, productId:{}",
+                 param.getUserId(), param.getProductId());
+
+        Long orderId = orderService.create(param);
+
+        log.info("【订单】订单创建成功, orderId:{}", orderId);
+        return orderId;
+    }
+}
+```
+
+## 分页查询日志
+
+```java
+@Slf4j
+@Service
+public class OrderService {
+
+    public Page<OrderVO> pageList(OrderQueryParam param) {
+        log.info("【订单】分页查询订单, pageNum:{}, pageSize:{}, keyword:{}",
+                 param.getPage().getPageNum(),
+                 param.getPage().getPageSize(),
+                 param.getKeyword());
+
+        PageMethod.startPage(param.getPage().getPageNum(), param.getPage().getPageSize());
+        List<OrderEntity> records = orderMapper.selectList(buildWrapper(param));
+        Page<OrderVO> result = new Page<>(BeanUtil.copyToList(records, OrderVO.class));
+
+        log.info("【订单】分页查询完成, total:{}", result.getTotal());
+        return result;
+    }
+}
+```
+
+## 条件日志输出
+
+```java
+// 对于 debug/trace 级别，使用条件输出
+if (log.isDebugEnabled()) {
+    log.debug("详细数据: {}", expensiveOperation());
+}
+
+// 或使用 Lambda 形式（推荐）
+log.debug("详细数据: {}", () -> expensiveOperation());
+```
+
+## Profile 环境配置示例
+
+```yaml
+spring:
+  profiles:
+    active: dev
+
+---
+# 开发环境
+spring:
+  profiles: dev
+logging:
+  level:
+    net.xnzn.core: DEBUG
+
+---
+# 生产环境
+spring:
+  profiles: prod
+logging:
+  level:
+    net.xnzn.core: INFO
+  profiles:
+    include: no_log_console
+```
+
+## Logback 配置示例
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<configuration>
+    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
+    <include resource="org/springframework/boot/logging/logback/console-appender.xml"/>
+    <include resource="org/springframework/boot/logging/logback/file-appender.xml"/>
+
+    <springProfile name="!no_log_console">
+        <root level="INFO">
+            <appender-ref ref="CONSOLE"/>
+        </root>
+    </springProfile>
+
+    <springProfile name="!no_log_file">
+        <root level="INFO">
+            <appender-ref ref="FILE"/>
+        </root>
+    </springProfile>
+</configuration>
+```