medical-mall/doc_mall/consumer/backup_doc_full/SUPABASE_INTEGRATION.md

Supabase 集成与数据库架构 (Consumer App)

本文档详细描述了消费者端 (Consumer App) 涉及的所有数据库集成点、核心表结构以及 supabaseService.uts 提供的 API 服务。

更新时间: 2026-02-03 状态: 已完成核心业务闭环 (订单、支付、售后、客服、足迹等)

🗄️ 核心数据架构

消费者端业务依赖以下核心数据库表：

1. 交易与订单 (Orders & Transactions)

表名	描述	关键字段
ml_orders	订单主表	id, user_id, merchant_id, order_status (1:待付, 2:待发, 3:待收, 4:完成, 5:取消), total_amount
ml_order_items	订单商品明细	order_id, product_id, image_url (快照), specifications (快照)
ml_refunds	[新增] 售后/退款申请	order_id, reason_category, refund_amount, status (0:待审, 1:同意, 2:拒绝), refund_type (1:仅退款, 2:退货退款)

2. 互动与消息 (Interaction & Communication)

表名	描述	关键字段
ml_chat_messages	[新增] 客服聊天记录	session_id, sender_id, receiver_id, content, msg_type, is_from_user
ml_notifications	消息通知	type (system/order/promotion), title, is_read
ml_product_reviews	商品评价	order_id, product_id, rating, content, images

3. 用户行为 (User Behavior)

表名	描述	关键字段
ml_browsing_history	足迹/浏览记录	user_id, product_id, view_time
ml_favorites	收藏夹	user_id, target_id, type (1:商品, 2:店铺)
ml_user_addresses	收货地址	user_id, receiver_name, phone, province...

---

🔌 API 服务层 (utils/supabaseService.uts)

所有后端交互通过单例 supabaseService 进行，主要模块如下：

1. 售后/退款服务 (Refunds)

状态: ✅ 已集成 (apply-refund.uvue)

// 创建退款/售后申请
async createRefund(data: {
    order_id: string,
    refund_type: number,
    refund_amount: number,
    reason_category: string,
    description: string,
    images: string[]
}): Promise<boolean>

2. 在线客服/消息服务 (Chat & Messages)

状态: ✅ 已集成 (chat.uvue, messages.uvue)

// 获取当前用户的聊天记录
async getUserChatMessages(): Promise<ChatMessage[]>

// 发送聊天消息 (持久化到 ml_chat_messages)
async sendChatMessage(content: string, type: string = 'text'): Promise<boolean>

// (测试用) 模拟客服自动回复
async simulateServiceReply(content: string): Promise<boolean>

3. 订单与支付 (Orders & Payment)

状态: ✅ 已集成 (checkout.uvue, payment.uvue, orders.uvue)

// 创建订单 (由购物车或直接购买触发)
async createOrder(orderData: any): Promise<string | null>

// 获取订单详情 (包含商品明细)
async getOrderDetail(orderId: string): Promise<any | null>

// 支付订单 (模拟支付，更新订单状态 1->2，记录支付时间)
async payOrder(orderId: string, paymentMethod: string, amount: number): Promise<boolean>

// 确认收货 (3->4)
async confirmReceipt(orderId: string): Promise<Result>

4. 商品与搜索 (Products)

状态: ✅ 已集成 (search.uvue, product-detail.uvue)

// 搜索商品 (支持关键词、分类、价格排序、销量排序)
async searchProducts(keyword: string, page: number, pageSize: number, sort: string, asc: boolean): Promise<PaginatedResponse<Product>>

// 获取足迹
async getFootprints(): Promise<any[]>

---

📊 页面集成状态一览表

页面模块	文件路径	数据源状态	说明
首页	pages/mall/consumer/index.uvue	✅ Real DB	金刚区、推荐商品已接入
搜索	pages/mall/consumer/search.uvue	✅ Real DB	关键词搜索、排序、分页正常
购物车	pages/mall/consumer/cart.uvue	✅ Real DB	加减购、结算校验正常
结算台	pages/mall/consumer/checkout.uvue	✅ Real DB	地址选择、订单创建正常
收银台	pages/mall/consumer/payment.uvue	✅ Real DB	读取待付金额，更新支付状态
订单列表	pages/mall/consumer/orders.uvue	✅ Real DB	状态筛选 (全部/待付/待收/退款) 正常
订单详情	pages/mall/consumer/order-detail.uvue	✅ Real DB	地址、商品、金额展示正常
申请售后	pages/mall/consumer/apply-refund.uvue	✅ Real DB	[本次完成] 关联订单金额，提交至 ml_refunds
在线客服	pages/mall/consumer/chat.uvue	✅ Real DB	[本次完成] 消息收发持久化，支持历史记录
消息中心	pages/mall/consumer/messages.uvue	✅ Real DB	能够统计未读客服消息数
我的评价	pages/mall/consumer/review.uvue	✅ Real DB	提交评价至 ml_product_reviews

🛠️ 下一步维护建议

1. 异常处理: 目前部分接口在网络异常时仅打印 console.error，建议增加全局统一的 Toasts 提示。
2. 图片上传: 目前退款和评价中的图片上传依赖 Mock 或简单路径，需对接真实的 OSS/Supabase Storage 文件上传。
3. 实时消息: 目前 chat.uvue 使用 polling (轮询) 或手动刷新，Supabase 支持 Realtime Subscription，后续可升级为 WebSocket 实时推送。