consumer模块完成90%，前端完成supabase对接

pages/mall/consumer/sql/SUPABASE_CONSUMER_INTEGRATION.md

@@ -0,0 +1,231 @@
+# Supabase 消费者端集成指南 (Consumer Frontend Integration Guide)
+
+本文档基于 `complete_mall_database.sql` 数据库设计，为消费者端 (Consumer App) 前端开发提供对接指引。
+
+## 1. 核心表结构概览
+
+所有商城相关表均以 `ml_` 开头。
+
+| 功能模块 | 核心表 | 视图 (推荐使用) | 说明 |
+| :--- | :--- | :--- | :--- |
+| **用户** | `ml_user_profiles`, `ml_user_addresses` | `ml_users_view` | 用户扩展信息、收货地址 |
+| **商品** | `ml_products`, `ml_categories`, `ml_product_skus` | `ml_products_detail_view` | 商品、分类、SKU库存 |
+| **店铺** | `ml_shops` | - | 店铺基础信息 |
+| **购物车** | `ml_shopping_cart` | - | 购物车数据 |
+| **订单** | `ml_orders`, `ml_order_items` | `ml_orders_detail_view` | 订单主表及明细 |
+| **营销** | `ml_user_coupons`, `ml_coupon_templates` | - | 优惠券 |
+| **互动** | `ml_user_favorites`, `ml_product_reviews` | - | 收藏、评价 |
+
+---
+
+## 2. 关键业务场景与查询示例
+
+### 2.1 首页展示
+
+#### 获取一级分类
+```typescript
+const { data, error } = await supabase
+  .from('ml_categories')
+  .select('id, name, icon_url')
+  .eq('level', 1)
+  .eq('is_active', true)
+  .order('sort_order', { ascending: true });
+```
+
+#### 获取热销/推荐商品
+```typescript
+const { data, error } = await supabase
+  .from('ml_products')
+  .select('id, name, main_image_url, base_price, sale_count')
+  .eq('status', 1)        // 上架状态
+  .eq('is_hot', true)     // 热销标记
+  .limit(10);
+```
+
+### 2.2 商品详情页
+
+建议优先使用 `ml_products` 表配合关联查询，或者使用视图。
+
+#### 获取商品基础信息
+```typescript
+const { data, error } = await supabase
+  .from('ml_products')
+  .select(`
+    *,
+    category:ml_categories(id, name),
+    brand:ml_brands(id, name),
+    shop:ml_shops(id, shop_name, shop_logo),
+    skus:ml_product_skus(*),
+    specs:ml_product_specs(*)
+  `)
+  .eq('id', productId)
+  .single();
+```
+
+*注意：`skus` 和 `specs` 是通过外键关联获取的，确保前端处理好 `1:N` 的关系。*
+
+### 2.3 购物车管理
+
+前端需维护购物车逻辑，数据均存储在 `ml_shopping_cart`。
+
+#### 获取我的购物车 (含商品详情)
+**重要**：务必使用内联查询 (`!inner` 或关联) 获取商品最新价格和图片。
+
+```typescript
+const { data, error } = await supabase
+  .from('ml_shopping_cart')
+  .select(`
+    id,
+    quantity,
+    selected,
+    sku_id,
+    product:ml_products!inner (
+      id,
+      name,
+      main_image_url,
+      base_price,    -- 基础价格
+      status,        -- 检查是否下架
+      merchant_id    -- 用于店铺分组
+    ),
+    sku:ml_product_skus (
+      id,
+      sku_code,
+      price,         -- SKU价格（如果有）
+      specifications,
+      stock,
+      image_url
+    )
+  `)
+  .eq('user_id', currentUserId)
+  .order('created_at', { ascending: false });
+```
+
+#### 店铺分组逻辑 (前端处理)
+前端获取数据后，应根据 `product.merchant_id` 进行分组，并聚合显示店铺名称 (需另外查询或关联 `ml_shops`)。
+
+### 2.4 收货地址
+
+#### 获取地址列表
+```typescript
+const { data, error } = await supabase
+  .from('ml_user_addresses')
+  .select('*')
+  .eq('user_id', currentUserId)
+  .eq('status', 1)  // 1: 正常
+  .order('is_default', { ascending: false }) // 默认地址排最前
+  .order('updated_at', { ascending: false });
+```
+
+### 2.5 订单列表
+
+#### 查询我的订单
+```typescript
+const { data, error } = await supabase
+  .from('ml_orders')
+  .select(`
+    id,
+    order_no,
+    total_amount,
+    order_status,
+    created_at,
+    items:ml_order_items (
+      id,
+      product_name,
+      image_url,
+      quantity,
+      price,
+      specifications
+    ),
+    shop:ml_shops (
+      shop_name
+    )
+  `)
+  .eq('user_id', currentUserId)
+  .order('created_at', { ascending: false });
+```
+
+---
+
+## 3. RLS (行级安全) 注意事项
+
+数据库已配置 RLS 策略，前端直接调用 Supabase Client 即可，**无需在查询时手动增加 `user_id` 过滤** (除了显式需要对业务逻辑进行过滤的地方，RLS 会自动兜底)。
+
+- **`ml_shopping_cart`**: 用户只能查/改/删自己的购物车记录。
+- **`ml_user_addresses`**: 用户只能查/改/删自己的地址。
+- **`ml_orders`**: 用户只能查看自己的订单。
+- **`ml_products`**: 设置为 `status = 1` 的商品所有人可读。
+
+*确保在 App 启动时正确初始化 Supabase Auth 并处于登录状态。*
+
+## 4. 推荐使用的数据库函数 (RPC)
+
+可以直接通过 ` supabase.rpc('function_name', params)` 调用以下函数：
+
+| 函数名 | 参数 | 描述 |
+| :--- | :--- | :--- |
+| `calculate_cart_total` | `p_user_id` | 计算当前用户购物车选中商品的总金额 (服务端计算更安全) |
+| `get_product_available_stock` | `p_product_id`, `p_sku_id` | 获取特定商品或SKU的实时可用库存 |
+| `get_user_default_address` | `p_user_id` | 快速获取用户的默认收货地址 |
+
+### 调用示例
+```typescript
+// 计算购物车总价
+const { data: total, error } = await supabase
+  .rpc('calculate_cart_total', { 
+    p_user_id: currentUserId 
+  });
+```
+
+## 5. 类型定义参考 (TypeScript)
+
+为方便前端开发，以下是核心表对应的推荐接口定义：
+
+```typescript
+// 购物车项 (结合了关联查询的结果)
+export interface CartItem {
+  id: string;
+  quantity: number;
+  selected: boolean;
+  product: {
+    id: string;
+    name: string;
+    main_image_url: string;
+    base_price: number;
+    merchant_id: string;
+  };
+  sku?: {
+    id: string;
+    price: number;
+    specifications: string; // JSON string
+    stock: number;
+  };
+  shop_name?: string; // 前端处理后注入
+}
+
+// 订单结构
+export interface Order {
+  id: string;
+  order_no: string;
+  total_amount: number;
+  order_status: number; // 1:待付款 2:待发货 3:待收货 4:已完成 ...
+  items: Array<{
+    product_name: string;
+    image_url: string;
+    quantity: number;
+    price: number;
+  }>;
+}
+```
+
+## 6. 特殊字段说明
+
+- **Product Images**:
+  - `main_image_url`: 列表页和购物车主图。
+  - `image_urls`: JSONB 数组，用于商品详情轮播图。
+- **Specifications**:
+  - 在 `ml_product_skus` 表中 `specifications` 为 JSONB 格式 (例如 `{"color": "红色", "size": "L"}`)，前端需解析展示。
+- **Money**:
+  - 数据库使用 `DECIMAL`，API 返回为 `number`，建议前端统一处理为两位小数展示。
+
+---
+*文档生成日期: 2026-02-02*