ai-engineering-init 1.3.4 → 1.4.0

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

@@ -1,7 +1,7 @@
 ---
 name: crud-development
 description: |
-  后端 CRUD 开发规范。基于 RuoYi-Vue-Plus 三层架构（Controller → Service → Mapper），无独立 DAO 层。
+  后端 CRUD 开发规范。基于 RuoYi-Vue-Plus 三层架构（Controller -> Service -> Mapper），无独立 DAO 层。
 
   触发场景：
   - 新建业务模块的 CRUD 功能
@@ -12,34 +12,30 @@ description: |
   触发词：CRUD、增删改查、新建模块、Entity、BO、VO、Service、Mapper、Controller、分页查询、buildQueryWrapper、@AutoMapper、BaseMapperPlus、TenantEntity
 
   注意：
-  - 本项目是三层架构，Service 直接注入 Mapper，无 DAO 层。
+  - 三层架构，Service 直接注入 Mapper，无 DAO 层。
   - 查询条件在 Service 层构建（buildQueryWrapper）。
   - 使用 @AutoMapper（单数）而非 @AutoMappers。
   - API 路径使用标准 RESTful 格式（/list、/{id}）。
 ---
 
-# CRUD 全栈开发规范（RuoYi-Vue-Plus 三层架构版）
-
-> **⚠️ 重要声明**: 本项目是 **RuoYi-Vue-Plus 纯后端项目**，采用三层架构！
-> 不同于其他四层架构项目，本项目 **无独立 DAO 层**，Service 直接调用 Mapper。
+# CRUD 开发规范（RuoYi-Vue-Plus 三层架构）
 
 ## 核心架构特征
 
-| 对比项 | 本项目 (RuoYi-Vue-Plus) |
-|--------|----------------------|
+| 项 | 规范 |
+|----|------|
 | **包名前缀** | `org.dromara.*` |
-| **架构** | 三层：Controller → Service → Mapper |
-| **DAO 层** | ❌ 不存在，Service 直接注入 Mapper |
+| **架构** | Controller -> Service -> Mapper（无 DAO 层） |
 | **查询构建** | Service 层 `buildQueryWrapper()` |
-| **Mapper 继承** | `BaseMapperPlus<Entity, VO>` |
+| **Mapper** | 继承 `BaseMapperPlus<Entity, VO>` |
 | **对象转换** | `MapstructUtils.convert()` |
 | **Entity 基类** | `TenantEntity`（多租户） |
-| **BO 映射** | `@AutoMapper` 注解（单数） |
-| **API 路径** | 标准 RESTful：`/list`、`/{id}` |
+| **BO 映射** | `@AutoMapper`（单数） |
+| **API 路径** | RESTful：`/list`、`/{id}` |
 
 ---
 
-## 1. Entity 实体类（继承 TenantEntity）
+## 1. Entity
 
 ```java
 package org.dromara.demo.domain;
@@ -50,97 +46,62 @@ import lombok.Data;
 import lombok.EqualsAndHashCode;
 import java.io.Serial;
 
-/**
- * XXX 对象
- *
- * @author Lion Li
- */
 @Data
 @EqualsAndHashCode(callSuper = true)
 @TableName("test_xxx")
-public class Xxx extends TenantEntity {  // ✅ 继承 TenantEntity（多租户）
+public class Xxx extends TenantEntity {
 
     @Serial
     private static final long serialVersionUID = 1L;
 
-    /**
-     * 主键 ID
-     */
     @TableId(value = "id")
     private Long id;
 
-    /**
-     * 名称
-     */
     private String xxxName;
 
-    /**
-     * 状态（0正常 1停用）
-     */
     private String status;
 
-    /**
-     * 删除标志
-     */
     @TableLogic
     private Long delFlag;
 }
 ```
 
----
-
-## 2. BO 业务对象（@AutoMapper 映射）
+## 2. BO
 
 ```java
 package org.dromara.demo.domain.bo;
 
 import io.github.linpeilie.annotations.AutoMapper;
 import org.dromara.demo.domain.Xxx;
-import org.dromara.demo.domain.vo.XxxVo;
 import org.dromara.common.core.validate.AddGroup;
 import org.dromara.common.core.validate.EditGroup;
+import org.dromara.common.mybatis.core.domain.BaseEntity;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
-import org.dromara.common.mybatis.core.domain.BaseEntity;
 import jakarta.validation.constraints.*;
 
-/**
- * XXX 业务对象
- */
 @Data
 @EqualsAndHashCode(callSuper = true)
-@AutoMapper(target = Xxx.class, reverseConvertGenerate = false)  // ✅ 映射到 Entity
+@AutoMapper(target = Xxx.class, reverseConvertGenerate = false)
 public class XxxBo extends BaseEntity {
 
-    /**
-     * 主键 ID
-     */
-    @NotNull(message = "主键 ID 不能为空", groups = {EditGroup.class})
+    @NotNull(message = "主键不能为空", groups = {EditGroup.class})
     private Long id;
 
-    /**
-     * 名称
-     */
     @NotBlank(message = "名称不能为空", groups = {AddGroup.class, EditGroup.class})
     private String xxxName;
 
-    /**
-     * 状态
-     */
     private String status;
 }
 ```
 
----
-
-## 3. VO 视图对象（@AutoMapper 映射）
+## 3. VO
 
 ```java
 package org.dromara.demo.domain.vo;
 
 import io.github.linpeilie.annotations.AutoMapper;
 import org.dromara.demo.domain.Xxx;
-import org.dromara.demo.domain.bo.XxxBo;
 import cn.idev.excel.annotation.ExcelIgnoreUnannotated;
 import cn.idev.excel.annotation.ExcelProperty;
 import lombok.Data;
@@ -148,45 +109,28 @@ import java.io.Serial;
 import java.io.Serializable;
 import java.util.Date;
 
-/**
- * XXX 视图对象
- */
 @Data
 @ExcelIgnoreUnannotated
-@AutoMapper(target = Xxx.class)  // ✅ VO 也使用 @AutoMapper
+@AutoMapper(target = Xxx.class)
 public class XxxVo implements Serializable {
 
     @Serial
     private static final long serialVersionUID = 1L;
 
-    /**
-     * 主键 ID
-     */
-    @ExcelProperty(value = "主键 ID")
+    @ExcelProperty(value = "主键")
     private Long id;
 
-    /**
-     * 名称
-     */
     @ExcelProperty(value = "名称")
     private String xxxName;
 
-    /**
-     * 状态
-     */
     @ExcelProperty(value = "状态")
     private String status;
 
-    /**
-     * 创建时间
-     */
     @ExcelProperty(value = "创建时间")
     private Date createTime;
 }
 ```
 
----
-
 ## 4. Service 接口
 
 ```java
@@ -199,46 +143,17 @@ import org.dromara.common.mybatis.core.page.TableDataInfo;
 import java.util.Collection;
 import java.util.List;
 
-/**
- * XXX 服务接口
- */
 public interface IXxxService {
-
-    /**
-     * 根据 ID 查询
-     */
     XxxVo queryById(Long id);
-
-    /**
-     * 查询列表
-     */
     List<XxxVo> queryList(XxxBo bo);
-
-    /**
-     * 分页查询
-     */
     TableDataInfo<XxxVo> queryPageList(XxxBo bo, PageQuery pageQuery);
-
-    /**
-     * 新增
-     */
     Boolean insertByBo(XxxBo bo);
-
-    /**
-     * 修改
-     */
     Boolean updateByBo(XxxBo bo);
-
-    /**
-     * 删除
-     */
     Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);
 }
 ```
 
----
-
-## 5. Service 实现类（⭐ 核心：三层架构，NO DAO 层）
+## 5. Service 实现（核心）
 
 ```java
 package org.dromara.demo.service.impl;
@@ -262,16 +177,11 @@ import java.util.Collection;
 import java.util.List;
 import java.util.Map;
 
-/**
- * XXX 服务实现
- *
- * @author Lion Li
- */
 @Service
 @RequiredArgsConstructor
 public class XxxServiceImpl implements IXxxService {
 
-    private final XxxMapper baseMapper;  // ✅ 直接注入 Mapper（NO DAO!）
+    private final XxxMapper baseMapper;  // 直接注入 Mapper（无 DAO 层）
 
     @Override
     public XxxVo queryById(Long id) {
@@ -285,14 +195,14 @@ public class XxxServiceImpl implements IXxxService {
 
     @Override
     public TableDataInfo<XxxVo> queryPageList(XxxBo bo, PageQuery pageQuery) {
-        LambdaQueryWrapper<Xxx> lqw = buildQueryWrapper(bo);  // ✅ Service 层构建查询
+        LambdaQueryWrapper<Xxx> lqw = buildQueryWrapper(bo);
         Page<XxxVo> result = baseMapper.selectVoPage(pageQuery.build(), lqw);
         return TableDataInfo.build(result);
     }
 
     @Override
     public Boolean insertByBo(XxxBo bo) {
-        Xxx add = MapstructUtils.convert(bo, Xxx.class);  // ✅ MapstructUtils 转换
+        Xxx add = MapstructUtils.convert(bo, Xxx.class);
         validEntityBeforeSave(add);
         return baseMapper.insert(add) > 0;
     }
@@ -315,42 +225,25 @@ public class XxxServiceImpl implements IXxxService {
         return baseMapper.deleteByIds(ids) > 0;
     }
 
-    /**
-     * 构建查询条件
-     * ✅ Service 层直接构建（不是 DAO 层）
-     */
     private LambdaQueryWrapper<Xxx> buildQueryWrapper(XxxBo bo) {
         Map<String, Object> params = bo.getParams();
         LambdaQueryWrapper<Xxx> lqw = Wrappers.lambdaQuery();
-
-        // ✅ 精确匹配
         lqw.eq(bo.getId() != null, Xxx::getId, bo.getId());
         lqw.eq(StringUtils.isNotBlank(bo.getStatus()), Xxx::getStatus, bo.getStatus());
-
-        // ✅ 模糊匹配
         lqw.like(StringUtils.isNotBlank(bo.getXxxName()), Xxx::getXxxName, bo.getXxxName());
-
-        // ✅ 时间范围
         lqw.between(params.get("beginCreateTime") != null && params.get("endCreateTime") != null,
             Xxx::getCreateTime, params.get("beginCreateTime"), params.get("endCreateTime"));
-
-        // ✅ 排序
         lqw.orderByAsc(Xxx::getId);
         return lqw;
     }
 
-    /**
-     * 保存前验证
-     */
     private void validEntityBeforeSave(Xxx entity) {
         // TODO 做一些数据校验，如唯一约束
     }
 }
 ```
 
----
-
-## 6. Mapper 接口（继承 BaseMapperPlus）
+## 6. Mapper
 
 ```java
 package org.dromara.demo.mapper;
@@ -359,17 +252,12 @@ import org.dromara.demo.domain.Xxx;
 import org.dromara.demo.domain.vo.XxxVo;
 import org.dromara.common.mybatis.core.mapper.BaseMapperPlus;
 
-/**
- * XXX Mapper 接口
- */
 public interface XxxMapper extends BaseMapperPlus<Xxx, XxxVo> {
-    // ✅ 继承 BaseMapperPlus，已提供 selectVoById、selectVoPage、selectVoList 等方法
+    // 已提供 selectVoById、selectVoPage、selectVoList 等方法
 }
 ```
 
----
-
-## 7. Controller 控制器（标准 RESTful 路径）
+## 7. Controller
 
 ```java
 package org.dromara.demo.controller;
@@ -396,41 +284,26 @@ import org.dromara.demo.domain.vo.XxxVo;
 import org.dromara.demo.domain.bo.XxxBo;
 import org.dromara.demo.service.IXxxService;
 
-/**
- * XXX 管理控制器
- */
 @Validated
 @RequiredArgsConstructor
 @RestController
 @RequestMapping("/demo/xxx")
-public class XxxController extends BaseController {  // ✅ 继承 BaseController
+public class XxxController extends BaseController {
 
     private final IXxxService xxxService;
 
-    /**
-     * 查询列表
-     * ✅ RESTful 路径：/list（不是 /pageXxxs）
-     */
     @SaCheckPermission("demo:xxx:list")
     @GetMapping("/list")
     public TableDataInfo<XxxVo> list(XxxBo bo, PageQuery pageQuery) {
         return xxxService.queryPageList(bo, pageQuery);
     }
 
-    /**
-     * 获取详情
-     * ✅ RESTful 路径：/{id}（不是 /getXxx/{id}）
-     */
     @SaCheckPermission("demo:xxx:query")
     @GetMapping("/{id}")
     public R<XxxVo> getInfo(@NotNull(message = "主键不能为空") @PathVariable Long id) {
         return R.ok(xxxService.queryById(id));
     }
 
-    /**
-     * 新增
-     * ✅ POST 空路径
-     */
     @SaCheckPermission("demo:xxx:add")
     @Log(title = "XXX管理", businessType = BusinessType.INSERT)
     @RepeatSubmit()
@@ -439,10 +312,6 @@ public class XxxController extends BaseController {  // ✅ 继承 BaseControlle
         return toAjax(xxxService.insertByBo(bo));
     }
 
-    /**
-     * 修改
-     * ✅ PUT 空路径
-     */
     @SaCheckPermission("demo:xxx:edit")
     @Log(title = "XXX管理", businessType = BusinessType.UPDATE)
     @RepeatSubmit()
@@ -451,10 +320,6 @@ public class XxxController extends BaseController {  // ✅ 继承 BaseControlle
         return toAjax(xxxService.updateByBo(bo));
     }
 
-    /**
-     * 删除
-     * ✅ DELETE /{ids}
-     */
     @SaCheckPermission("demo:xxx:remove")
     @Log(title = "XXX管理", businessType = BusinessType.DELETE)
     @DeleteMapping("/{ids}")
@@ -462,9 +327,6 @@ public class XxxController extends BaseController {  // ✅ 继承 BaseControlle
         return toAjax(xxxService.deleteWithValidByIds(Arrays.asList(ids), true));
     }
 
-    /**
-     * 导出
-     */
     @SaCheckPermission("demo:xxx:export")
     @Log(title = "XXX管理", businessType = BusinessType.EXPORT)
     @PostMapping("/export")
@@ -475,21 +337,14 @@ public class XxxController extends BaseController {  // ✅ 继承 BaseControlle
 }
 ```
 
----
-
-## 8. 数据库建表（SQL）
+## 8. 建表 SQL
 
 ```sql
--- 表前缀：demo_（根据模块选择：sys_/demo_/workflow_ 等）
 CREATE TABLE demo_xxx (
-    id           BIGINT(20)   NOT NULL COMMENT '主键 ID',  -- ✅ 雪花 ID，不用 AUTO_INCREMENT
-    tenant_id    VARCHAR(20)  DEFAULT '000000' COMMENT '租户 ID',
-
-    -- 业务字段
+    id           BIGINT(20)   NOT NULL COMMENT '主键（雪花ID，不用AUTO_INCREMENT）',
+    tenant_id    VARCHAR(20)  DEFAULT '000000' COMMENT '租户ID',
     xxx_name     VARCHAR(100) NOT NULL COMMENT '名称',
     status       CHAR(1)      DEFAULT '0' COMMENT '状态(0正常 1停用)',
-
-    -- 审计字段（必须）
     create_dept  BIGINT(20)   DEFAULT NULL COMMENT '创建部门',
     create_by    BIGINT(20)   DEFAULT NULL COMMENT '创建人',
     create_time  DATETIME     DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
@@ -497,141 +352,58 @@ CREATE TABLE demo_xxx (
     update_time  DATETIME     DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
     remark       VARCHAR(255) DEFAULT NULL COMMENT '备注',
     del_flag     BIGINT(20)   DEFAULT 0 COMMENT '删除标志(0正常 1已删除)',
-
     PRIMARY KEY (id)
 ) ENGINE=InnoDB COMMENT='XXX表';
 ```
 
 ---
 
-## 架构对比
-
-### 三层架构流程图
-
-```
-请求到达
-   ↓
-Controller （路由转发 + 权限检查 + 参数校验）
-   ↓
-Service （业务逻辑 + 查询构建 + 对象转换）
-   ↓
-Mapper （数据持久化）
-   ↓
-数据库
-```
-
-### 关键差异
-
-| 环节 | 操作 | 位置 |
-|------|------|------|
-| **查询构建** | `buildQueryWrapper()` | **Service 层** ✅ |
-| **Mapper 注入** | 在 Service 中注入 | ✅ 直接注入 baseMapper |
-| **DAO 层** | 是否存在 | ❌ **不存在** |
-| **对象转换** | `MapstructUtils.convert()` | Service 层 |
-| **权限注解** | `@DataPermission` | Mapper 接口方法 |
-
----
-
 ## 常见错误速查
 
-### ❌ 不要做
-
 ```java
-// 错误 1: 在 Service 层注入 DAO
-@Service
-public class XxxServiceImpl {
-    private final IXxxDao xxxDao;  // ❌ 本项目没有 DAO 层！
-}
-
-// 错误 2: 使用 BeanUtil
-BeanUtil.copyProperties(bo, entity);  // ❌ 必须用 MapstructUtils.convert()
-
-// 错误 3: Service 继承基类
-public class XxxServiceImpl extends ServiceImpl<XxxMapper, Xxx> {  // ❌ 不继承！
-}
-
-// 错误 4: 使用 @AutoMappers（复数）
-@AutoMappers({  // ❌ 本项目用单数 @AutoMapper
-    @AutoMapper(target = Xxx.class)
-})
-public class XxxBo { }
-
-// 错误 5: 包名错误
-package org.dromara.xxx;  // ❌ 必须是 org.dromara.xxx
-
-// 错误 6: 使用错误的路径格式
-@GetMapping("/pageXxxs")  // ❌ 应该是 /list
-@GetMapping("/getXxx/{id}")  // ❌ 应该是 /{id}
-```
-
-### ✅ 正确做法
-
-```java
-// 正确 1: 直接在 Service 中注入 Mapper
-@Service
-@RequiredArgsConstructor
-public class XxxServiceImpl implements IXxxService {
-    private final XxxMapper baseMapper;  // ✅ 直接注入 Mapper
-}
-
-// 正确 2: 使用 MapstructUtils
-Xxx entity = MapstructUtils.convert(bo, Xxx.class);  // ✅
-
-// 正确 3: Service 只实现接口
-public class XxxServiceImpl implements IXxxService {  // ✅
-
-// 正确 4: 使用 @AutoMapper（单数）
-@AutoMapper(target = Xxx.class)  // ✅
-public class XxxBo { }
-
-// 正确 5: 使用 org.dromara 包名
-package org.dromara.demo.service;  // ✅
-
-// 正确 6: 使用标准 RESTful 路径
-@GetMapping("/list")  // ✅
-@GetMapping("/{id}")  // ✅
-@PostMapping
-@PutMapping
-@DeleteMapping("/{ids}")
+// ---- 错误写法 ----
+private final IXxxDao xxxDao;                    // 本项目没有 DAO 层
+BeanUtil.copyProperties(bo, entity);             // 必须用 MapstructUtils.convert()
+class XxxServiceImpl extends ServiceImpl<...> {} // Service 不继承基类
+@AutoMappers({@AutoMapper(...)})                 // 用单数 @AutoMapper
+@GetMapping("/pageXxxs")                         // 应该是 /list
+@GetMapping("/getXxx/{id}")                      // 应该是 /{id}
+
+// ---- 正确写法 ----
+private final XxxMapper baseMapper;              // 直接注入 Mapper
+MapstructUtils.convert(bo, Xxx.class);           // MapstructUtils 转换
+class XxxServiceImpl implements IXxxService {}   // 只实现接口
+@AutoMapper(target = Xxx.class)                  // 单数注解
+@GetMapping("/list")                             // RESTful 路径
+@GetMapping("/{id}")                             // RESTful 路径
 ```
 
 ---
 
 ## 检查清单
 
-生成代码前必须检查：
-
-- [ ] **包名是否是 `org.dromara.*`**？
-- [ ] **Service 是否只实现接口，不继承任何基类**？
-- [ ] **Service 是否直接注入 Mapper（无 DAO 层）**？
-- [ ] **buildQueryWrapper() 是否在 Service 层实现**？
-- [ ] **Entity 是否继承 `TenantEntity`**？
-- [ ] **BO 是否使用 `@AutoMapper`（单数）映射到 Entity**？
-- [ ] **VO 是否使用 `@AutoMapper` 映射**？
-- [ ] **是否使用 `MapstructUtils.convert()` 转换对象**？
-- [ ] **是否所有类型都先 import 再使用短类名**？
-- [ ] **Mapper 是否继承 `BaseMapperPlus<Entity, VO>`**？
-- [ ] **Controller 是否使用标准 RESTful 路径（/list、/{id} 等）**？
-- [ ] **是否使用了 `@DataPermission` 进行行级权限控制**？
-- [ ] **SQL 是否使用了 `del_flag`（非 `is_deleted`）**？
-- [ ] **主键是否使用雪花 ID（无 AUTO_INCREMENT）**？
-- [ ] **所有代码注释是否使用中文**？（Javadoc、行内注释、SQL 注释）
-- [ ] **SQL COMMENT 是否使用中文**？（禁止英文 COMMENT）
+- [ ] 包名是 `org.dromara.*`？
+- [ ] Service 只实现接口，不继承基类？
+- [ ] Service 直接注入 Mapper（无 DAO）？
+- [ ] `buildQueryWrapper()` 在 Service 层？
+- [ ] Entity 继承 `TenantEntity`？
+- [ ] BO 使用 `@AutoMapper`（单数）？
+- [ ] 使用 `MapstructUtils.convert()` 转换？
+- [ ] Mapper 继承 `BaseMapperPlus<Entity, VO>`？
+- [ ] Controller 使用 RESTful 路径？
+- [ ] SQL 使用 `del_flag`（0正常 1删除）？
+- [ ] 主键使用雪花 ID（无 AUTO_INCREMENT）？
+- [ ] 代码注释和 SQL COMMENT 使用中文？
 
 ---
 
 ## 参考实现
 
-查看已有的完整实现：
-
-- **Entity 参考**: `org.dromara.demo.domain.TestDemo`
-- **BO 参考**: `org.dromara.demo.domain.bo.TestDemoBo`
-- **VO 参考**: `org.dromara.demo.domain.vo.TestDemoVo`
-- **Service 参考**: `org.dromara.demo.service.impl.TestDemoServiceImpl`
-- **Mapper 参考**: `org.dromara.demo.mapper.TestDemoMapper`
-- **Controller 参考**: `org.dromara.demo.controller.TestDemoController`
-
-**特别注意**：上述参考代码是本项目的标准实现，严格遵循三层架构（Service 直接调用 Mapper，无 DAO 层）。
-
-
-<!-- 抓蛙师 -->
+| 类型 | 类名 |
+|------|------|
+| Entity | `org.dromara.demo.domain.TestDemo` |
+| BO | `org.dromara.demo.domain.bo.TestDemoBo` |
+| VO | `org.dromara.demo.domain.vo.TestDemoVo` |
+| Service | `org.dromara.demo.service.impl.TestDemoServiceImpl` |
+| Mapper | `org.dromara.demo.mapper.TestDemoMapper` |
+| Controller | `org.dromara.demo.controller.TestDemoController` |