# 数据库命名与注释规范

## 一、表命名规范

### 基本格式
`<app_name>_<function_name>` 或 `<app_name>_<function_name>_<type_name>`

### 规则说明
- **app_name**：应用名称缩写，小写
- **function_name**：功能名称，小写
- **type_name**：类型名称（可选），小写

### 示例
| 应用 | 功能 | 类型 | 表名 |
|:----|:-----|:-----|:-----|
| cms | article | - | `cms_article` |
| cms | article | type | `cms_article_type` |
| sys | user | - | `sys_user` |
| sys | user | role | `sys_user_role` |
| order | goods | - | `order_goods` |
| order | goods | detail | `order_goods_detail` |

## 二、字段命名规范

### 主键字段
自增ID字段命名为最后一个name + '_id'

| 表名 | 主键字段 |
|:-----|:---------|
| cms_article | `article_id` |
| cms_article_type | `type_id` |
| sys_user | `user_id` |
| sys_user_role | `user_role_id` |

### 外键字段
命名为关联表最后一个name + '_id'

| 当前表 | 关联表 | 外键字段 |
|:-------|:-------|:---------|
| cms_article | cms_article_type | `type_id` |
| order_goods | sys_user | `user_id` |

### 普通字段
采用小写蛇形命名

| 字段名 | 含义 |
|:-------|:-----|
| `user_name` | 用户名 |
| `created_at` | 创建时间 |
| `is_deleted` | 是否删除 |

## 三、注释规范

### 字段注释格式
`中文名：[最小值，最大值]描述(关联信息)`

### [最小值，最大值]规则
- **数值类型**：最小数值到最大数值
- **字符串类型**：最小字符串长度到最大字符串长度

### 关联信息格式
- **关联表**：`关联表名.主键字段名.关联字段名称`
- **枚举类型**：`(枚举值1|枚举值2|枚举值3)`

### 完整示例

#### 数值类型字段
```sql
`type_id` INT NOT NULL DEFAULT 0 COMMENT '分类ID：[0, 1000]文章的分类(cms_article_type.type_id.name)',
`status` TINYINT NOT NULL DEFAULT 0 COMMENT '状态：[0, 2]文章状态(0草稿|1发布|2归档)',
`sort_order` INT NOT NULL DEFAULT 0 COMMENT '排序：[0, 9999]显示顺序',
`view_count` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '浏览量：[0, 4294967295]文章浏览次数',
```

#### 字符串类型字段
```sql
`article_title` VARCHAR(255) NOT NULL COMMENT '文章标题：[1, 255]文章的标题',
`article_summary` VARCHAR(500) DEFAULT NULL COMMENT '文章摘要：[0, 500]文章的简要描述',
`author_name` VARCHAR(64) NOT NULL COMMENT '作者名称：[1, 64]文章作者',
`email` VARCHAR(128) NOT NULL COMMENT '邮箱：[6, 128]用户邮箱地址',
`mobile` VARCHAR(11) DEFAULT NULL COMMENT '手机号：[0, 11]用户手机号码',
```

#### 枚举类型字段
```sql
`is_active` TINYINT NOT NULL DEFAULT 1 COMMENT '是否激活：[0, 1]用户状态(0否|1是)',
`gender` TINYINT DEFAULT NULL COMMENT '性别：[0, 2]用户性别(0未知|1男|2女)',
`is_deleted` TINYINT NOT NULL DEFAULT 0 COMMENT '是否删除：[0, 1]软删除标记(0否|1是)',
```

#### 日期时间字段
```sql
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间：[0, 0]记录创建时间',
`updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间：[0, 0]记录更新时间',
`deleted_at` DATETIME DEFAULT NULL COMMENT '删除时间：[0, 0]软删除时间',
`publish_time` DATETIME DEFAULT NULL COMMENT '发布时间：[0, 0]文章发布时间',
```

#### 关联表字段
```sql
`user_id` BIGINT NOT NULL COMMENT '用户ID：[0, 9223372036854775807]所属用户(sys_user.user_id.user_name)',
`article_id` BIGINT NOT NULL COMMENT '文章ID：[0, 9223372036854775807]关联文章(cms_article.article_id.article_title)',
`type_id` INT NOT NULL COMMENT '类型ID：[0, 1000]文章分类(cms_article_type.type_id.name)',
```

### 表注释格式
`表中文名`

```sql
CREATE TABLE `cms_article` (
  ...
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文章表';
```

## 四、索引命名规范

### 唯一索引
`uk_<表名缩写>_<字段名>`

### 普通索引
`idx_<表名缩写>_<字段名>`

### 联合索引
`idx_<表名缩写>_<字段1>_<字段2>`

### 示例
| 索引类型 | 索引名称 | 说明 |
|:---------|:---------|:-----|
| 唯一索引 | `uk_cms_art_title` | 文章标题唯一索引 |
| 普通索引 | `idx_cms_art_type` | 文章类型索引 |
| 联合索引 | `idx_cms_art_type_status` | 类型+状态联合索引 |

## 五、完整建表示例

```sql
CREATE TABLE `cms_article` (
  `article_id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '文章ID：[0, 9223372036854775807]自增主键',
  `type_id` INT NOT NULL DEFAULT 0 COMMENT '分类ID：[0, 1000]文章的分类(cms_article_type.type_id.name)',
  `article_title` VARCHAR(255) NOT NULL COMMENT '文章标题：[1, 255]文章的标题',
  `article_summary` VARCHAR(500) DEFAULT NULL COMMENT '文章摘要：[0, 500]文章的简要描述',
  `article_content` LONGTEXT COMMENT '文章内容：[0, 4294967295]文章的正文内容',
  `author_name` VARCHAR(64) NOT NULL COMMENT '作者名称：[1, 64]文章作者',
  `status` TINYINT NOT NULL DEFAULT 0 COMMENT '状态：[0, 2]文章状态(0草稿|1发布|2归档)',
  `sort_order` INT NOT NULL DEFAULT 0 COMMENT '排序：[0, 9999]显示顺序',
  `view_count` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '浏览量：[0, 4294967295]文章浏览次数',
  `is_deleted` TINYINT NOT NULL DEFAULT 0 COMMENT '是否删除：[0, 1]软删除标记(0否|1是)',
  `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间：[0, 0]记录创建时间',
  `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间：[0, 0]记录更新时间',
  `deleted_at` DATETIME DEFAULT NULL COMMENT '删除时间：[0, 0]软删除时间',
  PRIMARY KEY (`article_id`),
  UNIQUE KEY `uk_cms_art_title` (`article_title`),
  KEY `idx_cms_art_type` (`type_id`),
  KEY `idx_cms_art_status` (`status`),
  KEY `idx_cms_art_created` (`created_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文章表';
```