Spaces:
Sleeping
Sleeping
| title: 交互式学习平台 | |
| emoji: 📚 | |
| colorFrom: blue | |
| colorTo: purple | |
| sdk: docker | |
| app_port: 7860 | |
| pinned: false | |
| # 交互式英语学习平台 | |
| 基于 data 数据结构的交互式英语学习应用，支持点读、音频播放、翻译显示等功能。 | |
| ## 📋 功能特性 | |
| ### 书籍目录页面 | |
| - 📚 显示所有可用教材 | |
| - 🔍 搜索教材名称和分类 | |
| - 📊 显示统计信息（教材数、页面数、内容片段数等） | |
| - 🎨 精美的卡片式布局 | |
| ### 阅读页面 | |
| - 📖 交互式点读功能 | |
| - 🔊 音频播放控制 | |
| - 🌐 中英文翻译切换 | |
| - 📑 章节目录导航 | |
| - 🔖 书签功能 | |
| - 🔍 全文搜索 | |
| - ⚙️ 个性化设置（播放速度、自动翻译等） | |
| - ⌨️ 键盘快捷键支持 | |
| ## 🚀 快速开始 | |
| ### 1. 环境要求 | |
| - Python 3.12 | |
| - SQLite 3 | |
| - 现代浏览器（Chrome、Firefox、Safari、Edge） | |
| ### 2. 安装依赖 | |
| ```bash | |
| pip install flask flask-cors | |
| ``` | |
| ### 3. 准备数据 | |
| 将 `data` 目录放置在项目根目录下： | |
| ``` | |
| /data/zhangl/code/hf/point/ | |
| ├── data/ # 教材数据目录 | |
| │ ├── 168_一年级上册/ | |
| │ │ ├── book_info.json | |
| │ │ ├── pages.json | |
| │ │ ├── catalog.json | |
| │ │ ├── images/ | |
| │ │ └── audios/ | |
| │ ├── 169_二年级上册/ | |
| │ └── ... | |
| ├── app.py | |
| ├── import_book_data.py | |
| └── ... | |
| ``` | |
| ### 4. 导入数据到数据库 | |
| ```bash | |
| # 首次导入（会自动创建数据库） | |
| python3 import_book_data.py data | |
| # 重新导入所有数据（删除现有数据库） | |
| python3 import_book_data.py data --recreate | |
| # 仅验证数据 | |
| python3 import_book_data.py --verify-only | |
| ``` | |
| 导入选项： | |
| - `data_dir`: 数据目录路径（默认：data） | |
| - `--db`: 数据库文件路径（默认：books.db） | |
| - `--schema`: Schema 文件路径（默认：db_schema.sql） | |
| - `--recreate`: 删除现有数据库并重新创建 | |
| - `--verify-only`: 仅验证数据，不导入 | |
| ### 5. 启动应用 | |
| ```bash | |
| python3 app.py | |
| ``` | |
| 应用将在 `http://0.0.0.0:7860` 启动。 | |
| 访问地址： | |
| - 书籍目录：`http://localhost:7860/` | |
| - 阅读页面：`http://localhost:7860/reader?book_id=168` | |
| ## 📁 项目结构 | |
| ``` | |
| /data/zhangl/code/hf/point/ | |
| ├── data/ # 教材数据目录 | |
| ├── static/ | |
| │ ├── css/ | |
| │ │ ├── style.css # 主样式文件 | |
| │ │ ├── inter.css # Inter 字体 | |
| │ │ └── all.min.css # Font Awesome 图标 | |
| │ └── js/ | |
| │ ├── catalog.js # 书籍目录页面逻辑 | |
| │ └── reader.js # 阅读页面逻辑 | |
| ├── app.py # Flask 应用主文件 | |
| ├── db_manager.py # 数据库管理器 | |
| ├── import_book_data.py # 数据导入脚本 | |
| ├── db_schema.sql # 数据库结构定义 | |
| ├── index.html # 书籍目录页面 | |
| ├── reader.html # 阅读页面 | |
| ├── books.db # SQLite 数据库（自动生成） | |
| └── README.md | |
| ``` | |
| ## 🗄️ 数据库结构 | |
| ### books 表 | |
| 存储书籍的基本信息： | |
| - `market_book_id`: 书籍ID（主键） | |
| - `market_book_name`: 书籍名称 | |
| - `market_book_cover`: 封面图片路径 | |
| - `max_page`: 最大页码 | |
| - `grade_id`: 年级ID | |
| - `reel_id`: 学期ID（1=上册，2=下册） | |
| - 等等... | |
| ### pages 表 | |
| 存储页面信息： | |
| - `page_id`: 页面ID（主键） | |
| - `book_id`: 所属书籍ID | |
| - `page_number`: 页码 | |
| - `origin_img_url`: 原始图片路径 | |
| - `encrypt_img_url`: 加密图片路径 | |
| ### pieces 表 | |
| 存储页面内容片段： | |
| - `piece_id`: 片段ID（主键） | |
| - `page_id`: 所属页面ID | |
| - `original`: 原文（英文） | |
| - `translation`: 译文（中文） | |
| - `origin_sound_url`: 音频路径 | |
| - `duration`: 音频时长 | |
| - `coordinate_x/y/width/height`: 坐标信息 | |
| - 等等... | |
| ### catalogs 表 | |
| 存储书籍目录结构： | |
| - `catalog_id`: 目录项ID（主键） | |
| - `book_id`: 所属书籍ID | |
| - `catalog_name`: 目录名称（英文） | |
| - `catalog_name_cn`: 目录名称（中文） | |
| - `start_page/end_page`: 起止页码 | |
| - `parent_id`: 父级目录ID（支持树形结构） | |
| ### pieces_fts 表 | |
| 全文搜索索引（FTS5）： | |
| - 支持在 `original` 和 `translation` 字段中快速搜索 | |
| ## 🔌 API 接口 | |
| ### 书籍相关 | |
| #### 获取所有书籍列表 | |
| ``` | |
| GET /api/v2/books?grade_id=40 | |
| ``` | |
| #### 获取书籍详情 | |
| ``` | |
| GET /api/v2/books/{book_id} | |
| ``` | |
| #### 获取书籍页面列表 | |
| ``` | |
| GET /api/v2/books/{book_id}/pages | |
| ``` | |
| #### 获取书籍目录结构 | |
| ``` | |
| GET /api/v2/books/{book_id}/catalog | |
| ``` | |
| #### 获取页面内容 | |
| ``` | |
| GET /api/v2/books/{book_id}/pages/{page_number} | |
| ``` | |
| ### 搜索相关 | |
| #### 在书籍中搜索 | |
| ``` | |
| GET /api/v2/books/{book_id}/search?keyword=hello&limit=20 | |
| ``` | |
| #### 全局搜索 | |
| ``` | |
| GET /api/v2/search?keyword=hello&limit=50 | |
| ``` | |
| ### 统计相关 | |
| #### 获取书籍统计信息 | |
| ``` | |
| GET /api/v2/books/{book_id}/statistics | |
| ``` | |
| #### 获取整体统计信息 | |
| ``` | |
| GET /api/v2/statistics | |
| ``` | |
| ## ⌨️ 键盘快捷键 | |
| 在阅读页面中： | |
| - `←` / `→`: 上一页 / 下一页 | |
| - `Space`: 播放/暂停音频 | |
| - `T`: 切换翻译显示 | |
| - `I`: 切换交互区域显示 | |
| - `Esc`: 关闭弹出面板 | |
| ## 🎨 功能亮点 | |
| 1. **按需加载**: 页面内容按需加载，提高性能 | |
| 2. **全文搜索**: 使用 SQLite FTS5 实现高效全文搜索 | |
| 3. **响应式设计**: 自适应不同屏幕尺寸 | |
| 4. **交互式点读**: 点击文本片段播放对应音频 | |
| 5. **坐标系统**: 使用相对坐标，适配不同分辨率 | |
| 6. **目录导航**: 支持章节目录快速跳转 | |
| 7. **本地资源**: 支持从本地 data 目录加载资源 | |
| ## 🔧 开发调试 | |
| ### 启用调试模式 | |
| ```bash | |
| export FLASK_DEBUG=True | |
| python3 app.py | |
| ``` | |
| ### 查看日志 | |
| 应用日志存储在 `logs/app.log` | |
| ### 数据库操作 | |
| 使用 `db_manager.py` 提供的数据库管理器： | |
| ```python | |
| from db_manager import get_db_instance | |
| db = get_db_instance('books.db') | |
| # 获取所有书籍 | |
| books = db.get_all_books() | |
| # 搜索内容 | |
| results = db.search_content(book_id=168, keyword='hello', limit=20) | |
| # 获取统计信息 | |
| stats = db.get_overall_statistics() | |
| ``` | |
| ## 📝 数据格式说明 | |
| ### 坐标系统 | |
| 文本片段的坐标使用相对坐标（0-1范围）： | |
| ```json | |
| { | |
| "coordinate": { | |
| "x": 0.0482, // 左上角X坐标（相对于图片宽度） | |
| "y": 0.0357, // 左上角Y坐标（相对于图片高度） | |
| "width": 0.3195, // 宽度（相对于图片宽度） | |
| "height": 0.0982 // 高度（相对于图片高度） | |
| } | |
| } | |
| ``` | |
| ### 资源路径 | |
| 资源路径采用相对路径格式： | |
| ``` | |
| 168_一年级上册/images/page_001.jpg | |
| 168_一年级上册/audios/page_002_piece_00.mp3 | |
| ``` | |
| 实际访问时会自动拼接为： | |
| ``` | |
| data/168_一年级上册/images/page_001.jpg | |
| data/168_一年级上册/audios/page_002_piece_00.mp3 | |
| ``` | |
| ## 🐛 故障排除 | |
| ### 数据库导入失败 | |
| - 检查 data 目录是否存在 | |
| - 确保每个书籍目录包含 book_info.json、pages.json | |
| - 检查 db_schema.sql 文件是否存在 | |
| ### 页面加载失败 | |
| - 检查数据库是否正确导入 | |
| - 查看浏览器控制台是否有错误 | |
| - 检查 data 目录下的资源文件是否完整 | |
| ### 音频播放失败 | |
| - 检查音频文件路径是否正确 | |
| - 确保浏览器支持 MP3 格式 | |
| - 查看浏览器控制台错误信息 | |
| ## 📄 许可证 | |
| 本项目仅供学习和研究使用。 | |
| ## 👥 贡献 | |
| 欢迎提交 Issue 和 Pull Request。 | |
| ## 📞 联系方式 | |
| 如有问题或建议，请联系开发团队。 | |
| --- | |
| **版本**: v2.0.0 | |
| **更新日期**: 2025-10-17 | |
| **Python版本**: 3.12 | |
| **数据库**: SQLite 3 | |