ai-engineering-init 1.4.3 → 1.6.0

package/src/skills/leniu-architecture-design/SKILL.md

@@ -0,0 +1,383 @@
+---
+name: leniu-architecture-design
+description: |
+  leniu-tengyun-core 项目架构设计指南。基于 pigx-framework 的云食堂双库架构，包含四层架构规范、双库多租户实现、模块划分、Entity 设计。
+
+  触发场景：
+  - 新模块/新功能的架构设计与代码分层
+  - 双库架构（系统库+商户库）数据路由决策
+  - 四层架构（Controller→Business→Service→Mapper）编排
+  - 多租户数据隔离与跨租户操作
+  - Entity/DTO/VO 结构设计
+  - Mapper XML 文件放置与配置
+
+  适用项目：
+  - 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
+
+  触发词：架构设计、双库架构、商户库、系统库、pigx框架、四层架构、模块划分、Business层、分层设计、代码结构
+---
+
+# leniu-tengyun-core 架构设计指南
+
+## 双库架构
+
+物理分离双库，**Entity 无 tenant_id 字段**：
+
+| 库类型 | 数据范围 | 访问方式 |
+|--------|---------|---------|
+| **系统库** | 租户信息、商户配置、系统字典 | `Executors.doInSystem()` |
+| **商户库** | 订单、菜品、用户、设备等 | 默认（请求头 `MERCHANT-ID`） |
+
+### 多租户上下文切换
+
+```java
+// 获取当前租户
+Long tenantId = TenantContextHolder.getTenantId();
+
+// 在指定商户库执行
+Executors.doInTenant(tenantId, () -> { /* 商户库 */ });
+
+// 在系统库执行
+Executors.doInSystem(() -> { /* 系统库 */ });
+
+// 遍历所有租户执行（定时任务场景）
+Executors.doInAllTenant(tenantId -> { /* 每个租户 */ });
+```
+
+### 双库路由场景
+
+```java
+// 场景1：商户业务（默认，前端请求头携带 MERCHANT-ID）
+@PostMapping("/order/add")
+public void addOrder(@RequestBody LeRequest<OrderDTO> request) {
+    orderService.add(request.getContent()); // 自动路由商户库
+}
+
+// 场景2：系统配置操作
+@PostMapping("/merchant/config")
+public void updateConfig(@RequestBody LeRequest<ConfigDTO> request) {
+    Executors.doInSystem(() -> configService.update(request.getContent()));
+}
+
+// 场景3：定时任务遍历所有租户
+public void execute() {
+    Executors.doInAllTenant(tenantId -> reportService.generate(tenantId));
+}
+
+// 场景4：MQ 消费指定租户
+@RabbitListener(queues = "order.queue")
+public void consumeOrder(Message message) {
+    Long tenantId = getTenantFromMessage(message);
+    Executors.doInTenant(tenantId, () -> orderService.process(message));
+}
+```
+
+---
+
+## 四层架构
+
+```
+Controller → Business → Service → Mapper
+```
+
+| 层 | 职责 | 命名 |
+|----|------|------|
+| **Controller** | 接收请求、参数校验、路由分端 | `XxxWebController` |
+| **Business** | 业务编排、跨 Service 协调 | `XxxWebBusiness` |
+| **Service** | 单表 CRUD、事务 | `XxxServiceImpl` |
+| **Mapper** | ORM 映射（XML 同目录） | `XxxMapper` |
+
+> **Business 层**是本项目核心特色，复杂逻辑在此编排，简单 CRUD 可跳过直接 Controller→Service。
+
+### Controller 示例
+
+```java
+package net.xnzn.core.xxx.controller;
+
+import com.pig4cloud.pigx.common.core.util.LeRequest;
+import net.xnzn.framework.secure.filter.annotation.RequiresAuthentication;
+
+@RestController
+@RequiresAuthentication
+@RequestMapping("/api/v2/web/xxx")
+public class XxxWebController {
+
+    @Autowired
+    private XxxWebBusiness xxxBusiness;
+
+    @PostMapping("/add")
+    public void add(@Validated @RequestBody LeRequest<XxxDTO> request) {
+        xxxBusiness.add(request.getContent());
+    }
+
+    @PostMapping("/query")
+    public Page<XxxVO> query(@Validated @RequestBody LeRequest<PageDTO> request) {
+        return xxxBusiness.query(request.getContent());
+    }
+}
+```
+
+### Business 示例
+
+```java
+package net.xnzn.core.xxx.business.impl;
+
+@Component
+public class XxxWebBusiness {
+
+    @Autowired
+    private XxxServiceImpl xxxService;
+    @Autowired
+    private YyyServiceImpl yyyService;
+
+    public void add(XxxDTO dto) {
+        // 编排多个 Service
+        xxxService.add(dto);
+        yyyService.bindRelation(dto.getId());
+    }
+
+    public Page<XxxVO> query(PageDTO dto) {
+        return xxxService.query(dto);
+    }
+}
+```
+
+### Service 示例
+
+```java
+package net.xnzn.core.xxx.service.impl;
+
+@Service
+public class XxxServiceImpl {
+    @Autowired
+    private XxxMapper xxxMapper;
+
+    public void add(XxxDTO dto) {
+        long id = Id.next();
+        XxxEntity entity = new XxxEntity();
+        BeanUtil.copyProperties(dto, entity);
+        entity.setId(id);
+        xxxMapper.insert(entity);
+    }
+
+    public Page<XxxVO> query(PageDTO dto) {
+        return xxxMapper.page(dto.getMpPage(), dto.getKeyword());
+    }
+}
+```
+
+### Mapper 示例
+
+```java
+package net.xnzn.core.xxx.mapper;
+
+@Mapper
+public interface XxxMapper extends BaseMapper<XxxEntity> {
+    Page<XxxVO> page(Page<Object> page, @Param("keyword") String keyword);
+}
+```
+
+### Mapper XML（与 Java 同目录）
+
+```
+src/main/java/net/xnzn/core/xxx/mapper/
+├── XxxMapper.java
+└── XxxMapper.xml    ← 同目录，非 resources/mapper/
+```
+
+**pom.xml 必须配置资源过滤：**
+```xml
+<build>
+    <resources>
+        <resource>
+            <directory>src/main/java</directory>
+            <includes>
+                <include>**/*.xml</include>
+            </includes>
+        </resource>
+        <resource>
+            <directory>src/main/resources</directory>
+        </resource>
+    </resources>
+</build>
+```
+
+**XML 文件示例：**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
+    "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
+<mapper namespace="net.xnzn.core.xxx.mapper.XxxMapper">
+    <select id="page" resultType="net.xnzn.core.xxx.vo.XxxVO">
+        SELECT id, name, status, crtime, uptime
+        FROM xxx_table
+        WHERE del_flag = 2
+        <if test="keyword != null and keyword != ''">
+            AND name LIKE CONCAT('%', #{keyword}, '%')
+        </if>
+    </select>
+</mapper>
+```
+
+---
+
+## 多端 Controller 路由
+
+| 端 | 路由前缀 | Controller 命名 |
+|----|---------|----------------|
+| Web 管理端 | `/api/v2/web/{module}` | `XxxWebController` |
+| 移动端 | `/api/v2/mobile/{module}` | `XxxMobileController` |
+| 设备端 | `/api/v2/android/{module}` | `XxxAndroidController` |
+| 开放接口 | `/api/v2/open/{module}` | `XxxOpenController` |
+
+---
+
+## Entity 设计
+
+```java
+package net.xnzn.core.xxx.model;
+
+@Data
+@TableName("xxx_table")
+public class XxxEntity {
+
+    @TableId(value = "id", type = IdType.ASSIGN_ID)
+    private Long id;  // 雪花ID：Id.next()
+
+    private String name;
+    private Integer status;
+
+    // 审计字段
+    @TableField(fill = FieldFill.INSERT)
+    private String crby;
+    @TableField(fill = FieldFill.INSERT)
+    private LocalDateTime crtime;
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    private String upby;
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    private LocalDateTime uptime;
+
+    // 逻辑删除：1=删除，2=正常
+    private Integer delFlag;
+}
+```
+
+### DelFlagEnum
+
+```java
+public enum DelFlagEnum {
+    DEL_TRUE(1, "删除"),
+    DEL_FALSE(2, "正常");
+
+    private final Integer key;
+    private final String val;
+}
+```
+
+### 对应建表 SQL
+
+```sql
+CREATE TABLE xxx_table (
+    id       BIGINT      NOT NULL COMMENT '主键（雪花ID）',
+    name     VARCHAR(100) COMMENT '名称',
+    status   INT          COMMENT '状态',
+    crby     VARCHAR(64)  COMMENT '创建人',
+    crtime   DATETIME     COMMENT '创建时间',
+    upby     VARCHAR(64)  COMMENT '更新人',
+    uptime   DATETIME     COMMENT '更新时间',
+    del_flag INT DEFAULT 2 COMMENT '删除标识(1-删除,2-正常)',
+    PRIMARY KEY (id)
+);
+-- 无需 tenant_id（双库物理隔离）
+```
+
+---
+
+## 请求响应封装
+
+```java
+// 请求体：LeRequest<T> 包装
+@PostMapping("/add")
+public void add(@Validated @RequestBody LeRequest<XxxDTO> request) {
+    XxxDTO dto = request.getContent();
+}
+
+// 分页请求
+@PostMapping("/query")
+public Page<XxxVO> query(@Validated @RequestBody LeRequest<PageDTO> request) {
+    return xxxService.query(request.getContent());
+}
+```
+
+### PageDTO
+
+```java
+@Data
+public class PageDTO {
+    @NotNull @Min(1)
+    private Integer pageNum;
+    @NotNull @Min(1)
+    private Integer pageSize;
+    private String keyword;
+
+    public Page<Object> getMpPage() {
+        return new Page<>(pageNum, pageSize);
+    }
+}
+```
+
+---
+
+## 异常与国际化
+
+```java
+// 业务异常
+throw new LeException("业务错误信息");
+
+// 带国际化
+throw new LeException(I18n.getMessage("error.key"));
+```
+
+---
+
+## 项目模块结构
+
+```
+leniu-tengyun-core/
+├── core-base/          # 公共基础模块
+├── sys-common/         # 公共业务（支付、通知、对接）
+├── sys-canteen/        # 食堂业务
+├── sys-kitchen/        # 后场厨房
+├── sys-drp/            # 供应链
+├── sys-logistics/      # 物流
+└── sys-open/           # 开放接口
+```
+
+### 标准包结构
+
+```
+net.xnzn.core.[module]/
+├── controller/         # 按端分：web/mobile/android
+├── business/impl/      # 业务编排
+├── service/impl/       # 服务层
+├── mapper/             # Mapper + XML（同目录）
+├── model/              # Entity
+├── vo/                 # 响应对象
+├── dto/                # 请求参数
+├── constants/          # 枚举和常量
+├── mq/                 # 消息队列
+└── task/               # 定时任务
+```
+
+---
+
+## 参考代码位置
+
+| 类型 | 路径 |
+|------|------|
+| 订单 Controller | `sys-canteen/.../order/web/controller/OrderInfoWebController.java` |
+| 订单 Business | `sys-canteen/.../order/web/business/impl/OrderWebBusiness.java` |
+| 订单 Service | `sys-canteen/.../order/common/service/impl/OrderInfoService.java` |
+| 排班 Controller | `sys-kitchen/.../attendance/scheduling/controller/BackAttendanceWorkShiftController.java` |
+| Bootstrap 配置 | `core-base/src/main/resources/bootstrap.yml` |

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

@@ -0,0 +1,277 @@
+---
+name: leniu-backend-annotations
+description: |
+  leniu-yunshitang-core 项目后端注解速查指南。包含认证、校验、Swagger、MyBatis-Plus、审计字段等注解的正确用法。
+
+  触发场景：
+  - 配置 leniu 认证注解（@RequiresAuthentication, @RequiresGuest）
+  - 配置参数校验和分组校验（InsertGroup, UpdateGroup）
+  - 配置 Swagger 文档注解（@Api, @ApiOperation）
+  - 配置 Entity 审计字段注解
+  - 排查注解使用错误（javax vs jakarta、AddGroup vs InsertGroup）
+
+  适用项目：leniu-tengyun-core（云食堂项目）
+
+  触发词：@RequiresAuthentication、@RequiresGuest、@Validated、@NotNull、@Api、@ApiOperation、InsertGroup、UpdateGroup、注解用法、审计字段注解
+---
+
+# leniu 后端注解速查
+
+## 注解总览
+
+| 注解 | 作用层 | 包路径 | 场景 |
+|------|--------|--------|------|
+| `@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. 认证注解
+
+```java
+import net.xnzn.framework.secure.filter.annotation.RequiresAuthentication;
+import net.xnzn.framework.secure.filter.annotation.RequiresGuest;
+
+@RestController
+@RequiresAuthentication                    // 类级别：所有方法默认需登录
+@RequestMapping("/api/v2/web/xxx")
+@Api(tags = "XXX管理")
+public class XxxController {
+
+    @PostMapping("/add")                   // 继承类级别：需要登录
+    @ApiOperation(value = "XXX-新增")
+    public void add(@Validated(InsertGroup.class) @RequestBody LeRequest<XxxDTO> request) {
+        xxxService.add(request.getContent());
+    }
+
+    @RequiresGuest                         // 方法级别覆盖：允许游客
+    @GetMapping("/list")
+    @ApiOperation(value = "XXX-公开列表")
+    public List<XxxVO> list() {
+        return xxxService.list();
+    }
+}
+```
+
+---
+
+## 2. 参数校验注解
+
+### 分组校验（新增/修改场景区分）
+
+```java
+// 分组接口
+public interface InsertGroup {}
+public interface UpdateGroup {}
+
+// Controller 中使用分组
+@PostMapping("/add")
+public void add(@Validated(InsertGroup.class) @RequestBody LeRequest<XxxDTO> request) {}
+
+@PostMapping("/update")
+public void update(@Validated(UpdateGroup.class) @RequestBody LeRequest<XxxDTO> request) {}
+
+// 不需要分组时用 @Valid 或 @Validated（不带参数）
+@PostMapping("/query")
+public Page<XxxVO> query(@Valid @RequestBody LeRequest<XxxQueryParam> request) {}
+```
+
+### DTO 校验字段
+
+```java
+import jakarta.validation.constraints.*;   // JDK 21 必须 jakarta
+
+@Data
+@ApiModel("XXX DTO")
+public class XxxDTO implements Serializable {
+
+    @NotNull(message = "ID不能为空", groups = {UpdateGroup.class})
+    @ApiModelProperty("主键ID")
+    private Long id;
+
+    @NotBlank(message = "名称不能为空", groups = {InsertGroup.class, UpdateGroup.class})
+    @Size(max = 100, message = "名称长度不能超过100个字符")
+    @ApiModelProperty(value = "名称", required = true)
+    private String name;
+
+    @Min(value = 0, message = "状态不能小于0")
+    @Max(value = 1, message = "状态不能大于1")
+    @ApiModelProperty("状态")
+    private Integer status;
+
+    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
+    @ApiModelProperty("手机号")
+    private String phone;
+
+    @Email(message = "邮箱格式不正确")
+    @ApiModelProperty("邮箱")
+    private String email;
+
+    @NotNull(message = "开始时间不能为空", groups = {InsertGroup.class, UpdateGroup.class})
+    @ApiModelProperty(value = "开始时间", required = true)
+    private Date startTime;
+
+    @Size(max = 500, message = "备注长度不能超过500个字符")
+    @ApiModelProperty("备注")
+    private String remark;
+}
+```
+
+---
+
+## 3. Swagger 文档注解
+
+```java
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiModelProperty;
+import io.swagger.annotations.ApiParam;
+
+// 类级别
+@Api(value = "XXX管理", tags = "XXX管理")
+public class XxxController {}
+
+// 方法级别
+@ApiOperation(value = "XXX-分页查询")
+@PostMapping("/page")
+public Page<XxxVO> page(@Valid @RequestBody LeRequest<XxxDTO> request) {}
+
+// 路径参数
+@GetMapping("/get/{id}")
+public XxxVO getById(@ApiParam(value = "主键ID", required = true) @PathVariable Long id) {}
+
+// 查询参数
+@PostMapping("/search")
+public List<XxxVO> search(@ApiParam(value = "搜索关键词") @RequestParam(required = false) String keyword) {}
+```
+
+### VO 字段文档
+
+```java
+@Data
+@ApiModel("XXX VO")
+public class XxxVO implements Serializable {
+
+    @ApiModelProperty("主键ID")
+    private Long id;
+
+    @ApiModelProperty("名称")
+    private String name;
+
+    @ApiModelProperty("创建时间")
+    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+    private Date crtime;
+}
+```
+
+---
+
+## 4. Entity 注解（MyBatis-Plus + 审计字段）
+
+```java
+import com.baomidou.mybatisplus.annotation.*;
+
+@Data
+@TableName("xxx_table")
+public class XxxEntity implements Serializable {
+
+    @ApiModelProperty("主键ID")
+    @TableId(value = "id", type = IdType.AUTO)
+    private Long id;
+
+    @ApiModelProperty("名称")
+    @TableField("name")
+    private String name;
+
+    // ===== 审计字段（leniu 标准） =====
+    @ApiModelProperty("创建人")
+    @TableField(value = "crby", fill = FieldFill.INSERT)
+    private String crby;
+
+    @ApiModelProperty("创建时间")
+    @TableField(value = "crtime", fill = FieldFill.INSERT)
+    private LocalDateTime crtime;
+
+    @ApiModelProperty("更新人")
+    @TableField(value = "upby", fill = FieldFill.INSERT_UPDATE)
+    private String upby;
+
+    @ApiModelProperty("更新时间")
+    @TableField(value = "uptime", fill = FieldFill.INSERT_UPDATE)
+    private LocalDateTime uptime;
+
+    @ApiModelProperty("删除标识(1-删除,2-正常)")
+    private Integer delFlag;
+}
+```
+
+### Mapper 接口
+
+```java
+import org.apache.ibatis.annotations.Mapper;
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+
+@Mapper
+public interface XxxMapper extends BaseMapper<XxxEntity> {}
+```
+
+---
+
+## 5. 注解组合速查
+
+| 层级 | 标准注解组合 |
+|------|-------------|
+| 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)` |
+
+---
+
+## 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`
+- [ ] 校验包：`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`
+
+---
+
+## 参考代码位置
+
+| 类型 | 路径 |
+|------|------|
+| Controller 示例 | `sys-canteen/.../order/web/controller/OrderInfoWebController.java` |
+| DTO 示例 | `sys-kitchen/.../attendance/.../dto/` |
+| Entity 示例 | `sys-canteen/.../order/common/model/OrderInfo.java` |