# 数据库变更：2026-06-16 M01-B 核心 schema 基线

## 背景

M01-B 开始建立正式数据库迁移与旧表兼容层。旧 SQL 仅作为表意、字段类别和业务关系参考，不导入旧 `INSERT` 数据、文件 URL、日志或生产配置。

## Up

- `database/migrations/2026061601_m01b_core_schema.up.sql`
- 新增迁移记录表：`qipai_schema_migrations`
- 新增核心业务表：`qipai_tenants`、`qipai_stores`、`qipai_rooms`、`qipai_members`、`qipai_orders`、`qipai_payments`、`qipai_devices`、`qipai_audit_logs`
- 新增兼容映射表：`qipai_legacy_table_mappings`

## Down

- `database/migrations/2026061601_m01b_core_schema.down.sql`
- 仅用于空库、本地开发库或预生产演练库回滚；生产含业务数据后必须先备份并按运维流程人工确认。

## 数据迁移说明

- 首期只提供 schema 与脱敏 seed，不迁移真实旧数据。
- 旧表映射写入 `database/seeds/2026061601_m01b_minimal_seed.sql`。
- 金额字段统一使用整数分，例如 `total_amount_cents`、`paid_amount_cents`、`amount_cents`。
- 时间字段统一 `DATETIME(3)`，内部按 UTC 保存，业务日期后续按门店 `timezone` 计算。
- 业务表包含 `tenant_id`；可逻辑删除的表包含 `deleted_at`。

## 验证方式

```bash
npm --prefix backend test
powershell -ExecutionPolicy Bypass -File scripts/dev/windows/check-backend.ps1
```

`backend/tests/migration-contract.test.mjs` 会检查 up/down/verify/seed 文件包含核心表、`tenant_id`、整数分金额字段、`DATETIME(3)` 和旧表映射。

## 2026-06-18 MySQL 8 空库往返验证

- 环境：WSL Ubuntu 26.04 原生临时副本，MySQL `8.4.9`；该结果不代替 Ubuntu 24.04 生产验收。
- 顺序：`up → verify → down → up → verify`。
- 结果：首次及再次 up 均恢复 10 张核心表和迁移版本 `2026061601`；down 后 10 张表全部移除。
- 语句数：up `11`、verify `3`、down `10`。
- 清理：随机临时数据库与最小权限临时账号在正常和模拟异常退出后均删除，残留计数为 `0/0`。
- 入口：在 WSL 原生测试副本执行 `bash scripts/dev/wsl/mysql-migration-roundtrip.sh`。
- 部署影响：无；未连接生产数据库，未修改部署菜单和正式 schema。