qipai/docs/db-changelog/2026-06-16-M01-B-core-schema.md

数据库变更：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。

验证方式

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。

2026-06-18 脱敏旧库副本验证

• 新增 database/fixtures/2026061801_m01b_legacy_schema.sql，仅包含虚构门店、房间、订单和设备结构及边界数据。
• 在 WSL MySQL 8.4.9 临时库中先载入 8 条 fixture 语句，再执行 up → verify → down → up → verify。
• 旧表在迁移前、首次迁移后、down 后和再次迁移后均可通过只读 Repository 查询。
• 已验证 tenant_id 与父级过滤不会读取另一租户数据，订单金额 25.80/20.00/5.80/0.00/NULL 分别转换为 2580/2000/580/0/null。
• down 只删除新 qipai_* 表，不删除或改写旧表；未导入任何真实旧数据。
• 部署影响：无；仅增加开发测试 fixture 和集成测试，正式迁移 SQL 未变化。