# Lyrria AI 英语语音助手 - 前端

## 🎯 项目简介

基于 React + TypeScript + Vite + Tailwind CSS 构建的现代化语音交互界面，完美支持各种屏幕尺寸和移动端浏览器。

---

## ✨ 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| **React** | 18.2 | UI 框架 |
| **TypeScript** | 5.3 | 类型系统 |
| **Vite** | 5.0 | 构建工具 |
| **Tailwind CSS** | 4.0 | 样式方案 ⭐ |
| **React Router** | 7.9 | 路由管理 |
| **Zustand** | 4.4 | 状态管理 |
| **Video.js** | 8.23 | 视频播放 |
| **Recorder Core** | 1.2 | 音频录制 |

---

## 🚀 快速开始

### 安装依赖
```bash
cd frontend
npm install
```

### 开发环境
```bash
npm run dev
# 访问 http://localhost:3000
```

### 生产构建
```bash
npm run build
npm run preview  # 预览构建结果
```

---

## 📱 浏览器兼容性

### ✅ 完全支持
- Chrome 90+ (Android/Windows/macOS)
- Safari 14+ (iOS 14+, macOS)
- Firefox 88+ (Android/Windows/macOS)
- Edge 90+ (Windows/Android)
- 夸克浏览器 (最新版)

### ⚠️ 降级支持
- Safari 13.1-14 (iOS 13): 部分 CSS 特性降级为固定值

### 🧪 测试设备
- ✅ iPhone SE / 11 / 14 Pro Max
- ✅ iPad / iPad Pro
- ✅ Samsung Galaxy S21
- ✅ Xiaomi 12
- ✅ 横屏/竖屏模式

---

## 🎨 响应式设计

### 移动端优先策略

项目采用 **Tailwind CSS** 实现完全响应式布局：

- **流式字体**: `clamp(24px, 6vw, 32px)` 自动缩放
- **视口单位**: `18vh`、`5vw` 等相对单位
- **断点系统**: `sm:`、`md:`、`lg:` 等前缀
- **混合布局**: `max(164px, 18vh)` 确保最小值

**示例**:
```tsx
<h1 className="text-fluid-2xl sm:text-3xl md:text-4xl">
  {/* 移动端 24-32px，平板 30px，桌面 36px */}
</h1>
```

---

## 📁 项目结构

```
frontend/
├── src/
│   ├── assets/          # 静态资源（图片、字体）
│   ├── pages/           # 页面组件
│   │   ├── WelcomePage.tsx       ✅ Tailwind
│   │   ├── LoadingPage.tsx       ✅ Tailwind
│   │   ├── GreetingPage.tsx      ✅ Tailwind
│   │   ├── VideoIntroPage.tsx    ⚠️ 待迁移
│   │   └── ChatBotPage.tsx       ⚠️ 待迁移
│   ├── components/      # 可复用组件（未来）
│   ├── store/           # Zustand 状态
│   ├── utils/           # 工具函数
│   ├── router/          # 路由配置
│   ├── index.css        # Tailwind 入口
│   └── main.tsx         # 应用入口
├── docs/                # 技术文档
│   ├── Tailwind_CSS迁移文档.md
│   └── Tailwind_快速参考.md
├── tailwind.config.js   # Tailwind 配置
├── postcss.config.js    # PostCSS 配置
├── vite.config.ts       # Vite 配置
└── package.json
```

---

## 🎯 页面流程

```
WelcomePage (欢迎页)
    ↓
LoadingPage (加载页)
    ↓
VideoIntroPage (视频介绍)
    ↓
GreetingPage (输入姓名)
    ↓
ChatBotPage (语音对话)
```

---

## 🛠️ 核心功能

### 1. 语音录制
```tsx
import Recorder from 'recorder-core';

const recorder = new Recorder({
  type: 'pcm',
  sampleRate: 16000,
  bitRate: 16,
});
```

### 2. WebSocket 通信
```tsx
import ReconnectingWebSocket from 'reconnecting-websocket';

const ws = new ReconnectingWebSocket('wss://backend/ws');
ws.send(JSON.stringify({ type: 'audio_chunk', data }));
```

### 3. 视频播放
```tsx
import videojs from 'video.js';

const player = videojs(videoRef.current, {
  autoplay: true,
  controls: false,
  playsinline: true,
});
```

---

## 📖 样式开发指南

### 使用 Tailwind CSS

**推荐写法**:
```tsx
<div className="w-full h-screen flex items-center justify-center bg-[#F5F5F5]">
  <div className="max-w-mobile p-4 rounded-xl shadow-lg">
    <h1 className="text-fluid-2xl font-semibold text-black">
      标题
    </h1>
  </div>
</div>
```

### 自定义值
```tsx
<div className="top-[max(164px,18vh)]">
  {/* 方括号支持任意 CSS 值 */}
</div>
```

### 响应式
```tsx
<div className="text-base sm:text-lg md:text-xl">
  {/* 移动端 16px，小屏 18px，中屏 20px */}
</div>
```

**详细参考**: [Tailwind_快速参考.md](./docs/Tailwind_快速参考.md)

---

## 🔧 配置说明

### 环境变量 (`.env`)
```bash
# HTTPS 开关（开发环境）
VITE_ENABLE_HTTPS=false

# SSL 证书路径（可选）
VITE_SSL_KEYFILE=../ssl/key.pem
VITE_SSL_CERTFILE=../ssl/cert.pem
```

### Tailwind 自定义
```javascript
// tailwind.config.js
export default {
  theme: {
    extend: {
      colors: {
        'bg-main': '#E8E8E8',
        'accent': '#007AFF',
      },
      fontSize: {
        'fluid-2xl': 'clamp(24px, 6vw, 32px)',
      },
    },
  },
}
```

---

## 📊 性能指标

### 构建结果
- **CSS 大小**: 85KB → 20KB (gzip)
- **JS 大小**: 1.29MB → 405KB (gzip)
- **首屏加载**: < 1s (4G 网络)

### 优化措施
- ✅ Vite 代码分割
- ✅ Tailwind JIT 编译
- ✅ 图片懒加载
- ✅ Tree-shaking 优化

---

## 🐛 常见问题

### Q: 样式不生效？
检查 Tailwind 配置：
```bash
npm run build  # 查看是否有编译错误
```

### Q: 移动端视口问题？
确保 `index.html` 包含：
```html
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
```

### Q: iOS 安全区域？
使用自定义类：
```tsx
<div className="safe-top safe-bottom">
  {/* 自动避开刘海屏 */}
</div>
```

---

## 📚 文档

- [Tailwind CSS 迁移文档](./docs/Tailwind_CSS迁移文档.md)
- [Tailwind 快速参考](./docs/Tailwind_快速参考.md)
- [技术方案](../项目文档/Tailwind_CSS技术方案.md)
- [更新日志](./CHANGELOG.md)

---

## 🤝 开发规范

### 组件规范
```tsx
// ✅ 推荐
export const MyComponent: React.FC<Props> = ({ prop }) => {
  return (
    <div className="mobile-container">
      {/* 使用语义化类名 */}
    </div>
  );
};

// ❌ 避免
export const MyComponent = (props) => {
  return <div style={{ width: '100vw' }}>{/* 避免内联样式 */}</div>;
};
```

### 样式规范
- ✅ 优先使用 Tailwind 类名
- ✅ 复杂样式提取为组件
- ✅ 避免过长的 className（> 10 个类）
- ❌ 避免内联 `style` 属性

### TypeScript 规范
- ✅ 所有函数添加类型注解
- ✅ 使用接口定义 Props
- ❌ 禁止使用 `any` 类型

---

## 🚀 后续计划

### v2.1.0
- [ ] 迁移 VideoIntroPage 到 Tailwind
- [ ] 迁移 ChatBotPage 到 Tailwind
- [ ] 添加暗黑模式

### v2.2.0
- [ ] 提取公共组件库
- [ ] 添加单元测试
- [ ] 国际化支持 (i18n)

---

## 📄 许可证

MIT License - 详见 [LICENSE](../LICENSE)

---

## 👥 联系方式

如有问题，请联系开发团队或查看 [项目文档](../项目文档/)

---

**Built with ❤️ using React + Tailwind CSS**