medical-mall/doc_mall/consumer/backup_sql_full/SUPABASE_CONSUMER_INTEGRATION.md

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 首页展示

获取一级分类

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 });

获取热销/推荐商品

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 表配合关联查询，或者使用视图。

获取商品基础信息

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 或关联) 获取商品最新价格和图片。

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 收货地址

获取地址列表

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 订单列表

查询我的订单

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	快速获取用户的默认收货地址

调用示例

// 计算购物车总价
const { data: total, error } = await supabase
  .rpc('calculate_cart_total', { 
    p_user_id: currentUserId 
  });

5. 类型定义参考 (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