docs/QUICK_START.md

🚀 Flask 版本快速开始指南

📦 安装依赖

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

🎯 启动应用

方式一：直接运行（推荐）

python3.12 app.py

方式二：使用启动脚本

chmod +x run_flask.sh
./run_flask.sh

方式三：生产环境（Gunicorn）

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

🧪 测试应用

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

# 健康检查
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 或设置环境变量：

export OPENSEARCH_HOST=192.168.3.33
export OPENSEARCH_PORT=9200

使用 OpenSearch 客户端

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 集成	❌	✅
会话管理	❌	✅
日志记录	基础	完善
生产环境支持	❌	✅
热重载	❌	✅

🔙 回滚到原版本

如果需要回到原版本：

cp app.py.backup app.py
python3.12 app.py

📚 更多文档

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

🆘 常见问题

Q: 端口被占用？

./kill_port.sh 7860

Q: 依赖安装失败？

# 使用虚拟环境
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Q: OpenSearch 连接失败？

检查 OpenSearch 服务是否运行：

curl http://192.168.3.33:9200

🎉 开始使用

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

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

---

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