BodyBalanceEvaluation/install/README.md

# 最小功能测试框架

## 概述

这是一个最小功能测试框架，用于验证 Flask + SocketIO + threading 技术栈在打包成 exe 后的可用性。

## 功能特性

- ✅ Flask HTTP 服务
- ✅ SocketIO WebSocket 服务  
- ✅ 强制使用 threading 异步模式
- ✅ 完整的前端测试界面
- ✅ HTTP API 测试
- ✅ WebSocket 连接测试
- ✅ 实时消息收发测试
- ✅ 系统信息显示

## 文件结构

```
install/
├── minimal_test_app.py      # 主应用文件
├── build_minimal.py         # 打包脚本
├── requirements_minimal.txt # 最小依赖列表
└── README.md               # 说明文档
```

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements_minimal.txt
```

### 2. 测试运行

```bash
python minimal_test_app.py
```

然后在浏览器中访问 http://localhost:5000 进行测试。

### 3. 打包成 exe

```bash
python build_minimal.py
```

### 4. 测试 exe

打包完成后，运行：

```bash
# 方式1：直接运行
dist/MinimalTestApp.exe

# 方式2：使用脚本
dist/start_test.bat
```

## 测试步骤

### HTTP API 测试

1. 点击「测试 HTTP API」按钮
2. 确认返回成功响应
3. 检查响应数据包含服务器信息

### WebSocket 测试

1. 页面加载时会自动连接 WebSocket
2. 确认连接状态显示为「已连接」
3. 点击「发送测试消息」
4. 确认能收到服务器响应
5. 测试断开和重连功能

### 系统信息检查

- 服务器时间：确认时间正确
- SocketIO模式：确认显示为 "threading"
- Flask版本：确认版本信息

## 技术要点

### 异步模式选择

```python
# 强制使用 threading 模式，避免 eventlet/gevent 依赖问题
socketio = SocketIO(
    app, 
    cors_allowed_origins='*', 
    async_mode='threading',  # 关键配置
    logger=False,
    engineio_logger=False
)
```

### 打包配置

```python
# PyInstaller 隐藏导入配置
hiddenimports=[
    'flask',
    'flask_socketio',
    'socketio',
    'engineio',
    'engineio.async_drivers.threading',  # 关键：threading 驱动
    'socketio.namespace',
    'dns',
    'dns.resolver',
    'dns.asyncresolver'
],
# 排除不需要的异步模式
excludes=[
    'eventlet',
    'gevent', 
    'gevent_uwsgi'
]
```

## 故障排除

### 常见问题

1. **"Invalid async_mode specified" 错误**
   - 确认已安装所有依赖
   - 检查 PyInstaller 隐藏导入配置
   - 确认排除了不需要的异步模式

2. **WebSocket 连接失败**
   - 检查防火墙设置
   - 确认端口 5000 未被占用
   - 查看控制台错误信息

3. **打包失败**
   - 确认 PyInstaller 版本兼容
   - 检查依赖版本冲突
   - 查看详细错误输出

### 调试模式

如需调试，可以修改 `minimal_test_app.py`：

```python
# 启用调试模式
socketio.run(
    app,
    host='0.0.0.0',
    port=5000,
    debug=True,  # 启用调试
    allow_unsafe_werkzeug=True
)
```

## 扩展指南

### 添加新功能

1. **新增 HTTP 路由**
   ```python
   @app.route('/api/new-endpoint')
   def new_endpoint():
       return jsonify({'message': 'New endpoint'})
   ```

2. **新增 SocketIO 事件**
   ```python
   @socketio.on('new_event')
   def handle_new_event(data):
       emit('response', {'status': 'received'})
   ```

3. **添加依赖**
   - 更新 `requirements_minimal.txt`
   - 更新 `build_minimal.py` 中的 `hiddenimports`
   - 重新测试打包

### 渐进式集成

按照以下顺序逐步添加业务功能：

1. ✅ 基础 Flask + SocketIO（当前阶段）
2. 🔄 添加数据库支持
3. 🔄 添加文件操作
4. 🔄 添加外部库依赖
5. 🔄 添加硬件设备支持

每个阶段都要确保打包和运行正常，出现问题时更容易定位。

## 版本信息

- Flask: 2.3.3
- Flask-SocketIO: 5.3.6
- PyInstaller: 6.1.0
- Python: 3.8+

## 许可证

MIT License