篮球培训教学反馈系统

项目简介

这是一个基于AI的篮球培训教学反馈系统，帮助教练快速生成学员的训练周报PDF，并自动推送到企业微信家长群。

主要功能

• 智能表格管理：创建和管理学员信息表格
• AI内容扩写：使用DeepSeek AI将简短的教学记录扩写成专业的训练周报
• PDF生成：自动生成带有Logo水印的PDF周报
• 批量处理：异步处理多个学员的周报生成
• 预览与编辑：支持预览PDF，不满意可重新生成
• 企业微信集成：自动推送PDF到对应的家长群
• Web界面：简洁美观的前端UI，方便操作

技术栈

• 后端：Python + Flask
• AI：DeepSeek API
• PDF生成：ReportLab
• 表格服务：腾讯文档API
• 企业微信：企微机器人API
• 前端：HTML + CSS + JavaScript

安装与运行

方式一：使用启动脚本（推荐）

1. 双击运行 start.bat
2. 系统会自动创建虚拟环境、安装依赖并启动服务
3. 在浏览器中访问 http://localhost:9000

方式二：手动安装

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 运行应用
python app.py

配置说明

环境变量（.env文件）

CLIENT=你的腾讯文档CLIENT_ID
TOKEN=你的腾讯文档TOKEN
OPENID=你的腾讯文档OPENID
DEEPSEEK_API_KEY=你的DeepSeek API密钥

系统配置（config.json）

• table_name: 表格名称
• trigger_keyword: 触发生成周报的关键词
• qiwx_token: 企微机器人token
• guid: 企微guid
• webhook_secret: Webhook密钥

使用流程

1. 初始化配置

1. 在"配置管理"页面设置表格名称和触发关键词
2. 点击"初始化表格"创建学员信息表
3. 系统会自动生成表格并返回访问链接

2. 填写学员信息

在腾讯文档的表格中填写以下信息：

• 姓名
• 班级
• 学习亮点
• 本周所学内容
• 下周学习计划
• 教练
• 对应发送群名称

3. 生成周报

方式一：Web界面手动触发

1. 在"生成周报"页面点击"开始生成PDF"
2. 等待AI扩写和PDF生成完成
3. 在预览界面查看生成的PDF

方式二：企业微信关键词触发

1. 在文件传输助手发送关键词（如"发送教学反馈"）
2. 系统自动读取表格并生成PDF
3. 通过预览链接查看结果

4. 预览与发送

1. 系统生成PDF后会显示预览列表
2. 点击"查看PDF"可以预览文档
3. 对不满意的PDF可以点击"重新生成"
4. 选择要发送的PDF，点击"发送选中的PDF"
5. 系统自动发送到对应的企业微信群

文件结构

Basketball-training/
├── app.py                  # 主应用入口
├── config.json            # 系统配置
├── .env                   # 环境变量
├── requirements.txt       # Python依赖
├── start.bat             # Windows启动脚本
├── README.md             # 项目文档
│
├── services/             # 服务层
│   ├── __init__.py
│   ├── table_service.py  # 腾讯文档服务
│   ├── ai_service.py     # AI扩写服务
│   ├── pdf_service.py    # PDF生成服务
│   └── wechat_service.py # 企业微信服务
│
├── utils/                # 工具层
│   ├── __init__.py
│   └── config_manager.py # 配置管理器
│
├── templates/            # 前端模板
│   └── index.html
│
├── static/               # 静态资源
│   ├── css/
│   │   └── style.css
│   └── js/
│       └── app.js
│
├── logo/                 # Logo资源
│   └── 星启途体育logo.png
│
├── pdffiles/             # 生成的PDF文件
│
└── example/              # 示例文件
    └── 张毅的篮球训练周报.pdf

API接口

配置管理

• GET /api/config - 获取配置
• POST /api/config - 更新配置

表格管理

• POST /api/init-table - 初始化表格

PDF生成

• POST /api/generate-pdfs - 生成PDF
• GET /api/preview/<task_id> - 获取预览数据
• POST /api/regenerate-pdf - 重新生成单个PDF

PDF发送

• POST /api/send-pdfs - 发送选中的PDF

企业微信回调

• POST /api/data - 接收企业微信消息回调

部署说明

服务器部署

1. 上传代码到服务器（42.51.34.82）
2. 确保9000端口已开放
3. 安装Python 3.8+
4. 配置.env文件
5. 运行 python app.py

使用gunicorn部署（生产环境）

pip install gunicorn

# 启动服务（4个worker进程）
gunicorn -w 4 -b 0.0.0.0:9000 app:app

使用systemd管理（Linux）

创建服务文件 /etc/systemd/system/basketball-training.service:

[Unit]
Description=Basketball Training Feedback System
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/Basketball-training
Environment="PATH=/path/to/Basketball-training/venv/bin"
ExecStart=/path/to/Basketball-training/venv/bin/python app.py
Restart=always

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl start basketball-training
sudo systemctl enable basketball-training

注意事项

1. 中文字体：PDF生成需要系统中文字体支持，Windows系统会自动使用微软雅黑
2. 异步处理：使用异步方式处理多个学员，提高生成效率
3. 文件清理：未发送的PDF会自动清理，只保留成功发送的
4. 错误处理：生成失败的PDF支持单独重新生成
5. 企微回调：需要在企微机器人后台配置回调地址 http://your-server:9000/api/data

常见问题

Q: PDF中文显示乱码？

A: 确保系统已安装中文字体，Windows系统通常自带微软雅黑

Q: AI扩写失败？

A: 检查DeepSeek API密钥是否正确，网络是否正常

Q: 表格创建失败？

A: 检查腾讯文档的TOKEN是否过期

Q: 企业微信回调没反应？

A: 确认回调地址配置正确，webhook密钥匹配

更新日志

v1.0.0 (2026-07-30)

• ✅ 完成基础架构搭建
• ✅ 实现腾讯文档表格管理
• ✅ 集成DeepSeek AI扩写
• ✅ 实现PDF生成功能
• ✅ 开发Web前端界面
• ✅ 集成企业微信回调
• ✅ 支持异步批量处理
• ✅ 实现预览与重新生成功能

许可证

MIT License

联系方式

如有问题或建议，请联系开发团队。

---

星启途体育 - 让每一次训练都被记录，让每一份进步都被看见