medical-mall/docs/sql/09_migrations_and_versions.md

09 迁移与版本策略（complete vs migration vs tests）

本节解释仓库中与商城数据库相关的脚本如何分工、适合在什么场景使用，以及推荐的执行顺序。

---

1. 你现在有哪几类 SQL

1.1 “完整初始化脚本”（偏一次性创建）

• doc_mall/database/complete_mall_database.sql

特点：

• 覆盖范围大：表结构、索引、触发器、函数、视图、RLS 策略、初始化数据、SEO 函数等。
• 更像“新环境一键搭建”的脚本。

风险点：

• 若在已有环境重复执行，可能因为对象已存在/差异存在导致失败（脚本虽有部分 IF NOT EXISTS，但不是全幂等）。

适用场景：

• 新环境快速搭建
• 演示/验证/PoC

1.2 “迁移脚本”（偏幂等/可增量）

• doc_mall/database/mall_migration.sql

特点：

• 大量使用 CREATE TABLE IF NOT EXISTS、CREATE INDEX IF NOT EXISTS。
• 触发器创建使用 DO $$ ... IF NOT EXISTS 的方式避免重复创建报错。
• 插入初始化数据使用 ON CONFLICT DO NOTHING。

适用场景：

• 在已有数据库上“补齐商城模块”
• 生产环境更安全的增量迁移

1.3 “升级/差异修复脚本”（按数据库现状推荐执行）

从 mall_sql/tests/mall_database_check.sql 可看出项目侧存在“根据现状推荐脚本”的思路，提到：

• mall_alter_upgrade.sql：完整升级（表 + 字段 + 索引 + 函数）
• mall_fields_only_upgrade.sql：仅字段升级（最小化修改）
• mall_migration.sql：完整建表（全新部署/缺表时）
• mall_seo_security.sql：SEO 优化与安全策略

这些脚本在 doc_mall/database/ 与 mall_sql/migrations/ 中都有对应版本（具体以仓库实际文件为准）。

1.4 “检查/测试脚本”（偏验收与自检）

• mall_sql/tests/mall_database_check.sql
• mall_sql/tests/validation_test.sql
• mall_sql/tests/mock_data_insert.sql
• mall_sql/tests/verify_mock_data_fix.sql
• mall_sql/tests/create_supabase_auth_users.sql

适用场景：

• 验收环境是否缺表/缺字段/缺索引
• 生成建议与 ALTER 语句
• 插入 mock 数据用于联调

---

2. 推荐执行顺序（生产/测试通用）

2.1 新环境（从 0 到可用）

推荐路径（更稳妥）：

1. 执行 mall_migration.sql（幂等建表 + 基础索引 + 关键函数/触发器）
2. 执行 SEO 与安全策略脚本（如 mall_seo_security.sql，若 migration 未覆盖）
3. 执行订阅模块脚本（如需要）：create_mall_subscription_tables.sql
4. 执行检查脚本：mall_database_check.sql 5.（测试环境）执行 mock 数据脚本：mock_data_insert.sql

替代路径（快速但风险更高）：

• 直接执行 complete_mall_database.sql 一次性完成（适合演示/PoC）。

2.2 已有环境（补齐缺失）

1. 先执行检查脚本：mall_database_check.sql
2. 根据输出建议选择：
   • 缺字段多 + 缺表：mall_alter_upgrade.sql
   • 只缺字段：mall_fields_only_upgrade.sql
   • 只缺表：mall_migration.sql
3. 再执行 SEO/RLS 策略脚本（如缺失）
4. 再跑一次检查脚本确认

---

3. 版本差异与兼容性注意点

3.1 订单状态口径差异

在不同脚本中对 order_status = 5 的文字描述存在差异（“取消/取货”）。

建议：

• 在应用层/文档中统一口径
• 如需扩展状态，务必迁移更新 CHECK 约束与相关触发器逻辑

3.2 用户角色字段差异：ak_users.role vs ml_user_profiles.user_type

• mall_migration.sql：在 ml_user_profiles 引入 user_type
• complete_mall_database.sql：更多使用 ak_users.role（并在视图里做 role_name 映射）

建议：

• 明确项目最终“权威字段”是哪一个
• 避免两个口径长期并存造成权限与业务判断分裂

---

4. 推荐的团队规范

• 生产环境：优先使用“幂等迁移脚本 + 小步变更”，避免一次性大脚本覆盖执行。
• 每次变更：
  • 同步更新检查脚本/验收项
  • 明确回滚策略（尤其是约束、枚举、数据迁移）
• 对外接口依赖的 cid/slug：变更需谨慎（可能影响 SEO 与路由）。