客户（Client）小程序功能文档

一、概述

客户是餐饮商家/餐厅的采购人员，使用小程序进行商品采购、订单管理、结算等操作。

主题色：清新绿 #07c160
渐变色：linear-gradient(135deg, #07c160 0%, #1989fa 100%)

二、功能模块

1. 账户与认证

功能	接口路径	说明
账号密码登录	POST `/api/mini/auth/login`	输入用户名密码登录
微信一键登录	POST `/api/mini/auth/sms-login`	通过微信授权获取手机号登录
登出	POST `/api/mini/auth/logout`	退出当前登录状态
修改密码	POST `/api/mini/user/change-password`	自主修改登录密码
获取当前用户信息	GET `/api/mini/auth/current-user`	获取登录用户基本信息
获取个人资料	GET `/api/mini/client/profile`	获取客户详细信息
更新个人资料	PUT `/api/mini/client/profile`	修改姓名、手机号等基本信息

2. 地址管理

功能	接口路径	方法	说明
获取地址列表	`/api/mini/client/addresses`	GET	获取客户的全部收货地址
获取地址详情	`/api/mini/client/addresses/{addressId}`	GET	查看单个地址的详细信息
创建地址	`/api/mini/client/addresses`	POST	新增收货地址
更新地址	`/api/mini/client/addresses/{addressId}`	PUT	编辑已有地址
删除地址	`/api/mini/client/addresses/{addressId}`	DELETE	删除地址
设置默认地址	`/api/mini/client/addresses/{addressId}/set-default`	POST	将某地址设为默认收货地址

3. 商品采购（外卖风格展示）

参考美团外卖、饿了么等平台风格，展示商品分类和商品列表，支持浏览、搜索、加购。

3.1 商品分类与列表

功能	接口路径	方法	说明
获取商品分类	`/api/mini/client/product-categories`	GET	获取商品分类及分类下的商品（外卖风格左侧分类栏）
获取商品列表	`/api/mini/client/products`	GET	按分类/关键词分页查询商品（支持搜索）

3.2 价格表

功能	接口路径	方法	说明
获取当前价格表	`/api/mini/client/price-list`	GET	获取当前生效的价目表（含商品价格）
获取价格表商品	`/api/mini/client/price-list/products`	GET	分页获取价格表中的商品列表

3.3 外卖风格页面布局

参考美团外卖、饿了么等主流外卖平台，页面采用以下布局：

┌─────────────────────────────────────┐
│ 🔍 搜索商品...                    │  ← 顶部搜索栏
├─────────────────────────────────────┤
│ ┌──────┬─────────────────────────┐ │
│ │ 蔬菜  │  ┌─────┐ ┌─────┐ ┌────┐│ │
│ ├──────┤  │白菜  │ │萝卜  │ │土豆  ││ │  ← 右侧商品网格
│ │ 水果  │  │2.5元│ │1.8元│ │2.0元││ │
│ ├──────┤  └─────┘ └─────┘ └────┘│ │
│ │ 肉类  │  ┌─────┐ ┌─────┐ ┌────┐│ │
│ ├──────┤  │猪肉  │ │牛肉  │ │羊肉  ││ │
│ │ 禽蛋  │  │15元 │ │38元 │ │42元 ││ │
│ ├──────┤  └─────┘ └─────┘ └────┘│ │
│ │ 海鲜  │                         │ │
│ ├──────┤                         │ │
│ │ 调料  │                         │ │
│ └──────┴─────────────────────────┘ │
├─────────────────────────────────────┤
│ 🛒 购物车                    ¥128 │  ← 底部购物车悬浮栏
│        [去结算(3件)]              │
└─────────────────────────────────────┘

3.4 商品卡片样式

每个商品卡片展示以下信息：

┌────────────────────┐
│                    │
│    [商品图片]       │  ← 商品图片（支持懒加载）
│                    │
├────────────────────┤
│ 新鲜大白菜           │  ← 商品名称
│ 斤                  │  ← 规格单位
├────────────────────┤
│ ¥2.50              │  ← 价格（醒目展示）
│           [+ 添加] │  ← 添加按钮
└────────────────────┘

3.5 商品详情弹窗

点击商品卡片弹出详情：

┌─────────────────────────────────────┐
│                           [×]       │
│  ┌─────────────────────────────┐    │
│  │                             │    │
│  │      [商品大图]              │    │
│  │                             │    │
│  └─────────────────────────────┘    │
│                                     │
│  新鲜大白菜                          │
│  规格：斤 / 公斤                      │
│                                     │
│  ¥2.50/斤    ¥5.00/公斤             │
│                                     │
│  商品描述：产地直供，新鲜采摘...       │
│                                     │
├─────────────────────────────────────┤
│  ┌───────────────────────────────┐  │
│  │ 购买数量： [-]  [1]  [+]      │  │
│  └───────────────────────────────┘  │
│                                     │
│  [        加入购物车        ]       │
└─────────────────────────────────────┘

3.6 搜索功能

顶部搜索栏支持：

关键词搜索商品
热门搜索推荐
搜索历史记录
搜索结果高亮显示

3.7 购物车交互

底部购物车悬浮栏：

┌─────────────────────────────────────┐
│ 🛒                          ¥128   │
│                                     │
│  ┌───────────────────────────────┐  │
│  │ 蔬菜                    共3件 │  │  ← 按分类展示
│  ├───────────────────────────────┤  │
│  │ 白菜        ¥2.50 × 2   [-][+]|  │
│  │ 萝卜        ¥1.80 × 1   [-][+]|  │
│  ├───────────────────────────────┤  │
│  │ 肉类                    共1件 │  │
│  ├───────────────────────────────┤  │
│  │ 猪肉        ¥15.00 × 1 [-][+]|  │
│  └───────────────────────────────┘  │
│                                     │
│  [    清空购物车    ] [去结算(4件)]  │
└─────────────────────────────────────┘

3.8 特色功能

功能	说明
猜你喜欢	根据采购历史推荐商品
限时特价	突出显示特价商品
批量采购	支持批量添加同类商品
价格波动提示	价格变动时显示提示

3.9 分类切换动画

左侧分类切换时：

平滑滚动动画
右侧商品列表联动切换
顶部固定分类名称（吸顶效果）

4. 购物车

功能	接口路径	方法	说明
获取购物车列表	`/api/mini/client/cart`	GET	查看购物车全部商品
添加商品到购物车	`/api/mini/client/cart`	POST	添加商品，指定数量
更新商品数量	`/api/mini/client/cart/{cartId}`	PUT	修改购物车中某商品的数量
删除单个商品	`/api/mini/client/cart/{cartId}`	DELETE	从购物车移除单个商品
清空购物车	`/api/mini/client/cart`	DELETE	一键清空全部商品
批量删除商品	`/api/mini/client/cart/batch`	DELETE	批量移除购物车商品
订单预览	`/api/mini/client/orders/preview`	POST	下单前预览订单信息（价格版本、商品明细、金额）
从购物车创建订单	`/api/mini/client/orders/from-cart`	POST	将购物车商品合并下单

5. 订单管理

功能	接口路径	方法	说明
直接创建订单	`/api/mini/client/orders`	POST	基于价格表直接下单
获取订单列表	`/api/mini/client/orders`	GET	分页查询订单（支持状态筛选）
获取订单详情	`/api/mini/client/orders/{orderId}`	GET	查看订单详细信息
发起取消申请	`/api/mini/client/orders/{orderId}/cancel`	POST	申请取消订单（需运营审核）
直接取消订单	`/api/mini/client/orders/{orderId}/direct-cancel`	POST	直接取消未支付订单
确认收货	`/api/mini/client/orders/{orderId}/confirm-receive`	POST	确认商品已送达
查看配送进度	`/api/mini/client/orders/{orderId}/delivery-progress`	GET	查看实时配送状态和配送员信息
催单	`/api/mini/client/orders/{orderId}/urge`	POST	催促配送

订单状态说明

状态值	显示文本	说明
pending_payment	待支付	等待客户支付
pending_review_cancel	待审核取消	取消申请待运营审核
pending_delivery	待分配配送	已支付，等待分配配送员
delivering	配送中	配送员正在配送
partial_delivered	部分送达	部分商品已送达
pending_confirm	待确认收货	等待客户确认收货
completed	已完结	订单已完成
cancelled	已取消	订单已取消

6. 支付

功能	接口路径	方法	说明
发起微信支付	`/api/mini/client/orders/{orderId}/wechat-pay`	POST	调起微信支付
查询支付状态	`/api/mini/client/orders/{orderId}/pay-status`	GET	查询订单支付结果
获取支付配置	`/api/payment/config`	GET	获取微信支付相关配置

说明：支持线上微信支付和线下转账等方式，具体由运营配置。

7. 发票管理

功能	接口路径	方法	说明
申请开票	`/api/mini/client/invoices`	POST	基于订单申请开具发票
获取可开票订单	`/api/mini/client/invoices/available-orders`	GET	查询可申请开票的订单
获取发票列表	`/api/mini/client/invoices`	GET	分页查询发票（支持状态筛选）
获取发票详情	`/api/mini/client/invoices/{invoiceId}`	GET	查看发票详细信息
获取发票汇总	`/api/mini/client/invoices/summary`	GET	查看已开票金额汇总
下载发票	`/api/mini/client/invoices/{invoiceId}/download`	GET	下载发票文件

发票状态说明

状态值	显示文本	说明
pending	待开票	申请已提交，等待开票
issued	已开票	发票已开具
cancelled	已作废	发票已作废

8. 结算与退款

功能	接口路径	方法	说明
获取结算列表	`/api/mini/client/settlements`	GET	分页查询结算记录
获取结算统计	`/api/mini/client/settlements/statistics`	GET	查看结算金额汇总
获取退款列表	`/api/mini/client/refunds`	GET	分页查询退款记录
获取退款统计	`/api/mini/client/refunds/statistics`	GET	查看退款金额汇总

9. 消息通知

功能	接口路径	方法	说明
获取消息列表	`/api/message/list`	GET	分页查询系统消息
获取未读消息数	`/api/message/unread-count`	GET	获取未读消息数量
发送消息	`/api/message/send`	POST	给其他用户发送消息
全部标记已读	`/api/message/mark-all-read`	POST	将所有消息标记为已读

10. 数据统计

功能	接口路径	方法	说明
仪表盘统计	`/api/mini/client/dashboard/statistics`	GET	获取客户订单、金额等统计数据

三、页面结构

pages/client/
├── home/                    # 首页/商品采购（外卖风格）
│   └── home.vue            # 商品分类+列表+购物车（一体化页面）
├── cart/                    # 购物车
│   └── cart.vue            # 购物车详情页（可从首页底部展开）
├── product/                 # 商品详情
│   └── detail.vue          # 商品详情弹窗/页面
├── order/                   # 订单模块
│   ├── order.vue           # 订单列表
│   ├── create/             # 创建订单
│   │   └── create.vue      # 订单确认页（选择地址、备注）
│   ├── detail/             # 订单详情
│   │   └── detail.vue     # 订单详情页
│   └── pay/                # 支付
│       └── pay.vue         # 支付页面
├── address/                 # 地址管理
│   └── address.vue         # 收货地址列表/管理
├── settlement/              # 结算
│   └── settlement.vue      # 结算记录页
├── refund/                  # 退款
│   └── refund.vue          # 退款记录页
├── invoice/                 # 发票
│   └── invoice.vue         # 发票申请/列表
└── profile/                 # 个人中心
    └── profile.vue         # 个人资料、设置

四、状态标签样式

// 待支付/待处理
.status-tag.warning { background: #fff7e6; color: #ff976a; }

// 配送中/进行中
.status-tag.primary { background: #e6f7ff; color: #1989fa; }

// 已完成/成功
.status-tag.success { background: #f6ffed; color: #07c160; }

// 已取消/异常
.status-tag.danger { background: #fff1f0; color: #ee0a24; }

// 已完结/禁用
.status-tag.info { background: #f5f5f5; color: #999; }

五、外卖风格界面设计规范

5.1 整体布局

元素	规范
页面宽度	最大 414px（适配主流手机）
内边距	左右 20rpx
卡片圆角	12rpx
阴影	0 2px 8px rgba(0, 0, 0, 0.08)

5.2 左侧分类栏

元素	规范
宽度	180rpx（固定）
背景色	#f5f5f5
选中背景	#ffffff
文字大小	26rpx
行高	100rpx
选中样式	左侧 4rpx 主题色边框

5.3 右侧商品区

元素	规范
商品卡片宽度	(750rpx - 180rpx - 40rpx) / 2 ≈ 265rpx
商品图片高度	200rpx
图片圆角	8rpx
商品名称	26rpx，最多2行，超出省略
价格	32rpx，主题色，加粗
单位	22rpx，灰色

5.4 商品卡片交互

状态	样式
默认	白色背景，轻微阴影
点击	轻微缩小 transform: scale(0.98)
无货	图片置灰，添加"暂时缺货"标签

5.5 底部购物车栏

元素	规范
高度	100rpx
背景色	#333333
购物车图标	60rpx × 60rpx，顶部 -30rpx 悬浮
数量角标	红色圆形，右侧 8rpx，上方 -8rpx
总价	白色，32rpx，加粗
结算按钮	主题色背景，宽度 200rpx，圆角 40rpx

5.6 添加按钮样式

类型	样式
加号按钮	圆形 44rpx，主题色边框，+ 图标
数量显示	宽度 40rpx，居中
减少按钮	同加号按钮，图标变为 -

六、交互规范

按钮样式

类型	样式	圆角
主要按钮	实心背景 `$client-primary`	24rpx
次要按钮	边框样式	24rpx
文字按钮	无背景无边框	-

表单验证

实时校验
错误提示：红色文字 + 底部提示
必填标识：红色星号

列表操作

查看：跳转详情
编辑：跳转编辑页或弹窗
删除：二次确认弹窗

七、技术说明

框架：uni-app + Vue3 + TypeScript
UI 组件：Vant Weapp
状态管理：Pinia
接口前缀： /api/mini/
金额单位：API 传分（整数），前端展示元（除以100，保留2位小数）
时间格式：前端展示 YYYY-MM-DD HH:mm:ss

小程序-客户功能文档.md 17 KB Permalink History Raw