Hugging Face's logo

Spaces:
eithney
/
point
Sleeping

App Files Community
1
point / README.md
eithney
code ref
e74eb63
preview code
|
Raw
History Blame Contribute Delete
7.64 kB
metadata 
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. 安装依赖 

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. 导入数据到数据库 

# 首次导入（会自动创建数据库）
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. 启动应用 

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 目录加载资源

🔧 开发调试

启用调试模式 

export FLASK_DEBUG=True
python3 app.py

查看日志

应用日志存储在 logs/app.log

数据库操作

使用 db_manager.py 提供的数据库管理器：

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范围）：

{
  "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