# 4.10 数据库设计

:::tip 概述
数据库层有三个设计支点：**多方言驱动注册表**（一套代码五种数据库）、**统一列约定**（审计字段 + 软删 + 租户）、**全局钩子**（红线在 SQL 层执行）。
:::

## 多方言驱动注册表

```text
internal/model/db/db.go
driverRegistry: 驱动名 → 工厂函数
内置注册：mysql / postgres / sqlserver / sqlite
扩展注册：oracle（构建标签 -tags oracle，经 RegisterDriver 挂入）
```

`db.Init` 按 `database.default.driver` 选择方言工厂建立连接池（maxOpen/maxIdle/connMaxLifetime），SQL 调试日志受 `debug` 开关控制。切换方言只改配置，代码零改动。

## 全库列约定

```text
id            主键（INT 自增）
create_user   创建人        create_time  创建时间
update_user   更新人        update_time  更新时间
del_flag      软删标记（0 正常 / 1 删除）
tenant_id     租户 ID（仅租户级表，白名单 9 张）
```

写侧由全局钩子补齐（业务不赋值），读侧由 Scope 过滤（del_flag=0、租户条件）。

## 表清单（25 张）

| 域 | 表 |
|---|---|
| 组织权限 | gin_user、gin_user_role、gin_role、gin_role_menu、gin_menu、gin_dept、gin_level、gin_position、gin_tenant |
| 内容 | gin_article、gin_category、gin_notice、gin_link |
| 数据配置 | gin_dict、gin_dict_item、gin_param、gin_config、gin_config_item、gin_city |
| 任务日志 | gin_job、gin_job_log、gin_operation_log、gin_login_log |
| 工具 | gin_file_template、gin_example |

列级详情见 [附录 B 数据库表结构速查](/zh/appendix/database-tables.html)。

## 关联模型

```text
gin_user ──< gin_user_role >── gin_role ──< gin_role_menu >── gin_menu
gin_dept 树形（parent_id），数据权限按 dept_id 收敛
gin_menu 树形（parent_id），permission 列承载权限节点
```

应用层不使用外键——引用完整性由软删除纪律与业务校验维护（删除前 ExistsByCond 检查引用）。

## 索引规约

| 类型 | 命名 | 场景 |
|---|---|---|
| 普通索引 | idx_{表}_{列} | 查询高频列（del_flag、外键列、模糊列） |
| 唯一索引 | uk_{表}_{列} | 唯一约束（与 UniqueFields 预检配套，以 uk 为最终防线） |

## 软删除与数据生命周期

```text
业务删除 → UPDATE del_flag=1（Ctx 过滤后不可见）
物理 DELETE → 全局钩子拦截，WithPhysicalDelete(ctx) 显式放行
超期清理 → LogClean 定时任务物理清理过期日志（放行场景的典型用例）
```

## 事务

`db.WithTrans(ctx, fn)`：回调 ctx 携带事务连接，返回错误整体回滚。跨模块写操作（如用户+关联角色）必须同事务。

## 跨库迁移

`cmd/migrator`（`make migrator`）实现源库内省 → 目标方言 DDL → 分批搬运 → 序列修复，支持五方言互迁。见 [7.6 数据库迁移工具](/zh/tools/db-migrate.html)。

## 下一步

→ [4.11 安全架构设计](/zh/architecture/security.html)