ai-engineering-init 1.1.0

package/.codex/skills/dev/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: dev
+description: |
+  当需要从零开始开发新功能、完整开发流程时自动使用此 Skill。
+
+  触发场景：
+  - 需要从零开始开发一个新功能
+  - 需要设计数据库表并生成代码
+  - 需要完整的开发流程引导
+  - 需要配置代码生成器并生成后端代码
+
+  触发词：开发功能、dev、新功能、功能开发、从零开发、完整开发、开发新模块
+---
+
+# /dev - 开发新功能（RuoYi-Vue-Plus 纯后端版）
+
+智能代码生成器配置助手，专为 RuoYi-Vue-Plus 三层架构（Controller→Service→Mapper）设计。
+
+## 🎯 核心优势
+- ✅ **纯后端专注**：无前端，专注后端 CRUD 代码生成
+- ✅ **包名适配**：`org.dromara.*`
+- ✅ **智能推断**：模块 → 表前缀 → 包名 → 图标自动识别
+- ✅ **全自动配置**：代码生成器配置完整（gen_table + gen_table_column）
+- ✅ **菜单权限**：自动生成完整的菜单和权限配置
+
+## 🚀 执行流程
+
+### 第一步：需求确认
+
+```
+请告诉我要开发的功能：
+
+1. **功能名称**？（如：广告管理、反馈管理）
+2. **所属模块**？（system/business/其他）
+```
+
+**自动推断**：
+
+| 模块 | 表前缀 | 包名 | 上级菜单 |
+|------|--------|------|---------|
+| system | `sys_` | `org.dromara.system` | 系统管理 |
+| business | `b_` | `org.dromara.business` | 业务管理 |
+| 其他（如 demo） | `demo_` | `org.dromara.demo` | [模块]管理 |
+
+---
+
+### 第二步：功能重复检查（强制执行）⭐⭐⭐⭐⭐
+
+**⚠️ 重要**：检查功能是否已存在，避免重复开发
+
+```bash
+# 1. 检查后端代码
+Grep pattern: "[功能名]Service" path: ruoyi-modules/ output_mode: files_with_matches
+Grep pattern: "[功能名]Controller" path: ruoyi-modules/ output_mode: files_with_matches
+
+# 2. 检查数据库表
+SHOW TABLES LIKE '[表前缀]%';
+
+# 3. 检查菜单
+SELECT menu_name FROM sys_menu WHERE menu_name LIKE '%[功能名]%';
+```
+
+---
+
+### 第三步：数据库现状分析（自动执行）
+
+从 `ruoyi-admin/src/main/resources/application-dev.yml` 动态读取数据库配置。
+
+---
+
+### 第四步：智能表结构设计
+
+#### 智能字段命名和推断
+
+| 字段后缀 | 推断结果 | 控件类型 | 查询方式 |
+|---------|---------|---------|---------|
+| `xxx_name` | 名称 | input | LIKE |
+| `xxx_title` | 标题 | input | LIKE |
+| `xxx_content` | 内容 | editor | 富文本 |
+| `status` | 状态 | select | EQ + sys_normal_disable |
+| `xxx_type` | 分类 | select | EQ + 自定义字典 |
+| `is_xxx` | 是否 | radio | EQ + sys_boolean_flag |
+| `xxx_amount` / `xxx_price` | 金额 | numberInput | EQ |
+| `xxx_time` / `xxx_date` | 时间 | datetime | BETWEEN |
+
+#### 标准表结构模板
+
+```sql
+CREATE TABLE [表前缀]_[功能名] (
+    id              BIGINT(20)   NOT NULL COMMENT '主键ID',
+    tenant_id       VARCHAR(20)  DEFAULT '000000' COMMENT '租户ID',
+
+    -- 业务字段
+    xxx_name        VARCHAR(100) NOT NULL COMMENT '名称',
+    xxx_type        CHAR(1)      DEFAULT '1' COMMENT '类型',
+    status          CHAR(1)      DEFAULT '1' COMMENT '状态(0停用 1正常)',
+
+    -- 审计字段
+    create_by       BIGINT(20)   DEFAULT NULL COMMENT '创建人',
+    create_time     DATETIME     DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    update_by       BIGINT(20)   DEFAULT NULL COMMENT '更新人',
+    update_time     DATETIME     DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+    remark          VARCHAR(500) DEFAULT NULL COMMENT '备注',
+    del_flag        CHAR(1)      DEFAULT '0' COMMENT '删除标志',
+
+    PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='xxx表';
+```
+
+---
+
+### 第五步：生成方案并确认（仅此一次确认）
+
+```markdown
+## 📋 代码生成方案
+
+### 基本配置
+- **功能名称**：广告管理
+- **模块**：business
+- **表名**：b_ad
+- **Java类名**：Ad
+- **包名**：org.dromara.business
+- **接口路径**：/business/ad
+
+### 菜单配置
+- **上级菜单**：业务管理 (menu_id: 1001)
+- **菜单顺序**：20
+- **菜单图标**：ad (自动匹配)
+
+**确认开始生成？**
+```
+
+---
+
+### 第六步：自动执行生成（无需确认）
+
+用户确认后，AI 自动执行：
+1. 建表 SQL
+2. 创建字典（如需要）
+3. 生成代码生成器配置 SQL
+
+---
+
+### 第七步：完成报告
+
+```markdown
+## 🎉 代码生成方案配置完成！
+
+### 已完成
+- ✅ 数据库表创建：b_ad
+- ✅ 业务字典创建：b_ad_type（3 个字典项）
+- ✅ 菜单配置：广告管理（自动导入启用）
+- ✅ 代码生成配置：表 + 11 个字段
+
+## 🚀 下一步：前往代码生成器生成代码
+
+1. **登录系统后台**：http://localhost:8080
+2. **导航**：系统工具 → 代码生成
+3. **查找表**：找到 `b_ad` 表
+4. **生成代码**：点击【生成代码】按钮
+5. **重启服务**：代码生成后需重启后端服务
+
+### 生成后的文件结构
+
+\`\`\`
+ruoyi-system/
+├── controller/business/AdController.java
+├── domain/Ad.java
+├── domain/bo/AdBo.java
+├── domain/vo/AdVo.java
+├── mapper/AdMapper.java
+├── service/IAdService.java
+└── service/impl/AdServiceImpl.java
+\`\`\`
+```
+
+---
+
+## ⚠️ AI 执行规则
+
+1. ✅ **仅后端**：三层架构（Controller→Service→Mapper）
+2. ✅ **包名**：必须是 `org.dromara.*`
+3. ✅ **一次确认**：第五步确认后全自动执行
+4. ✅ **tenant_id**：框架自动处理，所有权限配置为 0
+5. ✅ **检查功能重复**：禁止重复开发相同功能
+6. ✅ **智能字段推断**：根据字段名后缀自动推断控件和查询方式
+7. ✅ **字典智能处理**：检查字典存在性，不存在则创建

package/.codex/skills/error-handler/SKILL.md

@@ -0,0 +1,361 @@
+---
+name: error-handler
+description: |
+  后端异常处理规范。包含 ServiceException 用法、全局异常处理器、参数校验、日志规范、错误码设计。
+
+  触发场景：
+  - 抛出业务异常（ServiceException）
+  - 全局异常处理器配置
+  - 参数校验异常处理
+  - 日志记录规范
+  - 错误码设计与国际化
+  - 事务异常处理
+
+  触发词：异常、ServiceException、throw、错误处理、全局异常、@Validated、参数校验、日志、log、错误码、事务、@Transactional、try-catch、异常捕获
+
+  注意：
+  - 如果是安全相关（认证授权、数据脱敏），请使用 security-guard。
+  - 如果是数据权限（@DataPermission），请使用 data-permission。
+---
+
+# 后端异常处理指南
+
+> 本项目是纯后端项目，本文档专注于 Java 后端异常处理规范。
+
+---
+
+## 快速索引
+
+| 场景 | 推荐方式 |
+|------|---------|
+| 业务异常 | `throw new ServiceException("msg")` |
+| 带参数异常 | `throw new ServiceException("用户 {} 不存在", userId)` |
+| 带错误码 | `throw new ServiceException("msg", 200101)` |
+| 参数校验 | `@Validated(AddGroup.class)` |
+| 日志记录 | `log.error("msg: {}", e.getMessage(), e)` |
+
+---
+
+## 1. 业务异常 - ServiceException
+
+### 基本用法
+
+```java
+import org.dromara.common.core.exception.ServiceException;
+
+// ✅ 基本用法：抛出业务异常
+throw new ServiceException("用户不存在");
+
+// ✅ 带占位符（支持 {} 占位符，使用 Hutool StrFormatter）
+throw new ServiceException("用户 {} 不存在", userId);
+throw new ServiceException("订单 {} 状态 {} 无法支付", orderId, status);
+
+// ✅ 带错误码（第二个参数是 Integer code）
+throw new ServiceException("用户不存在", 200101);
+
+// ✅ 条件抛出（手动检查）
+if (ObjectUtil.isNull(user)) {
+    throw new ServiceException("用户不存在");
+}
+
+// ✅ 参数校验
+if (StringUtils.isBlank(bo.getName())) {
+    throw new ServiceException("名称不能为空");
+}
+```
+
+### ServiceException 完整 API
+
+> **🔴 重要**：ServiceException **没有静态工厂方法**（如 `of()`）和条件检查方法（如 `throwIf()`, `notNull()`），必须使用 `new` 关键字创建异常对象。
+
+| 构造函数 | 说明 | 示例 |
+|---------|------|------|
+| `new ServiceException(String message)` | 只有错误消息 | `new ServiceException("操作失败")` |
+| `new ServiceException(String message, Object... args)` | 带占位符参数 | `new ServiceException("用户{}不存在", userId)` |
+| `new ServiceException(String message, Integer code)` | 带错误码 | `new ServiceException("用户不存在", 200101)` |
+
+**链式调用方法**：
+- `setMessage(String message)`: 设置错误消息
+- `setDetailMessage(String detailMessage)`: 设置详细错误（用于内部调试）
+
+**源码位置**: `ruoyi-common/ruoyi-common-core/src/main/java/org/dromara/common/core/exception/ServiceException.java`
+
+---
+
+## 2. 全局异常处理器
+
+框架已提供全局异常处理器，自动捕获并处理各类异常。
+
+**位置**: `ruoyi-common/ruoyi-common-web/src/main/java/org/dromara/common/web/handler/GlobalExceptionHandler.java`
+
+### 异常处理映射
+
+> **注意**：所有异常的 HTTP 响应状态码均为 200，错误码通过 `R.code` 字段返回。
+
+| 异常类型 | 处理方式 | R.code |
+|---------|---------|--------|
+| `ServiceException` | 返回业务错误信息 | 自定义 code 或 500 |
+| `BindException` | 返回参数绑定错误 | 500 |
+| `ConstraintViolationException` | 返回参数校验错误 | 500 |
+| `MethodArgumentNotValidException` | 返回参数校验错误 | 500 |
+| `HandlerMethodValidationException` | 返回 @Validated 校验错误 | 500 |
+| `HttpRequestMethodNotSupportedException` | 请求方式不支持 | 405 |
+| `NoHandlerFoundException` | 路由不存在 | 404 |
+| `JsonParseException` | JSON 解析失败 | 400 |
+| `HttpMessageNotReadableException` | 请求参数格式错误 | 400 |
+| `ExpressionException` | SpEL 表达式解析失败 | 500 |
+| `RuntimeException` / `Exception` | 系统错误 | 500 |
+
+---
+
+## 3. 参数校验
+
+### 使用 @Validated 自动校验
+
+```java
+import org.dromara.common.core.validate.AddGroup;
+import org.dromara.common.core.validate.EditGroup;
+
+// Controller 层校验
+@PostMapping
+public R<Long> add(@Validated(AddGroup.class) @RequestBody XxxBo bo) {
+    // 参数校验失败会自动抛出异常
+    // 全局异常处理器会自动捕获并返回错误信息
+    return R.ok(xxxService.insert(bo));
+}
+
+@PutMapping
+public R<Void> edit(@Validated(EditGroup.class) @RequestBody XxxBo bo) {
+    return toAjax(xxxService.update(bo));
+}
+```
+
+### BO 类校验注解
+
+```java
+public class XxxBo extends BaseEntity {
+
+    @NotNull(message = "ID不能为空", groups = { EditGroup.class })
+    private Long id;
+
+    @NotBlank(message = "名称不能为空", groups = { AddGroup.class, EditGroup.class })
+    @Size(max = 100, message = "名称长度不能超过100个字符")
+    private String name;
+
+    @Email(message = "邮箱格式不正确")
+    private String email;
+
+    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
+    private String phone;
+
+    @Min(value = 0, message = "数量不能小于0")
+    @Max(value = 9999, message = "数量不能大于9999")
+    private Integer count;
+}
+```
+
+### 手动校验（Service 层）
+
+```java
+import org.dromara.common.core.utils.ValidatorUtils;
+
+// 手动触发校验
+ValidatorUtils.validate(bo, AddGroup.class);
+ValidatorUtils.validate(bo, EditGroup.class);
+```
+
+---
+
+## 4. 日志规范
+
+### 日志级别
+
+| 级别 | 使用场景 | 示例 |
+|------|---------|------|
+| ERROR | 系统错误、业务异常 | 数据库连接失败、第三方接口超时 |
+| WARN | 警告信息、潜在问题 | 缓存未命中、重试操作 |
+| INFO | 重要业务流程、操作记录 | 用户登录、订单创建 |
+| DEBUG | 开发调试信息 | 方法入参、中间变量 |
+| TRACE | 详细追踪信息 | 循环内部数据 |
+
+### 日志最佳实践
+
+```java
+import lombok.extern.slf4j.Slf4j;
+
+@Slf4j
+@Service
+public class XxxServiceImpl implements IXxxService {
+
+    // ✅ 好的：使用占位符（性能更好）
+    log.info("处理订单: {}, 状态: {}", orderId, status);
+
+    // ❌ 不好：字符串拼接（每次都会拼接，即使日志级别不输出）
+    log.info("处理订单: " + orderId + ", 状态: " + status);
+
+    // ✅ 好的：异常日志带堆栈（第三个参数传异常对象）
+    log.error("处理失败: {}", e.getMessage(), e);
+
+    // ❌ 不好：只记录消息，丢失堆栈
+    log.error("处理失败: {}", e.getMessage());
+
+    // ✅ 好的：判断日志级别（避免不必要的序列化开销）
+    if (log.isDebugEnabled()) {
+        log.debug("详细数据: {}", JsonUtils.toJsonString(data));
+    }
+
+    // ✅ 好的：敏感信息脱敏
+    log.info("用户登录，手机: {}", DesensitizedUtil.mobilePhone(phone));
+
+    // ❌ 不好：记录敏感信息
+    log.info("用户登录，手机: {}", phone);
+}
+```
+
+### Service 层日志示例
+
+```java
+@Slf4j
+@RequiredArgsConstructor
+@Service
+public class SysUserServiceImpl implements ISysUserService {
+
+    private final SysUserMapper baseMapper;
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public Long insertUser(SysUserBo bo) {
+        log.info("开始新增用户，用户名: {}", bo.getUserName());
+
+        // 1. 业务校验
+        SysUser existUser = baseMapper.selectUserByUserName(bo.getUserName());
+        if (ObjectUtil.isNotNull(existUser)) {
+            throw new ServiceException("用户名 {} 已存在", bo.getUserName());
+        }
+
+        // 2. 执行插入
+        SysUser user = MapstructUtils.convert(bo, SysUser.class);
+        baseMapper.insert(user);
+
+        log.info("新增用户成功，用户ID: {}, 用户名: {}", user.getUserId(), user.getUserName());
+        return user.getUserId();
+    }
+
+    @Override
+    public SysUserVo selectUserById(Long userId) {
+        SysUser user = baseMapper.selectById(userId);
+        if (ObjectUtil.isNull(user)) {
+            throw new ServiceException("用户 {} 不存在", userId);
+        }
+        return MapstructUtils.convert(user, SysUserVo.class);
+    }
+}
+```
+
+---
+
+## 5. 错误码设计
+
+### 错误码规范
+
+```java
+// 格式: 模块(2位) + 类型(2位) + 序号(2位)
+// 模块: 10-系统, 20-用户, 30-订单, 40-商品
+// 类型: 01-参数错误, 02-业务错误, 03-权限错误, 04-系统错误
+
+public class ErrorCode {
+    // 通用错误
+    public static final int SUCCESS = 200;
+    public static final int ERROR = 500;
+    public static final int UNAUTHORIZED = 401;
+    public static final int FORBIDDEN = 403;
+
+    // 用户模块 20xxxx
+    public static final int USER_NOT_FOUND = 200201;      // 用户不存在
+    public static final int USER_PASSWORD_ERROR = 200202; // 密码错误
+    public static final int USER_DISABLED = 200203;       // 用户已禁用
+
+    // 订单模块 30xxxx
+    public static final int ORDER_NOT_FOUND = 300201;     // 订单不存在
+    public static final int ORDER_STATUS_ERROR = 300202;  // 订单状态错误
+}
+
+// 使用示例
+throw new ServiceException("用户不存在", ErrorCode.USER_NOT_FOUND);
+```
+
+### 错误消息国际化
+
+```java
+import org.dromara.common.core.utils.MessageUtils;
+
+// 使用 MessageUtils.message() 获取国际化消息
+throw new ServiceException(MessageUtils.message("user.not.exists"));
+
+// 带参数的国际化消息
+throw new ServiceException(MessageUtils.message("user.password.retry.limit.exceed", maxRetryCount));
+```
+
+---
+
+## 6. 用户友好提示
+
+### 错误提示规范
+
+```java
+// ✅ 好的：用户友好提示
+throw new ServiceException("订单已发货，无法取消");
+throw new ServiceException("库存不足，请减少购买数量");
+throw new ServiceException("验证码已过期，请重新获取");
+throw new ServiceException("该用户名已被注册，请换一个试试");
+
+// ❌ 不好：技术术语
+throw new ServiceException("order.status.invalid");
+throw new ServiceException("NullPointerException at line 123");
+throw new ServiceException("数据库连接失败");
+throw new ServiceException("Duplicate entry for key 'uk_username'");
+```
+
+---
+
+## 7. 事务异常处理
+
+```java
+@Transactional(rollbackFor = Exception.class)  // 所有异常都回滚
+public void batchOperation() {
+    // 业务逻辑
+}
+
+// ✅ 好的：指定回滚异常类型
+@Transactional(rollbackFor = Exception.class)
+
+// ❌ 不好：使用默认（只回滚 RuntimeException）
+@Transactional
+```
+
+---
+
+## 错误处理检查清单
+
+- [ ] 业务异常使用 `new ServiceException()`（不是 `ServiceException.of()`）
+- [ ] 条件检查使用 `if + ObjectUtil.isNull()` 判断
+- [ ] 参数校验使用 `@Validated(XxxGroup.class)`
+- [ ] 事务方法添加 `@Transactional(rollbackFor = Exception.class)`
+- [ ] 日志记录异常堆栈：`log.error("msg: {}", e.getMessage(), e)`
+- [ ] 日志使用占位符 `{}`，不使用字符串拼接
+- [ ] 敏感信息脱敏后再记录日志
+- [ ] 重要操作记录 INFO 日志
+- [ ] 错误提示使用用户友好语言
+
+---
+
+## 快速对照表
+
+| ❌ 错误写法 | ✅ 正确写法 |
+|-----------|-----------|
+| `throw ServiceException.of("msg")` | `throw new ServiceException("msg")` |
+| `ServiceException.throwIf(cond, "msg")` | `if (cond) { throw new ServiceException("msg"); }` |
+| `ServiceException.notNull(obj, "msg")` | `if (ObjectUtil.isNull(obj)) { throw new ServiceException("msg"); }` |
+| `log.error("失败: " + e.getMessage())` | `log.error("失败: {}", e.getMessage(), e)` |
+| `@Transactional` | `@Transactional(rollbackFor = Exception.class)` |
+| `throw new ServiceException("DB error")` | `throw new ServiceException("数据保存失败，请重试")` |