rtc_prd/docs/API_SPECIFICATION.md

# Airhub 后台接口规范文档

> 版本: 1.0.0
> 更新日期: 2025-02-09
> 基于 PRD HTML 原型与 airhub_app Flutter 代码分析整理

---

## 目录

- [概述](#概述)
- [通用规范](#通用规范)
- [接口列表](#接口列表)
  - [1. 用户认证](#1-用户认证)
  - [2. 用户信息](#2-用户信息)
  - [3. 设备管理](#3-设备管理)
  - [4. 角色记忆](#4-角色记忆)
  - [5. 故事模块](#5-故事模块)
  - [6. 音乐模块](#6-音乐模块)
  - [7. 通知模块](#7-通知模块)
  - [8. 系统接口](#8-系统接口)
- [数据模型](#数据模型)
- [开发优先级](#开发优先级)
- [附录：代码对照表](#附录代码对照表)

---

## 概述

本文档定义了 Airhub 智能硬件控制中心 APP 所需的全部后台接口。接口设计基于以下来源：

1. **PRD HTML 原型文件** - 根目录下的 `.html` 文件
2. **airhub_app Flutter 代码** - `airhub_app/lib/` 目录
3. **已实现的接口调用** - `music-creation.html` 中的实际 API 调用

### 技术栈建议

- 后端框架: Node.js (Express/Fastify) 或 Python (FastAPI)
- 数据库: PostgreSQL / MySQL
- 缓存: Redis
- 对象存储: 阿里云 OSS
- 实时通信: SSE (Server-Sent Events)

---

## 通用规范

### 基础 URL

```
开发环境: http://localhost:3000/api
生产环境: https://api.airhub.com/v1
```

### 请求头

```http
Content-Type: application/json
Authorization: Bearer {access_token}
X-Device-Id: {device_uuid}
X-App-Version: 1.0.0
```

### 响应格式

**成功响应**
```json
{
  "code": 0,
  "message": "success",
  "data": { ... }
}
```

**错误响应**
```json
{
  "code": 40001,
  "message": "参数错误",
  "data": null
}
```

### 错误码定义

| 错误码 | 说明 |
|--------|------|
| 0 | 成功 |
| 40001 | 参数错误 |
| 40101 | 未授权 (Token 无效) |
| 40102 | Token 过期 |
| 40301 | 无权限 |
| 40401 | 资源不存在 |
| 50001 | 服务器内部错误 |

---

## 接口列表

### 1. 用户认证

#### 1.1 发送验证码

```http
POST /api/auth/send-code
```

**请求参数**
```json
{
  "phone": "13800138000"
}
```

**响应**
```json
{
  "code": 0,
  "message": "验证码已发送",
  "data": {
    "expire_in": 60
  }
}
```

**说明**: 验证码 60 秒内有效，同一手机号 60 秒内只能发送一次

---

#### 1.2 验证码登录

```http
POST /api/auth/login
```

**请求参数**
```json
{
  "phone": "13800138000",
  "code": "123456"
}
```

**响应**
```json
{
  "code": 0,
  "message": "登录成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "expire_in": 604800,
    "user": {
      "id": "u_12345678",
      "phone": "138****8000",
      "nickname": "用户8000",
      "avatar_url": null
    }
  }
}
```

**Flutter 代码对应**: `AuthRemoteDataSource.loginWithPhone()`

---

#### 1.3 一键登录

```http
POST /api/auth/one-click-login
```

**请求参数**
```json
{
  "access_token": "运营商SDK返回的token"
}
```

**响应**: 同验证码登录

**说明**: 使用运营商 SDK (如阿里云号码认证) 获取本机号码

**Flutter 代码对应**: `AuthRemoteDataSource.oneClickLogin()`

---

#### 1.4 刷新 Token

```http
POST /api/auth/refresh-token
```

**请求参数**
```json
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}
```

**响应**
```json
{
  "code": 0,
  "data": {
    "access_token": "新的access_token",
    "expire_in": 604800
  }
}
```

---

#### 1.5 退出登录

```http
POST /api/auth/logout
```

**请求头**: 需要 Authorization

**响应**
```json
{
  "code": 0,
  "message": "已退出登录"
}
```

**Flutter 代码对应**: `AuthRepository.logout()`

---

#### 1.6 账号注销

```http
DELETE /api/auth/account
```

**请求头**: 需要 Authorization

**响应**
```json
{
  "code": 0,
  "message": "账号注销申请已提交，将在7个工作日内处理"
}
```

**PRD 来源**: `settings.html` - 账号注销功能

---

### 2. 用户信息

#### 2.1 获取用户资料

```http
GET /api/user/profile
```

**响应**
```json
{
  "code": 0,
  "data": {
    "id": "u_12345678",
    "phone": "138****8000",
    "nickname": "土豆",
    "avatar_url": "https://oss.airhub.com/avatars/xxx.jpg",
    "gender": "男",
    "birthday": "1994-12-09",
    "created_at": "2025-01-15T10:30:00Z"
  }
}
```

**Flutter 代码对应**: `profile_page.dart` - 用户卡片显示

---

#### 2.2 更新用户资料

```http
PUT /api/user/profile
```

**请求参数**
```json
{
  "nickname": "新昵称",
  "gender": "女",
  "birthday": "1995-06-15"
}
```

**响应**
```json
{
  "code": 0,
  "message": "保存成功"
}
```

**Flutter 代码对应**: `profile_info_page.dart` - 保存按钮

---

#### 2.3 上传头像

```http
POST /api/user/avatar
Content-Type: multipart/form-data
```

**请求参数**
```
file: (binary)
```

**响应**
```json
{
  "code": 0,
  "data": {
    "avatar_url": "https://oss.airhub.com/avatars/xxx.jpg"
  }
}
```

**Flutter 代码对应**: `profile_info_page.dart` - `_pickImage()`

---

### 3. 设备管理

#### 3.1 获取设备列表

```http
GET /api/devices
```

**响应**
```json
{
  "code": 0,
  "data": {
    "devices": [
      {
        "id": "dev_001",
        "name": "毛绒机芯",
        "model": "Airhub_5G",
        "status": "online",
        "battery": 85,
        "firmware_version": "2.1.3",
        "is_ai": true,
        "icon": "Capybara.png"
      },
      {
        "id": "dev_002",
        "name": "电子吧唧 AI",
        "model": "Badge_AI",
        "status": "offline",
        "battery": 0,
        "is_ai": true
      }
    ]
  }
}
```

**设备状态枚举**:
- `online` - 在线
- `offline` - 离线
- `pairing` - 配对中
- `updating` - 固件更新中

**Flutter 代码对应**: `product_selection_page.dart`

---

#### 3.2 获取设备详情

```http
GET /api/devices/{device_id}
```

**响应**
```json
{
  "code": 0,
  "data": {
    "id": "dev_001",
    "name": "毛绒机芯",
    "model": "Airhub_5G",
    "status": "online",
    "battery": 85,
    "firmware_version": "2.1.3",
    "mac_address": "AA:BB:CC:DD:EE:FF",
    "settings": {
      "nickname": "小毛球",
      "user_name": "土豆",
      "volume": 60,
      "brightness": 85,
      "allow_interrupt": true,
      "privacy_mode": true
    },
    "wifi_list": [
      {
        "ssid": "Home_WiFi",
        "is_connected": true
      }
    ],
    "bound_memory_id": "mem_001"
  }
}
```

**Flutter 代码对应**: `device_control_page.dart` - 设置页面

---

#### 3.3 更新设备设置

```http
PUT /api/devices/{device_id}
```

**请求参数**
```json
{
  "nickname": "新昵称",
  "user_name": "主人称呼",
  "volume": 70,
  "brightness": 90,
  "allow_interrupt": false,
  "privacy_mode": true
}
```

**响应**
```json
{
  "code": 0,
  "message": "设置已保存"
}
```

**PRD 来源**: `device-control.html` - 设备设置面板

---

#### 3.4 绑定设备

```http
POST /api/devices/{device_id}/bind
```

**请求参数**
```json
{
  "mac_address": "AA:BB:CC:DD:EE:FF",
  "wifi_ssid": "Home_WiFi",
  "wifi_password": "password123"
}
```

**响应**
```json
{
  "code": 0,
  "message": "设备绑定成功",
  "data": {
    "device_id": "dev_001",
    "memory_id": "mem_001"
  }
}
```

**PRD 来源**: `bluetooth.html`, `wifi-config.html`

---

#### 3.5 解绑设备

```http
DELETE /api/devices/{device_id}/unbind
```

**响应**
```json
{
  "code": 0,
  "message": "设备已解绑",
  "data": {
    "memory_id": "mem_001",
    "memory_name": "Cloud_Mem_01"
  }
}
```

**说明**: 解绑后角色记忆自动保存到云端

**PRD 来源**: `device-control.html` - 解绑设备弹窗

---

#### 3.6 配置设备 WiFi

```http
POST /api/devices/{device_id}/wifi
```

**请求参数**
```json
{
  "ssid": "New_WiFi",
  "password": "password123"
}
```

**响应**
```json
{
  "code": 0,
  "message": "WiFi 配置成功"
}
```

**PRD 来源**: `wifi-config.html`

---

### 4. 角色记忆

#### 4.1 获取角色记忆列表

```http
GET /api/agents
```

**响应**
```json
{
  "code": 0,
  "data": {
    "agents": [
      {
        "id": "mem_001",
        "name": "Airhub_Mem_01",
        "icon": "🧠",
        "nickname": "小毛球",
        "bound_device": {
          "id": "dev_001",
          "name": "Airhub_5G"
        },
        "status": "bound",
        "created_at": "2025-01-15"
      },
      {
        "id": "mem_002",
        "name": "Airhub_Mem_02",
        "icon": "🐾",
        "nickname": "豆豆",
        "bound_device": null,
        "status": "unbound",
        "created_at": "2024-08-22"
      }
    ]
  }
}
```

**角色记忆状态**:
- `bound` - 已绑定设备
- `unbound` - 未绑定 (可注入)

**Flutter 代码对应**: `agent_manage_page.dart`

---

#### 4.2 解绑角色记忆

```http
POST /api/agents/{agent_id}/unbind
```

**响应**
```json
{
  "code": 0,
  "message": "已解绑角色记忆，数据已保留在云端"
}
```

---

#### 4.3 注入角色记忆

```http
POST /api/agents/{agent_id}/inject
```

**请求参数**
```json
{
  "device_id": "dev_002"
}
```

**响应**
```json
{
  "code": 0,
  "message": "角色记忆注入成功"
}
```

**PRD 来源**: `agent-manage.html` - 注入设备按钮

---

### 5. 故事模块

#### 5.1 获取故事列表

```http
GET /api/stories
```

**查询参数**
```
shelf_id: 1          # 书架 ID，可选
page: 1              # 页码
page_size: 20        # 每页数量
```

**响应**
```json
{
  "code": 0,
  "data": {
    "stories": [
      {
        "id": "story_001",
        "title": "卡皮巴拉的奇幻漂流",
        "cover_url": "https://oss.airhub.com/covers/xxx.jpg",
        "content": "在一条蜿蜒的小河边...",
        "has_video": true,
        "video_url": "https://oss.airhub.com/videos/xxx.mp4",
        "created_at": "2025-01-20T15:30:00Z"
      }
    ],
    "total": 5,
    "page": 1,
    "page_size": 20
  }
}
```

**Flutter 代码对应**: `device_control_page.dart` - `_mockStories`

---

#### 5.2 获取故事详情

```http
GET /api/stories/{story_id}
```

**响应**
```json
{
  "code": 0,
  "data": {
    "id": "story_001",
    "title": "卡皮巴拉的奇幻漂流",
    "cover_url": "https://oss.airhub.com/covers/xxx.jpg",
    "content": "完整故事内容...",
    "has_video": true,
    "video_url": "https://oss.airhub.com/videos/xxx.mp4",
    "created_at": "2025-01-20T15:30:00Z"
  }
}
```

**Flutter 代码对应**: `story_detail_page.dart`

---

#### 5.3 生成故事 (SSE 流式)

```http
POST /api/stories/generate
Accept: text/event-stream
```

**请求参数**
```json
{
  "mode": "random",
  "prompt": "关于卡皮巴拉的冒险故事",
  "theme": "adventure"
}
```

**生成模式**:
- `random` - 随机生成
- `keyword` - 关键词生成
- `theme` - 主题生成

**SSE 响应流**
```
data: {"stage": "generating", "progress": 10, "message": "正在构思故事大纲..."}

data: {"stage": "generating", "progress": 50, "message": "正在撰写故事内容..."}

data: {"stage": "done", "progress": 100, "story": {...}}
```

**Flutter 代码对应**: `story_loading_page.dart`

---

#### 5.4 保存故事

```http
POST /api/stories/{story_id}/save
```

**请求参数**
```json
{
  "shelf_id": 1
}
```

**响应**
```json
{
  "code": 0,
  "message": "故事已保存到书架"
}
```

**PRD 来源**: `story-detail.html` - 保存故事按钮

---

#### 5.5 生成动态绘本 (SSE 流式)

```http
POST /api/stories/{story_id}/video
Accept: text/event-stream
```

**SSE 响应流**
```
data: {"stage": "processing", "progress": 20, "message": "正在生成插画..."}

data: {"stage": "processing", "progress": 60, "message": "正在合成视频..."}

data: {"stage": "done", "progress": 100, "video_url": "https://..."}
```

**说明**: 生成动态绘本消耗 10 SP (积分)

**Flutter 代码对应**: `story_detail_page.dart` - `runGenerationProcess()`

---

#### 5.6 解锁新书架

```http
POST /api/stories/shelves/unlock
```

**请求参数**
```json
{
  "cost_points": 500
}
```

**响应**
```json
{
  "code": 0,
  "message": "解锁成功",
  "data": {
    "shelf_id": 2,
    "remaining_points": 1500
  }
}
```

**Flutter 代码对应**: `device_control_page.dart` - `_showUnlockDialog()`

---

### 6. 音乐模块

> ⚠️ **重要**: 此模块在 `music-creation.html` 中已有实际 API 调用实现

#### 6.1 生成音乐 (SSE 流式)

```http
POST /api/create_music
Accept: text/event-stream
```

**请求参数**
```json
{
  "text": "水豚在雨中等公交，心情却很平静",
  "mood": "chill"
}
```

**心情类型**:
- `chill` - Chill Lofi (慵懒·治愈)
- `happy` - Happy Funk (活力·奔跑)
- `sleep` - Deep Sleep (白噪音·助眠)
- `focus` - Focus Flow (心流·专注)
- `mystery` - 盲盒惊喜 (AI随机)
- `custom` - 自由创作

**SSE 响应流**
```
data: {"stage": "connecting", "progress": 5, "message": "🎼 正在连接 AI..."}

data: {"stage": "lyrics", "progress": 20, "message": "🎵 正在生成歌词..."}

data: {"stage": "music", "progress": 30, "message": "🎹 正在作曲..."}

data: {"stage": "done", "progress": 100, "file_path": "/music/xxx.mp3", "metadata": {"lyrics": "歌词内容..."}}
```

**错误响应**
```
data: {"stage": "error", "message": "生成失败，请重试"}
```

**HTML 代码位置**: `music-creation.html:1730`

**Flutter 代码对应**: `music_creation_page.dart` - `_mockGenerate()`

---

#### 6.2 获取播放列表

```http
GET /api/playlist
```

**响应**
```json
{
  "code": 0,
  "data": {
    "playlist": [
      {
        "id": 1,
        "title": "卡皮巴拉蹦蹦蹦",
        "lyrics": "卡皮巴拉\n啦啦啦啦...",
        "audio_url": "/music/卡皮巴拉蹦蹦蹦.mp3",
        "cover_url": "Capybara.png",
        "mood": "happy",
        "duration": 204,
        "created_at": "2025-01-15T10:00:00Z"
      }
    ]
  }
}
```

**HTML 代码位置**: `music-creation.html:2006`

**Flutter 代码对应**: `music_creation_page.dart` - `_playlist`

---

#### 6.3 删除播放列表项

```http
DELETE /api/playlist/{track_id}
```

**响应**
```json
{
  "code": 0,
  "message": "已从播放列表移除"
}
```

---

#### 6.4 收藏音乐

```http
POST /api/playlist/{track_id}/favorite
```

**响应**
```json
{
  "code": 0,
  "message": "已收藏"
}
```

---

### 7. 通知模块

#### 7.1 获取通知列表

```http
GET /api/notifications
```

**查询参数**
```
type: all            # all, system, activity, device
page: 1
page_size: 20
```

**响应**
```json
{
  "code": 0,
  "data": {
    "notifications": [
      {
        "id": "notif_001",
        "type": "system",
        "title": "系统更新",
        "description": "Airhub V1.2.0 版本更新已准备就绪",
        "content": "<p><strong>更新说明：</strong></p><ul><li>新增喂养指南功能</li></ul>",
        "is_read": false,
        "created_at": "2025-02-09T10:30:00Z"
      },
      {
        "id": "notif_002",
        "type": "activity",
        "title": "新春活动",
        "description": "领取您的新春限定水豚皮肤",
        "image_url": "https://...",
        "is_read": true,
        "created_at": "2025-02-08T09:00:00Z"
      }
    ],
    "unread_count": 1
  }
}
```

**通知类型**:
- `system` - 系统通知
- `activity` - 活动通知
- `device` - 设备通知

**Flutter 代码对应**: `notification_page.dart`

---

#### 7.2 标记通知已读

```http
PUT /api/notifications/{notification_id}/read
```

**响应**
```json
{
  "code": 0,
  "message": "已标记为已读"
}
```

---

#### 7.3 标记全部已读

```http
PUT /api/notifications/read-all
```

**响应**
```json
{
  "code": 0,
  "message": "全部标记为已读"
}
```

---

### 8. 系统接口

#### 8.1 提交意见反馈

```http
POST /api/feedback
```

**请求参数**
```json
{
  "content": "希望增加深色模式功能",
  "contact": "user@email.com"
}
```

**响应**
```json
{
  "code": 0,
  "message": "感谢您的反馈！"
}
```

**Flutter 代码对应**: `feedback_dialog.dart`

---

#### 8.2 检查版本更新

```http
GET /api/version/check
```

**查询参数**
```
platform: ios        # ios, android
current_version: 1.0.0
```

**响应**
```json
{
  "code": 0,
  "data": {
    "latest_version": "1.2.0",
    "current_version": "1.0.0",
    "update_required": false,
    "force_update": false,
    "update_url": "https://apps.apple.com/...",
    "release_notes": "1. 新增喂养指南\n2. 优化连接稳定性"
  }
}
```

**Flutter 代码对应**: `settings_page.dart` - 检查更新

---

## 数据模型

### User (用户)

```typescript
interface User {
  id: string;
  phone: string;           // 脱敏显示
  nickname: string;
  avatar_url: string | null;
  gender: '男' | '女' | null;
  birthday: string | null; // YYYY-MM-DD
  created_at: string;
}
```

### Device (设备)

```typescript
interface Device {
  id: string;
  name: string;
  model: string;
  status: 'online' | 'offline' | 'pairing' | 'updating';
  battery: number;        // 0-100
  firmware_version: string;
  mac_address: string;
  is_ai: boolean;
  settings: DeviceSettings;
  bound_memory_id: string | null;
}

interface DeviceSettings {
  nickname: string;       // 设备昵称
  user_name: string;      // 用户称呼
  volume: number;         // 0-100
  brightness: number;     // 0-100
  allow_interrupt: boolean;
  privacy_mode: boolean;
}
```

### Agent (角色记忆)

```typescript
interface Agent {
  id: string;
  name: string;           // Airhub_Mem_01
  icon: string;           // Emoji
  nickname: string;       // 小毛球
  bound_device: Device | null;
  status: 'bound' | 'unbound';
  created_at: string;
}
```

### Story (故事)

```typescript
interface Story {
  id: string;
  title: string;
  cover_url: string;
  content: string;
  has_video: boolean;
  video_url: string | null;
  shelf_id: number;
  created_at: string;
}
```

### Track (音乐)

```typescript
interface Track {
  id: number;
  title: string;
  lyrics: string;
  audio_url: string;
  cover_url: string;
  mood: 'chill' | 'happy' | 'sleep' | 'focus' | 'mystery' | 'custom';
  duration: number;       // 秒
  created_at: string;
}
```

### Notification (通知)

```typescript
interface Notification {
  id: string;
  type: 'system' | 'activity' | 'device';
  title: string;
  description: string;
  content: string | null;  // HTML 内容
  image_url: string | null;
  is_read: boolean;
  created_at: string;
}
```

---

## 开发优先级

| 优先级 | 模块 | 说明 | 依赖 |
|--------|------|------|------|
| **P0** | 用户认证 | 登录/注册是基础功能 | 运营商 SDK |
| **P0** | 设备管理 | 核心业务：设备绑定、配网 | 蓝牙 SDK |
| **P1** | 音乐模块 | 已有 HTML 实现，需对接 MiniMax API | MiniMax API |
| **P1** | 故事模块 | 核心功能：AI 生成故事 | LLM API |
| **P2** | 角色记忆 | 差异化功能 | 设备管理 |
| **P2** | 用户信息 | 个人中心相关 | 用户认证 |
| **P3** | 通知模块 | 辅助功能 | 推送 SDK |
| **P3** | 系统接口 | 反馈、版本检查 | - |

---

## 附录：代码对照表

| 接口 | PRD HTML 文件 | Flutter 代码 |
|------|---------------|--------------|
| 登录 | `login.html` | `auth_remote_data_source.dart` |
| 用户资料 | `profile.html`, `profile-info.html` | `profile_page.dart`, `profile_info_page.dart` |
| 设备管理 | `products.html`, `device-control.html` | `product_selection_page.dart`, `device_control_page.dart` |
| 配网 | `bluetooth.html`, `wifi-config.html` | `bluetooth_page.dart`, `wifi_config_page.dart` |
| 角色记忆 | `agent-manage.html` | `agent_manage_page.dart` |
| 故事 | `story-detail.html`, `story-loading.html` | `story_detail_page.dart`, `story_loading_page.dart` |
| 音乐 | `music-creation.html` | `music_creation_page.dart` |
| 通知 | `notifications.html` | `notification_page.dart` |
| 设置 | `settings.html` | `settings_page.dart` |

---

## 更新日志

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0.0 | 2025-02-09 | 初版，基于 PRD 和 Flutter 代码分析 |

---

*本文档由 Claude Code 自动生成，如有问题请联系开发团队。*