ai-engineering-init 1.14.0 → 1.14.2

package/.codex/skills/code-patterns/SKILL.md

@@ -101,6 +101,120 @@ feat(order): 新增订单导出功能
 Closes #123
 ```
 
+## 数据类型规范
+
+### 布尔语义字段必须使用 Boolean
+
+```java
+// ❌ 错误
+private Integer ifNarrow;
+private Integer isEnabled;
+
+// ✅ 正确
+private Boolean narrow;     // getter 自动生成 isNarrow()
+private Boolean enabled;    // getter 自动生成 isEnabled()
+```
+
+**规则**：
+- 语义为"是/否"的字段，类型必须为 `Boolean`
+- 字段名不加 `if`/`is`/`has` 前缀（JavaBean 规范中 `Boolean` 的 getter 自动生成 `isXxx()`）
+- 数据库字段使用 `TINYINT(1)` 或 `BIT(1)`
+
+### 枚举字段必须提供明确约束
+
+```java
+// ❌ 错误：调用方无法知道合法值
+@ApiModelProperty(value = "操作类型")
+private Integer tradeType;
+
+// ✅ 方案一：VO/DTO 层直接用枚举（推荐）
+@ApiModelProperty(value = "操作类型")
+private AccTradeTypeEnum tradeType;
+
+// ✅ 方案二：保留 Integer 但标注合法值
+@ApiModelProperty(value = "操作类型：1-充值 2-消费 3-退款", allowableValues = "1,2,3")
+private Integer tradeType;
+```
+
+### 金额字段禁止使用浮点类型
+
+```java
+// ❌ 错误
+private Double amount;
+private Float price;
+
+// ✅ 正确：Entity/Service 层用 Long（分），VO 层展示用 BigDecimal（元）
+private Long amountFen;
+private BigDecimal amountYuan;
+```
+
+### 原始类型 vs 包装类型
+
+| 场景 | 用原始类型 | 用包装类型 |
+|------|----------|----------|
+| Entity / VO / DTO 字段 | — | ✅ 统一用包装类型 |
+| 方法参数（不允许 null） | ✅ `int count` | — |
+| 方法参数（允许 null） | — | ✅ `Integer count` |
+| 局部变量 | ✅ `int i = 0` | — |
+
+## Optional 使用规范
+
+```java
+// ❌ 错误：of() 不接受 null，value 为 null 直接 NPE
+Optional.of(value).orElse(defaultValue);
+
+// ✅ 正确：ofNullable() 安全处理 null
+Optional.ofNullable(value).orElse(defaultValue);
+
+// ❌ 禁止：Optional 作为方法参数或类字段
+public void process(Optional<String> name) { ... }
+private Optional<String> name;
+
+// ✅ 允许：Optional 作为方法返回值、链式处理
+public Optional<Entity> findById(Long id) { ... }
+Optional.ofNullable(entity).map(Entity::getConfig).orElse(DEFAULT_VALUE);
+```
+
+## @Transactional 规范
+
+```java
+// ❌ 错误：默认只回滚 RuntimeException
+@Transactional
+public void createOrder() { ... }
+
+// ✅ 正确：显式指定回滚异常
+@Transactional(rollbackFor = Exception.class)
+public void createOrder() { ... }
+```
+
+- 所有 `@Transactional` 必须显式写 `rollbackFor = Exception.class`
+- 只读查询不加 `@Transactional`（或用 `readOnly = true`）
+- 事务方法不要 try-catch 吞掉异常，否则事务不回滚
+
+## TODO 管理规范
+
+```java
+// ❌ 错误：无负责人、无日期、无跟踪
+// TODO 修改一下
+
+// ✅ 正确：完整 TODO 格式
+// TODO(@陈沈杰, 2026-03-20, #TASK-1234): 移动端 AppId 赋值逻辑待产品确认
+```
+
+- 每个 TODO 必须有对应的任务号
+- 超过 2 个迭代未处理的 TODO 必须清理
+- 不用的代码直接删除，不要注释保留
+
+## 代码格式化规范
+
+| 项目 | 规范 |
+|------|------|
+| 缩进 | 4 个空格（不用 Tab） |
+| 行宽 | 120 字符 |
+| 大括号 | K&R 风格（同行开始） |
+| 空行 | 方法间 1 个空行，逻辑块间 1 个空行 |
+| import | 分组排序：java → jakarta → org → net → com，组间空行 |
+
 ## 代码示例
 
 ### 统一响应格式
@@ -161,3 +275,8 @@ public enum OrderStatusEnum {
 | Git 提交信息写"fix bug" | 写清楚修了什么：`fix(order): 修复金额计算精度丢失` |
 | Boolean 变量名：`flag` | 有意义的名字：`isActive`, `hasPermission` |
 | 缩写命名：`usr`, `mgr` | 完整命名：`user`, `manager` |
+| `Optional.of(可能null值)` | `Optional.ofNullable(value)` |
+| `@Transactional` 无 rollbackFor | `@Transactional(rollbackFor = Exception.class)` |
+| TODO 无负责人和日期 | `// TODO(@负责人, 日期, #任务号): 描述` |
+| 布尔字段用 `Integer` | 用 `Boolean` 类型 |
+| 枚举字段无合法值说明 | `@ApiModelProperty` 标注合法值或直接用枚举类型 |

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

@@ -394,9 +394,186 @@ 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. **使用参数化查询**：`#{}` 而非 `${}`

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

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

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

@@ -22,7 +22,7 @@ description: |
 | XML 位置 | **与 Mapper 接口同目录**（非 `resources/mapper/`） |
 | 分页 | PageHelper → `PageMethod.startPage(PageDTO)` → `PageVO.of(list)` |
 | 逻辑删除 | **1=删除，2=正常**（与 RuoYi 相反） |
-| Service | 无接口，直接 `@Service` 类，Mapper 字段名统一用 `baseMapper` |
+| Service | **两种模式并存**：简单 CRUD 继承 `ServiceImpl`（`this.baseMapper`）；业务聚合直接 `@Service`（`@Autowired XxxMapper xxxMapper`） |
 | 循环依赖 | 跨模块依赖用 `@Autowired @Lazy` |
 
 ## Mapper 接口模板
@@ -147,28 +147,36 @@ List<XxxEntity> list = mapper.selectList(
 
 ## Service 注入规范
 
+项目中 Service 有两种模式，Mapper 字段名也不统一——参考周围已有代码的风格即可。
+
+**模式 A：继承 ServiceImpl（简单 CRUD）**
+```java
+@Service
+public class XxxServiceImpl extends ServiceImpl<XxxMapper, XxxEntity> implements XxxService {
+    // 通过 this.baseMapper 访问 Mapper（父类自动注入）
+    public boolean exists(String macOrderId) {
+        return this.baseMapper.existsOne(
+            Wrappers.lambdaQuery(XxxEntity.class)
+                .eq(XxxEntity::getMacOrderId, macOrderId)
+                .eq(XxxEntity::getDelFlag, 2)
+        );
+    }
+}
+```
+
+**模式 B：直接 @Service（业务聚合）**
 ```java
 @Slf4j
 @Service
-@Validated
 public class XxxService {
-
     @Autowired
-    private XxxMapper baseMapper;        // ✅ 统一命名 baseMapper
+    private XxxMapper xxxMapper;  // 字段名跟随 Mapper 类名
 
     @Autowired @Lazy
-    private XxxDetailService xxxDetailService;  // ✅ 跨模块用 @Lazy
+    private YyyService yyyService;  // 跨模块用 @Lazy
 
     public XxxEntity getOne(Long id) {
-        return baseMapper.selectById(id);
-    }
-
-    public boolean exists(String macOrderId) {
-        return baseMapper.existsOne(
-            Wrappers.lambdaQuery(XxxEntity.class)
-                .eq(XxxEntity::getMacOrderId, macOrderId)
-                .eq(XxxEntity::getDelFlag, 2)
-        );
+        return xxxMapper.selectById(id);
     }
 }
 ```
@@ -250,8 +258,9 @@ wrapper.eq(XxxEntity::getDelFlag, 0);
 // ❌ MapstructUtils（用 BeanUtil.copyProperties）
 MapstructUtils.convert(source, Target.class);
 
-// ❌ Service 继承 IService / ServiceImpl
-public interface IXxxService extends IService<XxxEntity> {}
+// ❌ 业务聚合 Service 不要继承 IService / ServiceImpl（简单 CRUD Service 可以继承）
+// 错误：在报表/业务编排 Service 中继承 ServiceImpl
+// 正确：简单单表 CRUD 可以继承 ServiceImpl，复杂业务直接 @Service
 ```
 
 ## XML 文件位置