TakeoutSaaS.AdminApi/Document/04A_管理后台API.md

管理后台 API 设计（Admin API）

• 项目：TakeoutSaaS.AdminApi
• 版本前缀：/api/admin/v1
• 认证：JWT + RBAC（平台、租户、商家角色）
• 租户识别：X-Tenant-Id 头或 Token Claim

1. 通用规范

• Content-Type: application/json
• 成功响应 { "success": true, "code": 200, "message": "OK", "data": {} }
• 失败响应 { "success": false, "code": 422, "message": "业务异常" }

2. 认证与权限

• POST /api/admin/v1/auth/login
• POST /api/admin/v1/auth/refresh
• GET /api/admin/v1/auth/profile
• 角色：PlatformAdmin、TenantAdmin、MerchantAdmin、Staff

3. 租户与商家管理

• 租户
  • GET /api/admin/v1/tenants
  • POST /api/admin/v1/tenants
  • PUT /api/admin/v1/tenants/{id}
  • PATCH/api/admin/v1/tenants/{id}/status
• 商家
  • GET /api/admin/v1/merchants
  • POST /api/admin/v1/merchants
  • GET /api/admin/v1/merchants/{id}
  • PUT /api/admin/v1/merchants/{id}
  • DELETE /api/admin/v1/merchants/{id}
• 门店
  • GET /api/admin/v1/stores
  • POST /api/admin/v1/stores

4. 菜品管理

• 分类
  • GET /api/admin/v1/categories
  • POST /api/admin/v1/categories
  • PUT /api/admin/v1/categories/{id}
  • DELETE /api/admin/v1/categories/{id}
• 菜品
  • GET /api/admin/v1/dishes
  • POST /api/admin/v1/dishes
  • GET /api/admin/v1/dishes/{id}
  • PUT /api/admin/v1/dishes/{id}
  • PATCH/api/admin/v1/dishes/batch-status

5. 订单与售后

• 订单
  • GET /api/admin/v1/orders
  • GET /api/admin/v1/orders/{id}
  • POST /api/admin/v1/orders/{id}/accept
  • POST /api/admin/v1/orders/{id}/cook
  • POST /api/admin/v1/orders/{id}/deliver
  • POST /api/admin/v1/orders/{id}/complete
  • POST /api/admin/v1/orders/{id}/cancel
• 售后
  • GET /api/admin/v1/refunds
  • POST /api/admin/v1/refunds/{id}/approve
  • POST /api/admin/v1/refunds/{id}/reject

6. 营销与用户运营

• 优惠券
  • GET /api/admin/v1/coupons
  • POST /api/admin/v1/coupons
  • PUT /api/admin/v1/coupons/{id}
  • PATCH/api/admin/v1/coupons/{id}/status
• 评价
  • GET /api/admin/v1/reviews
  • POST /api/admin/v1/reviews/{id}/reply

7. 统计报表

• GET /api/admin/v1/statistics/merchant/overview?merchantId=
• GET /api/admin/v1/statistics/platform/overview

8. 文件上传

• POST /api/admin/v1/files/upload (multipart/form-data)

9. WebSocket（可选）

• ws://{host}/ws/admin?token=xxx
• 主题：order.new、order.status、refund.updated