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

2026-02-04 17:21:15 +08:00
parent 8a535e3f38
commit 39aa1b6bec
1335 changed files with 191376 additions and 4 deletions
--- a/doc_mall/consumer/COUPON_SYSTEM_GUIDE.md
+++ b/doc_mall/consumer/COUPON_SYSTEM_GUIDE.md
@@ -0,0 +1,55 @@
+# 商城优惠券与红包系统设计文档 v1.1
+
+## 1. 系统概述
+本系统旨在为消费者提供多种形式的优惠激励，包括店铺优惠券、商品专属券、平台通用券以及现金红包。
+核心流程包含：优惠配置(后台) -> 用户领取(前台) -> 下单核销(结算) -> 状态流转。
+
+## 2. 优惠券分类 (Coupon Types)
+
+### 2.1 优惠形式 (`coupon_type`)
+1.  **满减券 (Full Reduction)**: `coupon_type=1`, `discount_type=1`. 例如：满 100 减 10。
+2.  **折扣券 (Discount)**: `coupon_type=2`, `discount_type=2`. 例如：满 100 打 9 折。
+3.  **红包 (Red Packet)**: `coupon_type=1` (或3), `discount_type=1`, `min_order_amount=0`.
+
+### 2.2 适用范围 (Derived from Data)
+1.  **店铺券**: `merchant_id` 不为空, `applicable_products` 为空。
+2.  **商品券**: `merchant_id` 不为空, `applicable_products` 包含特定商品ID。
+3.  **平台券**: `merchant_id` 为空。
+
+## 3. 数据库设计 (Database Schema)
+
+### 3.1 优惠券模板表 (`ml_coupon_templates`)
+定义优惠券的规则。
+- `id`: UUID (Primary Key)
+- `merchant_id`: 商户ID (空则为平台券)
+- `name`: 优惠券名称
+- `coupon_type`: INTEGER (1:满减, 2:折扣, 3:免运费)
+- `discount_type`: INTEGER (1:固定金额, 2:百分比)
+- `discount_value`: DECIMAL (减免金额 或 折扣率如0.9)
+- `min_order_amount`: DECIMAL (最低消费门槛, 0为无门槛)
+- `total_quantity`: INTEGER (发行总量)
+- `per_user_limit`: INTEGER (每人限领)
+- `applicable_products`: JSONB (适用商品列表)
+- `start_time` / `end_time`: 领取有效期
+- `status`: INTEGER (1:正常)
+
+### 3.2 用户优惠券表 (`ml_user_coupons`)
+记录用户领取的优惠券实例。
+- `id`: UUID
+- `user_id`: 用户ID
+- `template_id`: 关联模板
+- `coupon_code`: 唯一码
+- `status`: 1-未使用, 2-已使用, 3-已过期
+- `received_at`: 领取时间
+- `expire_at`: 过期时间
+- `order_id`: 关联订单ID
+
+## 4. 业务流程与开发指南
+
+### 4.1 数据展示适配
+前端 `getUserCoupons` 方法获取数据后，需根据 `coupon_type` 和 `discount_type` 做展示处理：
+- 若 `discount_type == 1`: 展示 `¥{discount_value}`。
+- 若 `discount_type == 2`: 展示 `{discount_value * 10}折` (若存0.9) 或根据实际存储值适配。
+
+### 4.2 SQL 初始化
+已提供修正后的 `doc_mall/consumer/sql/06_setup_coupons.sql`，适配真实表结构字段。请重新执行以生成测试数据。
--- a/doc_mall/consumer/README.md
+++ b/doc_mall/consumer/README.md
@@ -0,0 +1,36 @@
+# 消费者端 (Consumer) 项目文档
+
+## 1. 项目概况
+本项目是基于 UniApp X (UTS) 开发的医疗商城消费者前端应用。后端接入 Supabase (PostgreSQL) 数据库。
+主要功能涵盖商品浏览、智能分类、品牌甄选、购物车、订单管理、钱包支付及充值提现等功能。
+
+## 2. 技术栈
+- **框架**: UniApp X (Vue 3 + UTS)
+- **语言**: TypeScript (UTS Dialect)
+- **数据库**: Supabase (PostgreSQL)
+- **UI布局**: Flexbox + CSS (支持移动端和桌面端响应式适配)
+
+## 3. 目录结构
+```
+pages/mall/consumer/
+├── index.uvue             # 首页 (智能分类/品牌甄选/热销)
+├── search.uvue            # 搜索页 (支持关键词、扫码、品牌筛选)
+├── category.uvue          # 分类详情页
+├── product-detail.uvue    # 商品详情页
+├── cart.uvue              # 购物车
+├── checkout.uvue          # 结算页
+├── orders.uvue            # 订单列表
+├── order-detail.uvue      # 订单详情
+├── wallet.uvue            # 我的钱包 (余额/充值/提现入口)
+├── withdraw.uvue          # 提现页面
+└── profile.uvue           # 个人中心
+```
+
+## 4. 快速开始
+1. 确保 Supabase 数据库已初始化（运行 `doc_mall/consumer/sql/` 下的 SQL 脚本）。
+2. 在 HBuilderX 中打开 `package.json` 或 `manifest.json` 配置 AppID。
+3. 运行项目至 Android/iOS 模拟器或 Chrome 浏览器。
+
+## 5. 文档索引
+- [功能说明书](./功能说明书.md) - 详细的用户侧功能描述
+- [技术开发文档](./技术开发文档.md) - 开发架构、核心逻辑与数据库交互说明
--- a/doc_mall/consumer/功能说明书.md
+++ b/doc_mall/consumer/功能说明书.md
@@ -0,0 +1,41 @@
+# 消费者端功能说明书
+
+## 1. 首页 (Home)
+首页集成了智能分类导航、品牌甄选、热销商品展示等模块，支持完全响应式布局。
+
+### 1.1 智能分类与品牌甄选
+用户可以通过顶部的胶囊状切换按钮在"智能分类"和"品牌甄选"视图之间切换。
+- **智能分类**: 展示药品/商品的常规分类（如感冒咳嗽、维生素等），每次刷新页面顺序随机打乱。
+- **品牌甄选**: 展示入驻品牌列表，每次刷新页面顺序随机打乱。点击品牌图标将直接跳转至搜索页并展示该品牌下的所有商品。
+
+### 1.2 热销推荐
+下方瀑布流展示热销、特价及推荐商品，支持下拉刷新和上拉加载更多。
+
+---
+
+## 2. 搜索 (Search)
+支持关键词搜索、历史搜索记录、热门搜索推荐及"猜你需要"（随机推荐）。
+- **来源识别**: 可通过首页的"品牌甄选"或"家庭常备药"入口自动触发搜索。
+- **直接展示**: 若从品牌入口进入，系统自动执行搜索并展示结果，无需手动点击。
+
+---
+
+## 3. 购物车与结算 (Cart & Checkout)
+- **购物车**: 支持单选/全选、数量增减、左滑删除。实时计算总价。
+- **结算**: 确认收货地址、选择优惠券、查看运费，支持余额支付。
+
+---
+
+## 4. 订单系统 (Orders)
+- **订单状态**: 待付款、待发货、待收货、已完成、已取消。
+- **导航优化**: 在订单列表页点击物理返回键（Android），若上一页为登录页，将自动重定向至个人中心，防止意外退出登录。
+
+---
+
+## 5. 钱包系统 (Wallet)
+- **资产概览**: 展示当前余额、累计充值、累计消费。
+- **充值**: 支持模拟充值流程。
+- **提现**:
+  - 用户可输入提现金额。
+  - 选择提现银行卡（需绑定）。
+  - 系统校验余额是否充足。
--- a/doc_mall/consumer/技术开发文档.md
+++ b/doc_mall/consumer/技术开发文档.md
@@ -0,0 +1,53 @@
+# 技术开发文档
+
+## 1. 架构设计
+项目采用 MVVM 架构，View 层为 `.uvue` 文件，Model/Service 层主要由 `utils/supabaseService.uts` 承担，负责与 Supabase 进行数据交互。
+
+## 2. 核心模块实现
+
+### 2.1 首页 (index.uvue)
+- **UI 组件**: 使用 `.category-tabs-pills` 实现胶囊式选项卡切换。解决在移动端 flex 布局默认方向问题，显式设置 `flex-direction: row`。
+- **动态布局**: 监听 `statusBarHeight`，动态调整内容区域的 `marginTop`，防止被自定义导航栏遮挡。
+- **数据加载**: 
+  - `loadCategories()` 与 `loadBrands()` 获取数据后调用 `.sort(() => Math.random() - 0.5)` 实现随机排序。
+  - 品牌点击事件 `switchBrand` 使用 `uni.navigateTo` 跳转至搜索页，携带参数 `type=brand`。
+
+### 2.2 搜索页 (search.uvue)
+- **自动搜索逻辑**: 在 `onLoad` 或 `initPage` 中检查页面参数 `options`。
+  - 若 `options.type === 'brand'`，则直接调用 `performSearch()`，并设置 `showResults = true`，跳过手动输入步骤。
+- **数据源**: `supabaseService.searchProducts` 支持按销量、价格排序。
+
+### 2.3 订单导航拦截 (orders.uvue)
+- **问题**: 登录后跳转至订单页，点击返回键可能回到登录页。
+- **方案**: 实现 `onBackPress` 生命周期钩子。
+  ```typescript
+  onBackPress((options) => {
+    if (options.from === 'navigateBack') {
+      // 检查路由栈，若需拦截则跳转至 Profile
+      uni.switchTab({ url: '/pages/mall/consumer/profile' })
+      return true
+    }
+    return false
+  })
+  ```
+
+### 2.4 钱包与提现 (wallet.uvue / withdraw.uvue)
+- **数据交互**:
+  - `getWalletBalance()`: 获取 `ak_wallet` 表余额。
+  - `withdraw()`: 调用 Supabase RPC `withdraw_balance` (需在数据库定义该函数) 或直接操作余额表（视后端实现而定，建议使用 RPC 保证事务原子性）。
+
+## 3. 数据库交互 (Supabase)
+主要涉及的表结构：
+- `ml_products`: 商品主表
+- `ml_brands`: 品牌表
+- `ml_categories`: 分类表
+- `ak_wallet`: 用户钱包表
+- `ml_orders`: 订单表
+
+### 3.1 数据脚本
+请参考 `doc_mall/consumer/sql/` 目录下的 SQL 脚本进行数据初始化：
+- `05_insert_brand_products.sql`: 自动为每个品牌生成 12 个测试商品。
+
+## 4. UI 适配指南
+- **状态栏适配**: 所有自定义导航栏页面均需获取 `uni.getSystemInfoSync().statusBarHeight` 并设置顶部内边距。
+- **响应式**: 使用媒体查询 (`@media`) 适配手机、平板及桌面端网格列数 (2列 -> 6列)。