@llryiop/avatar-boot-cli 1.0.1 → 1.0.2

package/templates/.claude/skills/avatar-boot-starter-web/references//351/205/215/347/275/256/345/217/202/350/200/203.md

@@ -0,0 +1,107 @@
+# 配置参考
+
+## 完整配置项
+
+```yaml
+avatar:
+  web:
+    # 是否启用请求拦截器（默认: true）
+    interceptor-enabled: true
+
+    # 是否启用全局异常处理（默认: true）
+    exception-handler-enabled: true
+
+    # 拦截器配置
+    interceptor:
+      # TraceId 请求头名称（默认: X-Trace-Id）
+      trace-id-header: X-Trace-Id
+
+      # 拦截路径（默认: /**）
+      include-paths:
+        - /**
+
+      # 排除路径
+      exclude-paths:
+        - /error
+        - /actuator/**
+        - /swagger-ui/**
+        - /v3/api-docs/**
+
+    # 日志配置
+    log:
+      # 是否记录请求日志（默认: false）
+      request-enabled: false
+
+      # 是否记录响应日志（默认: false）
+      response-enabled: false
+
+      # 慢请求阈值（毫秒，默认: 3000）
+      slow-request-threshold: 3000
+
+    # 指标监控配置
+    metrics:
+      # 是否启用指标记录（默认: true，需要 Micrometer）
+      enabled: true
+```
+
+## 常用场景配置
+
+### 只拦截 /api/** 路径
+
+```yaml
+avatar:
+  web:
+    interceptor:
+      include-paths:
+        - /api/**
+      exclude-paths:
+        - /api/public/**
+        - /health
+```
+
+### 开启请求/响应日志（调试用）
+
+```yaml
+avatar:
+  web:
+    log:
+      request-enabled: true
+      response-enabled: true
+```
+
+> 生产环境建议关闭，避免敏感数据写入日志。
+
+### 调整慢请求阈值
+
+```yaml
+avatar:
+  web:
+    log:
+      slow-request-threshold: 5000  # 5秒
+```
+
+### 关闭全局异常处理（自行实现时）
+
+```yaml
+avatar:
+  web:
+    exception-handler-enabled: false
+```
+
+### 关闭指标监控
+
+```yaml
+avatar:
+  web:
+    metrics:
+      enabled: false
+```
+
+### 自定义 TraceId 请求头名称
+
+```yaml
+avatar:
+  web:
+    interceptor:
+      trace-id-header: X-Request-Id  # 改为自定义名称
+```

package/templates/.claude/skills/crud-generator/SKILL.md

@@ -20,25 +20,25 @@ description: |
 ### 方式一：提供表 DDL
 
 ```sql
-CREATE TABLE t_user (
-    id BIGINT NOT NULL COMMENT '主键ID',
-    username VARCHAR(64) NOT NULL COMMENT '用户名',
-    email VARCHAR(128) DEFAULT NULL COMMENT '邮箱',
-    phone VARCHAR(20) DEFAULT NULL COMMENT '手机号',
-    status TINYINT NOT NULL DEFAULT 1 COMMENT '状态：0-禁用 1-启用',
-    create_time DATETIME NOT NULL COMMENT '创建时间',
-    update_time DATETIME NOT NULL COMMENT '更新时间',
-    is_deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除：0-未删除 1-已删除',
-    PRIMARY KEY (id),
-    UNIQUE KEY uk_username (username),
-    KEY idx_email (email)
+CREATE TABLE zz_plt_user (
+                             id BIGINT NOT NULL COMMENT '主键ID',
+                             username VARCHAR(64) NOT NULL COMMENT '用户名',
+                             email VARCHAR(128) DEFAULT NULL COMMENT '邮箱',
+                             phone VARCHAR(20) DEFAULT NULL COMMENT '手机号',
+                             status TINYINT NOT NULL DEFAULT 1 COMMENT '状态：0-禁用 1-启用',
+                             create_time DATETIME NOT NULL COMMENT '创建时间',
+                             update_time DATETIME NOT NULL COMMENT '更新时间',
+                             is_deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除：0-未删除 1-已删除',
+                             PRIMARY KEY (id),
+                             UNIQUE KEY uk_username (username),
+                             KEY idx_email (email)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';
 ```
 
 ### 方式二：提供表结构描述
 
 ```
-表名: t_user (用户表)
+表名: zz_plt_user (用户表)
 字段:
 - username: 用户名, VARCHAR(64), 必填, 唯一
 - email: 邮箱, VARCHAR(128), 可选
@@ -52,7 +52,7 @@ CREATE TABLE t_user (
 
 ## 输出文件列表
 
-以 `t_user` 表为例，生成的文件按垂直功能组织：
+以 `zz_plt_user` 表为例，生成的文件按垂直功能组织：
 
 ### API 模块 (`avatar-api`)
 
@@ -68,23 +68,57 @@ CREATE TABLE t_user (
 
 | 文件 | 路径 |
 |------|------|
-| Entity | `com/iflytek/avatar/dao/beans/User.java` |
-| Mapper | `com/iflytek/avatar/dao/mapper/UserMapper.java` |
+| Entity | `com/iflytek/avatar/repository/entity/UserEntity.java` |
+| Mapper | `com/iflytek/avatar/repository/mapper/UserMapper.java` |
+| Repository | `com/iflytek/avatar/repository/UserRepository.java` |
 | Service 接口 | `com/iflytek/avatar/service/UserService.java` |
 | Service 实现 | `com/iflytek/avatar/service/impl/UserServiceImpl.java` |
 | Controller | `com/iflytek/avatar/controller/UserController.java` |
 
 ---
 
+## 架构设计原则
+
+### Repository 层设计模式
+
+本项目采用 **Repository 模式** 进行数据访问层的封装：
+
+- **Repository 是唯一可以修改数据的类**：所有数据库操作必须通过 Repository 层进行
+- **Service 层通过 Repository 访问数据**：Service 不直接使用 Mapper，而是依赖 Repository
+- **Repository 继承 ServiceImpl**：Repository 类继承 `ServiceImpl<Mapper, Entity>`，封装 MyBatis Plus 的 CRUD 能力
+- **目录结构**：
+    - `repository/` - Repository 类（数据访问层封装）
+    - `repository/entity/` - Entity 实体类
+    - `repository/mapper/` - MyBatis Mapper 接口
+
+### 分层职责
+
+```
+Controller → Service → Repository → Mapper → Database
+    ↓          ↓           ↓
+Request DTO  业务逻辑    数据访问封装
+Response DTO
+```
+
+- **Controller**：参数校验、Result 封装
+- **Service**：业务逻辑编排、事务管理
+- **Repository**：数据访问封装、CRUD 操作（唯一可以修改数据的层）
+- **Mapper**：MyBatis 接口定义
+
+---
+
 ## 代码模板
 
-### 1. Entity — `dao/beans/User.java`
+### 1. Entity — `repository/entity/UserEntity.java`
 
 ```java
-package com.iflytek.avatar.dao.beans;
+package com.iflytek.avatar.repository.entity;
 
 import com.baomidou.mybatisplus.annotation.*;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
 import lombok.Data;
+import lombok.NoArgsConstructor;
 
 import java.time.LocalDateTime;
 
@@ -94,8 +128,11 @@ import java.time.LocalDateTime;
  * @author avatar-generator
  */
 @Data
-@TableName("t_user")
-public class User {
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+@TableName("zz_plt_user")
+public class UserEntity {
 
     /**
      * 主键ID
@@ -143,13 +180,13 @@ public class User {
 }
 ```
 
-### 2. Mapper — `dao/mapper/UserMapper.java`
+### 2. Mapper — `repository/mapper/UserMapper.java`
 
 ```java
-package com.iflytek.avatar.dao.mapper;
+package com.iflytek.avatar.repository.mapper;
 
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
-import com.iflytek.avatar.dao.beans.User;
+import com.iflytek.avatar.repository.entity.UserEntity;
 import org.apache.ibatis.annotations.Mapper;
 
 /**
@@ -158,19 +195,45 @@ import org.apache.ibatis.annotations.Mapper;
  * @author avatar-generator
  */
 @Mapper
-public interface UserMapper extends BaseMapper<User> {
+public interface UserMapper extends BaseMapper<UserEntity> {
 
 }
 ```
 
-### 3. Service 接口 — `service/UserService.java`
+### 3. Repository — `repository/UserRepository.java`
+
+```java
+package com.iflytek.avatar.repository;
+
+import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
+import com.iflytek.avatar.repository.entity.UserEntity;
+import com.iflytek.avatar.repository.mapper.UserMapper;
+import org.springframework.stereotype.Component;
+
+/**
+ * 用户数据访问层（Repository 层）
+ *
+ * 🔴 重要：Repository 是唯一可以修改数据的类
+ * - 所有数据库操作必须通过 Repository 进行
+ * - Service 层通过 Repository 访问数据，不直接使用 Mapper
+ * - 继承 ServiceImpl 封装 MyBatis Plus 的 CRUD 能力
+ *
+ * @author avatar-generator
+ */
+@Component
+public class UserRepository extends ServiceImpl<UserMapper, UserEntity> {
+
+    // 可以在这里添加自定义的数据访问方法
+    // 例如：复杂查询、批量操作等
+}
+```
+
+### 4. Service 接口 — `service/UserService.java`
 
 ```java
 package com.iflytek.avatar.service;
 
 import com.baomidou.mybatisplus.core.metadata.IPage;
-import com.baomidou.mybatisplus.extension.service.IService;
-import com.iflytek.avatar.dao.beans.User;
 import com.iflytek.avatar.entity.request.UserCreateRequest;
 import com.iflytek.avatar.entity.request.UserPageRequest;
 import com.iflytek.avatar.entity.request.UserUpdateRequest;
@@ -181,7 +244,7 @@ import com.iflytek.avatar.entity.response.UserResponse;
  *
  * @author avatar-generator
  */
-public interface UserService extends IService<User> {
+public interface UserService {
 
     /**
      * 创建用户
@@ -225,7 +288,7 @@ public interface UserService extends IService<User> {
 }
 ```
 
-### 4. ServiceImpl — `service/impl/UserServiceImpl.java`
+### 5. ServiceImpl — `service/impl/UserServiceImpl.java`
 
 ```java
 package com.iflytek.avatar.service.impl;
@@ -233,13 +296,12 @@ package com.iflytek.avatar.service.impl;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.baomidou.mybatisplus.core.metadata.IPage;
 import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
-import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
-import com.iflytek.avatar.dao.beans.User;
-import com.iflytek.avatar.dao.mapper.UserMapper;
 import com.iflytek.avatar.entity.request.UserCreateRequest;
 import com.iflytek.avatar.entity.request.UserPageRequest;
 import com.iflytek.avatar.entity.request.UserUpdateRequest;
 import com.iflytek.avatar.entity.response.UserResponse;
+import com.iflytek.avatar.repository.UserRepository;
+import com.iflytek.avatar.repository.entity.UserEntity;
 import com.iflytek.avatar.service.UserService;
 import lombok.RequiredArgsConstructor;
 import org.springframework.beans.BeanUtils;
@@ -251,81 +313,87 @@ import java.util.Objects;
 /**
  * 用户表 Service 实现类
  *
+ * 🔴 重要：Service 层通过 Repository 访问数据
+ * - 不直接使用 Mapper，而是依赖 Repository
+ * - Repository 是唯一可以修改数据的类
+ *
  * @author avatar-generator
  */
 @Service
 @RequiredArgsConstructor
-public class UserServiceImpl extends ServiceImpl<UserMapper, User> implements UserService {
+public class UserServiceImpl implements UserService {
+
+    private final UserRepository userRepository;
 
     @Override
     @Transactional(rollbackFor = Exception.class)
     public UserResponse create(UserCreateRequest request) {
-        User user = new User();
-        BeanUtils.copyProperties(request, user);
-        this.save(user);
-        return toResponse(user);
+        UserEntity entity = new UserEntity();
+        BeanUtils.copyProperties(request, entity);
+        userRepository.save(entity);
+        return toResponse(entity);
     }
 
     @Override
     @Transactional(readOnly = true)
     public UserResponse getDetail(Long id) {
-        User user = this.getById(id);
-        if (Objects.isNull(user)) {
+        UserEntity entity = userRepository.getById(id);
+        if (Objects.isNull(entity)) {
             throw new RuntimeException("用户不存在，ID: " + id);
         }
-        return toResponse(user);
+        return toResponse(entity);
     }
 
     @Override
     @Transactional(rollbackFor = Exception.class)
     public UserResponse update(Long id, UserUpdateRequest request) {
-        User user = this.getById(id);
-        if (Objects.isNull(user)) {
+        UserEntity entity = userRepository.getById(id);
+        if (Objects.isNull(entity)) {
             throw new RuntimeException("用户不存在，ID: " + id);
         }
-        BeanUtils.copyProperties(request, user);
-        user.setId(id);
-        this.updateById(user);
-        return toResponse(user);
+        BeanUtils.copyProperties(request, entity);
+        entity.setId(id);
+        userRepository.updateById(entity);
+        return toResponse(entity);
     }
 
     @Override
     @Transactional(rollbackFor = Exception.class)
     public void delete(Long id) {
-        User user = this.getById(id);
-        if (Objects.isNull(user)) {
+        UserEntity entity = userRepository.getById(id);
+        if (Objects.isNull(entity)) {
             throw new RuntimeException("用户不存在，ID: " + id);
         }
-        this.removeById(id);
+        userRepository.removeById(id);
     }
 
     @Override
     @Transactional(readOnly = true)
     public IPage<UserResponse> page(UserPageRequest request) {
-        Page<User> page = new Page<>(request.getPageNum(), request.getPageSize());
-        LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>();
+        Page<UserEntity> page = new Page<>(request.getPageNum(), request.getPageSize());
+        LambdaQueryWrapper<UserEntity> wrapper = new LambdaQueryWrapper<>();
 
         // 条件查询（按需添加）
         if (request.getUsername() != null) {
-            wrapper.like(User::getUsername, request.getUsername());
+            wrapper.like(UserEntity::getUsername, request.getUsername());
         }
         if (request.getStatus() != null) {
-            wrapper.eq(User::getStatus, request.getStatus());
+            wrapper.eq(UserEntity::getStatus, request.getStatus());
         }
 
         // 默认按创建时间倒序
-        wrapper.orderByDesc(User::getCreateTime);
+        wrapper.orderByDesc(UserEntity::getCreateTime);
 
-        IPage<User> result = this.page(page, wrapper);
+        IPage<UserEntity> result = userRepository.page(page, wrapper);
         return result.convert(this::toResponse);
     }
 
     /**
      * Entity 转 Response DTO
      */
-    private UserResponse toResponse(User user) {
+    private UserResponse toResponse(UserEntity entity) {
         UserResponse response = new UserResponse();
-        BeanUtils.copyProperties(user, response);
+        BeanUtils.copyProperties(entity, response);
         return response;
     }
 }
@@ -723,7 +791,7 @@ class UserServiceTest {
 
 ```
 请根据以下 DDL 只生成 Entity 和 Mapper：
-CREATE TABLE t_order (...);
+CREATE TABLE zz_plt_order (...);
 ```
 
 ### 自定义字段映射
@@ -752,16 +820,17 @@ throw new BusinessException(ErrorCode.USER_NOT_FOUND, "用户不存在，ID: " +
 ---
 
 ## 命名转换规则
+表名规则 {部门}_{业务域}_{实体}, 转成类名直接是{实体}
 
 | 数据库命名 | Java 命名 | 示例 |
 |-----------|-----------|------|
-| 表名 `t_user_order` | 类名 `UserOrder` | 去掉 `t_` 前缀，转 PascalCase |
+| 表名 `zz_plt_user_order` | 类名 `UserOrder` | 去掉 `t_` 前缀，转 PascalCase |
 | 列名 `user_name` | 字段名 `userName` | 转 camelCase |
-| 表名 `t_user` | URL `/api/v1/users` | 去掉 `t_` 前缀，复数形式 |
-| 表名 `t_user` | Mapper `UserMapper` | 类名 + Mapper |
-| 表名 `t_user` | Service `UserService` | 类名 + Service |
-| 表名 `t_user` | ServiceImpl `UserServiceImpl` | 类名 + ServiceImpl |
-| 表名 `t_user` | Controller `UserController` | 类名 + Controller |
+| 表名 `zz_plt_user` | URL `/api/v1/users` | 去掉 `t_` 前缀，复数形式 |
+| 表名 `zz_plt_user` | Mapper `UserMapper` | 类名 + Mapper |
+| 表名 `zz_plt_user` | Service `UserService` | 类名 + Service |
+| 表名 `zz_plt_user` | ServiceImpl `UserServiceImpl` | 类名 + ServiceImpl |
+| 表名 `zz_plt_user` | Controller `UserController` | 类名 + Controller |
 
 ---
 

package/templates/.claude/skills/database-design/README.md

@@ -0,0 +1,207 @@
+# MySQL 建表语句生成器 Skill
+
+MySQL 建表语句自动生成工具，帮助开发者快速创建符合 Avatar Boot 规范的标准数据库表结构。
+
+## 适用对象
+
+- **后端开发**：需要创建新的数据库表
+- **架构设计**：设计数据库表结构
+- **新成员**：快速了解建表规范并生成标准 SQL
+
+## 快速开始
+
+将本目录复制到项目的 `.claude/skills/` 或全局 `~/.claude/skills/` 目录，在 Claude Code 中描述需求即可触发：
+
+- "帮我创建一个用户表"
+- "生成一个角色表的建表语句"
+- "创建一个文章和标签的关联表"
+- "检查这个建表语句是否符合规范"
+
+## 功能覆盖
+
+| 功能 | 说明 |
+|:--|:--|
+| 创建新表 | 自动生成符合规范的完整建表语句 |
+| 生成关联表 | 创建中间表/关联表的标准结构 |
+| 验证表结构 | 检查现有建表语句是否符合规范 |
+| 查看规范 | 快速查阅命名、字段、索引规范 |
+
+## 核心特性
+
+### 1. 智能询问
+通过交互式问答收集必要信息：
+- 所属部门（讯飞智作、交互平台、资产平台、大模型）
+- 业务域（平台、用户、内容等）
+- 实体名称（角色、用户、文章等）
+- 业务字段（根据实际需求）
+
+### 2. 自动生成
+根据规范自动生成：
+- 标准表名（`{部门}_{业务域}_{实体}`）
+- 基础字段（id, created_at, updated_at, is_deleted）
+- 可选审计字段（created_by, updated_by）
+- 合适的索引（主键、唯一索引、普通索引）
+- 完整的注释（表注释、字段注释）
+
+### 3. 规范检查
+验证建表语句是否符合规范：
+- 表名格式检查
+- 基础字段完整性检查
+- 字段注释检查
+- 索引规范检查
+- 引擎和字符集检查
+
+### 4. 实体类建议
+提供 Spring 实体类命名建议：
+- 表名 `zz_plt_role` → 实体类 `Role`
+- 自动去除前缀，使用驼峰命名
+
+## 目录结构
+
+```
+mysql-table-generator-skill/
+├── SKILL.md                    # Skill 主文件
+├── README.md                   # 说明文档
+└── references/
+    ├── 命名规范.md              # 表名、字段名、索引名规范
+    ├── 字段类型规范.md          # 数据类型选择指南
+    └── 索引规范.md              # 索引设计原则
+```
+
+## 使用示例
+
+### 示例 1：创建业务表
+
+**用户**："帮我创建一个角色表"
+
+**助手**：
+1. 询问所属部门 → 用户选择"讯飞智作 (zz)"
+2. 询问业务域 → 用户输入"plt"
+3. 询问实体名 → 用户输入"role"
+4. 询问业务字段 → 用户输入"角色编码、角色名称、描述、是否启用、排序权重"
+5. 生成完整建表语句
+
+**输出**：
+```sql
+CREATE TABLE `zz_plt_role` (
+  `id`          BIGINT UNSIGNED  NOT NULL AUTO_INCREMENT COMMENT '主键ID',
+  `role_code`   VARCHAR(64)      NOT NULL COMMENT '角色编码',
+  `role_name`   VARCHAR(128)     NOT NULL COMMENT '角色名称',
+  `description` VARCHAR(512)     DEFAULT NULL COMMENT '角色描述',
+  `is_enabled`  TINYINT(1)       NOT NULL DEFAULT 1 COMMENT '是否启用：0-禁用，1-启用',
+  `sort_order`  INT              NOT NULL DEFAULT 0 COMMENT '排序权重',
+  `created_at`  DATETIME         NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `updated_at`  DATETIME         NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  `created_by`  BIGINT UNSIGNED  NOT NULL DEFAULT 0 COMMENT '创建人ID',
+  `updated_by`  BIGINT UNSIGNED  NOT NULL DEFAULT 0 COMMENT '更新人ID',
+  `is_deleted`  TINYINT(1)       NOT NULL DEFAULT 0 COMMENT '逻辑删除：0-未删除，1-已删除',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_zz_plt_role_code` (`role_code`),
+  KEY `idx_zz_plt_role_name` (`role_name`)
+) ENGINE=InnoDB
+  DEFAULT CHARSET=utf8mb4
+  COLLATE=utf8mb4_0900_ai_ci
+  COMMENT='智作平台-角色表 [zz][plt]';
+```
+
+### 示例 2：创建关联表
+
+**用户**："创建虚拟人和角色的关联表"
+
+**助手**：
+1. 询问所属部门和业务域
+2. 自动生成关联表结构
+3. 包含联合唯一索引和外键索引
+
+**输出**：
+```sql
+CREATE TABLE `zz_plt_avatar_role_rel` (
+  `id`          BIGINT UNSIGNED  NOT NULL AUTO_INCREMENT COMMENT '主键ID',
+  `avatar_id`   BIGINT UNSIGNED  NOT NULL COMMENT '虚拟人ID',
+  `role_id`     BIGINT UNSIGNED  NOT NULL COMMENT '角色ID',
+  `created_at`  DATETIME         NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `is_deleted`  TINYINT(1)       NOT NULL DEFAULT 0 COMMENT '逻辑删除：0-未删除，1-已删除',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_zz_plt_avatar_role_rel` (`avatar_id`, `role_id`),
+  KEY `idx_zz_plt_avatar_role_rel_role` (`role_id`)
+) ENGINE=InnoDB
+  DEFAULT CHARSET=utf8mb4
+  COLLATE=utf8mb4_0900_ai_ci
+  COMMENT='智作平台-虚拟人角色关联表 [zz][plt]';
+```
+
+### 示例 3：验证表结构
+
+**用户**："检查这个建表语句是否符合规范：CREATE TABLE user ..."
+
+**助手**：
+1. 分析表名格式
+2. 检查基础字段
+3. 检查字段注释
+4. 检查索引配置
+5. 检查引擎和字符集
+6. 给出修改建议
+
+## 规范要点
+
+### 表命名规范
+- 格式：`{部门缩写}_{业务域}_{实体名}`
+- 示例：`zz_plt_role`（讯飞智作-平台-角色）
+- 全小写，下划线分隔
+
+### 必须包含的基础字段
+```sql
+id          BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '主键ID',
+created_at  DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+updated_at  DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+is_deleted  TINYINT(1)      NOT NULL DEFAULT 0 COMMENT '逻辑删除：0-未删除，1-已删除',
+```
+
+### 索引命名规范
+- 主键：自动创建，无需显式声明
+- 唯一索引：`uk_{表名}_{字段}`
+- 普通索引：`idx_{表名}_{字段}`
+- 联合索引：`idx_{表名}_{字段1}_{字段2}`
+
+### 引擎和字符集
+```sql
+ENGINE=InnoDB
+DEFAULT CHARSET=utf8mb4
+COLLATE=utf8mb4_0900_ai_ci
+```
+
+## 版本要求
+
+- MySQL 8.0+
+- Java 21+ / Spring Boot 3.5.3+
+- MyBatis-Plus 3.5.15
+
+## 相关文档
+
+- [MySQL 数据库规范](../../database/mysql-specification.md)
+- [Avatar Boot MySQL Starter](../avatar-boot-starter-mysql-skill/)
+
+## 注意事项
+
+1. **表名前缀**：Spring 实体类不需要前缀，直接使用实体名
+2. **逻辑删除**：所有查询必须带 `AND is_deleted = 0` 条件
+3. **唯一索引**：需要在业务层做唯一性校验
+4. **字段注释**：每个字段都必须有清晰的注释
+5. **索引数量**：单表索引不超过 5 个
+
+## 常见问题
+
+**Q: 为什么要使用 BIGINT UNSIGNED 作为主键？**
+A: INT 最大约 21 亿，高频写入表容易溢出，BIGINT UNSIGNED 可以支持更大的数据量。
+
+**Q: 为什么使用 DATETIME 而不是 TIMESTAMP？**
+A: TIMESTAMP 有 2038 年问题，DATETIME 范围更大，更适合长期存储。
+
+**Q: 为什么不使用 ENUM 类型？**
+A: ENUM 修改需要 DDL，高并发下有锁风险，建议使用 TINYINT + 注释。
+
+**Q: 关联表需要 updated_at 字段吗？**
+A: 关联表通常只有创建和删除操作，不需要 updated_at 字段。
+
+**Q: 如何处理多租户场景？**
+A: 添加 `tenant_id` 字段和相关索引，详见 SKILL.md 中的特殊场景处理。