# TourGuide 数据库脚本说明

## 唯一规则

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

## 当前目录

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

## 执行步骤

### 1. 全新数据库

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

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

### 2. 已有数据库

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

作用：

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

### 3. 查看当前状态

```powershell
$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`

## 新增迁移规范

以后每个迁移文件必须：

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

## 常见错误

- 出现 `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` 记录，避免只完成部分结构变更。

示例：

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

-- 数据库变更内容

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