ai-engineering-init 1.3.3 → 1.4.0

package/.claude/skills/leniu-backend-annotations/SKILL.md

@@ -1,111 +1,60 @@
 ---
 name: leniu-backend-annotations
 description: |
-  leniu-yunshitang-core 项目后端注解使用指南。包含认证注解、参数校验注解、Swagger 文档注解、分组校验注解等核心注解的用法。
+  leniu-yunshitang-core 项目后端注解速查指南。包含认证、校验、Swagger、MyBatis-Plus、审计字段等注解的正确用法。
 
   触发场景：
-  - 配置认证注解（@RequiresAuthentication, @RequiresGuest）
-  - 配置参数校验（@Validated, @NotNull, @NotBlank）
-  - 配置 Swagger 文档注解（@Api, @ApiOperation, @ApiModelProperty）
-  - 配置分组校验（InsertGroup, UpdateGroup）
+  - 配置 leniu 认证注解（@RequiresAuthentication, @RequiresGuest）
+  - 配置参数校验和分组校验（InsertGroup, UpdateGroup）
+  - 配置 Swagger 文档注解（@Api, @ApiOperation）
+  - 配置 Entity 审计字段注解
+  - 排查注解使用错误（javax vs jakarta、AddGroup vs InsertGroup）
 
-  适用项目：
-  - 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
+  适用项目：leniu-tengyun-core（云食堂项目）
 
-  触发词：@RequiresAuthentication、@RequiresGuest、@Validated、@NotNull、@Api、@ApiOperation、@ApiModelProperty、分组校验、InsertGroup、UpdateGroup
+  触发词：@RequiresAuthentication、@RequiresGuest、@Validated、@NotNull、@Api、@ApiOperation、InsertGroup、UpdateGroup、注解用法、审计字段注解
 ---
 
-# leniu-yunshitang-core 后端注解指南
+# leniu 后端注解速查
 
-> 本文档专注于 leniu-tengyun-core 项目的 Java 后端注解使用规范。
+## 注解总览
 
-## 注解快速特征对比
-
-| 注解 | 作用范围 | 包路径 | 常用场景 |
-|------|--------|--------|---------|
-| `@RequiresAuthentication` | Controller 类/方法 | `net.xnzn.framework.secure.filter` | 需要登录认证 |
-| `@RequiresGuest` | Controller 类/方法 | `net.xnzn.framework.secure.filter` | 允许游客访问 |
-| `@Validated` | Controller 方法 | `jakarta.validation` | 参数校验 |
-| `@Valid` | Controller 方法 | `jakarta.validation` | 参数校验 |
-| `@Api` | Controller 类 | `io.swagger.annotations` | Swagger 文档 |
-| `@ApiOperation` | Controller 方法 | `io.swagger.annotations` | Swagger 文档 |
-| `@ApiModelProperty` | DTO/VO 字段 | `io.swagger.annotations` | Swagger 文档 |
+| 注解 | 作用层 | 包路径 | 场景 |
+|------|--------|--------|------|
+| `@RequiresAuthentication` | Controller 类/方法 | `net.xnzn.framework.secure.filter.annotation` | 需要登录 |
+| `@RequiresGuest` | Controller 类/方法 | `net.xnzn.framework.secure.filter.annotation` | 允许游客 |
+| `@Validated` | Controller 方法参数 | `org.springframework.validation.annotation` | 分组校验 |
+| `@Valid` | Controller 方法参数 | `jakarta.validation` | 简单校验 |
+| `@Api` | Controller 类 | `io.swagger.annotations` | Swagger 类文档 |
+| `@ApiOperation` | Controller 方法 | `io.swagger.annotations` | Swagger 方法文档 |
+| `@ApiModelProperty` | DTO/VO/Entity 字段 | `io.swagger.annotations` | Swagger 字段文档 |
+| `@TableName` | Entity 类 | `com.baomidou.mybatisplus.annotation` | 表名映射 |
+| `@TableId` | Entity 主键字段 | `com.baomidou.mybatisplus.annotation` | 主键策略 |
+| `@TableField` | Entity 字段 | `com.baomidou.mybatisplus.annotation` | 字段映射/自动填充 |
 
 ---
 
 ## 1. 认证注解
 
-### @RequiresAuthentication - 需要登录
-
 ```java
 import net.xnzn.framework.secure.filter.annotation.RequiresAuthentication;
-
-@RestController
-@RequestMapping("/api/xxx")
-@Api(tags = "XXX管理")
-@RequiresAuthentication  // 类级别：所有方法都需要登录
-public class XxxController {
-
-    @Resource
-    private XxxService xxxService;
-
-    @PostMapping("/add")
-    @ApiOperation(value = "XXX-新增")
-    public Long add(@Valid @RequestBody LeRequest<XxxDTO> request) {
-        return xxxService.add(request.getContent());
-    }
-
-    @PostMapping("/delete")
-    @ApiOperation(value = "XXX-删除")
-    public void delete(@RequestBody LeRequest<Long> request) {
-        xxxService.delete(request.getContent());
-    }
-}
-```
-
-### @RequiresGuest - 允许游客访问
-
-```java
 import net.xnzn.framework.secure.filter.annotation.RequiresGuest;
 
 @RestController
-@RequestMapping("/api/public")
-@Api(tags = "公开接口")
-public class PublicController {
-
-    @Resource
-    private PublicService publicService;
-
-    @RequiresGuest
-    @GetMapping("/config")
-    @ApiOperation(value = "获取配置")
-    public LeResponse<ConfigVO> getConfig() {
-        return LeResponse.succ(publicService.getConfig());
-    }
-}
-```
-
-### 混合使用
-
-```java
-@RestController
-@RequestMapping("/api/xxx")
+@RequiresAuthentication                    // 类级别：所有方法默认需登录
+@RequestMapping("/api/v2/web/xxx")
 @Api(tags = "XXX管理")
-@RequiresAuthentication  // 类级别默认需要登录
 public class XxxController {
 
-    // 继承类级别配置：需要登录
-    @PostMapping("/add")
+    @PostMapping("/add")                   // 继承类级别：需要登录
     @ApiOperation(value = "XXX-新增")
-    public Long add(@Valid @RequestBody LeRequest<XxxDTO> request) {
-        return xxxService.add(request.getContent());
+    public void add(@Validated(InsertGroup.class) @RequestBody LeRequest<XxxDTO> request) {
+        xxxService.add(request.getContent());
     }
 
-    // 覆盖类级别配置：允许游客访问
-    @RequiresGuest
+    @RequiresGuest                         // 方法级别覆盖：允许游客
     @GetMapping("/list")
-    @ApiOperation(value = "XXX-列表")
+    @ApiOperation(value = "XXX-公开列表")
     public List<XxxVO> list() {
         return xxxService.list();
     }
@@ -116,166 +65,97 @@ public class XxxController {
 
 ## 2. 参数校验注解
 
-### @Validated 和 @Valid
+### 分组校验（新增/修改场景区分）
 
 ```java
-import jakarta.validation.Valid;
-import jakarta.validation.Validated;
-import jakarta.validation.constraints.*;
+// 分组接口
+public interface InsertGroup {}
+public interface UpdateGroup {}
 
-@RestController
-@RequestMapping("/api/xxx")
-public class XxxController {
+// Controller 中使用分组
+@PostMapping("/add")
+public void add(@Validated(InsertGroup.class) @RequestBody LeRequest<XxxDTO> request) {}
 
-    // 使用 @Validated 进行分组校验
-    @PostMapping("/add")
-    @ApiOperation(value = "XXX-新增")
-    public Long add(@Validated(InsertGroup.class) @RequestBody LeRequest<XxxDTO> request) {
-        return xxxService.add(request.getContent());
-    }
+@PostMapping("/update")
+public void update(@Validated(UpdateGroup.class) @RequestBody LeRequest<XxxDTO> request) {}
 
-    // 使用 @Valid 进行简单校验
-    @PostMapping("/update")
-    @ApiOperation(value = "XXX-修改")
-    public void update(@Valid @RequestBody LeRequest<XxxDTO> request) {
-        xxxService.update(request.getContent());
-    }
-}
+// 不需要分组时用 @Valid 或 @Validated（不带参数）
+@PostMapping("/query")
+public Page<XxxVO> query(@Valid @RequestBody LeRequest<XxxQueryParam> request) {}
 ```
 
-### DTO 校验注解
+### DTO 校验字段
 
 ```java
-import jakarta.validation.constraints.*;
-import io.swagger.annotations.ApiModel;
-import io.swagger.annotations.ApiModelProperty;
-import lombok.Data;
-import java.io.Serializable;
+import jakarta.validation.constraints.*;   // JDK 21 必须 jakarta
 
-/**
- * XXX DTO
- */
 @Data
 @ApiModel("XXX DTO")
 public class XxxDTO implements Serializable {
 
-    private static final long serialVersionUID = 1L;
-
-    @ApiModelProperty(value = "主键ID")
-    @NotNull(message = "主键ID不能为空", groups = {UpdateGroup.class})
+    @NotNull(message = "ID不能为空", groups = {UpdateGroup.class})
+    @ApiModelProperty("主键ID")
     private Long id;
 
-    @ApiModelProperty(value = "名称", required = true)
     @NotBlank(message = "名称不能为空", groups = {InsertGroup.class, UpdateGroup.class})
     @Size(max = 100, message = "名称长度不能超过100个字符")
+    @ApiModelProperty(value = "名称", required = true)
     private String name;
 
-    @ApiModelProperty(value = "状态")
     @Min(value = 0, message = "状态不能小于0")
     @Max(value = 1, message = "状态不能大于1")
+    @ApiModelProperty("状态")
     private Integer status;
 
-    @ApiModelProperty(value = "邮箱")
-    @Email(message = "邮箱格式不正确")
-    private String email;
-
-    @ApiModelProperty(value = "手机号")
     @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
+    @ApiModelProperty("手机号")
     private String phone;
 
-    @ApiModelProperty(value = "身份证号")
-    @Pattern(regexp = "^[1-9]\\d{5}(19|20)\\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\\d|3[01])\\d{3}[\\dXx]$", message = "身份证号格式不正确")
-    private String idCard;
-
-    @ApiModelProperty(value = "URL")
-    @Pattern(regexp = "^https?://.+", message = "URL格式不正确")
-    private String url;
+    @Email(message = "邮箱格式不正确")
+    @ApiModelProperty("邮箱")
+    private String email;
 
-    @ApiModelProperty(value = "开始时间", required = true)
     @NotNull(message = "开始时间不能为空", groups = {InsertGroup.class, UpdateGroup.class})
+    @ApiModelProperty(value = "开始时间", required = true)
     private Date startTime;
 
-    @ApiModelProperty(value = "结束时间", required = true)
-    @NotNull(message = "结束时间不能为空", groups = {InsertGroup.class, UpdateGroup.class})
-    private Date endTime;
-
-    @ApiModelProperty(value = "备注")
     @Size(max = 500, message = "备注长度不能超过500个字符")
+    @ApiModelProperty("备注")
     private String remark;
 }
 ```
 
-### 分组校验
-
-```java
-// InsertGroup.java - 新增分组
-public interface InsertGroup {}
-
-// UpdateGroup.java - 修改分组
-public interface UpdateGroup {}
-```
-
 ---
 
 ## 3. Swagger 文档注解
 
-### @Api - 类级别
-
 ```java
 import io.swagger.annotations.Api;
-
-@RestController
-@RequestMapping("/api/xxx")
-@Api(value = "XXX管理", tags = "XXX管理")
-@RequiresAuthentication
-public class XxxController {
-    // ...
-}
-```
-
-### @ApiOperation - 方法级别
-
-```java
 import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiModelProperty;
+import io.swagger.annotations.ApiParam;
 
-@PostMapping("/add")
-@ApiOperation(value = "XXX-新增")
-public Long add(@Valid @RequestBody LeRequest<XxxDTO> request) {
-    return xxxService.add(request.getContent());
-}
-
-@PostMapping("/update")
-@ApiOperation(value = "XXX-修改")
-public void update(@Valid @RequestBody LeRequest<XxxDTO> request) {
-    xxxService.update(request.getContent());
-}
+// 类级别
+@Api(value = "XXX管理", tags = "XXX管理")
+public class XxxController {}
 
-@PostMapping("/delete")
-@ApiOperation(value = "XXX-删除")
-public void delete(@RequestBody LeRequest<Long> request) {
-    xxxService.delete(request.getContent());
-}
+// 方法级别
+@ApiOperation(value = "XXX-分页查询")
+@PostMapping("/page")
+public Page<XxxVO> page(@Valid @RequestBody LeRequest<XxxDTO> request) {}
 
+// 路径参数
 @GetMapping("/get/{id}")
-@ApiOperation(value = "XXX-获取详情")
-public XxxVO getById(@PathVariable Long id) {
-    return xxxService.getById(id);
-}
+public XxxVO getById(@ApiParam(value = "主键ID", required = true) @PathVariable Long id) {}
 
-@PostMapping("/page")
-@ApiOperation(value = "XXX-分页查询")
-public Page<XxxVO> page(@Valid @RequestBody LeRequest<XxxDTO> request) {
-    return xxxService.page(request.getContent());
-}
+// 查询参数
+@PostMapping("/search")
+public List<XxxVO> search(@ApiParam(value = "搜索关键词") @RequestParam(required = false) String keyword) {}
 ```
 
-### @ApiModelProperty - 字段级别
+### VO 字段文档
 
 ```java
-import io.swagger.annotations.ApiModel;
-import io.swagger.annotations.ApiModelProperty;
-import com.fasterxml.jackson.annotation.JsonFormat;
-
 @Data
 @ApiModel("XXX VO")
 public class XxxVO implements Serializable {
@@ -286,370 +166,105 @@ public class XxxVO implements Serializable {
     @ApiModelProperty("名称")
     private String name;
 
-    @ApiModelProperty("状态")
-    private String status;
-
-    @ApiModelProperty("状态描述")
-    private String statusDesc;
-
-    @ApiModelProperty(value = "创建时间")
+    @ApiModelProperty("创建时间")
     @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
     private Date crtime;
-
-    @ApiModelProperty(value = "更新时间")
-    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
-    private Date uptime;
-}
-```
-
-### @ApiParam - 参数级别
-
-```java
-import io.swagger.annotations.ApiParam;
-
-@GetMapping("/get/{id}")
-@ApiOperation(value = "XXX-获取详情")
-public XxxVO getById(
-    @ApiParam(value = "主键ID", required = true)
-    @PathVariable Long id
-) {
-    return xxxService.getById(id);
-}
-
-@PostMapping("/search")
-@ApiOperation(value = "XXX-搜索")
-public List<XxxVO> search(
-    @ApiParam(value = "搜索关键词")
-    @RequestParam(required = false) String keyword
-) {
-    return xxxService.search(keyword);
-}
-```
-
----
-
-## 4. MyBatis 注解
-
-### @Mapper - Mapper 接口
-
-```java
-import org.apache.ibatis.annotations.Mapper;
-
-@Mapper
-public interface XxxMapper extends BaseMapper<XxxEntity> {
-    // ...
-}
-```
-
-### @TableName - 实体类
-
-```java
-import com.baomidou.mybatisplus.annotation.TableName;
-
-@TableName("xxx_table")
-public class XxxEntity {
-    // ...
 }
 ```
 
-### @TableId - 主键
-
-```java
-import com.baomidou.mybatisplus.annotation.TableId;
-import com.baomidou.mybatisplus.annotation.IdType;
-
-@TableId(value = "id", type = IdType.AUTO)
-private Long id;
-```
-
-### @TableField - 字段映射
-
-```java
-import com.baomidou.mybatisplus.annotation.TableField;
-import com.baomidou.mybatisplus.annotation.FieldFill;
-
-@TableField("name")
-private String name;
-
-@TableField(value = "crby", fill = FieldFill.INSERT)
-private String crby;
-
-@TableField(value = "crtime", fill = FieldFill.INSERT)
-private Date crtime;
-
-@TableField(value = "upby", fill = FieldFill.INSERT_UPDATE)
-private String upby;
-
-@TableField(value = "uptime", fill = FieldFill.INSERT_UPDATE)
-private Date uptime;
-```
-
----
-
-## 5. JSON 序列化注解
-
-### @JsonFormat - 日期格式化
-
-```java
-import com.fasterxml.jackson.annotation.JsonFormat;
-
-@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
-private Date crtime;
-
-@JsonFormat(pattern = "yyyy-MM-dd")
-private Date date;
-```
-
 ---
 
-## 6. Lombok 注解
-
-### @Data - 实体类
+## 4. Entity 注解（MyBatis-Plus + 审计字段）
 
 ```java
-import lombok.Data;
+import com.baomidou.mybatisplus.annotation.*;
 
 @Data
 @TableName("xxx_table")
-public class XxxEntity {
-    private Long id;
-    private String name;
-}
-```
-
-### @Accessors(chain = true) - 链式调用
+public class XxxEntity implements Serializable {
 
-```java
-import lombok.Data;
-import lombok.experimental.Accessors;
-
-@Data
-@Accessors(chain = true)
-public class XxxEntity {
+    @ApiModelProperty("主键ID")
+    @TableId(value = "id", type = IdType.AUTO)
     private Long id;
-    private String name;
-}
-
-// 使用
-XxxEntity entity = new XxxEntity()
-    .setId(1L)
-    .setName("test");
-```
 
----
-
-## 7. 完整 Controller 示例
-
-```java
-package net.xnzn.core.xxx.controller;
-
-import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
-import com.pig4cloud.pigx.common.core.util.LeRequest;
-import io.swagger.annotations.Api;
-import io.swagger.annotations.ApiOperation;
-import io.swagger.annotations.ApiParam;
-import lombok.extern.slf4j.Slf4j;
-import net.xnzn.core.xxx.dto.XxxDTO;
-import net.xnzn.core.xxx.service.XxxService;
-import net.xnzn.core.xxx.vo.XxxVO;
-import net.xnzn.framework.secure.filter.annotation.RequiresAuthentication;
-import net.xnzn.framework.secure.filter.annotation.RequiresGuest;
-
-import org.springframework.web.bind.annotation.*;
-
-import jakarta.validation.Valid;
-import java.util.List;
-
-/**
- * XXX 管理控制器
- */
-@Slf4j
-@RestController
-@RequestMapping("/api/xxx")
-@Api(value = "XXX管理", tags = "XXX管理")
-@RequiresAuthentication
-public class XxxController {
-
-    @Resource
-    private XxxService xxxService;
-
-    /**
-     * 新增
-     */
-    @PostMapping("/add")
-    @ApiOperation(value = "XXX-新增")
-    public Long add(@Validated(InsertGroup.class) @RequestBody LeRequest<XxxDTO> request) {
-        log.info("新增XXX，参数: {}", request.getContent());
-        return xxxService.add(request.getContent());
-    }
-
-    /**
-     * 修改
-     */
-    @PostMapping("/update")
-    @ApiOperation(value = "XXX-修改")
-    public void update(@Validated(UpdateGroup.class) @RequestBody LeRequest<XxxDTO> request) {
-        log.info("修改XXX，参数: {}", request.getContent());
-        xxxService.update(request.getContent());
-    }
-
-    /**
-     * 删除
-     */
-    @PostMapping("/delete")
-    @ApiOperation(value = "XXX-删除")
-    public void delete(@RequestBody LeRequest<Long> request) {
-        log.info("删除XXX，参数: {}", request.getContent());
-        xxxService.delete(request.getContent());
-    }
-
-    /**
-     * 获取详情
-     */
-    @GetMapping("/get/{id}")
-    @ApiOperation(value = "XXX-获取详情")
-    @RequiresGuest
-    public XxxVO getById(
-        @ApiParam(value = "主键ID", required = true)
-        @PathVariable Long id
-    ) {
-        return xxxService.getById(id);
-    }
-
-    /**
-     * 分页查询
-     */
-    @PostMapping("/page")
-    @ApiOperation(value = "XXX-分页查询")
-    public Page<XxxVO> page(@Valid @RequestBody LeRequest<XxxDTO> request) {
-        log.info("分页查询XXX，参数: {}", request.getContent());
-        return xxxService.page(request.getContent());
-    }
-
-    /**
-     * 查询列表
-     */
-    @PostMapping("/list")
-    @ApiOperation(value = "XXX-查询列表")
-    @RequiresGuest
-    public List<XxxVO> list(@Valid @RequestBody LeRequest<XxxDTO> request) {
-        return xxxService.list(request.getContent());
-    }
-}
-```
-
----
-
-## 8. 常见错误对比
-
-### ❌ 错误写法
+    @ApiModelProperty("名称")
+    @TableField("name")
+    private String name;
 
-```java
-// 错误 1: 使用 RuoYi 的认证注解
-@SaCheckPermission("system:user:list")  // ❌ leniu 使用 @RequiresAuthentication
+    // ===== 审计字段（leniu 标准） =====
+    @ApiModelProperty("创建人")
+    @TableField(value = "crby", fill = FieldFill.INSERT)
+    private String crby;
 
-// 错误 2: 使用 javax.validation（JDK 21 应用 jakarta.validation）
-import javax.validation.Valid;  // ❌ 错误
-import javax.validation.constraints.NotNull;  // ❌ 错误
+    @ApiModelProperty("创建时间")
+    @TableField(value = "crtime", fill = FieldFill.INSERT)
+    private LocalDateTime crtime;
 
-// 错误 3: 使用 RuoYi 的分组
-@Validated(AddGroup.class)  // ❌ 应该用 InsertGroup.class
+    @ApiModelProperty("更新人")
+    @TableField(value = "upby", fill = FieldFill.INSERT_UPDATE)
+    private String upby;
 
-// 错误 4: Swagger 注解包错误
-import io.swagger.v3.oas.annotations.*;  // ❌ OpenAPI 3.0
-// 应该用
-import io.swagger.annotations.*;  // ✅ Swagger 2.0
+    @ApiModelProperty("更新时间")
+    @TableField(value = "uptime", fill = FieldFill.INSERT_UPDATE)
+    private LocalDateTime uptime;
 
-// 错误 5: 缺少 Swagger 文档注解
-@RestController
-public class XxxController {  // ❌ 缺少 @Api
-    @PostMapping("/add")
-    public Long add(@RequestBody LeRequest<XxxDTO> request) {  // ❌ 缺少 @ApiOperation
-        return xxxService.add(request.getContent());
-    }
+    @ApiModelProperty("删除标识(1-删除,2-正常)")
+    private Integer delFlag;
 }
-
-// 错误 6: 审计字段注解错误
-@TableField("create_by")  // ❌ 应该用 crby
-@TableField("create_time")  // ❌ 应该用 crtime
 ```
 
-### ✅ 正确写法
+### Mapper 接口
 
 ```java
-// 正确 1: 使用 leniu 的认证注解
-@RequiresAuthentication  // ✅
-@RequiresGuest  // ✅
-
-// 正确 2: 使用 Jakarta Validation
-import jakarta.validation.Valid;  // ✅
-import jakarta.validation.constraints.NotNull;  // ✅
-
-// 正确 3: 使用 leniu 的分组
-@Validated(InsertGroup.class)  // ✅
-
-// 正确 4: Swagger 注解包正确
-import io.swagger.annotations.Api;  // ✅
-import io.swagger.annotations.ApiOperation;  // ✅
-
-// 正确 5: Swagger 文档注解完整
-@RestController
-@Api(value = "XXX管理", tags = "XXX管理")  // ✅
-public class XxxController {
-    @PostMapping("/add")
-    @ApiOperation(value = "XXX-新增")  // ✅
-    public Long add(@RequestBody LeRequest<XxxDTO> request) {
-        return xxxService.add(request.getContent());
-    }
-}
+import org.apache.ibatis.annotations.Mapper;
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 
-// 正确 6: 审计字段注解正确
-@TableField(value = "crby", fill = FieldFill.INSERT)  // ✅
-@TableField(value = "crtime", fill = FieldFill.INSERT)  // ✅
+@Mapper
+public interface XxxMapper extends BaseMapper<XxxEntity> {}
 ```
 
 ---
 
-## 9. 检查清单
-
-使用注解前必须检查：
+## 5. 注解组合速查
 
-- [ ] **是否使用 `@RequiresAuthentication` 或 `@RequiresGuest`**？
-- [ ] **是否使用 Jakarta Validation**（jakarta.validation）？
-- [ ] **分组校验是否正确**（InsertGroup/UpdateGroup）？
-- [ ] **Controller 是否添加 `@Api` 注解**？
-- [ ] **方法是否添加 `@ApiOperation` 注解**？
-- [ ] **DTO/VO 是否添加 `@ApiModelProperty` 注解**？
-- [ ] **Swagger 注解包是否正确**（io.swagger.annotations）？
-- [ ] **Entity 是否正确配置 `@TableName`**？
-- [ ] **主键是否正确配置 `@TableId`**？
-- [ ] **审计字段是否配置 `FieldFill`**？
+| 层级 | 标准注解组合 |
+|------|-------------|
+| Controller 类 | `@Api` + `@RestController` + `@RequiresAuthentication` + `@RequestMapping` |
+| 写操作方法 | `@ApiOperation` + `@PostMapping` + `@Validated(InsertGroup/UpdateGroup.class)` |
+| 查询方法 | `@ApiOperation` + `@PostMapping` + `@Valid` 或 `@Validated` |
+| DTO 字段 | `@ApiModelProperty` + `@NotNull/@NotBlank` + `(groups = {InsertGroup.class})` |
+| Entity 类 | `@Data` + `@TableName` |
+| Entity 主键 | `@ApiModelProperty` + `@TableId(type = IdType.AUTO)` |
+| 审计字段 | `@ApiModelProperty` + `@TableField(fill = FieldFill.INSERT/INSERT_UPDATE)` |
 
 ---
 
-## 10. 快速参考
+## 6. 错误对比
 
-### 注解速查表
+| 错误写法 | 正确写法 | 说明 |
+|---------|---------|------|
+| `@SaCheckPermission("xxx")` | `@RequiresAuthentication` | leniu 不用 Sa-Token 细粒度权限 |
+| `import javax.validation.*` | `import jakarta.validation.*` | JDK 21 必须 jakarta |
+| `@Validated(AddGroup.class)` | `@Validated(InsertGroup.class)` | leniu 分组名为 InsertGroup |
+| `import io.swagger.v3.oas.*` | `import io.swagger.annotations.*` | leniu 用 Swagger 2.0 |
+| `@TableField("create_by")` | `@TableField(value = "crby", fill = FieldFill.INSERT)` | leniu 审计字段 |
+| `@TableField("create_time")` | `@TableField(value = "crtime", fill = FieldFill.INSERT)` | leniu 审计字段 |
+| `@TableId(type = IdType.ASSIGN_ID)` | `@TableId(type = IdType.AUTO)` | leniu 用自增主键 |
+| Controller 缺 `@Api` | 必须加 `@Api(tags = "模块名")` | Swagger 文档要求 |
+| 方法缺 `@ApiOperation` | 必须加 `@ApiOperation(value = "描述")` | Swagger 文档要求 |
 
-```
-@RequiresAuthentication → 需要登录认证
-@RequiresGuest       → 允许游客访问
-@Validated           → 参数校验（支持分组）
-@Valid              → 参数校验（不支持分组）
-@Api                → Swagger 文档（类级别）
-@ApiOperation        → Swagger 文档（方法级别）
-@ApiModelProperty     → Swagger 文档（字段级别）
-@ApiParam           → Swagger 文档（参数级别）
-```
+---
 
-### 注解组合速查
+## 检查清单
 
-```
-Controller:     @Api + @RequiresAuthentication
-Method:         @ApiOperation + @Validated(InsertGroup.class)
-DTO Field:      @ApiModelProperty + @NotNull/NotBlank
-Entity Field:    @TableField + @ApiModelProperty
-```
+- [ ] 认证注解：`@RequiresAuthentication` 或 `@RequiresGuest`
+- [ ] 校验包：`jakarta.validation`（非 `javax.validation`）
+- [ ] 分组名：`InsertGroup` / `UpdateGroup`（非 `AddGroup` / `EditGroup`）
+- [ ] Swagger 包：`io.swagger.annotations`（非 `io.swagger.v3.oas`）
+- [ ] Controller 有 `@Api`，方法有 `@ApiOperation`
+- [ ] DTO/VO 字段有 `@ApiModelProperty`
+- [ ] Entity 主键：`@TableId(type = IdType.AUTO)`
+- [ ] 审计字段：`crby/crtime/upby/uptime` + 正确的 `FieldFill`
 
 ---
 
@@ -657,8 +272,6 @@ Entity Field:    @TableField + @ApiModelProperty
 
 | 类型 | 路径 |
 |------|------|
-| Controller 示例 | `core-attendance/.../controller/AttendanceLeaveInfoController.java` |
-| DTO 示例 | `core-attendance/.../dto/AddOrUpdateAttendanceLeaveInfoDTO.java` |
-| Entity 示例 | `core-bus/.../model/BusLine.java` |
-
-**项目路径**：`/Users/xujiajun/Developer/gongsi_proj/leniu-api/leniu-tengyun-core`
+| Controller 示例 | `sys-canteen/.../order/web/controller/OrderInfoWebController.java` |
+| DTO 示例 | `sys-kitchen/.../attendance/.../dto/` |
+| Entity 示例 | `sys-canteen/.../order/common/model/OrderInfo.java` |