Merge origin/main into huangzhenbao-admin

pages/mall/admin/docs/sql/09_migrations_and_versions.md

@@ -0,0 +1,126 @@
+# 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 与路由）。