README.md

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