---
globs: ["**/*.sql", "**/mapper/**", "**/migration/**", "**/entity/**", "**/model/**", "**/mybatis/**"]
---

# MySQL 数据库设计规范

## 数据库版本与引擎
- 支持版本：MySQL 5.7.26 / 8.0.32
- 默认使用 InnoDB 存储引擎
- 字符集必须使用 `utf8mb4`
- 建库语句必须包含字符集和校对规则：`DEFAULT CHARACTER SET UTF8MB4 DEFAULT COLLATE UTF8MB4_GENERAL_BIN`

## 命名规范
- 全小写英文字母、数字、下划线，必须以字母开头
- 对象名不超过 32 个字符
- 禁止使用保留字和 `-` 分割
- 库名格式：`业务系统名_子模块名`，如 `zqyl_finance_base`
- 表名格式：`t_模块名_表功能`，禁止使用复数，如 `t_finance_invoice`
- 临时表：`tmp_表名_日期`，如 `tmp_login_users_20130501`
- 备份表：`bak_表名_日期`，存放备份库中，超期及时清理
- 字段命名：序号以 `_id` 后缀，编码以 `_code` 后缀，布尔以 `is_` 前缀
- 状态字段以 `_status` 后缀，日期字段以 `_date` 后缀，时间字段以 `_time` 后缀
- 索引命名：主键 `pk_字段名`，普通索引 `i_字段名`，唯一索引 `uk_字段名`

## 表设计规范
- 建表必须有 COMMENT，描述表和列含义；状态/类型字段必须说明各值含义
- 表必备字段：`id`（主键）、`create_time`（datetime）、`update_time`（datetime），可选 `create_id`、`update_id`
- `create_time` 默认值 `CURRENT_TIMESTAMP`，`update_time` 默认值 `CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP`
- 每个表必须设置 `is_del` 字段（0=未删除，1=删除），NOT NULL DEFAULT 0
- 生产环境禁止物理删除
- 单表字段数不超过 50 个，尽量精简
- 表设计满足第三范式(3NF)，减少冗余；频繁 JOIN 的字段允许反范式冗余
- JOIN 字段的名称、数据类型、长度、单位必须一致，避免隐式转换
- 主键为无符号整型有序递增，PK 字段禁止 UPDATE
- 所有字段必须 `NOT NULL`，根据业务定义 DEFAULT 值
- 禁止使用外键约束，由应用层控制
- 禁止使用枚举类型字段（ENUM/SET），使用 `TINYINT` 或 `SMALLINT` 替代
- 核心业务表单表物理大小不超过 8GB，数据控制在 2000W 内

## 数据类型选择
- 整型：根据范围选择 `TINYINT/SMALLINT/INT/BIGINT`，优先使用 `UNSIGNED`
- 浮点型：使用 `DECIMAL`，禁止 `FLOAT` 和 `DOUBLE`
- 金额：建议用 `INT`（程序端乘除 100），或 `DECIMAL`，必须统一计量单位
- 字符串：统一使用 `VARCHAR`，单个字段不超过 256 字符
- 超过 4000 字符使用 `TEXT`，必须拆分到独立子表
- 禁止使用 `TEXT/BLOB/MEDIUMTEXT/LONGTEXT`（特殊场景除外，且必须独立成表）
- 布尔值：使用 `TINYINT` 代替
- 精确到天使用 `DATE`，精确到秒使用 `DATETIME`，不建议使用 `TIMESTAMP`
- IP 地址：`VARCHAR(15)` 或转 `INT` 存储（`INET_ATON()`/`INET_NTOA()`）
- 手机号：`VARCHAR(11)`
- 禁止在数据库中存放 LOB 类型数据（文件/图片存文件系统，数据库存路径）

## SQL 编写规范
- `SELECT` 必须指定具体字段名称，禁止 `SELECT *`
- `INSERT` 必须指定具体字段名称
- 所有 DML 语句（除 INSERT）必须有 WHERE 条件且使用索引
- WHERE 条件等号左右字段类型必须一致
- WHERE 字段上禁止使用函数做类型转换
- 禁止使用 `NOW()/RAND()/SYSDATE()/CURRENT_USER()` 等不确定函数
- `IN` 操作集合元素控制在 1000 个以内，超过使用子查询
- 减少使用 `OR`，优化为 `UNION ALL` 并对各 WHERE 条件建索引
- 多表关联小表驱动大表
- 避免大事务，复杂 SQL 拆分为多步骤
- 禁止一次性更新几十万条记录，拆分为小事务（单事务不超过 8MB）
- 数据量增长表必须设计历史表
- 同一事务多表更新按约定顺序操作，避免死锁

## 禁用项
- 禁止使用存储过程、视图、触发器、Event
- 禁止使用外键与级联
- 禁止使用枚举类型（ENUM/SET）
- 禁止使用 TEXT/BLOB（非独立子表场景）

## 常见错误模式
- ❌ `SELECT * FROM t_user` → ✅ `SELECT id, name, status FROM t_user`
- ❌ `WHERE DATE_FORMAT(create_time, '%Y-%m') = '2024-01'` → ✅ `WHERE create_time >= '2024-01-01' AND create_time < '2024-02-01'`
- ❌ 表中使用 `FLOAT` 存金额 → ✅ 使用 `DECIMAL` 或 `INT`（分为单位）