leniu-dev 2.0.0

package/src/skills/database-ops/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: database-ops
+description: |
+  通用数据库操作指南。涵盖建表规范、审计字段、逻辑删除、索引设计等。
+  触发场景：建表、数据库设计、SQL 编写、数据迁移。
+  触发词：建表、数据库、SQL、DDL、数据迁移、索引。
+  注意：如果项目有专属技能（如 `leniu-database`），优先使用专属版本。
+---
+
+# 数据库操作指南
+
+> 通用模板。如果项目有专属技能（如 `leniu-database`），优先使用。
+
+## 核心规范
+
+### 建表标准模板
+
+```sql
+CREATE TABLE t_order (
+    id          BIGINT       NOT NULL                COMMENT '主键',
+    order_no    VARCHAR(64)  NOT NULL                COMMENT '订单编号',
+    status      TINYINT      NOT NULL DEFAULT 0      COMMENT '状态(0-待处理,1-已完成,2-已取消)',
+    amount      BIGINT       NOT NULL DEFAULT 0      COMMENT '金额(单位:分)',
+    remark      VARCHAR(500)          DEFAULT NULL   COMMENT '备注',
+    create_by   VARCHAR(64)           DEFAULT NULL   COMMENT '创建人',
+    create_time DATETIME              DEFAULT NULL   COMMENT '创建时间',
+    update_by   VARCHAR(64)           DEFAULT NULL   COMMENT '更新人',
+    update_time DATETIME              DEFAULT NULL   COMMENT '更新时间',
+    deleted     TINYINT      NOT NULL DEFAULT 0      COMMENT '删除标识(0-正常,1-删除)',
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_order_no (order_no),
+    KEY idx_status (status),
+    KEY idx_create_time (create_time)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='订单表';
+```
+
+### 审计字段规范
+
+| 字段 | 类型 | 说明 | 填充时机 |
+|------|------|------|---------|
+| `create_by` | VARCHAR(64) | 创建人 | INSERT |
+| `create_time` | DATETIME | 创建时间 | INSERT |
+| `update_by` | VARCHAR(64) | 更新人 | INSERT / UPDATE |
+| `update_time` | DATETIME | 更新时间 | INSERT / UPDATE |
+| `deleted` | TINYINT | 逻辑删除 | 手动 / 框架自动 |
+
+> 审计字段自动填充可通过 MyBatis-Plus 的 `MetaObjectHandler` 实现。
+
+### 逻辑删除
+
+- `deleted = 0` 表示正常
+- `deleted = 1` 表示已删除
+- MyBatis-Plus 配置：
+
+```yaml
+mybatis-plus:
+  global-config:
+    db-config:
+      logic-delete-field: deleted
+      logic-delete-value: 1
+      logic-not-delete-value: 0
+```
+
+### 命名规范
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 表名 | 小写下划线，建议加前缀 | `t_order`, `sys_user` |
+| 字段名 | 小写下划线 | `order_no`, `create_time` |
+| 主键 | `id` | `id BIGINT NOT NULL` |
+| 外键字段 | `关联表_id` | `user_id`, `order_id` |
+| 唯一索引 | `uk_字段名` | `uk_order_no` |
+| 普通索引 | `idx_字段名` | `idx_status` |
+| 联合索引 | `idx_字段1_字段2` | `idx_user_id_status` |
+
+## 代码示例
+
+### 审计字段自动填充
+
+```java
+@Component
+public class MyMetaObjectHandler implements MetaObjectHandler {
+
+    @Override
+    public void insertFill(MetaObject metaObject) {
+        this.strictInsertFill(metaObject, "createTime", LocalDateTime.class, LocalDateTime.now());
+        this.strictInsertFill(metaObject, "createBy", String.class, getCurrentUser());
+        this.strictInsertFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());
+        this.strictInsertFill(metaObject, "updateBy", String.class, getCurrentUser());
+    }
+
+    @Override
+    public void updateFill(MetaObject metaObject) {
+        this.strictUpdateFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());
+        this.strictUpdateFill(metaObject, "updateBy", String.class, getCurrentUser());
+    }
+
+    private String getCurrentUser() {
+        // 从安全上下文获取当前用户，按项目实际实现
+        return [你的用户上下文工具].getCurrentUsername();
+    }
+}
+```
+
+### 常见数据库设计模式
+
+#### 模式一：树结构 - 祖先路径法
+
+```sql
+CREATE TABLE t_org (
+    id          BIGINT       NOT NULL              COMMENT '主键',
+    parent_id   BIGINT                DEFAULT NULL COMMENT '父节点ID',
+    ancestors   VARCHAR(500)          DEFAULT NULL COMMENT '祖先路径(逗号分隔)',
+    name        VARCHAR(100) NOT NULL              COMMENT '节点名称',
+    sort        INT          NOT NULL DEFAULT 0    COMMENT '排序',
+    create_by   VARCHAR(64)           DEFAULT NULL COMMENT '创建人',
+    create_time DATETIME              DEFAULT NULL COMMENT '创建时间',
+    update_by   VARCHAR(64)           DEFAULT NULL COMMENT '更新人',
+    update_time DATETIME              DEFAULT NULL COMMENT '更新时间',
+    deleted     TINYINT      NOT NULL DEFAULT 0    COMMENT '删除标识(0-正常,1-删除)',
+    PRIMARY KEY (id),
+    KEY idx_parent_id (parent_id),
+    KEY idx_ancestors (ancestors(255))
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='组织树';
+```
+
+#### 模式二：关联表（多对多）
+
+```sql
+CREATE TABLE t_user_role (
+    id      BIGINT NOT NULL              COMMENT '主键',
+    user_id BIGINT NOT NULL              COMMENT '用户ID',
+    role_id BIGINT NOT NULL              COMMENT '角色ID',
+    create_time DATETIME DEFAULT NULL    COMMENT '创建时间',
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_user_role (user_id, role_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户角色关联';
+```
+
+#### 模式三：状态字段（枚举驱动）
+
+```java
+@Getter
+@AllArgsConstructor
+public enum OrderStatusEnum {
+
+    PENDING(0, "待处理"),
+    COMPLETED(1, "已完成"),
+    CANCELLED(2, "已取消");
+
+    private final int code;
+    private final String desc;
+}
+
+// SQL 字段
+// status TINYINT NOT NULL DEFAULT 0 COMMENT '状态(0-待处理,1-已完成,2-已取消)'
+```
+
+### 常见查询模式
+
+```sql
+-- 分页查询（配合 MyBatis-Plus Page）
+SELECT id, order_no, status, amount, create_time
+FROM t_order
+WHERE deleted = 0
+  AND status = #{status}
+ORDER BY create_time DESC;
+
+-- 批量插入
+INSERT INTO t_order (id, order_no, status, amount, create_by, create_time, deleted)
+VALUES
+    (#{id1}, #{orderNo1}, 0, #{amount1}, #{createBy}, NOW(), 0),
+    (#{id2}, #{orderNo2}, 0, #{amount2}, #{createBy}, NOW(), 0);
+
+-- 逻辑删除
+UPDATE t_order SET deleted = 1, update_by = #{updateBy}, update_time = NOW()
+WHERE id = #{id} AND deleted = 0;
+```
+
+### 索引设计原则
+
+1. **必须有主键**：推荐 BIGINT 雪花 ID 或自增
+2. **高频查询字段建索引**：WHERE、JOIN、ORDER BY 中的字段
+3. **联合索引遵循最左前缀**：把区分度高的字段放前面
+4. **避免在大文本字段上建索引**：TEXT、BLOB 等
+5. **控制单表索引数量**：建议不超过 5-6 个
+
+### 数据迁移脚本规范
+
+```sql
+-- V1.0.1__add_order_remark.sql
+-- 描述：订单表新增备注字段
+-- 作者：xxx
+-- 日期：2024-01-01
+
+ALTER TABLE t_order ADD COLUMN remark VARCHAR(500) DEFAULT NULL COMMENT '备注' AFTER amount;
+```
+
+## 常见错误
+
+| 错误 | 正确做法 |
+|------|---------|
+| 用 VARCHAR 存金额 | 用 BIGINT 存分，或 DECIMAL(10,2) |
+| 字段不加 COMMENT | 所有字段必须有注释 |
+| 表没有主键 | 每张表必须有主键 |
+| 用 UUID 做主键 | 推荐 BIGINT（索引友好） |
+| 逻辑删除值搞反 | 确认项目约定（通用：0=正常, 1=删除） |
+| 大表无索引 | 根据查询模式建立合适索引 |
+| 字段允许 NULL 但业务不允许 | 加 NOT NULL 约束 + DEFAULT 值 |
+| 直接物理删除数据 | 使用逻辑删除，保留数据可追溯 |

package/src/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/src/skills/error-handler/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: error-handler
+description: |
+  通用异常处理指南。涵盖自定义业务异常、全局异常处理器、参数校验等。
+  触发场景：异常设计、错误处理、参数校验、全局异常捕获。
+  触发词：异常处理、错误处理、参数校验、validation、异常捕获。
+  注意：如果项目有专属技能（如 `leniu-error-handler`），优先使用专属版本。
+---
+
+# 异常处理指南
+
+> 通用模板。如果项目有专属技能（如 `leniu-error-handler`），优先使用。
+
+## 核心规范
+
+### 异常分层设计
+
+```
+RuntimeException
+└── BusinessException          # 业务异常基类
+    ├── NotFoundException      # 资源不存在 (404)
+    ├── ForbiddenException     # 无权限 (403)
+    ├── BadRequestException    # 参数错误 (400)
+    └── ConflictException      # 数据冲突 (409)
+```
+
+### 异常处理原则
+
+1. **业务异常用自定义异常类**，不要直接抛 `RuntimeException`
+2. **全局统一捕获**，通过 `@RestControllerAdvice` 处理
+3. **区分异常层级**：Controller 层不 try-catch（交给全局处理器），Service 层只捕获需要转换的异常
+4. **异常信息面向用户**：不暴露堆栈、SQL 等技术细节
+5. **日志记录完整**：异常日志包含完整上下文和堆栈
+
+## 代码示例
+
+### 1. 自定义业务异常
+
+```java
+package [你的包名].exception;
+
+import lombok.Getter;
+
+@Getter
+public class BusinessException extends RuntimeException {
+
+    private final int code;
+
+    public BusinessException(String message) {
+        super(message);
+        this.code = 500;
+    }
+
+    public BusinessException(int code, String message) {
+        super(message);
+        this.code = code;
+    }
+
+    public BusinessException(int code, String message, Throwable cause) {
+        super(message, cause);
+        this.code = code;
+    }
+}
+```
+
+```java
+package [你的包名].exception;
+
+public class NotFoundException extends BusinessException {
+
+    public NotFoundException(String message) {
+        super(404, message);
+    }
+
+    public static NotFoundException of(String resource, Object id) {
+        return new NotFoundException(resource + " 不存在: " + id);
+    }
+}
+```
+
+### 2. 全局异常处理器
+
+```java
+package [你的包名].handler;
+
+import [你的包名].exception.BusinessException;
+import [你的包名].exception.NotFoundException;
+import jakarta.validation.ConstraintViolation;
+import jakarta.validation.ConstraintViolationException;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.validation.FieldError;
+import org.springframework.web.bind.MethodArgumentNotValidException;
+import org.springframework.web.bind.MissingServletRequestParameterException;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+import java.util.Map;
+import java.util.stream.Collectors;
+
+@Slf4j
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    /**
+     * 业务异常
+     */
+    @ExceptionHandler(BusinessException.class)
+    public ResponseEntity<Result<Void>> handleBusinessException(BusinessException e) {
+        log.warn("业务异常: {}", e.getMessage());
+        return ResponseEntity
+                .status(HttpStatus.BAD_REQUEST)
+                .body(Result.fail(e.getCode(), e.getMessage()));
+    }
+
+    /**
+     * 资源不存在
+     */
+    @ExceptionHandler(NotFoundException.class)
+    public ResponseEntity<Result<Void>> handleNotFoundException(NotFoundException e) {
+        log.warn("资源不存在: {}", e.getMessage());
+        return ResponseEntity
+                .status(HttpStatus.NOT_FOUND)
+                .body(Result.fail(404, e.getMessage()));
+    }
+
+    /**
+     * @RequestBody 参数校验失败
+     */
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ResponseEntity<Result<Map<String, String>>> handleValidationException(
+            MethodArgumentNotValidException e) {
+        Map<String, String> errors = e.getBindingResult().getFieldErrors().stream()
+                .collect(Collectors.toMap(
+                        FieldError::getField,
+                        fe -> fe.getDefaultMessage() != null ? fe.getDefaultMessage() : "校验失败",
+                        (v1, v2) -> v1
+                ));
+        log.warn("参数校验失败: {}", errors);
+        return ResponseEntity
+                .status(HttpStatus.BAD_REQUEST)
+                .body(Result.fail(400, "参数校验失败"));
+    }
+
+    /**
+     * @RequestParam / @PathVariable 校验失败
+     */
+    @ExceptionHandler(ConstraintViolationException.class)
+    public ResponseEntity<Result<Void>> handleConstraintViolation(ConstraintViolationException e) {
+        String message = e.getConstraintViolations().stream()
+                .map(ConstraintViolation::getMessage)
+                .collect(Collectors.joining("; "));
+        log.warn("约束校验失败: {}", message);
+        return ResponseEntity
+                .status(HttpStatus.BAD_REQUEST)
+                .body(Result.fail(400, message));
+    }
+
+    /**
+     * 缺少请求参数
+     */
+    @ExceptionHandler(MissingServletRequestParameterException.class)
+    public ResponseEntity<Result<Void>> handleMissingParam(MissingServletRequestParameterException e) {
+        log.warn("缺少请求参数: {}", e.getParameterName());
+        return ResponseEntity
+                .status(HttpStatus.BAD_REQUEST)
+                .body(Result.fail(400, "缺少参数: " + e.getParameterName()));
+    }
+
+    /**
+     * 兜底：未知异常
+     */
+    @ExceptionHandler(Exception.class)
+    public ResponseEntity<Result<Void>> handleException(Exception e) {
+        log.error("系统异常", e);
+        return ResponseEntity
+                .status(HttpStatus.INTERNAL_SERVER_ERROR)
+                .body(Result.fail(500, "系统繁忙，请稍后重试"));
+    }
+}
+```
+
+### 3. 参数校验（jakarta.validation）
+
+```java
+package [你的包名].dto;
+
+import jakarta.validation.constraints.*;
+import lombok.Data;
+
+@Data
+public class UserCreateDTO {
+
+    @NotBlank(message = "用户名不能为空")
+    @Size(min = 2, max = 32, message = "用户名长度 2-32 位")
+    private String username;
+
+    @NotBlank(message = "邮箱不能为空")
+    @Email(message = "邮箱格式不正确")
+    private String email;
+
+    @NotNull(message = "年龄不能为空")
+    @Min(value = 1, message = "年龄最小为 1")
+    @Max(value = 150, message = "年龄最大为 150")
+    private Integer age;
+
+    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
+    private String phone;
+}
+```
+
+**Controller 中使用**：
+```java
+@PostMapping
+public ResponseEntity<Result<Long>> create(@Valid @RequestBody UserCreateDTO dto) {
+    return ResponseEntity.ok(Result.ok(userService.create(dto)));
+}
+```
+
+### 4. 分组校验
+
+```java
+public interface CreateGroup {}
+public interface UpdateGroup {}
+
+@Data
+public class UserDTO {
+
+    @Null(groups = CreateGroup.class, message = "创建时不能指定 ID")
+    @NotNull(groups = UpdateGroup.class, message = "更新时必须指定 ID")
+    private Long id;
+
+    @NotBlank(groups = {CreateGroup.class, UpdateGroup.class})
+    private String username;
+}
+
+// Controller 使用
+@PostMapping
+public Result<Long> create(@Validated(CreateGroup.class) @RequestBody UserDTO dto) { ... }
+
+@PutMapping("/{id}")
+public Result<Void> update(@Validated(UpdateGroup.class) @RequestBody UserDTO dto) { ... }
+```
+
+### 5. Service 层异常使用
+
+```java
+@Service
+public class UserServiceImpl implements IUserService {
+
+    @Override
+    public UserVO getById(Long id) {
+        User user = userMapper.selectById(id);
+        if (user == null) {
+            throw NotFoundException.of("用户", id);
+        }
+        // ... 转换为 VO
+        return userVO;
+    }
+
+    @Override
+    public void updateEmail(Long id, String email) {
+        // 检查邮箱是否已被使用
+        User existing = userMapper.selectByEmail(email);
+        if (existing != null && !existing.getId().equals(id)) {
+            throw new BusinessException(409, "邮箱已被其他用户使用");
+        }
+        // ... 更新逻辑
+    }
+}
+```
+
+### 6. 日志规范
+
+```java
+@Slf4j
+@Service
+public class OrderServiceImpl {
+
+    // 使用占位符（性能更好）
+    log.info("创建订单: orderNo={}, amount={}", dto.getOrderNo(), dto.getAmount());
+
+    // 异常日志带堆栈（第三个参数传异常对象）
+    log.error("处理失败: {}", e.getMessage(), e);
+
+    // 事务方法：所有异常都回滚
+    @Transactional(rollbackFor = Exception.class)
+    public void createOrder(OrderCreateDTO dto) {
+        log.info("开始创建订单, orderNo={}", dto.getOrderNo());
+        // ... 业务逻辑
+        log.info("订单创建成功, id={}", order.getId());
+    }
+}
+```
+
+## 常见错误
+
+| 错误 | 正确做法 |
+|------|---------|
+| 抛 `RuntimeException("xxx")` | 使用自定义业务异常类 |
+| Controller 里 try-catch 所有异常 | 交给 `@RestControllerAdvice` 统一处理 |
+| 异常信息暴露 SQL / 堆栈 | 对用户返回友好提示，日志记录完整信息 |
+| 用 `javax.validation` 包 | JDK 17+ 使用 `jakarta.validation` |
+| 吞掉异常：`catch (Exception e) {}` | 至少记录日志 `log.error("...", e)` |
+| 所有异常都返回 200 状态码 | 根据异常类型返回对应 HTTP 状态码 |
+| 用 `e.getMessage()` 直接返回给用户 | 第三方异常信息可能包含敏感信息，需要包装 |
+| 校验逻辑写在 Controller 里 | 用 `@Valid` + DTO 注解声明式校验 |
+| 日志用字符串拼接 `"失败:" + msg` | 用占位符 `log.error("失败: {}", msg, e)` |
+| `@Transactional` 不指定回滚 | 加 `rollbackFor = Exception.class` |