Spaces:
Sleeping
Sleeping
快速开始指南
🚀 5分钟快速部署
步骤 1: 检查系统环境
# 检查Python版本（需要3.12+）
python3 --version
# 运行系统检查脚本
python3 test_setup.py
步骤 2: 安装依赖
pip install flask flask-cors
步骤 3: 准备数据
确保 data 目录在项目根目录下：
/data/zhangl/code/hf/point/
└── data/
├── 168_一年级上册/
├── 169_二年级上册/
└── ...
步骤 4: 导入数据到数据库
# 导入所有书籍数据
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. 重新导入数据
如果需要重新导入所有数据：
# 删除数据库并重新导入
python3 import_book_data.py data --recreate
📊 数据统计
查看已导入的数据统计：
# 运行验证脚本
python3 import_book_data.py --verify-only
或者访问 API:
curl http://localhost:7860/api/v2/statistics
🔍 API 测试
获取书籍列表
curl http://localhost:7860/api/v2/books
获取书籍详情
curl http://localhost:7860/api/v2/books/168
获取页面内容
curl http://localhost:7860/api/v2/books/168/pages/2
搜索内容
curl "http://localhost:7860/api/v2/books/168/search?keyword=hello"
🎯 下一步
- 探索更多功能，如书签、搜索等
- 自定义样式和主题
- 添加更多教材数据
- 集成到现有系统
📚 更多文档
💡 提示
- 首次使用: 建议先导入少量数据测试，确认无误后再导入全部数据
- 开发调试: 设置
export FLASK_DEBUG=True启用调试模式 - 性能优化: 对于大量数据，考虑使用生产级 WSGI 服务器（如 Gunicorn）
- 资源路径: 所有资源路径都是相对于
data目录的
🆘 获取帮助
如果遇到问题：
- 查看日志文件:
logs/app.log - 运行测试脚本:
python3 test_setup.py - 查看浏览器控制台错误信息
- 检查 README.md 中的故障排除部分
祝您使用愉快！ 🎉