zyc/rtc_prd

Fork 0

zyc 34dbfd7fd7 add setting

2026-02-09 15:36:18 +08:00

20 KiB

Raw Blame History

Airhub 后台接口规范文档

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

概述

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

PRD HTML 原型文件 - 根目录下的 .html 文件
airhub_app Flutter 代码 - airhub_app/lib/ 目录
已实现的接口调用 - 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

请求头

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

响应格式

成功响应

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

错误响应

{
  "code": 40001,
  "message": "参数错误",
  "data": null
}

错误码定义

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

接口列表

1. 用户认证

1.1 发送验证码

POST /api/auth/send-code

请求参数

{
  "phone": "13800138000"
}

响应

{
  "code": 0,
  "message": "验证码已发送",
  "data": {
    "expire_in": 60
  }
}

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

1.2 验证码登录

POST /api/auth/login

请求参数

{
  "phone": "13800138000",
  "code": "123456"
}

响应

{
  "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 一键登录

POST /api/auth/one-click-login

请求参数

{
  "access_token": "运营商SDK返回的token"
}

响应: 同验证码登录

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

Flutter 代码对应: AuthRemoteDataSource.oneClickLogin()

1.4 刷新 Token

POST /api/auth/refresh-token

请求参数

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

响应

{
  "code": 0,
  "data": {
    "access_token": "新的access_token",
    "expire_in": 604800
  }
}

1.5 退出登录

POST /api/auth/logout

请求头: 需要 Authorization

响应

{
  "code": 0,
  "message": "已退出登录"
}

Flutter 代码对应: AuthRepository.logout()

1.6 账号注销

DELETE /api/auth/account

请求头: 需要 Authorization

响应

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

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

2. 用户信息

2.1 获取用户资料

GET /api/user/profile

响应

{
  "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 更新用户资料

PUT /api/user/profile

请求参数

{
  "nickname": "新昵称",
  "gender": "女",
  "birthday": "1995-06-15"
}

响应

{
  "code": 0,
  "message": "保存成功"
}

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

2.3 上传头像

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

请求参数

file: (binary)

响应

{
  "code": 0,
  "data": {
    "avatar_url": "https://oss.airhub.com/avatars/xxx.jpg"
  }
}

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

3. 设备管理

3.1 获取设备列表

GET /api/devices

响应

{
  "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 获取设备详情

GET /api/devices/{device_id}

响应

{
  "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 更新设备设置

PUT /api/devices/{device_id}

请求参数

{
  "nickname": "新昵称",
  "user_name": "主人称呼",
  "volume": 70,
  "brightness": 90,
  "allow_interrupt": false,
  "privacy_mode": true
}

响应

{
  "code": 0,
  "message": "设置已保存"
}

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

3.4 绑定设备

POST /api/devices/{device_id}/bind

请求参数

{
  "mac_address": "AA:BB:CC:DD:EE:FF",
  "wifi_ssid": "Home_WiFi",
  "wifi_password": "password123"
}

响应

{
  "code": 0,
  "message": "设备绑定成功",
  "data": {
    "device_id": "dev_001",
    "memory_id": "mem_001"
  }
}

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

3.5 解绑设备

DELETE /api/devices/{device_id}/unbind

响应

{
  "code": 0,
  "message": "设备已解绑",
  "data": {
    "memory_id": "mem_001",
    "memory_name": "Cloud_Mem_01"
  }
}

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

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

3.6 配置设备 WiFi

POST /api/devices/{device_id}/wifi

请求参数

{
  "ssid": "New_WiFi",
  "password": "password123"
}

响应

{
  "code": 0,
  "message": "WiFi 配置成功"
}

PRD 来源: wifi-config.html

4. 角色记忆

4.1 获取角色记忆列表

GET /api/agents

响应

{
  "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 解绑角色记忆

POST /api/agents/{agent_id}/unbind

响应

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

4.3 注入角色记忆

POST /api/agents/{agent_id}/inject

请求参数

{
  "device_id": "dev_002"
}

响应

{
  "code": 0,
  "message": "角色记忆注入成功"
}

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

5. 故事模块

5.1 获取故事列表

GET /api/stories

查询参数

shelf_id: 1          # 书架 ID，可选
page: 1              # 页码
page_size: 20        # 每页数量

响应

{
  "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 获取故事详情

GET /api/stories/{story_id}

响应

{
  "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 流式)

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

请求参数

{
  "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 保存故事

POST /api/stories/{story_id}/save

请求参数

{
  "shelf_id": 1
}

响应

{
  "code": 0,
  "message": "故事已保存到书架"
}

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

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

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 解锁新书架

POST /api/stories/shelves/unlock

请求参数

{
  "cost_points": 500
}

响应

{
  "code": 0,
  "message": "解锁成功",
  "data": {
    "shelf_id": 2,
    "remaining_points": 1500
  }
}

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

6. 音乐模块

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

6.1 生成音乐 (SSE 流式)

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

请求参数

{
  "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 获取播放列表

GET /api/playlist

响应

{
  "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 删除播放列表项

DELETE /api/playlist/{track_id}

响应

{
  "code": 0,
  "message": "已从播放列表移除"
}

6.4 收藏音乐

POST /api/playlist/{track_id}/favorite

响应

{
  "code": 0,
  "message": "已收藏"
}

7. 通知模块

7.1 获取通知列表

GET /api/notifications

查询参数

type: all            # all, system, activity, device
page: 1
page_size: 20

响应

{
  "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 标记通知已读

PUT /api/notifications/{notification_id}/read

响应

{
  "code": 0,
  "message": "已标记为已读"
}

7.3 标记全部已读

PUT /api/notifications/read-all

响应

{
  "code": 0,
  "message": "全部标记为已读"
}

8. 系统接口

8.1 提交意见反馈

POST /api/feedback

请求参数

{
  "content": "希望增加深色模式功能",
  "contact": "user@email.com"
}

响应

{
  "code": 0,
  "message": "感谢您的反馈！"
}

Flutter 代码对应: feedback_dialog.dart

8.2 检查版本更新

GET /api/version/check

查询参数

platform: ios        # ios, android
current_version: 1.0.0

响应

{
  "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 (用户)

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

Device (设备)

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 (角色记忆)

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 (故事)

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 (音乐)

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 (通知)

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 自动生成，如有问题请联系开发团队。

20 KiB Raw Blame History Unescape Escape

Airhub 后台接口规范文档

目录

概述

技术栈建议

通用规范

基础 URL

请求头

响应格式

错误码定义

接口列表

1. 用户认证

1.1 发送验证码

1.2 验证码登录

1.3 一键登录

1.4 刷新 Token

1.5 退出登录

1.6 账号注销

2. 用户信息

2.1 获取用户资料

2.2 更新用户资料

2.3 上传头像

3. 设备管理

3.1 获取设备列表

3.2 获取设备详情

3.3 更新设备设置

3.4 绑定设备

3.5 解绑设备

3.6 配置设备 WiFi

4. 角色记忆

4.1 获取角色记忆列表

4.2 解绑角色记忆

4.3 注入角色记忆

5. 故事模块

5.1 获取故事列表

5.2 获取故事详情

5.3 生成故事 (SSE 流式)

5.4 保存故事

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

5.6 解锁新书架

6. 音乐模块

6.1 生成音乐 (SSE 流式)

6.2 获取播放列表

6.3 删除播放列表项

6.4 收藏音乐

7. 通知模块

7.1 获取通知列表

7.2 标记通知已读

7.3 标记全部已读

8. 系统接口

8.1 提交意见反馈

8.2 检查版本更新

数据模型

User (用户)

Device (设备)

Agent (角色记忆)

Story (故事)

Track (音乐)

Notification (通知)

开发优先级

附录：代码对照表

更新日志

20 KiB

Raw Blame History