consumer模块完成90%，前端完成supabase对接

2026-02-03 17:11:50 +08:00
parent b6200cda28
commit 8a535e3f38
69 changed files with 5020 additions and 33273 deletions
--- a/pages/mall/consumer/doc/FEATURES_&_PAGES.md
+++ b/pages/mall/consumer/doc/FEATURES_&_PAGES.md
@@ -0,0 +1,62 @@
+# 功能与页面状态详解
+
+本文档详细记录了 Consumer App 各个功能模块的实现状态与业务逻辑。
+
+> **状态图例**: ✅ 正常 (已对接真实 DB) | 🚧 开发中 | ❌ 未开始
+
+## 🛍️ 核心购物流程
+
+| 功能模块 | 页面路径 | 状态 | 备注 |
+| :--- | :--- | :--- | :--- |
+| **首页** | `pages/mall/consumer/index.uvue` | ✅ 正常 | 金刚区、Banner、推荐商品流。 |
+| **分类** | `pages/mall/consumer/category.uvue` | ✅ 正常 | 一级/二级分类联动，跳转搜索结果。 |
+| **商品详情** | `pages/mall/consumer/product-detail.uvue` | ✅ 正常 | SKU 选择、加入购物车、立即购买。 |
+| **购物车** | `pages/mall/consumer/cart.uvue` | ✅ 正常 | 数量增减、勾选计算、结算校验。 |
+| **结算页** | `pages/mall/consumer/checkout.uvue` | ✅ 正常 | 选择地址、运费计算、创建订单。 |
+| **收银台** | `pages/mall/consumer/payment.uvue` | ✅ 正常 | 模拟支付流程，更新订单为“待发货”。 |
+
+## 👤 个人中心 (Profile)
+
+**文件**: `pages/mall/consumer/profile.uvue`
+
+*   **资产看板**: 实时加载积分、余额、优惠券数量。
+*   **订单看板**: 待支付、待发货、待收货、退款/售后（跳转至 `refund.uvue`）。
+*   **服务矩阵**:
+    *   **地址管理**: `address-list.uvue` (CRUD 正常)
+    *   **我的收藏**: `favorites.uvue` (商品/店铺收藏 正常)
+    *   **浏览足迹**: `footprint.uvue` (按日期分组 正常)
+    *   **在线客服**: 跳转至 `chat.uvue`
+    *   **消息通知**: 跳转至 `messages.uvue`
+
+## 📦 订单管理体系
+
+**列表页**: `pages/mall/consumer/orders.uvue`
+*   **状态筛选**: 全部 / 待支付 / 待发货 / 待收货 / 已完成。
+*   **核心操作**:
+    *   **去支付**: 跳转收银台。
+    *   **确认收货**: 变更状态为已完成。
+    *   **申请售后**: 跳转 `apply-refund.uvue` (带入订单信息)。
+
+**详情页**: `pages/mall/consumer/order-detail.uvue`
+*   **信息展示**: 完整的地址、商品规格、金额明细、时间线。
+*   **业务状态**: 根据 `order_status` 动态展示可操作按钮。
+
+## 🔄 售后服务体系 (Refunds)
+
+**申请页**: `pages/mall/consumer/apply-refund.uvue`
+*   **功能**: 支持仅退款/退货退款。
+*   **逻辑**: 自动获取订单最大可退金额，防止超额申请。
+*   **提交**: 数据写入 `ml_refunds` 表。
+
+**记录页**: `pages/mall/consumer/refund.uvue`
+*   **列表**: 展示所有历史售后申请及其当前状态。
+*   **进度**: 可视化展示审核进度 (目前模拟进度条)。
+
+## 💬 社交与互动
+
+| 功能模块 | 页面路径 | 状态 | 说明 |
+| :--- | :--- | :--- | :--- |
+| **在线客服** | `pages/mall/consumer/chat.uvue` | ✅ 正常 | 支持文本/表情发送，历史记录持久化。 |
+| **消息中心** | `pages/mall/consumer/messages.uvue` | ✅ 正常 | 聚合系统通知订单消息与客服消息。 |
+| **商品评价** | `pages/mall/consumer/review.uvue` | ✅ 正常 | 支持星级评分与文本评价。 |
+
--- a/pages/mall/consumer/doc/MOCK_DATA_GUIDE.md
+++ b/pages/mall/consumer/doc/MOCK_DATA_GUIDE.md
@@ -0,0 +1,44 @@
+# 测试数据生成指南 (Mock Data Guide)
+
+为了有效测试消费者端前端功能，我们编写了 SQL 脚本来向数据库填充真实的模拟数据。
+
+## 📂 脚本位置
+
+所有脚本均位于 `doc_mall/consumer/sql/` 目录下。
+
+## 🛠 使用说明
+
+### 1. 修复现有数据问题 (优先级最高)
+**脚本**: `fix_order_items_data.sql`
+
+*   **适用场景**: 如果您的订单列表中，商品显示为空白图片或缺失名称。
+*   **功能**:
+    *   从 `ml_product_skus` 或 `ml_products` 表自动回填缺失的 `image_url`。
+    *   修正占位符形式的 `product_name`。
+    *   补充缺失的 `specifications` (如：规格参数)。
+
+### 2. 生成新的测试订单
+**脚本**: `add_mock_orders_corrected.sql`
+
+*   **适用场景**: 为测试用户 (`test@mall.com`) 创建一批全新的订单数据。
+*   **生成数据包含**:
+    *   1x **待支付** 订单
+    *   1x **待发货** 订单 (已支付)
+    *   1x **待收货** 订单 (已发货)
+    *   1x **已完成** 订单
+*   **注意**: 该脚本会随机选取数据库中现有的真实商品，确保数据关联正确无误。
+
+### 3. 生成评价测试数据
+**脚本**: `add_mock_reviews_for_test_user.sql`
+
+*   **适用场景**: 测试“我的评价”列表或商品详情页的评价展示。
+*   **功能**: 创建已完成的订单，并自动为其添加一条带图片的 5 星好评。
+
+## 🧪 建议测试流程
+
+1.  **运行** `add_mock_orders_corrected.sql`。
+2.  **打开 App** > 个人中心 (Profile) > 我的订单。
+3.  **验证**:
+    *   各状态标签页下是否有对应的订单。
+    *   商品图片和名称是否显示正常。
+    *   在“待收货”或“已完成”订单上点击**申请售后**，验证是否跳转正确。
--- a/pages/mall/consumer/doc/README.md
+++ b/pages/mall/consumer/doc/README.md
@@ -0,0 +1,62 @@
+# 商城消费者端 (Consumer) 开发文档
+
+本文档包含了商城消费者前端模块的详细开发指南和状态说明。
+
+## 📂 项目结构
+
+消费者端模块位于 `pages/mall/consumer/` 目录下，基于 UniApp x (UTS/UVUE) 开发。
+
+### 核心页面清单
+
+| 页面文件 | 描述 | 当前状态 |
+|-----------|-------------|--------|
+| `index.uvue` | 首页 (商城门面) | ✅ 正常 |
+| `category.uvue` | 商品分类浏览 | ✅ 正常 |
+| `cart.uvue` | 购物车 | ✅ 正常 |
+| `profile.uvue` | 个人中心 (用户主页) | ✅ 正常 |
+| `orders.uvue` | 订单列表管理 | ✅ 正常 |
+| `order-detail.uvue` | 订单详情页 | ✅ 正常 |
+| `apply-refund.uvue` | 申请售后 (退款/退货) | ✅ 正常 |
+| `refund.uvue` | 售后记录列表 | ✅ 正常 |
+| `chat.uvue` | 在线客服 | ✅ 正常 |
+| `messages.uvue` | 消息通知中心 | ✅ 正常 |
+
+### 关键功能实现
+
+1.  **用户个人中心**:
+    *   可视化展示用户状态（积分、余额）。
+    *   订单状态快捷入口（待支付、待发货、待收货等）。
+    *   **我的服务**: 优惠券、地址、收藏夹。
+    *   **新功能**: 已集成“评价”入口（跳转至待评价订单）和“退款/售后”入口（跳转至售后记录页）。
+
+2.  **订单管理**:
+    *   多状态标签页切换（全部、待支付、待收货、已完成）。
+    *   **操作**: 支付、取消、提醒发货、确认收货、评价、**申请售后**。
+    *   与 `supabaseService` 后端服务实时交互。
+
+3.  **售后系统**:
+    *   独立页面 `apply-refund.uvue`：支持仅退款/退货退款，关联原订单金额。
+    *   售后列表 `refund.uvue`：查看历史退款记录及进度。
+
+4.  **客服与消息**:
+    *   在线客服 `chat.uvue`：支持文本/表情发送，消息持久化存储。
+    *   消息中心 `messages.uvue`：聚合系统通知与客服消息。
+
+## 🛠 技术栈
+
+*   **框架**: UniApp x (Vue 3 + UTS)
+*   **后端**: Supabase (PostgreSQL)
+*   **语言**: UTS (TypeScript 方言)
+*   **样式**: SCSS / UVUE Styles
+
+## 🚀 快速开始
+
+1.  **环境准备**: 确保已安装 HBuilderX 并配置好 UniApp x 插件。
+2.  **数据库**: 运行 `doc_mall/consumer/sql/` 下的 SQL 脚本初始测试数据。
+3.  **运行**: 在 HBuilderX 中打开项目，运行到 Web 浏览器或 App 模拟器。
+
+## 📚 文档索引
+
+*   [功能与页面状态详解](./FEATURES_&_PAGES.md)
+*   [Supabase 集成与数据库架构](./SUPABASE_INTEGRATION.md)
+*   [测试数据生成指南](./MOCK_DATA_GUIDE.md)
--- a/pages/mall/consumer/doc/SUPABASE_INTEGRATION.md
+++ b/pages/mall/consumer/doc/SUPABASE_INTEGRATION.md
@@ -0,0 +1,121 @@
+# 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 实时推送。