122 lines
5.4 KiB
Markdown
122 lines
5.4 KiB
Markdown
# 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 实时推送。
|