ai-engineering-init 1.16.2 → 1.16.4

package/.cursor/skills/leniu-code-patterns/SKILL.md

@@ -394,187 +394,10 @@ public class OrderService {
 }
 ```
 
-## 数据类型规范
-
-### 布尔字段命名
-
-```java
-// ❌ 错误：前缀冗余、类型错误
-private Integer ifNarrow;
-private Integer isEnabled;
-
-// ✅ 正确：Boolean 类型，无前缀
-private Boolean narrow;     // getter → isNarrow()
-private Boolean enabled;    // getter → isEnabled()
-```
-
-### 枚举字段标注
-
-```java
-// ❌ 错误：只靠注释 @see
-/** @see AccTradeTypeEnum */
-private Integer tradeType;
-
-// ✅ 方案一：VO/DTO 用枚举类型（配合 @JsonValue）
-private AccTradeTypeEnum tradeType;
-
-// ✅ 方案二：@ApiModelProperty 标注合法值
-@ApiModelProperty(value = "操作类型：1-充值 2-消费 3-退款", allowableValues = "1,2,3")
-private Integer tradeType;
-```
-
-## MyBatis-Plus 安全规范
-
-### selectOne 必须有唯一保障
-
-```java
-// ❌ 危险：多条记录时抛 TooManyResultsException
-Entity entity = mapper.selectOne(wrapper);
-
-// ✅ 方案一：LIMIT 1
-Entity entity = mapper.selectOne(wrapper.last("LIMIT 1"));
-
-// ✅ 方案二：selectList 取第一条
-List<Entity> list = mapper.selectList(wrapper);
-Entity entity = CollUtil.isNotEmpty(list) ? list.get(0) : null;
-
-// ✅ 方案三：确保有唯一索引（注释说明）
-// 唯一索引：UNIQUE KEY (order_no, del_flag)
-Entity entity = mapper.selectOne(wrapper);
-```
-
-### 存在性判断用 EXISTS，禁用 selectCount
-
-```java
-// ❌ 低效：100万行表 ~200ms
-Long count = mapper.selectCount(wrapper);
-if (count > 0) { ... }
-
-// ✅ 高效：~2ms（MyBatis-Plus 3.5.4+）
-boolean exists = mapper.exists(wrapper);
-
-// ✅ 或 selectList + LIMIT 1
-boolean exists = CollUtil.isNotEmpty(mapper.selectList(wrapper.last("LIMIT 1")));
-```
-
-### Wrapper 嵌套不超过 2 层
-
-```java
-// ❌ 过于复杂的 Wrapper
-wrapper.and(w -> w.eq(A::getType, type)
-    .or(q -> q.eq(A::getType, 0))
-    .or(!PersonTypeEnum.LABOUR.getKey().equals(type),
-        q -> q.eq(A::getType, PSN_TYPE_SHARED)));
-
-// ✅ 复杂查询写到 XML 中
-List<Entity> list = mapper.selectByTypeCondition(type, isLabour);
-```
-
-### 禁止 SELECT *
-
-```xml
-<!-- ❌ 禁止 -->
-<select id="selectAll">SELECT * FROM t_order WHERE del_flag = 2</select>
-
-<!-- ✅ 明确列出字段 -->
-<select id="selectAll">SELECT id, order_no, amount, status, crtime FROM t_order WHERE del_flag = 2</select>
-```
-
-## Redis 使用规范
-
-### 禁止 KEYS 命令
-
-```java
-// ❌ 严禁：KEYS 阻塞 Redis
-Set<Object> keys = keysByPattern(pattern);
-Set<Object> keys = redisTemplate.keys(pattern);
-
-// ✅ 使用 Redisson deleteByPattern（内部 SCAN + UNLINK）
-RedissonClient redisson = SpringUtil.getBean(RedissonClient.class);
-redisson.getKeys().deleteByPattern(keyPattern);
-```
-
-## Optional 使用规范
-
-```java
-// ❌ 错误：of() 不接受 null
-Optional.of(value).orElse(defaultValue);
-
-// ✅ 正确：ofNullable()
-Optional.ofNullable(value).orElse(defaultValue);
-
-// ✅ 链式安全转换
-Optional.ofNullable(model.getReserveRate())
-    .map(BigDecimal::new)
-    .orElse(BigDecimal.ZERO);
-
-// ❌ 禁止作为方法参数或类字段
-// ✅ 允许作为方法返回值
-```
-
-## @Transactional 规范
-
-```java
-// ❌ 默认只回滚 RuntimeException
-@Transactional
-public void createOrder() { ... }
-
-// ✅ 显式指定 rollbackFor
-@Transactional(rollbackFor = Exception.class)
-public void createOrder() { ... }
-```
-
-- 事务方法不要 try-catch 吞掉异常
-- 只读查询不加 `@Transactional`
-
-## 业务逻辑分层规范
-
-```java
-// ❌ 错误：业务判断混在数据操作中
-public void processOrder(Long orderId) {
-    OrderInfo order = orderMapper.selectById(orderId);
-    if (order.getStatus() == 1 && order.getPayTime() != null
-        && ChronoUnit.HOURS.between(order.getPayTime(), LocalDateTime.now()) < 24) {
-        order.setStatus(2);
-        orderMapper.updateById(order);
-        accWalletService.deduct(order.getCustId(), order.getAmount());
-    }
-}
-
-// ✅ 正确：分层清晰
-public void processOrder(Long orderId) {
-    OrderInfo order = orderMapper.selectById(orderId);
-    if (ObjectUtil.isNull(order)) {
-        throw new LeException(I18n.getMessage("order_not_found"));
-    }
-    checkCanProcess(order);           // 业务校验（独立方法）
-    order.markAsProcessed();          // 状态变更（Entity 方法封装）
-    orderMapper.updateById(order);
-    afterOrderProcessed(order);       // 后续动作（独立方法）
-}
-```
-
-| 层 | 职责 | 不应做的 |
-|----|------|---------|
-| Controller | 参数接收、格式转换 | 不含业务判断 |
-| Business | 业务编排、跨 Service 协调 | 不直接操作 Mapper |
-| Service | 单表 CRUD、单表事务 | 不含跨表业务逻辑 |
-| Mapper | SQL 映射 | 不含业务逻辑 |
-
-## TODO 管理规范
-
-```java
-// ❌ 错误
-// TODO 修改一下
-
-// ✅ 正确
-// TODO(@陈沈杰, 2026-03-20, #TASK-1234): 移动端 AppId 赋值逻辑待产品确认
-```
-
-- 不用的代码直接删除，不要注释保留
-
 ## 通用代码规范
 
+无论使用哪种项目架构，以下规范都是通用的：
+
 1. **禁止使用 `SELECT *`**：明确指定字段
 2. **使用参数化查询**：`#{}` 而非 `${}`
 3. **异常必须处理**：不能吞掉异常

package/.cursor/skills/leniu-crud-development/SKILL.md

@@ -39,7 +39,6 @@ description: |
 | 架构 | Controller -> Business -> Service -> Mapper（四层） |
 | 无 DAO 层 | Service 直接注入 Mapper |
 | 对象转换 | `BeanUtil.copyProperties()` (Hutool) |
-| Service 模式 | **两种并存**：简单 CRUD 继承 `ServiceImpl`；业务聚合直接 `@Service` |
 | Entity 基类 | 无基类，自定义审计字段 |
 | 请求封装 | `LeRequest<T>` |
 | 响应封装 | `Page<T>` / `LeResponse<T>` / `void` |
@@ -111,38 +110,19 @@ private LocalDateTime uptime;
 private Integer delFlag;  // 1=删除, 2=正常
 ```
 
-### Service 两种模式
+### Service 注入模式
 
-项目中存在两种 Service 模式，根据业务复杂度选择：
-
-**模式 A：简单 CRUD Service**（适用于单表操作，利用 MyBatis-Plus 内置方法）
-```java
-// 接口
-public interface XxxService extends IService<XxxEntity> { }
-
-// 实现
-@Slf4j
-@Service
-public class XxxServiceImpl extends ServiceImpl<XxxMapper, XxxEntity> implements XxxService {
-    // 继承 ServiceImpl 获得 save/updateById/removeById/page 等内置方法
-    // 通过 this.baseMapper 访问 Mapper（父类提供）
-}
-```
-
-**模式 B：业务聚合 Service**（适用于跨表操作、复杂业务编排）
 ```java
 @Slf4j
 @Service
-public class XxxService {
-    @Autowired
+public class XxxServiceImpl implements XxxService {
+    @Resource
     private XxxMapper xxxMapper;  // 直接注入 Mapper，无 DAO 层
-    @Autowired
-    private YyyMapper yyyMapper;  // 可注入多个 Mapper
+
+    // 不继承 ServiceImpl，只实现接口
 }
 ```
 
-**选择建议**：新建简单单表 CRUD 用模式 A；涉及多表联查、报表、业务编排用模式 B。
-
 ### Controller 请求封装
 
 ```java
@@ -386,6 +366,7 @@ private String createBy;                  // -> crby
 entity.setDelFlag(0);                     // -> setDelFlag(2) 表示正常
 throw new ServiceException("...");        // -> throw new LeException("...")
 MapstructUtils.convert(src, Dst.class);   // -> BeanUtil.copyProperties(src, Dst.class)
+extends ServiceImpl<XxxMapper, Xxx>       // -> implements XxxService（不继承）
 @Resource private XxxDao xxxDao;          // -> @Resource private XxxMapper xxxMapper
 // XML 放 resources/mapper/              // -> 与 Java 同目录
 return null;                              // -> return Collections.emptyList()
@@ -396,7 +377,7 @@ return null;                              // -> return Collections.emptyList()
 ## 生成前检查清单
 
 - [ ] 包名 `net.xnzn.core.*`
-- [ ] Service 模式选择：简单 CRUD 用模式 A（继承 ServiceImpl）；业务聚合用模式 B（直接 @Service）
+- [ ] Service 只实现接口，不继承基类
 - [ ] Service 直接注入 Mapper（无 DAO）
 - [ ] 审计字段 crby/crtime/upby/uptime
 - [ ] delFlag: 1=删除, 2=正常

package/.cursor/skills/leniu-java-amount-handling/SKILL.md

@@ -0,0 +1,461 @@
+---
+name: leniu-java-amount-handling
+description: |
+  leniu-tengyun-core 项目金额处理规范。金融系统中金额以分（Long 类型）存储，展示时转换为元。
+
+  触发场景：
+  - VO/Entity 类含金额字段（amountFen/amountYuan）
+  - MyBatis XML 查询含金额字段
+  - Excel 导出含金额列，需分转元
+  - 报表合计查询含金额汇总
+
+  触发词：金额处理、分转元、元转分、Long金额、money、fen、BigDecimal金额、金额字段
+---
+
+# leniu-tengyun-core 金额处理规范
+
+## 两种金额存储模式
+
+项目中存在两种金额存储模式，根据业务模块选择：
+
+### 模式 A：Long（分）→ BigDecimal（元）[钱包/账户模块]
+
+适用于余额、充值、补贴等精度要求高的模块：
+
+- **数据库**：存储为 Long（分）
+- **Entity**：使用 Long 类型
+- **VO**：使用 BigDecimal 类型（MyBatis 自动转换分→元）
+- **Excel 导出**：使用 `CustomNumberConverter` 转换器
+
+### 模式 B：BigDecimal（分）[订单/报表模块]
+
+适用于订单金额、报表汇总等复杂计算模块：
+
+- **数据库**：存储为 BigDecimal（值为分，如 10000 = 100.00元）
+- **Entity**：直接使用 BigDecimal 类型（以分为单位）
+- **VO**：同样使用 BigDecimal（字段注释需标注单位）
+- **SQL SUM**：直接 `SUM(amount)`，不需要 /100
+
+> 参考：`OrderInfo.payableAmount`（BigDecimal，以分为单位）
+
+## 金额类型速查
+
+| 类型 | 用途 | 示例 |
+|------|------|------|
+| `Long` | 钱包/账户存储（分） | `private Long orderAmount; // 10000 = 100.00元` |
+| `BigDecimal` | 订单/报表存储（分） | `private BigDecimal payableAmount; // 10000 = 100.00元` |
+| `BigDecimal` | VO 展示（元，模式A） | `private BigDecimal amount; // 100.00` |
+
+## Entity（模式A：Long存储）
+
+```java
+import com.baomidou.mybatisplus.annotation.*;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import lombok.Data;
+
+@Data
+@TableName(value = "wallet_table", autoResultMap = true)
+public class WalletEntity {
+
+    @TableId
+    @ApiModelProperty(value = "钱包ID")
+    private Long id;
+
+    @ApiModelProperty(value = "余额（分）")
+    private Long balance;
+
+    @ApiModelProperty(value = "充值金额（分）")
+    private Long rechargeAmount;
+}
+```
+
+**要点**：
+- Entity 使用 `Long` 类型存储金额（分）
+- 字段注释明确标注"（分）"
+
+## Entity（模式B：BigDecimal存储，适用订单模块）
+
+```java
+@Data
+@TableName("order_info")
+public class OrderInfo {
+
+    @ApiModelProperty(value = "应付金额（分）")
+    private BigDecimal payableAmount;
+
+    @ApiModelProperty(value = "实付金额（分）")
+    private BigDecimal realAmount;
+
+    @ApiModelProperty(value = "优惠金额（分）")
+    private BigDecimal discountsAmount;
+}
+```
+
+**要点**：
+- 字段类型为 BigDecimal，但值以分为单位存储
+- 不需要 MyBatis 类型转换
+
+## VO（响应层）
+
+```java
+import com.alibaba.excel.annotation.ExcelProperty;
+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;
+
+@Data
+@Accessors(chain = true)
+@ApiModel("订单信息")
+public class OrderVO {
+
+    @ApiModelProperty("订单ID")
+    private Long id;
+
+    @ApiModelProperty("订单金额（元）")
+    @ExcelProperty(value = "订单金额（元）", converter = CustomNumberConverter.class)
+    private BigDecimal orderAmount;
+
+    @ApiModelProperty("优惠金额（元）")
+    @ExcelProperty(value = "优惠金额（元）", converter = CustomNumberConverter.class)
+    private BigDecimal discountAmount;
+
+    @ApiModelProperty("实付金额（元）")
+    @ExcelProperty(value = "实付金额（元）", converter = CustomNumberConverter.class)
+    private BigDecimal payAmount;
+}
+```
+
+**要点**：
+- VO 使用 `BigDecimal` 类型（元）
+- Excel 导出必须使用 `converter = CustomNumberConverter.class`
+- MyBatis 会自动将 Long 分转换为 BigDecimal 元
+
+## MyBatis XML 查询
+
+### 列表查询
+
+```xml
+<select id="listOrders" resultType="OrderVO">
+    SELECT
+        order_id,
+        order_amount,      -- ❌ 不要 /100.0
+        discount_amount,    -- ❌ 不要 /100.0
+        pay_amount          -- ❌ 不要 /100.0
+    FROM order_table
+    <where>...</where>
+    ORDER BY crtime DESC
+</select>
+```
+
+### 合计查询
+
+```xml
+<select id="getOrderTotal" resultType="OrderVO">
+    SELECT
+        SUM(order_amount) AS order_amount,    -- ❌ 不要 /100.0
+        SUM(discount_amount) AS discount_amount,-- ❌ 不要 /100.0
+        SUM(pay_amount) AS pay_amount       -- ❌ 不要 /100.0
+    FROM order_table
+    <where>...</where>
+</select>
+```
+
+**重要**：
+- 永远不要在 SQL 中使用 `/100.0`
+- 合计查询只返回数值字段，不返回非数值字段（如日期、名称）
+
+## 金额工具类
+
+### AmountUtil（分转元）
+
+```java
+import java.math.BigDecimal;
+import java.math.RoundingMode;
+
+/**
+ * 分与元金额转换
+ */
+public class AmountUtil {
+
+    /**
+     * 分转元（String）
+     */
+    public static String fen2YuanStr(Integer fen) {
+        if (fen == null) {
+            return "0.00";
+        }
+        BigDecimal amountFen = new BigDecimal(fen);
+        BigDecimal amountYuan = amountFen.divide(new BigDecimal("100"), 2, RoundingMode.HALF_UP);
+        return amountYuan.toPlainString();
+    }
+
+    /**
+     * 分转元（String 重载）
+     */
+    public static String fen2YuanStr(String fen) {
+        if (fen == null || fen.isEmpty()) {
+            return "0.00";
+        }
+        BigDecimal amountFen = new BigDecimal(fen);
+        BigDecimal amountYuan = amountFen.divide(new BigDecimal("100"), 2, RoundingMode.HALF_UP);
+        return amountYuan.toPlainString();
+    }
+
+    /**
+     * 分转元（BigDecimal）
+     */
+    public static BigDecimal fen2Yuan(Integer fen) {
+        if (fen == null) {
+            return BigDecimal.ZERO;
+        }
+        BigDecimal amountFen = new BigDecimal(fen);
+        return amountFen.divide(new BigDecimal("100"), 2, RoundingMode.HALF_UP);
+    }
+
+    /**
+     * 分转元（Long）
+     */
+    public static BigDecimal fen2Yuan(Long fen) {
+        if (fen == null) {
+            return BigDecimal.ZERO;
+        }
+        BigDecimal amountFen = new BigDecimal(fen);
+        return amountFen.divide(new BigDecimal("100"), 2, RoundingMode.HALF_UP);
+    }
+
+    /**
+     * 元转分
+     */
+    public static Integer yuan2Fen(String yuan) {
+        if (yuan == null || yuan.isEmpty()) {
+            return 0;
+        }
+        BigDecimal balance = new BigDecimal(yuan);
+        return Integer.parseInt(balance.multiply(new BigDecimal("100"))
+                                         .setScale(0, RoundingMode.HALF_UP)
+                                         .toPlainString());
+    }
+
+    /**
+     * 元转分（BigDecimal）
+     */
+    public static Integer yuan2Fen(BigDecimal yuan) {
+        if (yuan == null) {
+            return 0;
+        }
+        return yuan.multiply(new BigDecimal("100"))
+                  .setScale(0, RoundingMode.HALF_UP)
+                  .intValue();
+    }
+}
+```
+
+### 使用示例
+
+```java
+// 分转元
+Integer fenAmount = 10000;  // 10000分
+BigDecimal yuanAmount = AmountUtil.fen2Yuan(fenAmount);  // 100.00元
+
+// 元转分
+BigDecimal yuan = new BigDecimal("99.99");
+Integer fenAmount = AmountUtil.yuan2Fen(yuan);  // 9999分
+```
+
+## 常见场景
+
+### 场景1：订单报表 VO
+
+```java
+@Data
+@Accessors(chain = true)
+@ApiModel("订单报表")
+public class OrderReportVO {
+
+    @ExcelProperty(value = "月度", order = 1)
+    @ApiModelProperty("月度")
+    private String dateMonth;
+
+    @ExcelProperty(value = "订单总额（元）", order = 2, converter = CustomNumberConverter.class)
+    @ApiModelProperty("订单总额（元）")
+    private BigDecimal totalAmount;
+
+    @ExcelProperty(value = "订单数量", order = 3)
+    @ApiModelProperty("订单数量")
+    private Integer totalCount;
+
+    @ExcelProperty(value = "平均金额（元）", order = 4, converter = CustomNumberConverter.class)
+    @ApiModelProperty("平均金额（元）")
+    private BigDecimal avgAmount;
+}
+```
+
+### 场景2：工资汇总 VO
+
+```java
+@Data
+@Accessors(chain = true)
+@ApiModel("工资汇总")
+public class SalarySummaryVO {
+
+    @ExcelProperty(value = "月度", order = 1)
+    @ApiModelProperty("月度")
+    private String dateMonth;
+
+    @ExcelProperty(value = "基本工资（元）", order = 2, converter = CustomNumberConverter.class)
+    @ApiModelProperty("基本工资（元）")
+    private BigDecimal basicSalary;
+
+    @ExcelProperty(value = "绩效工资（元）", order = 3, converter = CustomNumberConverter.class)
+    @ApiModelProperty("绩效工资（元）")
+    private BigDecimal performanceSalary;
+
+    @ExcelProperty(value = "应发工资（元）", order = 4, converter = CustomNumberConverter.class)
+    @ApiModelProperty("应发工资（元）")
+    private BigDecimal totalSalary;
+}
+```
+
+### 场景3：合计行 SQL
+
+```xml
+<!-- 列表查询 -->
+<select id="pageSalary" resultType="SalarySummaryVO">
+    SELECT
+        date_month,
+        staff_count,
+        basic_salary,
+        performance_salary,
+        total_salary
+    FROM salary_summary
+    <where>...</where>
+    ORDER BY date_month DESC
+</select>
+
+<!-- 合计查询：只返回数值字段 -->
+<select id="getSalaryTotal" resultType="SalarySummaryVO">
+    SELECT
+        SUM(staff_count) AS staff_count,
+        SUM(basic_salary) AS basic_salary,
+        SUM(performance_salary) AS performance_salary,
+        SUM(total_salary) AS total_salary
+    FROM salary_summary
+    <where>...</where>
+</select>
+```
+
+### 场景4：平均值计算
+
+```xml
+<!-- 平均值计算（除零处理） -->
+CASE
+    WHEN SUM(staff_count) = 0 THEN 0
+    ELSE SUM(total_salary) / SUM(staff_count)
+END AS avgSalary
+
+<!-- 按维度平均 -->
+CASE
+    WHEN SUM(staff_count) = 0 THEN 0
+    ELSE SUM(total_salary) / COUNT(DISTINCT tenant_id)
+END AS avgSalary
+```
+
+## 数据流
+
+```
+数据库（Long/分） → MyBatis → VO（BigDecimal/元） → 前端（自动 /100）
+                                               ↓
+                                          Excel（converter /100）
+```
+
+## Excel 导出
+
+### 转换器
+
+```java
+@ExcelProperty(value = "订单金额（元）", converter = CustomNumberConverter.class)
+private BigDecimal orderAmount;
+```
+
+### 必要的导入
+
+```java
+import com.alibaba.excel.annotation.ExcelProperty;
+import net.xnzn.core.common.export.converter.CustomNumberConverter;
+```
+
+## 常见错误
+
+### 错误1：在 SQL 中使用 /100.0
+
+```xml
+<!-- ❌ 错误：在 SQL 中除以 100 -->
+SELECT
+    order_amount / 100.0 AS order_amount
+FROM order_table
+
+<!-- ✅ 正确：不进行除法，MyBatis 自动转换 -->
+SELECT
+    order_amount AS order_amount
+FROM order_table
+```
+
+### 错误2：钱包模块 Entity 使用 BigDecimal（模式A适用）
+
+```java
+// ❌ 错误：钱包/账户模块 Entity 使用 BigDecimal（应用 Long）
+@Data
+public class WalletEntity {
+    @ApiModelProperty("余额（元）")
+    private BigDecimal balance;
+}
+
+// ✅ 正确：钱包/账户模块 Entity 使用 Long（分）
+@Data
+public class WalletEntity {
+    @ApiModelProperty("余额（分）")
+    private Long balance;
+}
+```
+
+> **注意**：订单模块（OrderInfo）使用 BigDecimal 存储金额（以分为单位），这是模式B，属于正确用法，不是错误。
+
+### 错误3：VO 不使用转换器
+
+```java
+// ❌ 错误：Excel 导出不使用转换器
+@ExcelProperty(value = "订单金额（元）")
+private BigDecimal orderAmount;
+
+// ✅ 正确：使用 CustomNumberConverter
+@ExcelProperty(value = "订单金额（元）", converter = CustomNumberConverter.class)
+private BigDecimal orderAmount;
+```
+
+### 错误4：合计查询返回非数值字段
+
+```xml
+<!-- ❌ 错误：合计查询返回非数值字段 -->
+<select id="getOrderTotal" resultType="OrderVO">
+    SELECT
+        SUM(order_amount) AS order_amount,
+        order_date           -- ❌ 非数值字段
+    FROM order_table
+</select>
+
+<!-- ✅ 正确：只返回数值字段 -->
+<select id="getOrderTotal" resultType="OrderVO">
+    SELECT
+        SUM(order_amount) AS order_amount
+    FROM order_table
+</select>
+```
+
+## 参考文档
+
+详见：[leniu-tengyun-core 源码](/Users/xujiajun/Developer/gongsi_proj/core/leniu-tengyun-core)