# 消费者端前端数据库文档 (Consumer App DB Schema)

本文档基于现有消费者前端 (`mall/pages/mall/consumer`) 和 Supabase 服务层 (`mall/utils/supabaseService.uts`) 的调用逻辑生成。旨在协助商家端前端开发进行数据库对接。

## 1. 核心业务表 (Core Business Tables)

### 1.1 商品分类表 (`ml_categories`)
用于展示商品的一级/二级分类。

| 字段名 | 类型 | 描述 | 备注 |
| :--- | :--- | :--- | :--- |
| `id` | UUID | 主键 | |
| `name` | Text | 分类名称 | |
| `icon_url` | Text | 图标 URL | 前端可能回退到 Emoji |
| `description` | Text | 描述 | |
| `parent_id` | UUID | 父分类 ID | 用于树形结构 |
| `sort_order` | Integer | 排序权重 | |
| `is_active` | Boolean | 是否启用 | |

### 1.2 品牌表 (`ml_brands`)
商品所属品牌信息。

| 字段名 | 类型 | 描述 | 备注 |
| :--- | :--- | :--- | :--- |
| `id` | UUID | 主键 | |
| `name` | Text | 品牌名称 | |
| `logo_url` | Text | 品牌 Logo URL | |
| `description` | Text | 品牌描述 | |
| `country` | Text | 所属国家 | 可选 |
| `is_active` | Boolean | 是否启用 | |

### 1.3 商家/店铺表 (`ml_shops`)
商家端主要管理的店铺信息实体。

| 字段名 | 类型 | 描述 | 备注 |
| :--- | :--- | :--- | :--- |
| `id` | UUID | 主键 | |
| `merchant_id` | UUID | 关联的商户账号 ID | 对应 auth.users 或 merchants 表 |
| `shop_name` | Text | 店铺名称 | |
| `shop_logo` | Text | 店铺 Logo | |
| `shop_banner` | Text | 店铺背景图 | |
| `description` | Text | 店铺简介 | |
| `contact_name` | Text | 联系人 | |
| `contact_phone` | Text | 联系电话 | |
| `rating_avg` | Numeric | 平均评分 | |
| `total_sales` | Integer | 总销量 | |
| `status` | Integer | 状态 | 1: 正常, 0: 停用 |

---

## 2. 商品系统 (Product System)

### 2.1 商品主表 (`ml_products`)
商家发布的核心商品数据。

| 字段名 | 类型 | 描述 | 备注 |
| :--- | :--- | :--- | :--- |
| `id` | UUID | 主键 | |
| `merchant_id` | UUID | 所属商家 ID | |
| `category_id` | UUID | 所属分类 ID | |
| `brand_id` | UUID | 所属品牌 ID | |
| `name` | Text | 商品名称 | |
| `subtitle` | Text | 副标题 | 简短描述 |
| `description` | Text | 商品详情 | HTML 或 Markdown |
| `main_image_url` | Text | 主图 URL | |
| `image_urls` | JSON/Array | 轮播图列表 | `['url1', 'url2']` |
| `video_urls` | JSON/Array | 视频列表 | |
| `base_price` | Numeric | 基础售价 | 列表页展示价格 |
| `market_price` | Numeric | 市场价/划线价 | |
| `cost_price` | Numeric | 成本价 | 敏感字段，仅商家可见 |
| `total_stock` | Integer | 总库存 | |
| `status` | Integer | 状态 | 1: 上架, 0: 下架, 2: 审核中 |
| `is_hot` | Boolean | 是否热销 | |
| `is_new` | Boolean | 是否新品 | |
| `is_featured` | Boolean | 是否推荐 | |
| `attributes` | JSONB | 商品属性 | `{ "材质": "纯棉", "季节": "夏季" }` |
| `tags` | Text[] | 标签 | |
| `sale_count` | Integer | 销量 | 统计字段 |

### 2.2 商品 SKU 表 (`ml_product_skus`)
商品的多规格定义（如颜色、尺寸）。

| 字段名 | 类型 | 描述 | 备注 |
| :--- | :--- | :--- | :--- |
| `id` | UUID | 主键 | |
| `product_id` | UUID | 关联商品 ID | |
| `sku_code` | Text | SKU 编码 | 商家自定义编码 |
| `specifications` | JSONB | 规格键值对 | `{ "颜色": "红", "尺寸": "L" }` |
| `price` | Numeric | SKU 售价 | 特殊规格价格 |
| `market_price` | Numeric | SKU 市场价 | |
| `stock` | Integer | 当前库存 | |
| `image_url` | Text | 规格对应图片 | 如红色款对应红色的图 |
| `status` | Integer | 状态 | 1: 启用, 0: 禁用 |

### 2.3 商品详情视图 (`ml_products_detail_view`)
**重要**: 消费者端主要通过此视图查询商品，商家在维护数据时应确保这些关联字段能正确生成。
*   该视图通常 `JOIN` 了 `ml_shops` (获取 `shop_name`), `ml_brands` (获取 `brand_name`), `ml_categories` (获取 `category_name`)。
*   **商家端操作**: 不需要直接操作视图，只需维护上述基础表。

---

## 3. 交易系统 (Transaction System)

### 3.1 购物车 (`ml_shopping_cart`)

| 字段名 | 类型 | 描述 | 备注 |
| :--- | :--- | :--- | :--- |
| `id` | UUID | 主键 | |
| `user_id` | UUID | 用户 ID | |
| `product_id` | UUID | 商品 ID | |
| `sku_id` | UUID | SKU ID | 可空（若商品无多规格） |
| `quantity` | Integer |数量 | |
| `selected` | Boolean | 是否勾选 | 购物车状态 |
| `created_at` | Timestamp | 创建时间 | |

### 3.2 订单主表 (`ml_orders`) (推测结构)
商家端处理订单的核心表。

| 字段名 | 类型 | 描述 | 备注 |
| :--- | :--- | :--- | :--- |
| `id` | UUID | 主键 | |
| `user_id` | UUID | 用户 ID | |
| `merchant_id` | UUID | 商家 ID | |
| `order_no` | Text | 订单号 | 唯一业务单号 |
| `total_amount` | Numeric | 订单总金额 | |
| `pay_amount` | Numeric | 实付金额 | |
| `status` | Integer | 订单状态 | 0: 待付款, 1: 待发货, 2: 待收货, 3: 已完成, -1: 已取消 |
| `address_snapshot` | JSONB | 收货地址快照 | 下单时的地址信息 |
| `remark` | Text | 订单备注 | |
| `created_at` | Timestamp | 下单时间 | |

### 3.3 订单项表 (`ml_order_items`) (推测结构)

| 字段名 | 类型 | 描述 | 备注 |
| :--- | :--- | :--- | :--- |
| `id` | UUID | 主键 | |
| `order_id` | UUID | 订单 ID | |
| `product_id` | UUID | 商品 ID | |
| `sku_id` | UUID | SKU ID | |
| `product_name` | Text | 商品名称快照 | |
| `price` | Numeric | 成交单价 | |
| `quantity` | Integer | 购买数量 | |
| `sku_snapshot` | JSONB | 规格快照 | |

---

## 4. 用户相关 (User Relations)

### 4.1 用户地址 (`ml_user_addresses`)

| 字段名 | 类型 | 描述 | 备注 |
| :--- | :--- | :--- | :--- |
| `id` | UUID | 主键 | |
| `user_id` | UUID | 用户 ID | |
| `recipient_name` | Text | 收货人姓名 | |
| `phone` | Text | 手机号 | |
| `province` | Text | 省 | |
| `city` | Text | 市 | |
| `district` | Text | 区 | |
| `detail_address` | Text | 详细地址 | |
| `is_default` | Boolean | 是否默认地址 | |

### 4.2 聊天消息 (`ml_chat_messages`)
用于客服系统。

| 字段名 | 类型 | 描述 | 备注 |
| :--- | :--- | :--- | :--- |
| `id` | UUID | 主键 | |
| `session_id` | UUID | 会话 ID | 可选，或通过收发人聚合 |
| `sender_id` | UUID | 发送者 ID | |
| `receiver_id` | UUID | 接收者 ID | |
| `content` | Text | 消息内容 | |
| `msg_type` | Text | 消息类型 | 'text', 'image', 'product' |
| `is_read` | Boolean | 是否已读 | |
| `created_at` | Timestamp | 发送时间 | |

## 5. 对接建议 (Integration Tips for Merchant Frontend)

1.  **商品管理**:
    *   在创建商品时，必须先选择 `category_id` 和 `merchant_id`。
    *   如果有 `specifications` (多规格)，请同时向 `ml_product_skus` 插入数据。
    *   更新库存时，请优先更新 `ml_product_skus` 中的 `stock`，并同步总库存到 `ml_products`.`total_stock`。

2.  **图片处理**:
    *   消费者端支持 `main_image_url` (字符串) 和 `image_urls` (JSON 数组) 两种格式，请确保都正确填充。

3.  **状态管理**:
    *   上架商品请将 `status` 设为 `1`。
    *   如需在首页 "推荐/热销" 板块显示，请设置 `is_featured` 或 `is_hot` 为 `true`。

4.  **Supabase 安全策略 (RLS)**:
    *   请确保商家端账号有权限写入 `ml_products` 和 `ml_shops` 表，但只能修改 `merchant_id` 等于自己账号的数据。