# 📡 API 接口文档

家居装修 App 后端 API 完整参考。

Base URL: `http://house.openmenu.app` (生产) | `http://localhost:8000` (开发)

---

## 📋 目录

1. [健康检查](#健康检查)
2. [材料管理](#材料管理)
3. [户型图上传](#户型图上传)
4. [装修方案生成](#装修方案生成)
5. [方案查询](#方案查询)
6. [错误码](#错误码)

---

## 💚 健康检查

### `GET /health`

检查后端服务状态。

**响应**
```json
{
  "status": "healthy"
}
```

**状态码**
- `200 OK` - 服务正常

---

## 🧱 材料管理

### `GET /api/v1/materials`

获取材料列表，支持按市场、分类筛选。

**参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `market` | string | 否 | 市场区域：`CN`（中国）或 `US`（美国），默认 `CN` |
| `category` | string | 否 | 材料分类：`地面材料`、`墙面材料`、`厨卫` 等 |
| `search` | string | 否 | 搜索关键词（名称、品牌） |

**请求示例**
```bash
# 获取中国市场所有材料
curl "http://house.openmenu.app/api/v1/materials?market=CN"

# 获取北美市场地面材料
curl "http://house.openmenu.app/api/v1/materials?market=US&category=地面材料"

# 搜索"地板"
curl "http://house.openmenu.app/api/v1/materials?search=地板"
```

**响应示例**
```json
[
  {
    "id": "floor-001",
    "name": "圣象强化地板",
    "brand": "圣象",
    "category": "地面材料",
    "estimated_price": 4.99,
    "unit": "平米",
    "room": ["客厅", "卧室", "书房"],
    "model": "F系列产品",
    "supplier": "圣象官方旗舰店",
    "purchase_url": "https://detail.tmall.com/item.htm?id=123456"
  },
  {
    "id": "wall-001",
    "name": "多乐士乳胶漆",
    "brand": "多乐士",
    "category": "墙面材料",
    "estimated_price": 299.00,
    "unit": "桶",
    "room": ["客厅", "卧室", "厨卫"],
    "model": "A991 系列",
    "supplier": "多乐士官方旗舰店",
    "purchase_url": "https://detail.tmall.com/item.htm?id=789012"
  }
]
```

**状态码**
- `200 OK` - 成功返回材料列表
- `500 Internal Server Error` - 服务器错误

---

## 📤 户型图上传

### `POST /api/v1/upload-layout`

上传户型图（支持 PNG/JPG/WebP）。

**请求**
- Content-Type: `multipart/form-data`
- Body: 
  - `file`: 户型图文件（最大 10MB）

**请求示例**
```bash
curl -X POST "http://house.openmenu.app/api/v1/upload-layout" \
  -F "file=@/path/to/layout.png"
```

**响应示例**
```json
{
  "layout_id": "667bacd4-786a-42ac-ac6b-16ec209ea096",
  "filename": "layout.png",
  "size": 102400,
  "message": "上传成功"
}
```

**状态码**
- `200 OK` - 上传成功
- `400 Bad Request` - 文件格式不支持（仅支持 PNG/JPG/WebP）
- `413 Payload Too Large` - 文件超过 10MB
- `500 Internal Server Error` - 服务器错误

---

## 🎨 装修方案生成

### `POST /api/v1/generate-plan`

基于户型图生成 AI 装修方案（3套）。

**请求**
```json
{
  "layout_id": "667bacd4-786a-42ac-ac6b-16ec209ea096",
  "style": "现代简约",
  "room_type": "客厅"
}
```

**参数说明**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `layout_id` | string | ✅ | 户型图 ID（从上传接口获取） |
| `style` | string | ✅ | 装修风格：`现代简约`、`北欧`、`中式古典`、`工业风` 等 |
| `room_type` | string | ✅ | 房间类型：`客厅`、`卧室`、`厨房`、`卫生间` 等 |

**请求示例**
```bash
curl -X POST "http://house.openmenu.app/api/v1/generate-plan" \
  -H "Content-Type: application/json" \
  -d '{
    "layout_id": "667bacd4-786a-42ac-ac6b-16ec209ea096",
    "style": "现代简约",
    "room_type": "客厅"
  }'
```

**响应示例**
```json
{
  "plans": [
    {
      "name": "现代简约方案 A",
      "description": "简洁明亮的设计，注重功能性和空间利用率。采用浅色调搭配，营造舒适宜人的居住环境。",
      "image_base64": "iVBORw0KGgoAAAANSUhEUgAAB...（1024x1024 PNG base64）",
      "materials": [
        {
          "name": "圣象强化地板",
          "brand": "圣象",
          "model": "F系列",
          "category": "地面材料",
          "estimated_price": 4.99,
          "quantity": 25,
          "total_price": 124.75,
          "room": "客厅",
          "supplier": "圣象官方旗舰店",
          "purchase_url": "https://..."
        }
      ],
      "total_budget": 15780.50
    },
    {
      "name": "现代简约方案 B",
      ...
    },
    {
      "name": "现代简约方案 C",
      ...
    }
  ]
}
```

**状态码**
- `200 OK` - 方案生成成功
- `404 Not Found` - layout_id 不存在
- `500 Internal Server Error` - AI 服务调用失败

---

## 📋 方案查询

### `GET /api/v1/layouts/{layout_id}`

查询已上传的户型图信息。

**请求示例**
```bash
curl "http://house.openmenu.app/api/v1/layouts/667bacd4-786a-42ac-ac6b-16ec209ea096"
```

**响应示例**
```json
{
  "layout_id": "667bacd4-786a-42ac-ac6b-16ec209ea096",
  "filename": "layout.png",
  "size": 102400,
  "upload_time": "2026-05-04T19:30:00Z",
  "status": "processed"
}
```

---

## ❌ 错误码

| 状态码 | 说明 | 解决方案 |
|--------|------|----------|
| `400` | 请求参数错误 | 检查请求参数格式 |
| `404` | 资源不存在 | 检查 layout_id 是否正确 |
| `413` | 文件过大 | 确保文件 < 10MB |
| `415` | 不支持的文件类型 | 仅支持 PNG/JPG/WebP |
| `500` | 服务器内部错误 | 查看服务器日志，联系管理员 |
| `503` | AI 服务不可用 | 检查 ai-service 是否运行 |

**错误响应格式**
```json
{
  "detail": "错误描述信息"
}
```

---

## 🔒 认证（开发中）

未来版本将支持 JWT 认证：

**请求头**
```
Authorization: Bearer <jwt_token>
```

---

## 📡 AI 服务接口（内部）

AI 服务运行在 `8001` 端口，仅供后端调用。

### `POST /inference`

生成装修效果图（Stability AI）。

**请求**
```json
{
  "prompt": "现代简约风格客厅，浅色调...",
  "negative_prompt": "blurry, low quality...",
  "width": 1024,
  "height": 1024
}
```

**响应**
```json
{
  "image_base64": "iVBORw0KGgo...",
  "seed": 123456
}
```

---

## 📊 材料数据库统计

**中国市场（CN）**
- 总计：**22 种材料**
- 品牌：**10 个**（圣象、多乐士、立邦等）
- 分类：地面材料、墙面材料、厨卫、灯具、门窗

**北美市场（US）**
- 总计：**26 种材料**
- 品牌：**13 个**（Pergo、Behr、Kohler 等）
- 分类：Flooring、Wall、Kitchen & Bath、Lighting、Doors & Windows

---

📱 **配套 App**：[收据扫描 App API](../receipt-scan-app/docs/API.md)