# 商城系统数据库增量升级指南

本目录包含多个数据库升级脚本，适用于不同的部署场景。请根据您的实际情况选择合适的脚本执行。

## 🔧 最新修复

### PL/pgSQL 变量冲突修复
**2024年最新修复：mock_data_insert.sql 中的变量命名冲突和空值问题**

在 `mock_data_insert.sql` 中修复了三个重要问题：
1. **变量命名冲突**：将订单生成部分的变量 `merchant_id` 重命名为 `selected_merchant_id`
2. **订单商品价格空值**：使用 COALESCE 函数处理SKU价格为空的情况，确保价格字段不为空
3. **配送任务重复**：使用 DISTINCT ON 和 NOT EXISTS 确保每个订单只创建一个配送任务

修复的错误类型：
- `ERROR: 42702: column reference "merchant_id" is ambiguous`
- `ERROR: 23502: null value in column "price" violates not-null constraint`
- `ERROR: 23505: duplicate key value violates unique constraint "ml_delivery_tasks_order_id_key"`

详细信息请查看 `VARIABLE_CONFLICT_FIX_REPORT.md`

### 验证脚本
运行 `verify_mock_data_fix.sql` 可以验证修复效果和数据完整性

## ⚠️ 重要：角色字段统一升级

**版本更新：用户角色字段已从 `user_type` (INTEGER) 统一为 `role` (TEXT)**

为提高代码可读性和语义清晰度，我们将所有用户角色相关字段统一为 `role` 字段：
- `ak_users.role` - TEXT 类型，值：'admin', 'merchant', 'customer', 'delivery', 'service'
- `ml_user_profiles.role` - TEXT 类型，值：'admin', 'merchant', 'customer', 'delivery', 'service'

### 角色字段快速迁移
如果您的数据库中仍有 `user_type` 字段，请运行以下脚本进行迁移：
```bash
psql -f quick_role_migration.sql
```

该脚本会：
1. 安全地添加 `role` 字段
2. 将现有 `user_type` 数据迁移到 `role` 字段
3. 更新相关约束、索引、函数和视图
4. 同步 `ak_users` 和 `ml_user_profiles` 的角色字段

## 🔐 重要：Supabase Auth 用户创建

**在执行任何数据库升级之前，必须先创建 Supabase Auth 用户！**

### 第一步：创建 Supabase Auth 用户

#### 方法一：自动化脚本（推荐）
```bash
# 1. 安装依赖
npm install @supabase/supabase-js

# 2. 设置环境变量
export SUPABASE_URL="https://your-project.supabase.co"
export SUPABASE_SERVICE_ROLE_KEY="your-service-role-key"

# 3. 运行创建脚本
node create_supabase_auth_users.js
```

#### 方法二：Supabase Dashboard 手动创建
在 Dashboard → Authentication → Users 中创建以下测试用户：
- admin@mall.com (密码: Test123456!)
- merchant1@mall.com (密码: Test123456!)
- merchant2@mall.com (密码: Test123456!)
- customer1@mall.com (密码: Test123456!)
- customer2@mall.com (密码: Test123456!)
- customer3@mall.com (密码: Test123456!)
- driver1@mall.com (密码: Test123456!)
- driver2@mall.com (密码: Test123456!)

#### 验证用户创建
```sql
\i create_supabase_auth_users.sql
```

## �📋 脚本清单

### 🔍 检查脚本
- **`mall_database_check.sql`** - 数据库状态检查脚本
  - 分析现有数据库结构
  - 检查缺失的表、字段、索引
  - 生成个性化升级建议

### 🚀 升级脚本
- **`mall_alter_upgrade.sql`** - 完整增量升级脚本
  - 创建商城核心表（如果不存在）
  - 为 ak_users 表添加商城字段
  - 创建索引、触发器、函数
  - 插入基础配置数据

- **`mall_fields_only_upgrade.sql`** - 仅字段升级脚本
  - 专门为已有表添加缺失字段
  - 添加CID自增字段（SEO优化）
  - 创建相应索引和约束
  - 最小化修改，适用于生产环境

### 🔄 迁移脚本
- **`quick_role_migration.sql`** - 角色字段快速迁移脚本
  - 将 `user_type` 字段安全迁移为 `role` 字段
  - 更新相关约束、索引、函数和视图
  - 包含完整的回滚方案
- **`role_field_unification.sql`** - 角色字段统一升级脚本（完整版）
  - 全面的角色字段统一方案
  - 创建角色管理相关的辅助函数
  - 数据一致性检查和修复

### 👥 用户和数据脚本
- **`create_supabase_auth_users.sql`** - Supabase Auth 用户检查脚本
  - 检测Supabase环境
  - 提供用户创建指导
  - 验证Auth用户状态

- **`create_supabase_auth_users.js`** - Node.js 用户批量创建脚本
  - 使用 Admin API 自动创建测试用户
  - 自动处理已存在用户
  - 详细日志输出

- **`create_supabase_auth_users.js`** - Node.js 用户创建脚本
  - 使用Admin API批量创建测试用户
  - 自动处理重复用户
  - 详细的执行日志

- **`mock_data_insert.sql`** - 模拟数据插入脚本

## 🎯 使用场景选择

### 场景一：Supabase 环境全新部署
```bash
# Supabase 环境完整部署流程
1. create_supabase_auth_users.js  # (推荐) 使用Admin API创建Auth用户
   # 或 create_supabase_auth_users.sql  # 检查并指导创建Auth用户
2. mall_migration.sql             # 创建所有表和结构
3. mall_seo_security.sql          # SEO优化和安全策略
4. mock_data_insert.sql           # (可选) 插入测试数据
```

### 场景二：现有数据库 + 缺少商城表
```bash
# 如果已有 ak_users 但缺少商城表
1. create_supabase_auth_users.js  # (Supabase环境) 创建Auth用户
2. mall_database_check.sql        # 检查数据库状态
3. mall_alter_upgrade.sql         # 增量升级（推荐）
4. mall_seo_security.sql          # SEO优化和安全策略
```

### 场景三：已有商城表 + 缺少字段/CID
```bash
# 如果已有商城表但缺少某些字段或CID
1. create_supabase_auth_users.js  # (Supabase环境) 确保Auth用户存在
2. mall_database_check.sql        # 检查数据库状态
3. mall_fields_only_upgrade.sql   # 仅添加字段和CID（推荐）
```

### 场景四：非Supabase环境
```bash
# 如果使用标准PostgreSQL
1. mall_database_check.sql        # 检查数据库状态
2. mall_alter_upgrade.sql         # 或 mall_fields_only_upgrade.sql
3. mall_seo_security.sql          # SEO优化和安全策略
4. mock_data_insert.sql           # 模拟数据（会创建虚拟auth_id）
```

## 📖 详细使用步骤

### 🔐 第零步：创建Supabase Auth用户（Supabase环境必需）

如果您使用Supabase，必须先创建Auth用户，否则业务数据无法正确关联。

#### 方法一：使用Node.js脚本（推荐）
```bash
# 1. 安装依赖
npm install @supabase/supabase-js

# 2. 设置环境变量
export SUPABASE_URL=https://your-project.supabase.co
export SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# 3. 运行脚本
node create_supabase_auth_users.js
```

#### 方法二：使用Supabase Dashboard
```bash
# 1. 登录 https://supabase.com/dashboard
# 2. 进入您的项目 -> Authentication -> Users
# 3. 点击 "Add user" 创建以下测试用户：

测试用户列表（密码统一：Test123456!）：
📧 admin@mall.com      (角色: 管理员)
📧 merchant1@mall.com  (角色: 商家)
📧 merchant2@mall.com  (角色: 商家)  
📧 customer1@mall.com  (角色: 消费者)
📧 customer2@mall.com  (角色: 消费者)
📧 customer3@mall.com  (角色: 消费者)
📧 driver1@mall.com    (角色: 配送员)
📧 driver2@mall.com    (角色: 配送员)
```

#### 方法三：SQL检查脚本
```sql
-- 检查环境并获得创建指导
\i create_supabase_auth_users.sql
```

### 第一步：检查数据库状态
```sql
-- 在数据库中执行检查脚本
\i mall_database_check.sql
```

### 第二步：根据检查结果选择脚本
检查脚本会输出类似以下建议：
```
根据您的数据库状态分析：
• ak_users 表缺失字段数: 3
• 缺失商城核心表数: 5

推荐执行方案: 建议使用 mall_alter_upgrade.sql（完整升级脚本）
```

### 第三步：执行升级脚本
```sql
-- 根据建议执行相应脚本
\i mall_alter_upgrade.sql
-- 或
\i mall_fields_only_upgrade.sql
```

### 第四步：执行SEO优化（可选）
```sql
\i mall_seo_security.sql
```

## 🔧 脚本特性

### 安全特性
- ✅ 使用 `IF NOT EXISTS` 检查，避免重复创建
- ✅ 使用 `DO $$ ... END $$` 块进行条件检查
- ✅ 详细的日志输出，便于跟踪执行过程
- ✅ 事务安全，出错时自动回滚

### 兼容性
- ✅ PostgreSQL 12+
- ✅ Supabase 完全兼容
- ✅ 保持与现有数据的兼容性
- ✅ 复用 ak_users 表，新表使用 ml_ 前缀

## 📝 字段说明

### ak_users 表新增字段
| 字段名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `mall_status` | INTEGER | 1 | 商城状态 (1:正常 2:禁用) |
| `mall_type` | INTEGER | 1 | 用户类型 (1:消费者 2:商家 3:其他) |
| `total_orders` | INTEGER | 0 | 总订单数 |
| `total_spent` | DECIMAL | 0.00 | 总消费金额 |
| `user_level` | INTEGER | 1 | 用户等级 (1-10) |
| `points` | INTEGER | 0 | 用户积分 |
| `verified_status` | INTEGER | 0 | 认证状态 (0:未认证 1:已认证 2:失败) |

### 商城核心表
| 表名 | 说明 | CID字段 |
|------|------|---------|
| `ml_user_profiles` | 用户扩展信息 | ❌ |
| `ml_categories` | 商品分类 | ✅ |
| `ml_brands` | 品牌 | ✅ |
| `ml_products` | 商品 | ✅ |
| `ml_shops` | 店铺 | ✅ |
| `ml_orders` | 订单 | ✅ |

## ⚠️ 注意事项

### 执行前准备
1. **备份数据库** - 在生产环境执行前务必备份
2. **测试环境验证** - 先在测试环境执行和验证
3. **检查权限** - 确保有足够的数据库权限
4. **停止应用** - 执行期间建议停止相关应用

### 生产环境建议
1. **分步执行** - 可以分多次执行，每次执行一个脚本
2. **监控日志** - 注意观察执行过程中的日志输出
3. **验证结果** - 执行后检查表结构和数据完整性
4. **回滚准备** - 准备回滚方案以防出现问题

## 🔄 回滚方案

如果需要回滚，可以执行以下操作：

```sql
-- 删除新增字段（谨慎操作）
ALTER TABLE public.ak_users DROP COLUMN IF EXISTS mall_status;
ALTER TABLE public.ak_users DROP COLUMN IF EXISTS mall_type;
-- ... 其他字段

-- 删除新建表（谨慎操作）
DROP TABLE IF EXISTS public.ml_shopping_cart CASCADE;
DROP TABLE IF EXISTS public.ml_orders CASCADE;
-- ... 其他表（注意依赖关系）
```

## � Supabase Auth 用户创建详细说明

### 为什么需要先创建 Auth 用户？

在 Supabase 环境中，`ak_users.auth_id` 字段需要关联真实的 `auth.users.id`。如果 Auth 用户不存在，模拟数据脚本会创建虚拟 UUID，导致用户无法正常登录。

### 创建方式对比

| 方式 | 优点 | 缺点 | 适用场景 |
|------|------|------|----------|
| Node.js 脚本 | 自动化，批量处理，错误处理完善 | 需要配置环境变量 | 开发环境，批量创建 |
| Dashboard 手动 | 直观，不需要代码 | 手动操作，容易出错 | 少量用户，生产环境 |
| Admin API | 灵活，可集成到应用 | 需要编程实现 | 自定义集成 |

### 环境变量配置

创建 `.env` 文件或设置系统环境变量：
```bash
# Supabase 项目 URL
SUPABASE_URL=https://your-project-id.supabase.co

# Service Role Key (在 Dashboard > Settings > API 中找到)
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

### 验证 Auth 用户创建成功

```sql
-- 查看所有测试用户
SELECT 
    id,
    email,
    email_confirmed_at IS NOT NULL as confirmed,
    created_at,
    user_metadata
FROM auth.users 
WHERE email LIKE '%@mall.com'
ORDER BY email;

-- 检查 ak_users 关联状态
SELECT 
    u.email,
    u.nickname,
    u.user_type,
    CASE 
        WHEN au.id IS NOT NULL THEN '✓ 已关联'
        ELSE '✗ 未关联'
    END as auth_status
FROM ak_users u
LEFT JOIN auth.users au ON u.auth_id = au.id
WHERE u.email LIKE '%@mall.com'
ORDER BY u.email;
```

### 常见问题解决

#### 1. Service Role Key 权限不足
确保使用的是 Service Role Key，不是 anon key。

#### 2. 用户已存在错误
脚本会自动处理已存在的用户，不会重复创建。

#### 3. 邮箱验证问题
脚本设置 `email_confirm: true`，自动验证邮箱。

#### 4. 密码策略不符合要求
默认密码 `Test123456!` 符合大多数密码策略，如需修改请在脚本中调整。

## 🔧 故障排除

### Auth 用户创建失败
```bash
# 检查网络连接
curl -I https://your-project.supabase.co

# 验证 API Key
curl -H "Authorization: Bearer $SUPABASE_SERVICE_ROLE_KEY" \
     https://your-project.supabase.co/auth/v1/admin/users

# 重新运行创建脚本
node create_supabase_auth_users.js
```

## �📞 技术支持

如遇问题，请：
1. 检查数据库日志
2. 确认PostgreSQL版本兼容性
3. 验证执行权限
4. 查看详细错误信息
5. 确保 Supabase Auth 用户已正确创建

---

**最后更新：** 2024年12月
**版本：** v1.1
**兼容性：** PostgreSQL 12+, Supabase
**新增：** Supabase Auth 用户创建流程