# 管理后台 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