TourGuide 数据库脚本说明

唯一规则

全新数据库：只执行 schema.sql，不要再执行 legacy 中的历史升级脚本。
已有数据库：只执行 migrate-local.ps1，脚本会按文件名顺序执行 migrations，并自动跳过已登记版本。
历史脚本：统一存放在 legacy/2026-07-28，仅用于追溯，禁止批量执行。

当前目录

backend/db/
├─ schema.sql                 # 当前完整结构快照，仅用于新建数据库
├─ init-local.ps1             # 新建/重建本地数据库
├─ migrate-local.ps1          # 已有数据库增量迁移入口
├─ verify.sql                 # 查询迁移记录和关键功能完整性
├─ migrations/               # 以后唯一允许新增迁移脚本的位置
│  └─ 20260728_150000_current_schema_baseline.sql
└─ legacy/2026-07-28/        # 已归档旧脚本，不再执行

执行步骤

1. 全新数据库

cd "F:/code/TourGuide/backend/db"
./init-local.ps1

作用：执行完整的 schema.sql，创建当前代码所需全部表、索引、默认数据，并登记当前结构基线。

2. 已有数据库

cd "F:/code/TourGuide/backend/db"
./migrate-local.ps1

作用：

检查 tour_guide 是否存在。
创建或确认 sys_schema_migration。
按文件名升序读取 migrations/*.sql。
已登记版本直接跳过。
未登记版本执行后必须写入迁移记录，否则脚本报错停止。

3. 查看当前状态

$env:MYSQL_PWD = "你的密码"
mysql --default-character-set=utf8mb4 -h "127.0.0.1" -P 3306 -u "root" -D "tour_guide" -e "source F:/code/TourGuide/backend/db/verify.sql"
Remove-Item Env:MYSQL_PWD

2026-07-28 本地数据库核对结果

核对时数据库实际已经包含：

导游、讲解队及自动禁用配置。
城市管理、协议管理、反馈管理、平台设置。
景区主表、价格配置表、汇合点配置表。
订单详情、支付时间线和退款详情字段。
订单评价表。

但 sys_schema_migration 当时只登记了：

20260728_100213_REVIEW_MANAGEMENT
20260728_120000_FEEDBACK_MANAGEMENT

因此不能再通过“迁移记录缺失”判断脚本未执行。新的基线迁移会先验证实际结构，再登记：

20260728_150000_CURRENT_SCHEMA_BASELINE

新增迁移规范

以后每个迁移文件必须：

文件名格式：yyyyMMdd_HHmmss_feature_name.sql。
文件顶部声明：-- migration-version: VERSION。
文件末尾向 sys_schema_migration 写入相同的 VERSION。
尽量使用 CREATE TABLE IF NOT EXISTS 或结构检查，避免重复执行产生破坏。
不允许修改已发布迁移；修复问题必须新增更高版本脚本。

常见错误

出现 Unknown column 'xxx' in 'field list'，通常表示代码实体已经新增字段，但当前数据库尚未执行对应迁移。
已有数据库应执行 migrate-local.ps1，不要通过重新执行完整 schema.sql 修复字段缺失。
mini_user.id_card_no 对应迁移版本为 20260729_120000_ADD_MINI_USER_ID_CARD。
迁移后应同时检查字段、索引和 sys_schema_migration 记录，避免只完成部分结构变更。

示例：

-- migration-version: 20260729_090000_EXAMPLE
USE `tour_guide`;

-- 数据库变更内容

INSERT IGNORE INTO `sys_schema_migration` (`version`, `description`)
VALUES ('20260729_090000_EXAMPLE', '示例迁移');