344 lines
11 KiB
Markdown
344 lines
11 KiB
Markdown
# QTradeProgram - 大单检测程序源代码提交指南
|
||
|
||
## 一、提交前准备工作
|
||
|
||
### 1.1 代码完整性校验
|
||
|
||
在提交源代码前，需确保代码文件完整覆盖程序核心功能模块，具体需包含以下内容：
|
||
|
||
|
||
|
||
* **核心模块文件**：
|
||
|
||
|
||
* 主窗口模块：`QMainwindow/QMainwindow.h`、`QMainwindow/QMainwindow.cpp`、UI 表单文件`ui_QMainwindow.h`
|
||
|
||
* 订单处理模块：`Sqbase/qorderprocessor.h`、`Sqbase/qorderprocessor.cpp`、`Sqbase/OrderBookParser.h`、`Sqbase/OrderBookParser.cpp`
|
||
|
||
* 大单管理模块：`Sqbase/qbigordermanager.h`、`Sqbase/qbigordermanager.cpp`
|
||
|
||
* 数据结构定义：`include/BZStruct.h`、`include/qeventbus.h`、`include/ObjectPool.h`、`include/tool.h`
|
||
|
||
* 程序入口：`main.cpp`
|
||
|
||
* **依赖配置文件**：
|
||
|
||
|
||
* 项目配置文件（如 Visual Studio 项目文件`.vcxproj`、Qt 工程文件`.pro`）
|
||
|
||
* 库文件依赖说明（`lib/`目录下第三方库清单及版本说明，如 Futu API、Qt 5.9 库）
|
||
|
||
* 编译配置说明（编译选项、宏定义、目标平台架构，如 x86/x64）
|
||
|
||
### 1.2 代码格式规范检查
|
||
|
||
需按照 C++ 代码规范统一格式，避免因格式混乱影响审查或协作效率，具体规范如下：
|
||
|
||
|
||
|
||
* **代码缩进**：采用 4 个空格缩进，禁止使用 Tab 键缩进
|
||
|
||
* **命名规则**：
|
||
|
||
|
||
* 类名：采用帕斯卡命名法（如`QOrderProcessor`、`QBigOrderManager`）
|
||
|
||
* 函数名：采用驼峰命名法（如`findExtremeOrders`、`cacheResult`）
|
||
|
||
* 成员变量：前缀`m_`+ 驼峰命名（如`m_threadPool`、`m_cacheHits`）
|
||
|
||
* 常量：全大写 + 下划线分隔（如`MAX_CACHE_SIZE`）
|
||
|
||
* **注释要求**：
|
||
|
||
|
||
* 类 / 函数头部：需包含功能描述、参数说明、返回值说明（如`qorderprocessor.h`中函数注释格式）
|
||
|
||
* 关键算法逻辑：在复杂代码块（如大单检测算法、LRU 缓存逻辑）旁添加行注释，解释核心逻辑
|
||
|
||
* 注释占比：源代码注释量不低于代码总量的 30%，确保可读性
|
||
|
||
### 1.3 冗余文件清理
|
||
|
||
提交前需删除无关冗余文件，避免占用提交空间或造成混淆，需清理的文件类型包括：
|
||
|
||
|
||
|
||
* 编译生成文件：`Debug/`、`Release/`目录下的`.obj`、`.exe`、`.dll`等编译产物
|
||
|
||
* 临时缓存文件：IDE 生成的`.suo`、`.user`、`.qmake.stash`等配置缓存
|
||
|
||
* 日志 / 测试文件：程序运行中生成的`logs/`目录日志文件、测试用例临时数据文件
|
||
|
||
## 二、不同场景下的提交方式
|
||
|
||
### 2.1 软件著作权登记提交（官方要求）
|
||
|
||
若用于软件著作权登记，需严格遵循中国版权保护中心的提交规范，具体流程如下：
|
||
|
||
#### 2.1.1 纸质版提交
|
||
|
||
|
||
|
||
* **材料准备**：
|
||
|
||
1. 源代码打印：需打印完整源代码，若代码总量超过 60 页，可仅打印前 30 页和后 30 页；若不足 60 页，需全部打印
|
||
|
||
2. 页码标注：每页代码右上角需标注 “第 X 页，共 Y 页”（如 “第 5 页，共 48 页”），页码需连续且清晰
|
||
|
||
3. 封面制作：为源代码打印件添加封面，封面需包含软件名称（`QTradeProgram-大单检测程序`）、版本号（V1.0）、著作权人名称、提交日期
|
||
|
||
* **装订要求**：
|
||
|
||
|
||
* 采用左侧胶装或线装，禁止使用订书机装订
|
||
|
||
* 纸张规格：统一使用 A4 纸，打印分辨率不低于 300dpi，文字清晰可辨
|
||
|
||
* **提交地址**：
|
||
|
||
|
||
* 现场提交：中国版权保护中心各地方受理大厅（如北京总部：北京市西城区天桥南大街 1 号）
|
||
|
||
* 邮寄提交：北京市西城区天桥南大街 1 号中国版权保护中心，邮编 100050，收件人注明 “软件登记部”
|
||
|
||
#### 2.1.2 电子版提交
|
||
|
||
|
||
|
||
* **文件格式**：
|
||
|
||
|
||
* 源代码需转换为 PDF 格式，单个 PDF 文件大小不超过 20MB；若代码量大，可分多个 PDF 文件（需按模块或页码拆分，如 “源代码 1-30 页.pdf”“源代码 31-60 页.pdf”）
|
||
|
||
* PDF 文件需添加书签，按模块分类（如 “主窗口模块”“订单处理模块”“数据结构定义”），便于审查时快速定位
|
||
|
||
* **上传路径**：
|
||
|
||
1. 登录中国版权保护中心官网（[http://www.ccopyright.com.cn/](http://www.ccopyright.com.cn/)），进入 “软件著作权登记” 系统
|
||
|
||
2. 选择 “在线提交”，填写软件基本信息（名称、版本号、开发完成日期等）
|
||
|
||
3. 在 “上传材料” 环节，选择 “源代码文档”，上传 PDF 格式的源代码文件
|
||
|
||
4. 确认上传文件无误后，提交申请并在线缴纳登记费用（200 元 / 件）
|
||
|
||
### 2.2 团队协作提交（Git 版本控制）
|
||
|
||
若用于团队开发协作，需通过 Git 版本控制系统提交，确保代码管理规范且可追溯，具体步骤如下：
|
||
|
||
#### 2.2.1 仓库初始化与分支管理
|
||
|
||
|
||
|
||
* **仓库创建**：
|
||
|
||
1. 在 Git 仓库平台（如 GitHub、GitLab、Gitee）创建项目仓库，命名为`QTradeProgram`
|
||
|
||
2. 初始化仓库结构，创建`README.md`文件，说明项目功能、技术栈、编译步骤
|
||
|
||
* **分支策略**：
|
||
|
||
|
||
* 主分支：`main`（仅用于存放稳定版本代码，禁止直接提交）
|
||
|
||
* 开发分支：`develop`（团队日常开发分支，用于整合各功能模块代码）
|
||
|
||
* 功能分支：`feature/xxx`（如`feature/order-detection`用于开发大单检测功能，`feature/cache-optimize`用于优化缓存逻辑）
|
||
|
||
* 修复分支：`bugfix/xxx`（如`bugfix/thread-safety`用于修复线程安全问题）
|
||
|
||
#### 2.2.2 代码提交步骤
|
||
|
||
|
||
|
||
1. **克隆仓库**：
|
||
|
||
|
||
|
||
```
|
||
git clone https://github.com/\[用户名]/QTradeProgram.git
|
||
|
||
cd QTradeProgram
|
||
```
|
||
|
||
|
||
|
||
1. **创建功能分支**：
|
||
|
||
|
||
|
||
```
|
||
git checkout develop
|
||
|
||
git pull origin develop
|
||
|
||
git checkout -b feature/\[功能名称]
|
||
```
|
||
|
||
|
||
|
||
1. **添加代码文件**：
|
||
|
||
将本地源代码文件按目录结构复制到仓库中，确保目录与代码结构一致（如`QMainwindow/`、`Sqbase/`、`include/`），然后执行：
|
||
|
||
|
||
|
||
```
|
||
git add . # 添加所有文件
|
||
|
||
\# 或单独添加指定文件
|
||
|
||
git add QMainwindow/QMainwindow.h QMainwindow/QMainwindow.cpp
|
||
|
||
git add Sqbase/qorderprocessor.h Sqbase/qorderprocessor.cpp
|
||
```
|
||
|
||
|
||
|
||
1. **提交代码**：
|
||
|
||
|
||
|
||
```
|
||
git commit -m "feat: 新增订单处理模块核心逻辑
|
||
|
||
\- 实现findExtremeOrders大单检测算法
|
||
|
||
\- 添加LRU缓存机制（cacheResult/getCachedResult方法）
|
||
|
||
\- 支持多线程处理订单数据（QtConcurrent+线程池）"
|
||
```
|
||
|
||
提交信息需遵循 “类型：描述” 格式，类型包括`feat`（新功能）、`fix`（修复 bug）、`docs`（文档更新）、`style`（代码格式调整）等，描述需简洁明了，说明提交内容的核心作用。
|
||
|
||
|
||
|
||
1. **推送分支与合并请求**：
|
||
|
||
|
||
|
||
```
|
||
git push origin feature/\[功能名称]
|
||
```
|
||
|
||
推送完成后，在 Git 平台发起 “合并请求”（Pull Request/Merge Request），将功能分支合并到`develop`分支，指定团队成员进行代码审查，审查通过后完成合并。
|
||
|
||
### 2.3 本地备份与归档提交
|
||
|
||
若用于本地备份或归档，需将源代码按版本打包，便于后续追溯或恢复，具体方式如下：
|
||
|
||
|
||
|
||
* **压缩打包**：
|
||
|
||
1. 按代码目录结构选中所有文件，使用压缩工具（如 WinRAR、7-Zip）压缩为 ZIP 或 RAR 格式
|
||
|
||
2. 压缩包命名格式：`QTradeProgram_V[版本号]_源代码_YYYYMMDD.zip`（如`QTradeProgram_V1.0_源代码_20251111.zip`）
|
||
|
||
* **归档存储**：
|
||
|
||
1. 建立本地归档目录，按版本号分文件夹存储（如`归档/20251111_V1.0/`）
|
||
|
||
2. 在归档文件夹中添加`版本说明.txt`，记录该版本的功能更新、代码修改点、编译环境要求（如 “V1.0 版本：完成大单检测核心功能，支持沪深 A 股数据监控，编译环境为 Visual Studio 2015+Qt 5.9”）
|
||
|
||
## 三、提交注意事项
|
||
|
||
### 3.1 知识产权保护
|
||
|
||
|
||
|
||
* 源代码中需添加版权声明，在每个头文件和源文件的开头添加著作权信息，格式如下：
|
||
|
||
|
||
|
||
```
|
||
/\*
|
||
|
||
 \* QTradeProgram - 大单检测程序
|
||
|
||
 \* 版权所有 (C) \[年份] \[著作权人名称]（如北京XX科技有限公司/张三）
|
||
|
||
 \* 本软件为原创开发，拥有完整著作权，未经授权禁止复制、传播或修改
|
||
|
||
 \*/
|
||
```
|
||
|
||
|
||
|
||
* 若使用第三方库（如 Futu API、Qt 框架），需在提交材料中添加 “第三方依赖声明”，说明第三方库的名称、版本、授权方式（如 “Futu API V3.0：遵循富途开放平台服务协议，用于获取股票行情数据；Qt 5.9：遵循 GPLv3 开源协议，用于图形界面开发”），避免侵权风险。
|
||
|
||
### 3.2 版本一致性保障
|
||
|
||
|
||
|
||
* 提交的源代码版本需与软件设计说明书、用户手册中描述的版本一致，确保 “源代码 - 文档 - 程序功能” 三者匹配，具体需核对：
|
||
|
||
|
||
* 版本号：源代码中`main.cpp`或配置文件中的版本定义，需与著作权申请表中的版本号（V1.0）一致
|
||
|
||
* 功能模块：源代码实现的功能（如多线程处理、LRU 缓存、大单检测算法），需与软件设计说明书中 “核心功能” 章节描述一致
|
||
|
||
* 数据结构：`BZStruct.h`中定义的`BigOrderInfo`、`OrderBookData`等结构，需与设计说明书中 “数据结构设计” 章节一致
|
||
|
||
### 3.3 安全性与合规性
|
||
|
||
|
||
|
||
* 源代码中禁止包含敏感信息，如 Futu API 的密钥（`apiKey`、`secret`）、用户隐私数据、服务器地址等，若需使用密钥，需在代码中通过配置文件读取（如`config/`目录下的配置文件），且配置文件中不存储明文密钥
|
||
|
||
* 若软件涉及金融数据（如股票行情、交易订单），需在提交材料中添加 “数据合规声明”，说明数据来源合法（如 “本软件使用的股票行情数据来自富途开放平台，已获得合法授权，仅用于非商业用途”），符合金融数据相关监管要求
|
||
|
||
## 四、常见问题与解决方案
|
||
|
||
### 4.1 代码页数不足 60 页，如何提交？
|
||
|
||
若源代码总页数不足 60 页（如仅 48 页），需将所有代码全部打印（纸质版）或完整转换为 PDF（电子版），不可仅打印部分页数；同时在提交材料中添加 “代码页数说明”，注明 “本软件源代码共 48 页，不足 60 页，已完整提交”。
|
||
|
||
### 4.2 Git 提交时出现代码冲突，如何处理？
|
||
|
||
当多人协作提交代码时，若出现分支冲突（如两人同时修改`qorderprocessor.cpp`的同一函数），处理步骤如下：
|
||
|
||
|
||
|
||
1. 拉取远程分支最新代码：
|
||
|
||
|
||
|
||
```
|
||
git pull origin develop
|
||
```
|
||
|
||
|
||
|
||
1. 查看冲突文件：Git 会在冲突文件中标记冲突区域（`<<<<<<< HEAD`到`=======`为本地代码，`=======`到`>>>>>>> feature/xxx`为远程代码）
|
||
|
||
2. 解决冲突：根据业务逻辑保留正确代码，删除冲突标记（`<<<<<<<`、`=======`、`>>>>>>>`）
|
||
|
||
3. 重新提交：
|
||
|
||
|
||
|
||
```
|
||
git add \[冲突文件]
|
||
|
||
git commit -m "fix: 解决与develop分支的代码冲突，保留大单检测算法正确逻辑"
|
||
|
||
git push origin feature/xxx
|
||
```
|
||
|
||
### 4.3 著作权登记时，源代码格式不符合要求被退回，如何修改？
|
||
|
||
若因格式问题被退回，需按以下要求调整：
|
||
|
||
|
||
|
||
1. 页码：确保每页页码连续，无缺页、重页，页码位置统一（如右上角）
|
||
|
||
2. 字体：统一使用宋体或楷体，字号不小于小四号（12pt），确保文字清晰
|
||
|
||
3. 代码完整性：若被指出 “核心功能代码缺失”，需补充缺失的模块文件（如遗漏`OrderBookParser.cpp`，需重新打印并提交）
|
||
|
||
4. 注释：若注释量不足，需在关键函数、算法逻辑旁补充注释，确保注释占比达标后重新提交
|
||
|
||
> （注：文档部分内容可能由 AI 生成） |