# 数据库设计指南

:::tip 说明
本文介绍本项目的数据库设计规范，包括表命名、字段类型选择、索引策略、常见表模式等。
:::

## 表命名规范

| 规则 | 说明 | 示例 |
|------|------|------|
| 前缀 | 统一使用 `django_` 前缀 | `django_user` |
| 命名 | 小写字母 + 下划线 | `django_role_menu` |
| 关联表 | 两张表名拼接 | `django_user_role` |
| 日志表 | 模块名 + `_log` | `django_login_log` |

### Django 模型配置

```python
class Example(BaseModel):
    class Meta:
        db_table = 'django_example'  # 表名
        db_comment = '案例表'        # 表注释
```

## 字段类型选择

### 常用字段类型

| Django 类型 | MySQL 类型 | 适用场景 | 示例 |
|------------|-----------|---------|------|
| `AutoField` | INT AUTO_INCREMENT | 主键 | `id` |
| `CharField` | VARCHAR | 短文本 | 用户名、标题 |
| `TextField` | TEXT | 长文本 | 文章内容、备注 |
| `IntegerField` | INT | 整数 | 状态、排序、数量 |
| `BigIntegerField` | BIGINT | 大整数 | 时间戳、耗时 |
| `DecimalField` | DECIMAL | 精确小数 | 金额、价格 |
| `DateTimeField` | DATETIME | 日期时间 | 创建时间、更新时间 |
| `BooleanField` | TINYINT | 布尔值 | 是否启用 |

### 字段长度建议

| 字段类型 | 建议长度 | 说明 |
|---------|---------|------|
| 用户名 | 50 | `CharField(max_length=50)` |
| 标题 | 150-255 | `CharField(max_length=150)` |
| URL/路径 | 255 | `CharField(max_length=255)` |
| 编码/标识 | 100 | `CharField(max_length=100)` |
| 手机号 | 20 | `CharField(max_length=20)` |
| 邮箱 | 100 | `CharField(max_length=100)` |
| 备注 | 255 | `CharField(max_length=255)` |
| 内容 | 无限制 | `TextField()` |

## BaseModel 公共字段

所有业务模型继承 `BaseModel`，自动包含 6 个公共字段：

```python
# application/models.py
class BaseModel(models.Model):
    """基础模型类"""
    class Meta:
        abstract = True

    id = models.AutoField(primary_key=True, verbose_name='主键ID')
    create_user = models.CharField(max_length=50, null=True, blank=True, verbose_name='创建人')
    create_time = models.DateTimeField(auto_now_add=True, verbose_name='创建时间')
    update_user = models.CharField(max_length=50, null=True, blank=True, verbose_name='更新人')
    update_time = models.DateTimeField(auto_now=True, verbose_name='更新时间')
    is_delete = models.IntegerField(default=0, verbose_name='是否删除：0-正常 1-已删除')
```

:::tip 字段排序
通过 `class_prepared` 信号，BaseModel 的公共字段会自动排在业务字段之后，保证数据库表结构的可读性。
:::

## 索引设计原则

### 索引类型

| 类型 | Django 配置 | 说明 |
|------|------------|------|
| 单列索引 | `db_index=True` | 单字段查询 |
| 唯一索引 | `unique=True` | 唯一性约束 |
| 复合索引 | `index_together` | 多字段联合查询 |

### 索引设计建议

```python
class Example(BaseModel):
    name = models.CharField(max_length=100, db_index=True)  # 常用查询字段
    code = models.CharField(max_length=100, unique=True)     # 唯一编码
    status = models.IntegerField(db_index=True)              # 状态字段
    category_id = models.IntegerField(db_index=True)         # 外键字段

    class Meta:
        db_table = 'django_example'
        index_together = [
            ['status', 'is_delete'],  # 复合索引：状态 + 软删除
            ['category_id', 'sort'],  # 复合索引：分类 + 排序
        ]
```

### 索引注意事项

```
1. 不要过度索引：每个索引都会降低写入性能
2. 选择性高的字段优先：username 比 status 选择性更高
3. 复合索引顺序：选择性高的字段放前面
4. 覆盖索引：查询字段都在索引中时，无需回表
5. 定期分析：使用 EXPLAIN 分析慢查询
```

## 常见表模式

### 树形结构表

```python
class Category(BaseModel):
    """树形结构表（parent_id）"""
    name = models.CharField(max_length=100)
    parent_id = models.IntegerField(default=0)  # 0 表示顶级
    sort = models.IntegerField(default=0)

    class Meta:
        db_table = 'django_category'
```

### 关联表（多对多）

```python
class RoleMenu(BaseModel):
    """角色菜单关联表"""
    role_id = models.IntegerField(db_index=True)
    menu_id = models.IntegerField(db_index=True)

    class Meta:
        db_table = 'django_role_menu'
```

### 配置表（KV 结构）

```python
class ConfigItem(BaseModel):
    """配置项表（键值对）"""
    code = models.CharField(max_length=100, unique=True)  # 配置编码
    value = models.CharField(max_length=1000)              # 配置值
    type = models.CharField(max_length=50)                 # 值类型

    class Meta:
        db_table = 'django_config_item'
```

### 日志表

```python
class LoginLog(BaseModel):
    """登录日志表"""
    username = models.CharField(max_length=50, db_index=True)
    ip = models.CharField(max_length=50)
    status = models.IntegerField(default=0)
    log_type = models.IntegerField(default=1)

    class Meta:
        db_table = 'django_login_log'
```

## 数据库迁移最佳实践

### 创建迁移

```bash
# 为指定应用创建迁移
python manage.py makemigrations example

# 为所有应用创建迁移
python manage.py makemigrations
```

### 执行迁移

```bash
# 执行所有未执行的迁移
python manage.py migrate

# 执行指定应用的迁移
python manage.py migrate example

# 回滚到指定迁移
python manage.py migrate example 0001
```

### 迁移注意事项

```
1. 先备份：生产环境执行迁移前先备份数据库
2. 测试环境验证：先在测试环境验证迁移脚本
3. 分批执行：大数据表的迁移分批执行，避免锁表
4. 不要修改已提交的迁移：已提交到 Git 的迁移文件不要修改
5. 生成迁移后检查：检查生成的迁移文件是否符合预期
```

## 多数据库支持

项目通过 `DATABASE_ENGINE` 环境变量支持多种数据库：

```bash
# .env
# 可选值：mysql / postgresql / sqlite / oracle / sqlserver
DATABASE_ENGINE=mysql
DATABASE_NAME=djangoadmin
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_USER=root
DATABASE_PASSWORD=root
```

### 数据库方言差异

| 特性 | MySQL | PostgreSQL | SQLite |
|------|-------|-----------|--------|
| 自增主键 | AUTO_INCREMENT | SERIAL | AUTOINCREMENT |
| 布尔类型 | TINYINT | BOOLEAN | INTEGER |
| JSON 字段 | JSON | JSONB | TEXT |
| 全文索引 | FULLTEXT | GIN/GiST | FTS5 |

## 总结

数据库设计指南涵盖表命名规范、字段类型选择、索引设计、常见表模式、迁移最佳实践、多数据库支持等方面。核心原则：统一命名、合理索引、软删除、公共字段复用。