# 3.2 数据库建表

:::tip 概述
建表是模块开发的第一步。所有表必须包含公共字段（id、软删除、审计字段），这是模型 Trait 自动处理的基础。
:::

## 公共字段规范

所有业务表必须包含以下公共字段：

```sql
-- 公共字段（每个表都必须包含）
id              INT PRIMARY KEY AUTO_INCREMENT  COMMENT '主键',
is_delete       TINYINT(1) DEFAULT 0            COMMENT '软删除 0=正常 1=已删除',
create_user     VARCHAR(50) DEFAULT ''          COMMENT '创建人',
create_time     DATETIME                        COMMENT '创建时间',
update_user     VARCHAR(50) DEFAULT ''          COMMENT '更新人',
update_time     DATETIME                        COMMENT '更新时间'
```

:::warning 为什么必须包含这些字段？
- `is_delete`：`SoftDeleteFlagScope` 全局查询范围会自动过滤 `is_delete=1` 的数据（`SoftDeletesByFlag` Trait 注册）
- `create_user` / `create_time`：`HasAuditColumns` Trait 的 `creating` 事件自动填充
- `update_user` / `update_time`：`HasAuditColumns` Trait 的 `updating` 事件自动填充
- 表结构**不含** Laravel 默认的 `created_at` / `updated_at` 列，统一使用本项目的审计字段命名
:::

## 建表 SQL 示例（example 模块，摘自 `document/mysql/` 实际脚本）

```sql
CREATE TABLE laravel_example (
    -- 主键
    id              INT NOT NULL AUTO_INCREMENT  COMMENT '主键ID',

    -- 业务字段
    name            VARCHAR(255) NOT NULL         COMMENT '案例名称',
    avatar          VARCHAR(255) NULL DEFAULT NULL COMMENT '案例图片',
    type            INT NULL DEFAULT 0            COMMENT '案例类型：1-类型1 2-类型2 3-类型3 4-类型4',
    status          INT NULL DEFAULT 0            COMMENT '案例状态：1-在用 2-停用',
    sort            INT NULL DEFAULT 0            COMMENT '案例排序',

    -- 公共字段（必须）
    create_user     VARCHAR(50) NULL DEFAULT NULL  COMMENT '创建人',
    create_time     DATETIME NULL DEFAULT (now()) COMMENT '创建时间',
    update_user     VARCHAR(50) NULL DEFAULT NULL  COMMENT '更新人',
    update_time     DATETIME NULL DEFAULT (now()) COMMENT '更新时间',
    is_delete       INT NULL DEFAULT 0            COMMENT '删除标识：0-正常 1-已删除',

    -- 索引
    PRIMARY KEY (id),
    INDEX idx_think_level_is_delete (is_delete),
    INDEX idx_think_level_name (name),
    INDEX idx_think_level_status (status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='案例演示表';
```

:::tip 枚举注释写法
枚举字段的注释直接写成 `1-在用 2-停用` 格式，代码生成器据此自动解析选项（见 [10.4 表结构解析引擎](/zh/generator/parser.html)）。
:::

:::tip 表前缀
建表 SQL 中的表名**含** `laravel_` 前缀（与 `.env` 中 `DB_PREFIX` 一致）；模型层的 `$table` 只写不含前缀的 `example`，查询时由 Laravel 自动拼接前缀。
:::

## 字段与 Service 属性对应关系

（对照 `app/Services/ExampleService.php` 实际声明）

| 数据库字段 | 类型 | Service 属性 | 说明 |
|-----------|------|-----------|------|
| `name` | VARCHAR(255) | `pageLikeFields` + `uniqueFields` | LIKE 模糊搜索 + 名称唯一校验 |
| `status` | INT | `pageEqFields` + `serializeMaps` | 精确匹配 + 字典翻译（`example_status` → 补 `statusText`） |
| `type` | INT | —（普通表单/列表字段） | 注释含选项，前端按 `columns.ts` 渲染 |
| `sort` | INT | —（默认排序用基类 `pageOrderBy`） | 排序值 |
| `avatar` | VARCHAR(255) | —（前端 `UploadImg` 直传） | 图片路径字段 |

## 设计检查清单

| 检查项 | 说明 |
|--------|------|
| 公共字段齐全 | `id` / `is_delete` / 四个审计字段 |
| 字段小写下划线 | `category_id`、`create_time` |
| 枚举字段配字典 | 字段注释写明字典编码，便于生成器提取 |
| 模糊搜索字段建索引 | LIKE 查询字段建议加索引 |
| 需要唯一性的字段 | 在 Service 配置 `uniqueFields`（不是数据库唯一索引，软删除场景更安全） |

## 常见字段类型参考

| 用途 | 推荐类型 | 示例 |
|------|----------|------|
| 主键 | `INT AUTO_INCREMENT` | `id INT PRIMARY KEY AUTO_INCREMENT` |
| 外键 | `INT DEFAULT 0` | `category_id INT DEFAULT 0` |
| 短文本 | `VARCHAR(n)` | `name VARCHAR(200)` |
| 长文本 | `TEXT` | `content TEXT` |
| 布尔值 | `TINYINT(1)` | `status TINYINT(1) DEFAULT 1` |
| 整数 | `INT` | `sort INT DEFAULT 0` |
| 日期时间 | `DATETIME` | `create_time DATETIME` |
| 文件路径 | `VARCHAR(500)` | `avatar VARCHAR(500)` |

:::tip
本项目 `database/migrations/` 为空，建表后**直接执行 SQL**（或在已有数据库上 `ALTER TABLE`），无需迁移。多数据库脚本见 [2.5 数据库初始化](/zh/quickstart/database-init.html)。
:::