# 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)

```typescript
// 创建退款/售后申请
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)

```typescript
// 获取当前用户的聊天记录
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)

```typescript
// 创建订单 (由购物车或直接购买触发)
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)

```typescript
// 搜索商品 (支持关键词、分类、价格排序、销量排序)
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 实时推送。