# 消费者端前端数据库文档 (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 | 主键 | |
| `order_no` | VARCHAR | 订单号 | 唯一业务单号 |
| `user_id` | UUID | 用户 ID | |
| `merchant_id` | UUID | 商家 ID | |
| `product_amount` | NUMERIC | 商品金额 | 默认0 |
| `discount_amount` | NUMERIC | 优惠金额 | |
| `shipping_fee` | NUMERIC | 运费 | |
| `total_amount` | NUMERIC | 订单总金额 | |
| `paid_amount` | NUMERIC | 实付金额 | |
| `shipping_address` | JSONB | 收货地址 | |
| `order_status` | INTEGER | 订单状态 | 1:待付款, 2:待发货, 3:待收货, 4:已完成, 5:已取消, 0:退款中, -1:已取消 |
| `payment_status` | INTEGER | 支付状态 | 默认1 |
| `shipping_status` | INTEGER | 发货状态 | 默认1 |
| `paid_at` | TIMESTAMP | 支付时间 | |
| `shipped_at` | TIMESTAMP | 发货时间 | |
| `delivered_at` | TIMESTAMP | 收货时间 | |
| `completed_at` | TIMESTAMP | 完成时间 | |
| `remark` | TEXT | 订单备注 | |
| `merchant_memo` | TEXT | 商家备注 | |
| `cancel_reason` | TEXT | 取消原因 | |
| `created_at` | TIMESTAMP | 创建时间 | 默认now() |
| `updated_at` | TIMESTAMP | 更新时间 | |
| `cid` | INTEGER | 序号 | |
| `payment_method` | VARCHAR | 支付方式 | |
| `payment_time` | TIMESTAMP | 支付时间 | |
| `shipping_company` | VARCHAR | 物流公司 | 商家端发货填写 |
| `tracking_number` | VARCHAR | 物流单号 | 商家端发货填写 |

### 3.3 订单项表 (`ml_order_items`)

| 字段名 | 类型 | 描述 | 备注 |
| :--- | :--- | :--- | :--- |
| `id` | UUID | 主键 | |
| `order_id` | UUID | 订单 ID | |
| `product_id` | UUID | 商品 ID | |
| `sku_id` | UUID | SKU ID | 可空 |
| `product_name` | VARCHAR | 商品名称快照 | |
| `sku_name` | VARCHAR | SKU名称 | 可空 |
| `specifications` | JSONB | 规格信息 | 默认{} |
| `image_url` | TEXT | 商品图片 | 可空 |
| `price` | NUMERIC | 成交单价 | |
| `quantity` | INTEGER | 购买数量 | |
| `total_amount` | NUMERIC | 小计金额 | |
| `created_at` | TIMESTAMP | 创建时间 | |
| `sku_snapshot` | JSONB | SKU快照 | 默认{} |

### 3.4 订单详情视图 (`ml_orders_detail_view`)
订单联合查询视图。

| 字段名 | 类型 | 描述 | 备注 |
| :--- | :--- | :--- | :--- |
| `id` | UUID | 主键 | |
| `order_no` | VARCHAR | 订单号 | |
| `user_id` | UUID | 用户 ID | |
| `merchant_id` | UUID | 商家 ID | |
| `product_amount` | NUMERIC | 商品金额 | |
| `discount_amount` | NUMERIC | 优惠金额 | |
| `shipping_fee` | NUMERIC | 运费 | |
| `total_amount` | NUMERIC | 订单总金额 | |
| `paid_amount` | NUMERIC | 实付金额 | |
| `shipping_address` | JSONB | 收货地址 | |
| `order_status` | INTEGER | 订单状态 | |
| `payment_status` | INTEGER | 支付状态 | |
| `shipping_status` | INTEGER | 发货状态 | |
| `paid_at` | TIMESTAMP | 支付时间 | |
| `shipped_at` | TIMESTAMP | 发货时间 | |
| `delivered_at` | TIMESTAMP | 收货时间 | |
| `completed_at` | TIMESTAMP | 完成时间 | |
| `remark` | TEXT | 订单备注 | |
| `merchant_memo` | TEXT | 商家备注 | |
| `cancel_reason` | TEXT | 取消原因 | |
| `created_at` | TIMESTAMP | 创建时间 | |
| `updated_at` | TIMESTAMP | 更新时间 | |
| `customer_name` | VARCHAR | 客户姓名 | |
| `customer_phone` | TEXT | 客户电话 | |
| `merchant_name` | VARCHAR | 商家名称 | |
| `shop_name` | VARCHAR | 店铺名称 | |
| `order_status_name` | TEXT | 订单状态名称 | |
| `payment_status_name` | TEXT | 支付状态名称 | |

### 3.5 支付订单表 (`pay_order`)
支付网关订单表。

| 字段名 | 类型 | 描述 | 备注 |
| :--- | :--- | :--- | :--- |
| `id` | BIGINT | 主键 | |
| `merchant_id` | BIGINT | 商户ID | |
| `app_id` | BIGINT | 应用ID | |
| `channel_id` | BIGINT | 渠道ID | 可空 |
| `channel_code` | VARCHAR | 渠道编码 | 可空 |
| `merchant_order_id` | VARCHAR | 商户订单号 | |
| `subject` | VARCHAR | 订单标题 | |
| `body` | VARCHAR | 订单描述 | |
| `notify_url` | VARCHAR | 通知地址 | |
| `notify_status` | SMALLINT | 通知状态 | |
| `amount` | BIGINT | 金额 | |
| `channel_fee_rate` | DOUBLE | 渠道费率 | 可空 |
| `channel_fee_amount` | BIGINT | 渠道手续费 | 可空 |
| `status` | SMALLINT | 状态 | |
| `user_ip` | VARCHAR | 用户IP | |
| `expire_time` | TIMESTAMP | 过期时间 | |
| `success_time` | TIMESTAMP | 成功时间 | 可空 |
| `notify_time` | TIMESTAMP | 通知时间 | 可空 |
| `success_extension_id` | BIGINT | 成功扩展ID | 可空 |
| `refund_status` | SMALLINT | 退款状态 | |
| `refund_times` | SMALLINT | 退款次数 | |
| `refund_amount` | BIGINT | 退款金额 | |
| `channel_user_id` | VARCHAR | 渠道用户ID | 可空 |
| `channel_order_no` | VARCHAR | 渠道订单号 | 可空 |
| `creator` | VARCHAR | 创建人 | 可空 |
| `create_time` | TIMESTAMP | 创建时间 | |
| `updater` | VARCHAR | 更新人 | 可空 |
| `update_time` | TIMESTAMP | 更新时间 | |
| `deleted` | SMALLINT | 删除标记 | 默认0 |
| `tenant_id` | BIGINT | 租户ID | 默认0 |

### 3.6 支付订单扩展表 (`pay_order_extension`)
支付订单扩展信息表。

| 字段名 | 类型 | 描述 | 备注 |
| :--- | :--- | :--- | :--- |
| `id` | BIGINT | 主键 | |
| `no` | VARCHAR | 支付流水号 | |
| `order_id` | BIGINT | 支付订单ID | |
| `channel_id` | BIGINT | 渠道ID | |
| `channel_code` | VARCHAR | 渠道编码 | |
| `user_ip` | VARCHAR | 用户IP | |
| `status` | SMALLINT | 状态 | |
| `channel_extras` | VARCHAR | 渠道额外信息 | 可空 |
| `channel_notify_data` | VARCHAR | 渠道通知数据 | 可空 |
| `creator` | VARCHAR | 创建人 | 可空 |
| `create_time` | TIMESTAMP | 创建时间 | |
| `updater` | VARCHAR | 更新人 | 可空 |
| `update_time` | TIMESTAMP | 更新时间 | |
| `deleted` | SMALLINT | 删除标记 | 默认0 |
| `tenant_id` | BIGINT | 租户ID | 默认0 |

### 3.7 库存订单表 (`stock_orders`)
库存相关订单表。

| 字段名 | 类型 | 描述 | 备注 |
| :--- | :--- | :--- | :--- |
| `id` | UUID | 主键 | |
| `simulation_id` | UUID | 模拟ID | 可空 |
| `symbol` | TEXT | 交易标的 | |
| `side` | TEXT | 交易方向 | |
| `qty` | NUMERIC | 数量 | |
| `price` | NUMERIC | 价格 | 可空 |
| `status` | TEXT | 状态 | 默认created |
| `placed_at` | TIMESTAMP | 下单时间 | |
| `executed_at` | TIMESTAMP | 执行时间 | 可空 |
| `fee` | NUMERIC | 手续费 | 默认0 |

---

## 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` 等于自己账号的数据。