docs/QUICK_START.md

# 🚀 Flask 版本快速开始指南

## 📦 安装依赖

```bash
# 使用 Python 3.12（项目要求）
python3.12 -m pip install -r requirements.txt
```

## 🎯 启动应用

### 方式一：直接运行（推荐）
```bash
python3.12 app.py
```

### 方式二：使用启动脚本
```bash
chmod +x run_flask.sh
./run_flask.sh
```

### 方式三：生产环境（Gunicorn）
```bash
gunicorn -w 4 -b 0.0.0.0:7860 --timeout 120 app:app
```

## 🌐 访问应用

启动后访问：
- **主页**: http://localhost:7860/
- **健康检查**: http://localhost:7860/api/health
- **书籍信息**: http://localhost:7860/api/book/info

## 🧪 测试应用

```bash
python3.12 test_flask_app.py
```

## 🔑 新增功能

### 1. API 端点

| 端点 | 方法 | 描述 |
|------|------|------|
| `/api/health` | GET | 健康检查 |
| `/api/book/info` | GET | 获取书籍信息 |
| `/api/book/page/<num>` | GET | 获取指定页面 |
| `/api/progress/save` | POST | 保存学习进度 |
| `/api/progress/load` | GET | 加载学习进度 |
| `/api/search` | POST | 搜索内容 |
| `/api/stats` | GET | 学习统计 |
| `/api/opensearch/status` | GET | OpenSearch 状态 |

### 2. 测试 API

```bash
# 健康检查
curl http://localhost:7860/api/health

# 获取书籍信息
curl http://localhost:7860/api/book/info

# 搜索内容
curl -X POST http://localhost:7860/api/search \
  -H "Content-Type: application/json" \
  -d '{"keyword": "hello"}'

# 保存进度
curl -X POST http://localhost:7860/api/progress/save \
  -H "Content-Type: application/json" \
  -d '{"current_page": 5, "bookmarks": [1,3,5]}'

# 加载进度
curl http://localhost:7860/api/progress/load

# 获取统计
curl http://localhost:7860/api/stats
```

## 🔍 OpenSearch 集成

### 配置 OpenSearch

编辑 `config.py` 或设置环境变量：

```bash
export OPENSEARCH_HOST=192.168.3.33
export OPENSEARCH_PORT=9200
```

### 使用 OpenSearch 客户端

```python
from opensearch_client import OpenSearchClient, initialize_learning_index

# 创建客户端
client = OpenSearchClient(host='192.168.3.33', port=9200)

# 检查连接
if client.is_connected():
    print("✅ 连接成功")
    
    # 初始化索引
    initialize_learning_index(client)
    
    # 索引文档
    doc = {
        'type': 'word',
        'english': 'hello',
        'chinese': '你好',
        'page_num': 1
    }
    client.index_document('english_learning_content', 'word_hello', doc)
    
    # 搜索
    results = client.full_text_search(
        'english_learning_content', 
        'hello', 
        ['english', 'chinese']
    )
```

## 📝 与原版本对比

| 功能 | 原版本 | Flask 版本 |
|------|--------|-----------|
| 静态文件服务 | ✅ | ✅ |
| RESTful API | ❌ | ✅ |
| 学习进度保存 | ❌ | ✅ |
| 搜索功能 | ❌ | ✅ |
| OpenSearch 集成 | ❌ | ✅ |
| 会话管理 | ❌ | ✅ |
| 日志记录 | 基础 | 完善 |
| 生产环境支持 | ❌ | ✅ |
| 热重载 | ❌ | ✅ |

## 🔙 回滚到原版本

如果需要回到原版本：

```bash
cp app.py.backup app.py
python3.12 app.py
```

## 📚 更多文档

- **完整迁移指南**: 查看 `FLASK_MIGRATION.md`
- **端口管理**: 查看 `PORT_MANAGEMENT.md`
- **配置选项**: 查看 `config.py`

## 🆘 常见问题

### Q: 端口被占用？
```bash
./kill_port.sh 7860
```

### Q: 依赖安装失败？
```bash
# 使用虚拟环境
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### Q: OpenSearch 连接失败？
检查 OpenSearch 服务是否运行：
```bash
curl http://192.168.3.33:9200
```

## 🎉 开始使用

现在您已经完成了 Flask 重构！享受更强大的功能吧！

```bash
python3.12 app.py
# 访问 http://localhost:7860
```

---
**Python 版本**: 3.12  
**Flask 版本**: 3.0.0  
**最后更新**: 2025-10-16