# Airhub App PRD (产品需求文档)

## 产品概述

Airhub 是一款用于连接和控制智能硬件设备的移动应用，支持蓝牙配对、WiFi配网、NFC识别和设备控制。

---

## 支持的产品

| 产品 | 图标 | AI功能 | 连接方式 | 主题色 | 备注 |
|------|------|--------|----------|--------|------|
| **毛绒机芯** | 卡皮巴拉 + AI角标 | ✅ | 蓝牙 + WiFi | 暖棕色 | 完整流程 |
| **电子吧唧 AI版** | 圆形屏幕 + AI角标 | ✅ | 蓝牙 + WiFi | 科技蓝 | 完整流程 |
| **普通电子吧唧** | 圆形屏幕 (无角标) | ❌ | 仅蓝牙 | 浅灰蓝 | 仅蓝牙传图 |
| **AI手链** | 手绳图标 + AI角标 | ✅ | NFC扫描 | 活力橙 | RFID标签，无电子元件 |
| **洛天依** | 洛天依形象 | ✅ | 外部链接 | 青绿色 | 跳转下载专属APP |

> **设备识别**：蓝牙设备通过SN码识别，AI手链通过NFC RFID识别

---

## 页面架构

```
首页 (立即连接)
    │
    ├─ 蓝牙搜索页 ──→ 发现设备 ──→ 设备详情页
    │                              │
    │                              ├─ 毛绒机芯/电子吧唧AI → WiFi配网 → 设备控制页
    │                              └─ 普通电子吧唧 → 直接进入设备控制页
    │
    ├─ NFC扫描 (全局) ──→ AI手链详情页
    │
    └─ 产品选择页 (卡片列表) ──→ 各设备详情页
                              └─ 洛天依 → 外部下载链接
```

---

## 核心页面

### 0. APP启动逻辑
```
APP启动
    ├─ 首次使用 (无已连接设备) → 显示欢迎首页
    └─ 有已连接设备 → 显示最后操作的设备首页
```
> 使用 localStorage 记录 `lastActiveDevice`，每次操作设备时更新

### 1. 欢迎首页 ✅ 已完成
- Logo (像素风) + 吉祥物 (浮动) + 渐变背景 + "立即连接"
- **仅首次使用或无设备时显示**

### 2. 蓝牙搜索页
- 马里奥问号箱子动画 → 发现设备变换为产品图标
- SN码识别设备类型

### 3. 产品选择页
- 卡片形式展示所有产品
- 点击跳转对应设备页面
- 洛天依卡片 → 外部下载链接

### 4. 设备控制页 (Device Control)

#### 4.1 通用结构
- **头部**：沉浸式 Header，包含切换设备入口、设备状态指示。
- **底部**：悬浮式 Tab 导航栏 (Icon Only)，提供核心功能入口。

#### 4.2 毛绒机芯 (卡皮巴拉) 首页
- **UI布局**：
  - **Header**：
    - 左侧：🔄 切换按钮 (跳转产品列表)
    - 右侧：
      - 🟢 在线状态 (绿点 + "在线")
      - 🔋 电量显示 (Icon + 百分比)
      - ⚙️ 设置入口
  - **Main (视觉核心)**：
    - 居中展示卡皮巴拉形象 (PNG)
    - 交互：待机呼吸动画
  - **Footer (功能导航)**：
    - 🏠 **首页 (Home)**：当前设备状态
    - 📖 **故事 (Story)**：AI故事生成入口
    - 🎵 **歌曲 (Music)**：音乐/音效控制
    - 👤 **我的 (User)**：设备专属个人中心
    
  - **交互弹窗：故事生成器 (Story Generator)**：
    - **入口**：点击底部的 [故事] Tab。
    - **逻辑**：
      - **Tab分类**：角色 / 环境 / 道具。
      - **限制**：每类最多选3个，总数最多9个。
      - **自动跳转**：单类选满3个后，自动跳转下一 Tab。
      - **选中态**：右上角“毛绒徽章”对钩 (Apple Style)，无顶部预览栏。

### 5. WiFi配网页
- 选择网络 → 输入密码 → 配网进度 → 成功/失败

---

## 特殊逻辑

### NFC全局监听
```
APP任意页面 + 扫描AI手链NFC
    ├─ APP未打开 → 拉起APP → 跳转AI手链页面
    └─ APP已打开 → 直接跳转AI手链页面
```

### 切换设备
- 所有设备详情页头部有 🔄 图标
- 点击跳转到产品选择页

---

## 设计规范 (Visual Design System)

### 🎨 双层主题色体系

Airhub 采用 **双层主题色体系**，确保品牌统一性的同时支持产品个性化：

#### 1️⃣ App 级主视觉 (Global Theme)
> 适用范围：首页 → 蓝牙搜索 → WiFi配网 → 产品列表页

| 属性 | 值 | 说明 |
|------|-----|------|
| **主渐变** | `#22D3EE → #3B82F6 → #6366F1 → #8B5CF6` | 青 → 蓝 → 靛 → 紫，水平渐变 |
| **背景** | 粉紫流动渐变 | 柔和梦幻感，多层 radial-gradient 叠加 |
| **按钮** | 3D 发光胶囊 (见下方质感规范) | 所有主要 CTA 按钮 |

#### 2️⃣ 产品级主题色 (Product Theme)
> 适用范围：UI主色调、卡片背景、按钮激活态。采用 **4色阶全息渐变** 以提升通透感与高级感。

| 产品 | 标识色 | 4色阶渐变定义 (Left → Right) | 风格描述 |
|------|------|----------|------|
| **毛绒机芯** | 暖杏褐 | `#E6B98D` (35%) `#E8C9A8` (30%) `#D4A373` (25%) `#B07D5A` | **醇厚**：左侧杏色起手不发白，右侧收于深褐，质感扎实。 |
| **电子吧唧AI** | 科技青 | `#22D3EE` (35%) `#60A5FA` (30%) `#818CF8` (25%) `#A78BFA` | **鲜艳**：左侧高亮青色（同首页按钮），右侧转紫，色彩跨度大。 |
| **普通吧唧** | 柔光紫 | `#C084FC` (35%) `#D8B4FE` (30%) `#C4B5FD` (25%) `#A78BFA` | **通透**：左侧亮紫，中间过渡到柔和淡紫，避免油漆感。 |
| **AI手链** | 活力橙 | `#FDBA74` (35%) `#FB923C` (30%) `#FBAF85` (25%) `#E07B54` | **轻盈**：左侧亮橙，右侧收于赤陶色，拒绝死板橘红。 |
| **洛天依** | 未来绿 | `#34D399` (35%) `#5EEAD4` (30%) `#22D3EE` (25%) `#2DD4BF` | **偏光**：翠绿 → 冰蓝 → 青色，极具未来感的冷色流动。 |

> **规则**：
> 1.  **左实右虚**：渐变左侧起始色必须有足够饱和度，严禁使用近白色。
> 2.  **4色阶**：必须包含4个色彩节点，模仿光线在玉石/光盘表面的折射效果。
> 3.  **通透尾部**：渐变右侧颜色稍微提亮或降低"实心感"，保持呼吸感。

---

### ✨ 按钮质感规范 (Glowing Pill Button Standard)

> **无论主题色如何变化，所有主要按钮的"质感"必须统一。**

```
┌─────────────────────────────────────────────┐
│  ▓▓▓ 顶部高光层 (rgba(255,255,255,0.15))  ▓▓▓ │
│                                             │
│              按钮文字 (白色)                 │
│                                             │
│  ▒▒▒ 底部暗边 (inset shadow)             ▒▒▒ │
└─────────────────────────────────────────────┘
      ↓↓↓ 外发光 (主题色, opacity 0.15~0.4) ↓↓↓
```

| 质感属性 | CSS 实现 |
|----------|----------|
| **形状** | `border-radius: 50% of height` (胶囊形) |
| **3D 凸起** | `inset 0 1px 1px rgba(255,255,255,0.3)` 顶部高光 |
| **底部暗边** | `inset 0 -1px 2px rgba(0,0,0,0.1)` |
| **外发光** | `0 0 15px {主题色/0.35}, 0 0 30px {主题色/0.25}, 0 6px 20px {主题色/0.4}` |
| **扫光动画** | `shine` 动画，3s 周期 |
### 3. Visual System & Themes (New Standard)
*   **Global / Home Page (AI Tech)**:
    *   **Theme**: High-Tech, futuristic, crisp.
    *   **Colors**: Purple, Blue, Pink Gradients.
    *   **Buttons**: Glassmorphism or Tech Gradient.
*   **Device Page: Capybara (Warm Plush)**:
    *   **Theme**: Soft, organic, warm, friendly.
    *   **Colors**: "Plush Gradient" -> Soft Tan (`#ECCFA8`) to Warm Brown (`#C99672`).
    *   **Goal**: Match the physical product "Plush Machine Core" feel.
    *   **Note**: Avoid "Vibrant Tech Orange" (Safety/Alert color) for main actions here.

### 4. Technical Architecture
*   **Frontend**: Native JS, CSS Variables for theming.
| **按压反馈** | `transform: scale(0.98)` |

#### CSS 变量定义 (建议)
```css
:root {
  /* App 全局主题 */
  --theme-gradient: linear-gradient(90deg, #22D3EE 0%, #3B82F6 35%, #6366F1 65%, #8B5CF6 100%);
  --theme-glow-1: rgba(34, 211, 238, 0.35);
  --theme-glow-2: rgba(99, 102, 241, 0.25);
  --theme-glow-3: rgba(99, 102, 241, 0.4);
}

/* 产品主题覆盖 (示例：毛绒机芯) */
.theme-plush-core {
  --theme-gradient: linear-gradient(90deg, #D4A574 0%, #C08552 100%);
  --theme-glow-1: rgba(212, 165, 116, 0.35);
  --theme-glow-2: rgba(192, 133, 82, 0.25);
  --theme-glow-3: rgba(192, 133, 82, 0.4);
}
```

---

### 🧩 视觉一致性规则

| 规则 | 说明 |
|------|------|
| **背景统一** | 所有页面使用相同的动态渐变背景系统 |
| **按钮质感统一** | 所有主要按钮遵循 "Glowing Pill" 规范，仅颜色变化 |
| **卡片风格** | 轻量玻璃拟态 (`bg-white/20~30 + blur`)，带 `drop-shadow` 光晕 |
| **动作按钮** | **Glass Halo Capsule** (见下方详细规范) |
| **图标风格** | 像素风 SVG (Pixel Art)，统一 24x24 viewBox |
| **动效时长** | 微交互 150-300ms，页面过渡 300-500ms |
| **边框策略** | 玻璃态元素使用 `1px rgba(255,255,255,0.3)` 弱边框 |

---

### ✨ 毛玻璃光晕胶囊规范 (Glass Halo Capsule Standard)

> **用于卡片内部或深色渐变背景上的次要/功能性操作按钮。**

| 属性 | 实现方式 |
|------|----------|
| **背景** | `rgba(255, 255, 255, 0.2)` + `backdrop-filter: blur(8px)` |
| **边框** | `1px solid rgba(255, 255, 255, 0.3)` |
| **形状** | `border-radius: 20px` (胶囊形) |
| **文字/图标** | 针对不同操作设置颜色 (如 `#EF4444` 或 `#B07D5A`) |
| **防遮挡光晕** | **核心重点**：使用 `filter: drop-shadow(0 0 2px #FFF) drop-shadow(0 0 5px rgba(255,255,255,0.8))` 确保彩色内容在深色背景下不“吃字”。 |

---

### 📜 渐变遮罩滚动页规范 (Gradient Mask Scroll Standard)

> **用于设置页、法务文档（用户协议、隐私政策）等长文本滚动页面。**

#### 核心逻辑
- **Header**：背景**完全透明**，不使用毛玻璃，保持视觉纯净。
- **Content**：内容区域使用 CSS `mask-image` 实现顶部淡出效果，滚动时文字优雅消失，而非被 Header 硬切。

#### 参数标准

| 属性 | 值 | 说明 |
|------|-----|------|
| **内容顶部间距** | `calc(safe-area + 120px)` | 内容初始位置，避开 Header |
| **遮罩透明区** | `0px ~ 100px` | 此区域完全透明（文字不可见） |
| **遮罩过渡区** | `100px ~ 130px` | 30px 渐变过渡至完全显示 |

#### CSS 实现
```css
.content-scroll {
    padding-top: calc(env(safe-area-inset-top, 20px) + 120px);
    
    /* 淡出遮罩 */
    -webkit-mask-image: linear-gradient(to bottom, transparent 0px, transparent 100px, black 130px, black 100%);
    mask-image: linear-gradient(to bottom, transparent 0px, transparent 100px, black 130px, black 100%);
    
    /* 隐藏滚动条 */
    scrollbar-width: none;
}
.content-scroll::-webkit-scrollbar { display: none; }
```

#### 适用页面
- `privacy.html` - 隐私政策
- `agreement.html` - 用户协议
- `collection-list.html` - 个人信息收集清单
- `sharing-list.html` - 第三方信息共享清单
- `settings.html` - 设置页 (已应用)

---

### 🔧 共享 UI 组件规范

> **所有页面必须使用以下共享组件**，定义在 `styles.css` 中，确保一处修改全局生效。

#### Layout Tokens (CSS 变量)
```css
:root {
  --header-padding-top: calc(env(safe-area-inset-top, 20px) + 12px);
  --page-padding-x: 20px;
  --safe-area-bottom: env(safe-area-inset-bottom, 20px);
}
```

#### 共享组件类名

| 类名 | 用途 | 规格 |
|------|------|------|
| `.page-header` | 页面头部 | Grid 布局 (`40px 1fr 40px`) 实现完美居中 |
| `.back-btn` | 返回按钮 | 40×40px, 12px圆角, 简单玻璃磨砂 (首页/蓝牙同款) |
| `.page-title` | 页面标题 | 18px/700, 居中 (Grid Column 2) |
| `.primary-btn` | 主按钮 | Glowing Pill 质感, 高度 58px |
| `.scroll-container` | 滚动容器 | iOS 惯性滚动, 统一内边距 |

#### 使用示例
```html
<!-- Grid 让标题绝对居中，无需 Spacer -->
<header class="page-header">
    <button class="back-btn">←</button>
    <h1 class="page-title">选择产品</h1>
</header>
<main class="scroll-container">
    <!-- 页面内容 -->
</main>
```

---

### 字体规范

| 用途 | 字体 | 字重 | 说明 |
|------|------|------|------|
| **标题/Display** | Outfit | 500-700 | 现代几何无衬线，略带圆润，兼具科技感与友好感 |
| **正文/UI** | DM Sans | 400-600 | 几何无衬线，干净利落，阅读体验优秀 |
| **Logo/像素元素** | Press Start 2P | 400 | 像素风复古字体 |
| **回退字体栈** | -apple-system, BlinkMacSystemFont, Roboto | - | 系统字体兜底（含中文） |

> **字体选择理念 (遵循 frontend-design 规范)**
> - 拒绝 Inter/Arial/Roboto 等"AI 味"通用字体
> - Display + Body 双字体搭配，层次分明
> - Outfit 的圆润几何感与卡皮巴拉的友好气质匹配
> - DM Sans 比 Inter 更有个性，同时保持极佳可读性
> - 两者均为 Google Fonts 免费开源字体

---

## 技术接口预留

```javascript
// 蓝牙设备发现回调
onBluetoothDeviceFound(device) { /* SN码解析 */ }

// NFC扫描回调
onNFCTagRead(tagId) { /* RFID识别 */ }

// 设备类型枚举
DEVICE_TYPES = {
    PLUSH_CORE: 'plush_core',       // 毛绒机芯
    BADGE_AI: 'badge_ai',           // 电子吧唧AI
    BADGE_BASIC: 'badge_basic',     // 普通电子吧唧
    BRACELET_AI: 'bracelet_ai',     // AI手链
    LUOTIANYI: 'luotianyi'          // 洛天依
}
```

---

*文档最后更新: 2026-02-04*