medical-mall/pages/mall/admin/CONSUMER_DB_DOC(1).md

消费者端前端数据库文档 (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 等于自己账号的数据。