# 🔌 API 接口速查库

> 2026-06-08 | 兮楠女装项目全部API，写代码时快速调取

---

## 一、商城 API（FastAPI :8891）

**基础**: `https://shop.hunanningyuan.cloud/api/v1/`

| 方法 | 路径 | 用途 | 参数 |
|:-----|:------|:------|:------|
| GET | `products` | 商品列表 | `?page=1&page_size=200&category=西装&review_status=shelf` |
| GET | `products/{style_no}/detail` | 商品详情(SSR) | `style_no` (如 `FLY240420A12`) |
| GET | `recommend` | 搭配推荐 | `?style_no=X&limit=4` |
| POST | `cart` | 加购 | `{style_no, quantity, client_id}` |
| GET | `cart?client_id=X` | 购物车列表 | `client_id` |
| DELETE | `cart/{id}` | 删除购物车项 | `id` |
| POST | `favorites` | 收藏/取消 | `{style_no, action: toggle}` |
| GET | `favorites?client_id=X` | 收藏列表 | `client_id` |
| POST | `orders` | 下单(无真实支付) | `{items, address, remark}` |
| POST | `auth/login` | 手机号登录 | `{phone, code}` |
| GET | `addresses?user_id=X` | 地址列表 | `user_id` |
| POST | `addresses` | 新增地址 | `{user_id, name, phone, address}` |

**价格公式**: `¥{retail_price * 0.35}` (折扣价) + 原价划线

---

## 二、小程序 API（Express :3003）

**基础**: `https://shop.hunanningyuan.cloud/api/miniapp/`

| 方法 | 路径 | 用途 | 说明 |
|:-----|:------|:------|:------|
| GET | `goods` | 商品列表 | 支持 `?category=X&page=1` |
| GET | `goods/:id` | 商品详情 | 含 `cover_url`, `scene_images`, `ai_description` |
| GET | `categories` | 分类列表 | 门店独立分类 |
| POST | `favorites` | 收藏 | `{user_id, style_no}` |
| GET | `favorites/:userId` | 收藏列表 | |
| DELETE | `favorites/:id` | 取消收藏 | |
| POST | `recommend` | AI穿搭推荐 | `{user_id, scene, style}` |
| GET | `recommend/history/:userId` | 穿搭历史 | |
| GET | `shops` | 门店列表 | 支持定位 |
| POST | `user/login` | 登录 | `{code}` (微信静默登录) |
| GET | `user/:id` | 用户信息 | |
| POST | `upload` | 文件上传 | multipart |
| POST | `admin/features` | 功能开关 | 控制AI/模式切换 |
| POST | `admin/goods/sync` | 同步商品 | 从fashion.db同步 |

**小程序专属字段**:
```json
{
  "cover_url": "AI封面图(优先)",
  "scene_images": ["AI场景图数组"],
  "ai_description": "AI生成的描述文本",
  "image_url": "原厂图(兜底)"
}
```

---

## 三、云函数（微信小程序 wx.cloud）

| 函数名 | 用途 | 说明 |
|:-------|:------|:------|
| `ai-outfit-recommend` | AI穿搭(文字) | 混元Lite + Kimi |
| `aliyun-virtual-tryon` | AI试衣 | 阿里云DashScope aitryon-plus |
| `aliyun-image-gen` | AI生图 | 通义万相 wanx-v1 |
| `qwenvl-fashion-tagger` | 服装打标 | 通义千问VL |
| `baidu-image-recognition` | 图片识别 | 百度API |
| `generateOutfit` | 搭配生成 | |
| `outfit-feedback` | 穿搭反馈 | 含刷新次数限制 |
| `generatePoster` | 生成海报 | |

调用方式: `wx.cloud.callFunction({name: "ai-outfit-recommend", data: {...}})`

---

## 四、CDN / 图片

| 域名 | 用途 | 说明 |
|:------|:------|:------|
| `img.hunanningyuan.cloud` | 商品图片CDN | COS → CDN，支持 `imageView2/2/w/400` 缩略图 |
| `shop.hunanningyang.cloud` | API域名 | ⚠️ 注意是 `ningyang` 不是 `ningyuan` |
| `cloud://` | 云存储(小程序) | `cloudImageHandler.js` 自动转HTTPS |

---

## 五、API 通用约定

```
Headers:
  Content-Type: application/json
  Authorization: Bearer {token} (登录后)
  X-Client-ID: {clientId} (游客)

错误响应:
  {"detail": "错误信息"}        // FastAPI
  {"error": "错误信息"}         // Express

状态码:
  200 OK
  201 Created
  400 Bad Request
  404 Not Found
  500 Internal Server Error
```