# 小程序/用户端 API 设计（Mini API）

- 项目：TakeoutSaaS.MiniApi
- 版本前缀：/api/mini/v1
- 认证：JWT（小程序登录态）/ 第三方登录（微信/支付宝）
- 租户识别：X-Tenant-Id 头或域名/小程序场景参数

## 1. 通用规范
- Content-Type: application/json
- 成功响应
{
  "success": true,
  "code": 200,
  "message": "OK",
  "data": {}
}

## 2. 认证登录
- 微信登录
  - POST /api/mini/v1/auth/wechat/login
    - { code, encryptedData?, iv? }
- 刷新Token
  - POST /api/mini/v1/auth/refresh
- 获取用户信息
  - GET  /api/mini/v1/me

## 3. 商家与门店
- 获取推荐商家
  - GET /api/mini/v1/merchants/recommend?lat=&lng=&pageIndex=&pageSize=
- 商家详情（含门店与公告）
  - GET /api/mini/v1/merchants/{id}
- 门店列表（按距离）
  - GET /api/mini/v1/merchants/{id}/stores?lat=&lng=

## 4. 菜品与分类
- 分类列表
  - GET /api/mini/v1/categories?merchantId=
- 菜品列表
  - GET /api/mini/v1/dishes?merchantId=&categoryId=&keyword=&sort=
- 菜品详情
  - GET /api/mini/v1/dishes/{id}

## 5. 购物车
- 获取购物车
  - GET  /api/mini/v1/cart?merchantId=
- 同步购物车（幂等）
  - PUT  /api/mini/v1/cart
    - { merchantId, items:[{dishId,specId?,quantity}] }
- 清空购物车
  - DELETE /api/mini/v1/cart?merchantId=

## 6. 地址簿
- 地址列表
  - GET /api/mini/v1/addresses
- 新增地址
  - POST /api/mini/v1/addresses
- 更新地址
  - PUT /api/mini/v1/addresses/{id}
- 删除地址
  - DELETE /api/mini/v1/addresses/{id}
- 设为默认地址
  - POST /api/mini/v1/addresses/{id}/default

## 7. 订单
- 创建订单（下单）
  - POST /api/mini/v1/orders
    - { merchantId, storeId, items:[{dishId,specId?,quantity}], addressId, remark?, couponId? }
- 订单列表
  - GET  /api/mini/v1/orders?status=&pageIndex=&pageSize=
- 订单详情
  - GET  /api/mini/v1/orders/{id}
- 取消订单
  - POST /api/mini/v1/orders/{id}/cancel { reason }
- 再来一单
  - POST /api/mini/v1/orders/{id}/reorder

## 8. 支付
- 预下单（获取支付参数）
  - POST /api/mini/v1/payments
    - { orderId, method: wechat|alipay }
- 查询支付状态
  - GET /api/mini/v1/payments/{paymentNo}
- 第三方回调（回调专用）
  - POST /api/mini/v1/payments/callback/wechat
  - POST /api/mini/v1/payments/callback/alipay

## 9. 优惠券
- 可领取优惠券列表
  - GET /api/mini/v1/coupons/available?merchantId=
- 领取优惠券
  - POST /api/mini/v1/coupons/{id}/receive
- 我的优惠券
  - GET /api/mini/v1/user-coupons?status=

## 10. 评价
- 发表评价
  - POST /api/mini/v1/reviews { orderId, rating, content?, images?[] }
- 商家评价列表
  - GET /api/mini/v1/reviews?merchantId=&rating=&page=

## 11. 文件上传
- 上传评价图片/头像
  - POST /api/mini/v1/files/upload (multipart/form-data)

## 12. WebSocket（可选）
- ws://{host}/ws/mini?token=xxx
- 主题：order.status, payment.success