docs/QUICKSTART.md

# 快速开始指南

## 🚀 5分钟快速部署

### 步骤 1: 检查系统环境

```bash
# 检查Python版本（需要3.12+）
python3 --version

# 运行系统检查脚本
python3 test_setup.py
```

### 步骤 2: 安装依赖

```bash
pip install flask flask-cors
```

### 步骤 3: 准备数据

确保 `data` 目录在项目根目录下：

```
/data/zhangl/code/hf/point/
└── data/
    ├── 168_一年级上册/
    ├── 169_二年级上册/
    └── ...
```

### 步骤 4: 导入数据到数据库

```bash
# 导入所有书籍数据
python3 import_book_data.py data
```

预期输出：
```
📦 创建数据库: books.db
✅ 数据库结构创建成功
============================================================
开始批量导入书籍数据
============================================================
[1/30] 处理: 168_一年级上册
导入书籍信息成功: 168 - 一年级上册
导入 73 页内容，500 个片段成功
导入 12 个目录项成功
✅ 书籍 168_一年级上册 导入完成！
...
============================================================
批量导入完成！
成功: 30 本
失败: 0 本
============================================================
```

### 步骤 5: 启动应用

```bash
python3 app.py
```

预期输出：
```
🚀 交互式英语学习应用 - Flask 版本
============================================================
📦 创建数据库: books.db
✅ 数据库连接初始化成功
✅ 所有必要文件检查完成
✅ 应用初始化完成
🌐 监听端口: 7860
📁 工作目录: /data/zhangl/code/hf/point
🔧 调试模式: 关闭
============================================================
🎉 应用已准备就绪!
============================================================
```

### 步骤 6: 访问应用

在浏览器中打开：

- **书籍目录页**: http://localhost:7860/
- **阅读某本书**: http://localhost:7860/reader?book_id=168

## 📖 使用说明

### 书籍目录页面

1. 浏览所有可用的教材
2. 使用搜索框搜索教材
3. 点击教材卡片进入阅读页面

### 阅读页面

1. **点读功能**: 点击页面上的文本片段播放音频
2. **翻译切换**: 点击"翻译"按钮显示/隐藏中文翻译
3. **交互区域**: 点击"交互"按钮显示可点击区域
4. **目录导航**: 点击"目录"按钮查看章节目录
5. **搜索**: 点击"搜索"按钮在当前书籍中搜索内容
6. **设置**: 点击"设置"按钮调整播放速度等选项

### 键盘快捷键

- `←` / `→`: 翻页
- `Space`: 播放/暂停音频
- `T`: 切换翻译
- `I`: 切换交互区域
- `Esc`: 关闭弹出面板

## 🔧 常见问题

### 1. 数据导入失败

**问题**: `❌ 错误: 数据目录不存在: data`

**解决**: 
- 确保 `data` 目录在项目根目录下
- 检查目录中是否有书籍数据

### 2. 页面图片不显示

**问题**: 页面加载后图片不显示

**解决**:
- 检查 `data/xxx/images/` 目录是否存在
- 检查图片文件命名是否正确（格式：`page_001.jpg`）
- 查看浏览器控制台错误信息

### 3. 音频无法播放

**问题**: 点击文本片段后音频不播放

**解决**:
- 检查 `data/xxx/audios/` 目录是否存在
- 检查音频文件是否存在
- 确保浏览器支持 MP3 格式
- 检查浏览器是否允许自动播放音频

### 4. 端口被占用

**问题**: `Address already in use`

**解决**:
```bash
# 查找占用7860端口的进程
lsof -i:7860

# 或者使用其他端口
export PORT=8080
python3 app.py
```

### 5. 重新导入数据

如果需要重新导入所有数据：

```bash
# 删除数据库并重新导入
python3 import_book_data.py data --recreate
```

## 📊 数据统计

查看已导入的数据统计：

```bash
# 运行验证脚本
python3 import_book_data.py --verify-only
```

或者访问 API:
```bash
curl http://localhost:7860/api/v2/statistics
```

## 🔍 API 测试

### 获取书籍列表
```bash
curl http://localhost:7860/api/v2/books
```

### 获取书籍详情
```bash
curl http://localhost:7860/api/v2/books/168
```

### 获取页面内容
```bash
curl http://localhost:7860/api/v2/books/168/pages/2
```

### 搜索内容
```bash
curl "http://localhost:7860/api/v2/books/168/search?keyword=hello"
```

## 🎯 下一步

- 探索更多功能，如书签、搜索等
- 自定义样式和主题
- 添加更多教材数据
- 集成到现有系统

## 📚 更多文档

- [完整文档](README.md)
- [数据结构说明](BOOKS_API_DATA_文档.md)
- [API 文档](README.md#-api-接口)

## 💡 提示

1. **首次使用**: 建议先导入少量数据测试，确认无误后再导入全部数据
2. **开发调试**: 设置 `export FLASK_DEBUG=True` 启用调试模式
3. **性能优化**: 对于大量数据，考虑使用生产级 WSGI 服务器（如 Gunicorn）
4. **资源路径**: 所有资源路径都是相对于 `data` 目录的

## 🆘 获取帮助

如果遇到问题：

1. 查看日志文件: `logs/app.log`
2. 运行测试脚本: `python3 test_setup.py`
3. 查看浏览器控制台错误信息
4. 检查 README.md 中的故障排除部分

---

**祝您使用愉快！** 🎉