3D/P3藏书阁 v3.0 - 技术文档

📋 目录

1. 技术架构
2. 代码结构
3. 核心模块
4. 数据结构
5. API接口
6. 依赖库说明
7. 开发指南

技术架构

整体架构

┌─────────────────────────────────────────┐
│          GUI界面层 (tkinter)            │
├─────────────────────────────────────────┤
│    业务逻辑层 (LotteryQueryApp)          │
├─────────────────────────────────────────┤
│    数据处理层 (pandas)                  │
├─────────────────────────────────────────┤
│    文件I/O层 (openpyxl, xlrd)          │
├─────────────────────────────────────────┤
│    网络层 (requests)                    │
├─────────────────────────────────────────┤
│    注册系统层 (RSA加密)                 │
└─────────────────────────────────────────┘

技术栈

• GUI框架：tkinter + ttk
• 数据处理：pandas
• Excel支持：openpyxl, xlrd, pyexcel
• 网络请求：requests
• 加密系统：cryptography (RSA 2048位)
• 硬件识别：psutil
• 多线程：threading

代码结构

主程序文件结构

main.py (2051行)
├── 导入模块 (1-59行)
├── LotteryQueryApp类 (62-1825行)
│   ├── __init__ (初始化)
│   ├── 注册系统相关方法
│   ├── GUI创建方法
│   ├── 数据处理方法
│   ├── 查询方法
│   └── 工具方法
├── CustomActivationDialog类 (1826-2040行)
│   ├── __init__
│   ├── setup_ui
│   └── 激活相关方法
└── main函数 (2042-2051行)

模块组织

项目根目录/
├── main.py                          # 主程序
├── registration/                    # 注册系统模块
│   ├── client_license_validator.py # 客户端验证
│   └── production_registration_core.py # 注册核心
├── ftp/                             # FTP上传模块
│   └── license_ftp_uploader.py    # FTP上传
└── data/                            # 数据文件夹（运行时创建）

核心模块

1. LotteryQueryApp类

初始化方法 (__init__)

功能：初始化应用程序

主要操作：

1. 设置窗口标题和大小
2. 获取程序根目录路径
3. 创建data文件夹
4. 初始化数据存储变量
5. 初始化注册系统
6. 创建GUI界面
7. 检查激活状态

关键变量：

self.data = None                    # 数据DataFrame
self.data_file_path = None          # 数据文件路径
self.data_type = None               # 数据类型：'3D'或'P3'
self.program_directory = ...        # 程序根目录
self.data_directory = ...           # 数据文件夹路径
self.is_activated = False           # 激活状态

GUI创建方法

create_widgets：

• 创建工具栏
• 创建可滚动主容器
• 创建查询面板
• 创建数据表格面板
• 创建结果输出面板

create_query_panel：

• 创建历史号码查询组
• 创建试机号查询组（仅3D）
• 创建期号查询组
• 创建日期范围查询组

create_data_panel：

• 创建表格框架
• 创建滚动条
• 创建Treeview表格
• 根据数据类型动态设置列

create_result_panel：

• 创建结果输出文本框
• 创建操作按钮（一键复制、清空结果）

数据处理方法

load_data_file：

• 读取Excel文件（支持.xls和.xlsx）
• 解析标题行（使用第二行）
• 识别数据类型（根据列数）
• 映射列名（简化标题→完整标题）
• 数据验证和清理
• 更新表格显示

display_data：

• 清空现有数据
• 根据数据类型更新表格列
• 按期号降序排列数据
• 插入数据到表格
• 更新统计信息

update_table_columns：

• 根据数据类型动态更新表格列
• 3D数据：17列
• P3数据：12列
• 重新创建表格（如需要）

save_data：

• 获取数据类型和最后期号
• 生成默认文件名
• 选择保存位置（默认data文件夹）
• 准备标题行（根据数据类型）
• 保存为Excel文件

auto_update_data：

• 根据数据类型选择URL
• 发送HTTP请求（后台线程）
• 解析文本数据（空格分隔）
• 识别数据类型（根据列数）
• 更新数据表格

查询方法

query_number：

• 验证输入（3位数字）
• 提取百位、十位、个位
• 查询匹配记录
• 格式化输出结果
• 根据数据类型显示不同信息

query_trial_number：

• 验证数据类型（仅3D）
• 验证输入（3位数字）
• 查询匹配记录
• 统计开奖号分布
• 格式化输出结果

query_period：

• 验证输入（期号）
• 查询匹配记录
• 格式化输出结果
• 根据数据类型显示不同信息

query_date_range：

• 验证输入（日期格式）
• 查询匹配记录
• 格式化输出结果
• 根据数据类型显示额外信息

show_period_details：

• 根据期号查询数据
• 格式化显示详细信息
• 清空并显示结果

事件处理方法

on_item_click：

• 处理表格行单击事件
• 获取选中行的期号
• 调用show_period_details显示详情

on_item_double_click：

• 处理表格行双击事件
• 获取选中行的期号
• 填充期号到查询框
• 执行期号查询

注册系统方法

init_registration_system：

• 初始化ClientLicenseValidator
• 初始化FTP上传器
• 设置绝对路径

check_activation_status：

• 验证授权文件
• 更新激活状态
• 加载授权信息
• 触发FTP上传

update_activation_display：

• 更新激活状态标签
• 启用/禁用功能按钮
• 更新表格状态

show_activation_dialog：

• 创建CustomActivationDialog
• 显示激活对话框
• 处理激活结果

数据结构

DataFrame结构

3D数据DataFrame

columns = [
    '开奖期号',      # str/int
    '开奖日期',      # str (YYYY-MM-DD)
    '开奖号百位',    # int (0-9)
    '开奖号十位',    # int (0-9)
    '开奖号个位',    # int (0-9)
    '试机号百位',    # int (0-9)
    '试机号十位',    # int (0-9)
    '试机号个位',    # int (0-9)
    '机号',         # int
    '球号',         # int
    '投注总额',      # int
    '单选注数',      # int
    '单选金额',      # int
    '组三注数',      # int
    '组三金额',      # int
    '组六注数',      # int
    '组六金额'       # int
]

P3数据DataFrame

columns = [
    '开奖期号',      # str/int
    '开奖日期',      # str (YYYY-MM-DD)
    '开奖号百位',    # int (0-9)
    '开奖号十位',    # int (0-9)
    '开奖号个位',    # int (0-9)
    '投注总额',      # int
    '直选注数',      # int
    '直选金额',      # int
    '组三注数',      # int
    '组三金额',      # int
    '组六注数',      # int
    '组六金额'       # int
]

数据类型识别逻辑

if num_cols == 12:
    # 检查是否包含"直选注数"
    if has_zhixuan or self.data_type == 'P3':
        self.data_type = 'P3'
elif num_cols >= 17:
    self.data_type = '3D'

列名映射逻辑

简化标题映射

# 位置映射（根据列位置）
列0: 开奖期号
列1: 开奖日期
列2: 开奖号百位 (标题可能是"开")
列3: 开奖号十位 (标题可能是"奖")
列4: 开奖号个位 (标题可能是"号")
列5: 试机号百位 (标题可能是"试") - 仅3D
列6: 试机号十位 (标题可能是"机") - 仅3D
列7: 试机号个位 (标题可能是"号") - 仅3D
列8: 机号 (标题可能是"机") - 仅3D
列9: 球号 (标题可能是"球") - 仅3D
列10: 投注总额
列11: 单选注数/直选注数
列12: 单选金额/直选金额 (标题可能是"金额")
列13: 组三注数
列14: 组三金额 (标题可能是"金额")
列15: 组六注数
列16: 组六金额 (标题可能是"金额")

API接口

数据源API

3D数据源

• URL：`[数据源地址已隐藏]
• 格式：空格分隔的文本文件
• 列数：17列
• 编码：UTF-8或GBK

P3数据源

• URL：`[数据源地址已隐藏]
• 格式：空格分隔的文本文件
• 列数：12列
• 编码：UTF-8或GBK

数据格式

文本数据格式（自动更新）

期号 日期 百位 十位 个位 [试机号...] 投注总额 注数 金额 ...

示例（3D）：

2025303 2025-11-13 9 4 3 9 0 4 1 1 43677260 9974 1040 0 346 44656 173

示例（P3）：

2025303 2025-11-13 9 4 3 43677260 9974 1040 0 346 44656 173

依赖库说明

核心依赖

pandas (>=1.5.0)

• 用途：数据处理和分析
• 主要功能：
• DataFrame数据结构
• 数据查询和筛选
• 数据排序和分组
• Excel文件读写

openpyxl (>=3.0.0)

• 用途：读写Excel 2007+格式（.xlsx）
• 主要功能：
• 读取.xlsx文件
• 写入.xlsx文件
• 处理Excel格式

xlrd (==1.2.0)

• 用途：读取Excel 97-2003格式（.xls）
• 版本要求：必须使用1.2.0版本（2.0+不支持.xls）
• 主要功能：
• 读取.xls文件
• 解析Excel格式

pyexcel (>=0.7.0) + pyexcel-xls (>=0.6.0)

• 用途：xlrd 2.0+的替代方案，用于读取.xls文件
• 主要功能：
• 读取.xls文件（当xlrd版本>=2.0时使用）
• 提供兼容性支持

requests (>=2.25.0)

• 用途：HTTP请求，用于自动更新功能
• 主要功能：
• 发送HTTP GET请求
• 处理响应数据
• 错误处理

cryptography (>=3.4.8)

• 用途：RSA加密，用于注册系统
• 主要功能：
• 生成RSA密钥对
• 签名和验证
• 加密和解密

psutil (>=5.8.0)

• 用途：硬件信息获取，用于设备ID生成
• 主要功能：
• 获取CPU信息
• 获取内存信息
• 获取磁盘信息
• 获取网络信息

标准库

• tkinter：GUI框架
• os：文件系统操作
• sys：系统相关功能
• datetime：日期时间处理
• re：正则表达式
• threading：多线程支持
• io：输入输出操作

开发指南

开发环境设置

1. 安装Python

# 下载并安装Python 3.7+
# 确保添加到PATH
python --version

2. 创建虚拟环境

python -m venv .venv
.venv\Scripts\activate  # Windows

3. 安装依赖

pip install -r requirements.txt

4. 运行程序

python main.py

代码规范

命名规范

• 类名：PascalCase（如：LotteryQueryApp）
• 方法名：snake_case（如：query_number）
• 变量名：snake_case（如：data_type）
• 常量名：UPPER_SNAKE_CASE（如：REQUESTS_AVAILABLE）

代码组织

• 导入顺序：

1. 标准库
2. 第三方库
3. 本地模块

• 方法顺序：

1. __init__
2. 初始化方法
3. GUI创建方法
4. 数据处理方法
5. 查询方法
6. 事件处理方法
7. 工具方法

注释规范

• 文件头注释：包含软件信息
• 类注释：说明类的用途
• 方法注释：说明方法的功能、参数、返回值
• 关键代码注释：说明复杂逻辑

扩展开发

添加新查询功能

1. 在create_query_panel中添加UI组件
2. 创建查询方法（如query_xxx）
3. 在方法中实现查询逻辑
4. 格式化输出结果
5. 显示在结果框

添加新数据类型

1. 修改数据类型识别逻辑
2. 添加新的列映射
3. 更新表格列定义
4. 更新查询方法以支持新类型

修改数据源

1. 修改auto_update_data方法中的URL
2. 调整数据解析逻辑
3. 更新列映射

调试技巧

日志输出

import traceback
try:
    # 代码
except Exception as e:
    print(f"错误: {e}")
    traceback.print_exc()

数据验证

# 检查数据格式
print(f"数据形状: {df.shape}")
print(f"列名: {df.columns.tolist()}")
print(f"数据类型: {self.data_type}")

GUI调试

# 检查组件状态
print(f"激活状态: {self.is_activated}")
print(f"数据记录数: {len(self.data) if self.data is not None else 0}")

性能优化

大数据处理

• 使用pandas的向量化操作
• 避免循环处理DataFrame
• 使用索引加速查询

GUI响应

• 网络请求使用后台线程
• GUI更新使用root.after()
• 避免在主线程中执行耗时操作

内存管理

• 及时释放不需要的数据
• 使用生成器处理大数据
• 避免重复加载数据

部署说明

打包为exe

使用PyInstaller

pip install pyinstaller
pyinstaller --onefile --windowed --name "3D藏书阁" main.py

包含文件

• main.py
• registration/目录
• ftp/目录
• requirements.txt（用于安装依赖）

文件分发

参考打包文件清单.md文档，确保：

• 包含所有必需文件
• 不包含私钥文件
• 不包含开发工具
• 包含使用文档

版本历史

v3.0 (当前版本)

新增功能：

• ✅ 支持P3数据类型
• ✅ 自动识别数据类型
• ✅ 动态表格列显示
• ✅ 试机号查询功能
• ✅ 单击表格行显示详情
• ✅ 自动更新功能
• ✅ 数据保存功能
• ✅ data文件夹管理
• ✅ 注册系统集成
• ✅ FTP上传功能

改进：

• 优化界面布局
• 改进数据解析逻辑
• 增强错误处理
• 优化查询性能

技术支持

• QQ群：253799100 摸金门
• 邮箱：moqiuxiaowei@qq.com
• 微信号：moqiuxiaowei

3D/P3藏书阁 v3.0
© 2025 东湖沙湾论彩彩迷群 版权所有