TakeoutSaaS.TenantApi/Document/04B_小程序API.md

小程序/用户端 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