QTradeProgram/软件设计说明书.md

# QTradeProgram - 大单检测程序 软件设计说明书

## 一、软件概述

### 1.1 软件名称
**QTradeProgram - 大单检测程序**

### 1.2 软件版本
**V1.0**

### 1.3 开发目的
本软件旨在为金融投资领域提供专业的股票大单实时监控解决方案，帮助投资者及时发现市场中的大额交易行为，为投资决策提供参考依据。

### 1.4 适用范围
- 股票投资者
- 金融机构
- 量化交易团队
- 金融数据分析师

## 二、系统架构设计

### 2.1 总体架构
```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   用户界面层     │    │   业务逻辑层     │    │   数据访问层     │
│   (UI Layer)    │◄──►│ (Business Layer) │◄──►│  (Data Layer)   │
│                 │    │                 │    │                 │
│ • QMainwindow   │    │ • 订单处理       │    │ • Futu API      │
│ • 大单查看器     │    │ • 大单检测       │    │ • 配置文件      │
│ • 呼吸灯提示     │    │ • 日志管理       │    │ • 数据缓存      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

### 2.2 模块划分

#### 2.2.1 用户界面模块 (QMainwindow/)
- **职责**: 提供图形用户界面，处理用户交互
- **核心类**: 
  - `QMainwindow`: 主窗口类
  - `QBigOrderViewer`: 大单查看器
  - `QBreathingLight`: 呼吸灯提示控件

#### 2.2.2 业务逻辑模块 (Sqbase/)
- **职责**: 实现核心业务逻辑，包括大单检测、数据处理等
- **核心类**:
  - `QOrderProcessor`: 订单处理器
  - `QBigOrderManager`: 大单管理器
  - `OrderBookParser`: 订单簿解析器

#### 2.2.3 数据访问模块 (FTAPI/)
- **职责**: 封装外部API，提供数据访问接口
- **核心类**:
  - `CFTInterface`: Futu API接口封装
  - `QDataAcquisition`: 数据采集器

#### 2.2.4 工具模块 (Utilities/)
- **职责**: 提供通用工具和辅助功能
- **核心类**:
  - `QLogManager`: 日志管理器
  - `ObjectPool`: 对象池

## 三、详细设计

### 3.1 核心算法设计

#### 3.1.1 大单检测算法
```cpp
算法名称: 基于阈值的大单检测算法
输入: OrderBookData (订单簿数据), threshold (阈值)
输出: QVector<BigOrderInfo> (大单信息列表)

算法步骤:
1. 遍历买盘订单数据
2. 对每个订单条目，比较成交量与预设阈值
3. 如果成交量 ≥ 阈值，标记为大单并记录信息
4. 遍历卖盘订单数据，重复步骤2-3
5. 返回所有检测到的大单信息
```

#### 3.1.2 性能优化算法
```cpp
算法名称: 缓存优化算法
输入: cacheKey (缓存键), orderData (订单数据)
输出: QVector<BigOrderInfo> (大单信息列表)

算法步骤:
1. 根据股票代码和时间生成缓存键
2. 在缓存中查找是否存在该键对应的结果
3. 如果找到，直接返回缓存结果
4. 如果未找到，执行大单检测算法
5. 将检测结果存入缓存
6. 维护缓存大小，淘汰最久未使用的数据
```

### 3.2 数据结构设计

#### 3.2.1 核心数据结构
```cpp
// 订单簿条目
struct OrderBookEntry {
    double price;           // 价格
    double volume;          // 成交量
    int orderCount;         // 订单数量
    QString code;           // 股票代码
    QVector<OrderDetail> details; // 订单详情
};

// 大单信息
struct BigOrderInfo {
    double price;           // 价格
    double volume;          // 成交量
    long long orderId;      // 订单ID
    int nBigOrderType;      // 大单类型 (0:卖盘/1:买盘)
    bool isBigOrder;        // 是否为大单
    QString name;           // 股票名称
    QString code;           // 股票代码
    QString svrRecvTime;    // 交易所接收时间
};
```

#### 3.2.2 配置数据结构
```cpp
// 订阅项
struct ReplyCodeItem {
    QString code;           // 股票代码
    float quantity;         // 检测阈值
    QString name;           // 股票名称
};
```

### 3.3 类设计

#### 3.3.1 QOrderProcessor 类
```cpp
类名: QOrderProcessor
职责: 订单数据处理和大单检测

主要方法:
- processOrderBook(): 处理订单簿数据
- findExtremeOrders(): 检测大单
- findMaxVolumeItem(): 查找最大成交量订单
- setreplyCodeQuantity(): 设置阈值配置

主要属性:
- m_threadPool: 线程池
- m_replyCodeQuantity: 阈值配置映射
- m_orderCache: 订单缓存
```

#### 3.3.2 QBigOrderManager 类
```cpp
类名: QBigOrderManager
职责: 大单数据管理

设计模式: 单例模式

主要方法:
- addBigOrder(): 添加大单
- removeBigOrder(): 删除大单
- getBigOrders(): 获取大单列表
- clearAll(): 清空所有大单

主要属性:
- m_bigOrders: 大单列表
- m_orderMutex: 线程安全锁
```

### 3.4 接口设计

#### 3.4.1 信号槽接口
```cpp
// 大单检测信号
void maxOrderReady(BigOrderInfo bigOrderInfo);

// 处理状态信号
void processingStarted(const QString& code);
void processingFinished(const QString& code);
void errorOccurred(const QString& code, const QString& error);

// 大单管理信号
void bigOrderAdded(QSharedPointer<BigOrderInfo> order);
void bigOrderRemoved(const QString& code);
```

#### 3.4.2 配置接口
```cpp
// 阈值设置接口
void setreplyCodeQuantity(QMap<QString, float> CodeQuantity);

// 处理开关接口
void setProcessingEnabled(bool enabled);
void setJsonSaveEnabled(bool enabled);
```

## 四、技术实现

### 4.1 多线程处理

#### 4.1.1 线程池设计
```cpp
// 使用Qt线程池处理订单数据
QThreadPool m_threadPool;

// 异步处理订单数据
QtConcurrent::run(&m_threadPool, [this, stRsp]() {
    // 订单处理逻辑
});
```

#### 4.1.2 线程安全机制
```cpp
// 使用互斥锁保护共享数据
mutable QMutex m_dataMutex;
mutable QMutex m_cacheMutex;

// 使用QMutexLocker自动管理锁
QMutexLocker locker(&m_cacheMutex);
```

### 4.2 内存管理

#### 4.2.1 智能指针使用
```cpp
// 使用QSharedPointer管理对象生命周期
QList<QSharedPointer<BigOrderInfo>> m_bigOrders;
QList<QSharedPointer<ReplyCodeItem>> m_replyCodes;
```

#### 4.2.2 对象池设计
```cpp
// 使用对象池减少内存分配开销
ObjectPool<OrderBookData> m_dataPool;
ObjectPool<BigOrderInfo> m_orderPool;
```

### 4.3 性能优化

#### 4.3.1 缓存机制
```cpp
// 手动实现LRU缓存
mutable QMap<QString, QVector<BigOrderInfo>> m_orderCache;
mutable QList<QString> m_cacheKeys;
size_t m_cacheMaxSize = 200;
```

#### 4.3.2 算法优化
```cpp
// 使用高效的数据结构和算法
QMap<QString, float> m_replyCodeQuantity;  // O(log n)查找
QVector<OrderBookEntry> bids;              // 连续内存访问
```

## 五、数据流程设计

### 5.1 正常数据流程
```
Futu API推送数据 → CFTInterface::OnReply() → QOrderProcessor::processOrderBook()
    → OrderBookParser解析 → findExtremeOrders()检测大单 → emit maxOrderReady()
    → QBigOrderManager::addBigOrder() → 更新UI显示 → 呼吸灯提示
```

### 5.2 配置管理流程
```
用户界面操作 → 更新m_replyCodeQuantity → QOrderProcessor::setreplyCodeQuantity()
    → 保存到配置文件 → 实时生效
```

### 5.3 错误处理流程
```
API连接异常 → 触发错误信号 → 日志记录 → 用户界面提示
数据解析错误 → 异常捕获 → 错误日志 → 跳过当前数据处理
```

## 六、数据库设计

### 6.1 配置文件设计
```ini
# 订阅列表文件格式 (CSV)
股票代码,检测阈值(K),股票名称
00700,50,腾讯控股
00005,30,汇丰控股
```

### 6.2 日志文件设计
```text
[时间戳] [级别] [模块] [消息]
2025-11-11 10:00:00 INFO QOrderProcessor 开始处理股票00700
2025-11-11 10:00:01 WARNING QDataAcquisition API连接超时
```

## 七、安全设计

### 7.1 数据安全
- 所有敏感数据在内存中进行处理
- 配置文件使用明文存储，不包含敏感信息
- 网络通信使用Futu API的安全通道

### 7.2 程序安全
- 使用异常处理机制防止程序崩溃
- 内存访问使用智能指针防止内存泄漏
- 多线程操作使用互斥锁保证数据一致性

## 八、性能设计

### 8.1 响应时间
- 大单检测响应时间: < 100ms
- 界面更新响应时间: < 50ms
- 数据解析时间: < 10ms

### 8.2 并发处理
- 支持同时监控100+只股票
- 线程池最大线程数: 8
- 缓存容量: 200条记录

### 8.3 内存使用
- 初始内存占用: < 50MB
- 峰值内存占用: < 200MB
- 内存泄漏控制: 使用智能指针和对象池

## 九、扩展性设计

### 9.1 模块扩展
- 支持添加新的数据源
- 支持新的检测算法
- 支持新的输出格式

### 9.2 功能扩展
- 支持多种大单检测策略
- 支持历史数据回放
- 支持数据导出功能

## 十、测试设计

### 10.1 单元测试
- 大单检测算法测试
- 数据解析测试
- 缓存机制测试

### 10.2 集成测试
- 模块间接口测试
- 数据流程测试
- 性能压力测试

### 10.3 系统测试
- 完整功能测试
- 稳定性测试
- 兼容性测试

## 十一、部署设计

### 11.1 系统要求
- **操作系统**: Windows 10/11
- **运行环境**: .NET Framework 4.5+
- **依赖库**: Qt 5.9, Futu API, Protobuf

### 11.2 安装部署
1. 安装必要的运行环境
2. 复制程序文件到目标目录
3. 配置股票订阅列表
4. 启动应用程序

## 十二、维护设计

### 12.1 日志系统
- 分级日志记录 (INFO, WARNING, ERROR, FATAL)
- 日志文件自动轮转
- 日志查看器集成在界面中

### 12.2 错误处理
- 完善的异常捕获机制
- 友好的错误提示信息
- 自动恢复机制

---
**设计说明**: 本设计说明书详细描述了QTradeProgram大单检测程序的软件架构、模块设计、技术实现和性能优化等方面，为软件的开发、测试和维护提供了全面的技术指导。