medical-mall/mall_sql/README.md

# Mall SQL 数据库脚本集合

> **电商商城系统** - PostgreSQL + Supabase 数据库脚本总目录

---

## 📁 目录结构

```
mall_sql/
├── schemas/              # 数据库表结构定义
├── migrations/           # 数据库迁移/升级脚本
├── tests/                # 测试和验证脚本
├── subscription/         # 订阅系统专用脚本
├── scripts/              # 迁移脚本 (migrate.sh/ps1)
├── docs/                 # 数据库文档
├── deploy.sh             # Linux/Mac 自动部署脚本
├── deploy.bat            # Windows 自动部署脚本
└── README.md             # 本文件
```

---

## 🚀 快速开始

### 首次部署（全新数据库）

```bash
# 1. 执行完整数据库创建
psql -h db.example.com -U postgres -d akmon -f schemas/complete_mall_database.sql

# 2. 创建测试用户和模拟数据
psql -h db.example.com -U postgres -d akmon -f tests/mock_data_insert.sql
```

### 增量升级（已有数据库）

```bash
# 1. 先检查数据库状态
psql -h db.example.com -U postgres -d akmon -f tests/mall_database_check.sql

# 2. 执行增量升级
psql -h db.example.com -U postgres -d akmon -f migrations/mall_alter_upgrade.sql
```

---

## 📦 schemas/ - 数据库表结构

| 文件 | 说明 | 执行顺序 |
|------|------|----------|
| `complete_mall_database.sql` | 完整商城数据库（21个表）**推荐** | 1 |
| `ak_contents_product_extension.sql` | **备选方案**: 基于ak_contents扩展商品 | - |
| `product_database.sql` | 商品相关表补充 | 2 |
| `mall_seo_security.sql` | SEO优化和安全策略 | 3 |

### 两种实现方案

**方案一: 独立商城表（推荐）**
- 使用 `ml_products` 等独立表
- 执行: `complete_mall_database.sql`
- 优点: 职责清晰，不影响资讯系统

**方案二: 扩展ak_contents表（备选）**
- 复用 `ak_contents` 表，添加商品字段
- 执行: `ak_contents_product_extension.sql`
- 优点: 统一内容管理，但混合了资讯和商品

### complete_mall_database.sql

完整的商城系统数据库定义，包含：

**用户模块**:
- `ml_user_profiles` - 用户扩展信息
- `ml_user_addresses` - 用户地址

**商品模块**:
- `ml_categories` - 商品分类
- `ml_brands` - 品牌
- `ml_products` - 商品主表
- `ml_product_skus` - SKU规格
- `ml_product_images` - 商品图片

**订单模块**:
- `ml_orders` - 订单主表
- `ml_order_items` - 订单明细
- `ml_order_status_log` - 订单状态日志

**配送模块**:
- `ml_delivery_tasks` - 配送任务
- `ml_delivery_tracking` - 配送跟踪

**支付模块**:
- `ml_payments` - 支付记录

**营销模块**:
- `ml_coupons` - 优惠券
- `ml_user_coupons` - 用户优惠券

**订阅模块**:
- `ml_subscriptions` - 订阅计划
- `ml_user_subscriptions` - 用户订阅

---

## 🔄 migrations/ - 数据库迁移

| 文件 | 说明 | 使用场景 |
|------|------|----------|
| `mall_alter_upgrade.sql` | 完整增量升级 | 生产环境升级 |
| `mall_fields_only_upgrade.sql` | 仅字段升级 | 最小化修改 |
| `quick_role_migration.sql` | 角色字段快速迁移 | user_type→role |
| `mall_migration.sql` | 通用迁移脚本 | 兼容性处理 |
| `role_field_unification.sql` | 角色字段统一 | 数据一致性 |
| `role_field_cleanup.sql` | 角色字段清理 | 清理冗余字段 |
| `user_compatibility_implementation.sql` | 用户兼容性实现 | 跨模块兼容 |

### 重要迁移说明

**角色字段统一**:
- 旧字段: `user_type` (INTEGER)
- 新字段: `role` (TEXT)
- 迁移脚本: `quick_role_migration.sql`

**角色值映射**:
| user_type | role |
|-----------|------|
| 1 | 'admin' |
| 2 | 'merchant' |
| 3 | 'customer' |
| 4 | 'delivery' |
| 5 | 'service' |

---

## 🧪 tests/ - 测试和验证

| 文件 | 说明 |
|------|------|
| `mall_database_check.sql` | 数据库状态检查 |
| `validation_test.sql` | 数据完整性验证 |
| `verify_mock_data_fix.sql` | 模拟数据修复验证 |
| `mock_data_insert.sql` | 创建测试数据 |
| `create_supabase_auth_users.sql` | 创建Supabase Auth用户 |

### 测试数据说明

`mock_data_insert.sql` 创建以下测试数据：
- 1个管理员
- 2个商家
- 10个商品
- 3个客户
- 20个订单
- 2个配送员
- 5个配送任务

---

## 📬 subscription/ - 订阅系统

| 文件 | 说明 |
|------|------|
| `create_mall_subscription_tables.sql` | 订阅表创建 |
| `subscription_guard_trigger.sql` | 订阅守护触发器 |
| `subscription_rls_policies.sql` | 订阅RLS安全策略 |

### 订阅系统表

- `ml_subscriptions` - 订阅计划定义
- `ml_user_subscriptions` - 用户订阅记录
- `ml_subscription_payments` - 订阅支付记录

---

## 📚 docs/ - 文档

### 核心文档
| 文件 | 说明 |
|------|------|
| `MALL_README.md` | 商城系统主文档 |
| `TECHNICAL_IMPLEMENTATION.md` | 技术实现详解 |
| `MODULE_ANALYSIS.md` | 模块分析 |

### 部署与升级
| 文件 | 说明 |
|------|------|
| `UPGRADE_GUIDE.md` | 数据库升级指南 |
| `MIGRATION_GUIDE.md` | 迁移指南 |
| `QUICK_START_MIGRATION.md` | 快速迁移指南 |
| `MIGRATION_CHECKLIST.md` | 迁移检查清单 |
| `MIGRATION_SUMMARY.md` | 迁移总结 |
| `complete_deployment_guide.md` | 完整部署指南 |
| `deployment_guide.md` | 部署指南 |
| `migration_complete_report.md` | 迁移完成报告 |

### 角色与权限
| 文件 | 说明 |
|------|------|
| `ROLE_FIELD_SUMMARY.md` | 角色字段变更总结 |
| `ROLE_FIELD_FIX_REPORT.md` | 角色字段修复报告 |
| `user_reuse_summary.md` | 用户复用总结 |

### 问题修复报告
| 文件 | 说明 |
|------|------|
| `VARIABLE_CONFLICT_FIX_REPORT.md` | 变量冲突修复 |
| `database_syntax_fix_report.md` | 数据库语法修复 |
| `type_error_fix_report.md` | 类型错误修复 |

### 测试与数据
| 文件 | 说明 |
|------|------|
| `mock_data_documentation.md` | 测试数据文档 |
| `database_creation_report.md` | 数据库创建报告 |
| `FRONTEND_BACKEND_DEBUGGING.md` | 前后端调试指南 |

### SEO与优化
| 文件 | 说明 |
|------|------|
| `seo_optimization_guide.md` | SEO优化指南 |
| `seo_optimization_report.md` | SEO优化报告 |

### 订阅系统
| 文件 | 说明 |
|------|------|
| `README_subscription_consumer.md` | 订阅系统说明 |
| `裂变红包.md` | 裂变红包功能 |

### 页面报告
| 目录 | 说明 |
|------|------|
| `docs/reports/` | 页面生成报告 |
| `docs/analysis/` | 兼容性分析 |

---

## 🗄️ 数据库表总览

```
akmon (PostgreSQL Database)
│
├── public.ak_users                    # 用户主表（共享）
│
└── public.ml_* (商城系统表，21张)
    ├── ml_user_profiles               # 用户扩展信息
    ├── ml_user_addresses              # 用户地址
    ├── ml_categories                  # 商品分类
    ├── ml_brands                      # 品牌
    ├── ml_products                    # 商品
    ├── ml_product_skus                # SKU
    ├── ml_product_images              # 商品图片
    ├── ml_orders                      # 订单
    ├── ml_order_items                 # 订单明细
    ├── ml_order_status_log            # 订单日志
    ├── ml_delivery_tasks              # 配送任务
    ├── ml_delivery_tracking           # 配送跟踪
    ├── ml_payments                     # 支付
    ├── ml_coupons                     # 优惠券
    ├── ml_user_coupons                # 用户优惠券
    ├── ml_subscriptions               # 订阅计划
    ├── ml_user_subscriptions          # 用户订阅
    ├── ml_subscription_payments       # 订阅支付
    ├── ml_merchant_profiles            # 商家资料
    ├── ml_delivery_staff              # 配送员
    └── ml_notifications               # 通知
```

---

## 🔧 常用SQL操作

### 检查表是否存在
```sql
SELECT table_name, table_type
FROM information_schema.tables
WHERE table_schema = 'public'
  AND table_name LIKE 'ml_%'
ORDER BY table_name;
```

### 查看表结构
```sql
\d+ public.ml_products
-- 或
SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_schema = 'public'
  AND table_name = 'ml_products'
ORDER BY ordinal_position;
```

### 检查索引
```sql
SELECT indexname, indexdef
FROM pg_indexes
WHERE schemaname = 'public'
  AND tablename LIKE 'ml_%'
ORDER BY tablename, indexname;
```

### 检查RLS策略
```sql
SELECT schemaname, tablename, policyname, permissive, roles, cmd, qual
FROM pg_policies
WHERE schemaname = 'public'
  AND tablename LIKE 'ml_%'
ORDER BY tablename, policyname;
```

---

## ⚠️ 注意事项

### 执行顺序

1. **全新部署**: 按以下顺序执行
   - `schemas/complete_mall_database.sql`
   - `schemas/product_database.sql`
   - `schemas/mall_seo_security.sql`
   - `subscription/create_mall_subscription_tables.sql`
   - `tests/mock_data_insert.sql`

2. **增量升级**: 先检查后升级
   - `tests/mall_database_check.sql`
   - 根据检查结果选择合适的迁移脚本
   - `tests/validation_test.sql`

### Supabase Auth 用户

在执行任何脚本之前，**必须先创建 Supabase Auth 用户**：
```bash
psql -f tests/create_supabase_auth_users.sql
```

### 角色字段兼容性

如果你的数据库使用旧的 `user_type` 字段，请先执行角色迁移：
```bash
psql -f migrations/quick_role_migration.sql
```

---

## 📞 支持

如有问题，请查阅：
1. `docs/complete_deployment_guide.md` - 完整部署指南
2. `docs/UPGRADE_GUIDE.md` - 升级指南
3. `docs/ROLE_FIELD_SUMMARY.md` - 角色字段说明

---

**最后更新**: 2026-01-30
**维护者**: AKMON开发团队