AlphaFuturesPro/docs/开发文档/后端服务开发文档.md

# 后端服务开发文档

## 1. 项目结构

```
backend/
├── src/
│   ├── api/            # API路由
│   ├── config/         # 配置管理
│   ├── services/       # 业务服务
│   │   └── datasource/ # 数据源实现
│   ├── app.ts          # 应用入口
│   └── index.ts        # 导出模块
├── python_service/     # Python TQAPI服务
│   ├── api/            # Python API路由
│   ├── main.py         # Python服务入口
│   └── tqapi_service.py # TQAPI服务实现
├── config.json         # 配置文件
├── package.json        # Node.js依赖
└── tsconfig.json       # TypeScript配置
```

## 2. 核心功能

### 2.1 数据源管理

- **TQDataSource**：使用Python服务获取天勤量化数据
- **MockDataSource**：提供模拟数据，用于测试
- **DataSourceFactory**：数据源工厂，负责创建和管理数据源实例

### 2.2 Python TQAPI服务

- **功能**：与天勤量化SDK交互，提供期货市场数据
- **API端点**：合约列表、合约详情、K线数据、Tick数据
- **端口配置**：支持动态端口配置

### 2.3 集成服务

- **自动启动**：当使用TQSDK数据源时，自动启动Python服务
- **端口同步**：确保Python服务端口与Node.js连接端口一致

## 3. 关键修改

### 3.1 Python服务管理器修改

**文件**：`backend/src/services/datasource/PythonServiceManager.ts`

**修改内容**：
- 从配置中读取 `pythonPort`，默认8000
- 启动Python服务时传递端口参数
- 确保Python服务与Node.js服务端口一致

**关键代码**：
```typescript
// 从配置中读取端口，默认8000
const port = config.dataSource?.tqsdk?.pythonPort || 8000;

// 启动Python服务，传递端口参数
this.pythonProcess = spawn('python', [pythonServicePath, '--port', port.toString()], {
  cwd: path.join(__dirname, '../../../python_service'),
  stdio: 'inherit',
  shell: true
});
```

### 3.2 Python服务入口修改

**文件**：`backend/python_service/main.py`

**修改内容**：
- 添加命令行参数解析
- 支持通过 `--port` 参数设置服务端口
- 默认端口为8000

**关键代码**：
```python
# 解析命令行参数
parser = argparse.ArgumentParser(description="天勤量化 API 服务")
parser.add_argument("--port", type=int, default=8000, help="服务端口，默认8000")
parser.add_argument("--host", type=str, default="0.0.0.0", help="服务主机，默认0.0.0.0")
args = parser.parse_args()

# 启动服务
print(f"启动天勤量化 API 服务，监听 {args.host}:{args.port}")
uvicorn.run(app, host=args.host, port=args.port)
```

### 3.3 TQDataSource修改

**文件**：`backend/src/services/datasource/TQDataSource.ts`

**修改内容**：
- 从配置中读取 `pythonPort`，默认8000
- 动态构建Python服务URL，使用配置的端口
- 确保与Python服务端口一致

**关键代码**：
```typescript
// 从配置中读取端口，默认8000
const port = config.pythonPort || 8000;
this.config = {
  // 其他配置...
  pythonServiceUrl: config.pythonServiceUrl || `http://127.0.0.1:${port}/api`
};
```

### 3.4 应用启动逻辑修改

**文件**：`backend/src/app.ts`

**修改内容**：
- 在启动时检查配置，自动启动Python服务
- 确保服务启动顺序正确

**关键代码**：
```typescript
// 启动前检查是否需要启动Python TQAPI服务
async function startServer() {
  try {
    // 检查配置，是否使用TQSDK数据源
    if (config.dataSource?.defaultDataSource === 'tqsdk' || 
        (config.dataSource?.tqsdk && config.dataSource.tqsdk.enabled)) {
      console.log('检测到使用TQSDK数据源，准备启动Python服务...');
      const pythonStarted = await pythonServiceManager.start();
      if (!pythonStarted) {
        console.warn('Python服务启动失败，可能会影响TQSDK数据获取');
      }
    }

    // 启动Express服务器
    app.listen(port, () => {
      console.log(`服务器运行在 http://localhost:${port}`);
    });
  } catch (error) {
    console.error('启动服务器时出错:', error);
  }
}
```

## 4. 配置说明

### 4.1 配置文件结构

**文件**：`config.json`

```json
{
  "server": {
    "port": 3007
  },
  "dataSource": {
    "tqsdk": {
      "enabled": true,
      "username": "你的天勤账号",
      "password": "你的天勤密码",
      "timeout": 30000,
      "retries": 3,
      "maxConnections": 5,
      "pythonPort": 8000
    },
    "defaultDataSource": "tqsdk"
  }
}
```

### 4.2 关键配置项

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `server.port` | number | 3007 | Node.js服务端口 |
| `dataSource.tqsdk.enabled` | boolean | true | 是否启用TQSDK数据源 |
| `dataSource.tqsdk.username` | string | "" | 天勤量化账号 |
| `dataSource.tqsdk.password` | string | "" | 天勤量化密码 |
| `dataSource.tqsdk.pythonPort` | number | 8000 | Python服务端口 |
| `dataSource.defaultDataSource` | string | "tqsdk" | 默认数据源 |

## 5. 启动方法

### 5.1 依赖安装

#### Node.js 依赖

在 `backend` 目录下执行：

```bash
npm install
```

#### Python 依赖

在 `backend/python_service` 目录下执行：

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

### 5.2 启动服务

#### 方法一：使用启动脚本

执行 `start_services.bat` 脚本：

```bash
./start_services.bat
```

#### 方法二：手动启动

1. **启动 Node.js 服务**：
   ```bash
   cd backend
   npm run dev
   ```

2. **启动 Python 服务**（自动启动，无需手动）：
   - 当使用TQSDK数据源时，Node.js服务会自动启动Python服务

### 5.3 服务验证

- **Node.js 服务**：访问 http://localhost:3007/health
- **Python TQAPI 服务**：访问 http://localhost:8000/health

## 6. 注意事项

### 6.1 端口配置

- **端口一致性**：确保 `config.json` 中的 `pythonPort` 与 Python 服务实际使用的端口一致
- **端口冲突**：避免使用已被其他程序占用的端口
- **默认端口**：如果未配置 `pythonPort`，默认使用8000

### 6.2 依赖管理

- **Python版本**：建议使用 Python 3.7+ 
- **Node.js版本**：建议使用 Node.js 16+ 
- **依赖更新**：定期更新依赖包，确保安全性和稳定性

### 6.3 数据源配置

- **天勤账号**：确保天勤量化账号正确且已激活
- **网络连接**：确保网络连接正常，能够访问天勤量化服务器
- **备用方案**：当TQSDK数据源不可用时，可切换到MockDataSource

### 6.4 错误处理

- **Python服务启动失败**：检查Python是否安装，依赖是否完整
- **TQSDK连接失败**：检查网络连接，账号密码是否正确
- **数据获取失败**：检查合约代码是否正确，网络连接是否稳定

### 6.5 性能优化

- **连接池**：合理设置 `maxConnections`，避免连接过多
- **超时设置**：设置合理的 `timeout`，避免请求等待时间过长
- **重试机制**：通过 `retries` 配置，提高数据获取的可靠性

## 7. 故障排查

### 7.1 常见问题

#### 问题1：Python服务启动失败

**症状**：
- Node.js服务启动时提示Python服务启动失败
- 日志显示Python相关错误

**解决方案**：
- 检查Python是否安装：`python --version`
- 检查Python依赖：`pip install -r requirements.txt`
- 检查端口是否被占用：`netstat -ano | findstr :8000`

#### 问题2：TQSDK连接失败

**症状**：
- 日志显示"连接到天勤服务器失败"
- 数据获取API返回错误

**解决方案**：
- 检查天勤账号密码是否正确
- 检查网络连接是否正常
- 尝试手动登录天勤量化客户端，确认账号状态

#### 问题3：端口不一致

**症状**：
- 日志显示"fetch failed"错误
- 提示连接到错误端口

**解决方案**：
- 检查 `config.json` 中的 `pythonPort` 配置
- 确保Python服务实际使用的端口与配置一致
- 重启服务，确保配置生效

### 7.2 日志查看

- **Node.js日志**：在启动Node.js服务的终端中查看
- **Python日志**：在启动Python服务的终端中查看
- **API日志**：通过访问API端点，查看返回结果和错误信息

## 8. 开发建议

### 8.1 代码规范

- **TypeScript**：使用TypeScript编写Node.js代码，提高代码质量
- **ESLint**：使用ESLint检查代码风格，确保代码一致性
- **注释**：为关键代码添加注释，提高可维护性

### 8.2 测试策略

- **单元测试**：为核心功能编写单元测试
- **集成测试**：测试不同组件之间的集成
- **Mock数据**：使用MockDataSource进行测试，避免依赖外部服务

### 8.3 部署建议

- **环境变量**：使用环境变量存储敏感信息
- **配置管理**：使用配置文件管理不同环境的配置
- **监控告警**：添加监控和告警机制，及时发现问题

### 8.4 扩展性

- **模块化**：保持代码模块化，便于扩展和维护
- **接口设计**：设计清晰的接口，便于添加新功能
- **数据源扩展**：通过DataSourceFactory，可以方便地添加新的数据源实现

## 9. 总结

本开发文档提供了AI期货分析系统后端服务的详细说明，包括：

1. **项目结构**：清晰的目录结构和文件组织
2. **核心功能**：数据源管理、Python TQAPI服务和集成服务
3. **关键修改**：端口配置、服务集成和启动逻辑
4. **配置说明**：详细的配置项和默认值
5. **启动方法**：多种启动方式和服务验证
6. **注意事项**：端口配置、依赖管理和错误处理
7. **故障排查**：常见问题和解决方案
8. **开发建议**：代码规范、测试策略和部署建议

通过本文档，开发人员可以快速了解系统架构，掌握开发和部署流程，确保系统的稳定性和可靠性。