数据库与迁移规范

数据库规范的目标是让 TanzCMS 可以稳定安装、升级、备份、恢复和扩展。

一、表前缀规则

系统表名前缀由数据库连接统一处理。代码中不要写死物理表名，也不要拼接带前缀的表名。

推荐：

DB::table('content_categories')->where('status', 1)->get();

不推荐：

DB::table('tz_content_categories')->get();

这样可以让同一套代码适配不同站点的表前缀。

二、迁移位置

类型	迁移目录
核心平台表	database/migrations/
一方模块新增表	modules/{code}/database/migrations/
插件表	plugins/{code}/database/migrations/

历史上已经进入核心安装面的基础表继续由核心迁移维护。后续新增模块表优先归模块目录。

三、迁移写法

迁移只描述结构，不写业务导入逻辑。初始数据应通过安装器、Seeder、模块导入命令或后台导入流程处理。

Schema::create('demo_items', function (Blueprint $table): void {
    $table->id();
    $table->string('title', 120);
    $table->unsignedTinyInteger('status')->default(1);
    $table->timestamps();
});

表前缀由数据库连接负责，不在迁移里手动拼接。

四、字段规范

• 主键优先使用 id。
• 状态字段使用小整数或明确枚举值。
• 排序字段使用 sort。
• 时间字段使用 created_at、updated_at。
• 大文本、大 JSON 和正文不要在列表接口里默认全量查询。

五、索引规范

常用筛选、排序和关联字段应建立索引，例如：

• status
• sort
• created_at
• category_id
• member_id
• plugin_code

模糊搜索和复杂筛选应根据业务规模逐步迁移到搜索索引或专用搜索服务。

六、备份恢复

数据库备份用于数据恢复，不负责补齐缺失代码。恢复目标应已经部署对应代码并完成迁移。

恢复前确认：

• 目标数据库名称正确。
• 目标表前缀与备份数据一致。
• 目标代码版本与备份数据结构匹配。
• 上传附件和数据库来自同一时间点。

七、禁止事项

• 不在 SQL 字符串中拼用户输入。
• 不在模块或插件中修改核心迁移历史。
• 不长期保留补丁式兼容迁移污染安装面。
• 不让模块包或插件包覆盖核心迁移文件。
• 不混用带前缀和不带前缀的业务表。