215 lines
7.0 KiB
Markdown
215 lines
7.0 KiB
Markdown
# 开发文档：双色球 Web UI 系统
|
||
|
||
**版本**: v1.0
|
||
**开发人员**: 徐聪（costcodev）
|
||
**日期**: 2026-07-03
|
||
**Issue**: BIZ-75
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
双色球自动化系统 Web UI，提供号码生成、历史数据查看、生成记录管理和统计分析功能。支持 PC 端和移动端响应式访问，监听 0.0.0.0:8085，局域网可访问。
|
||
|
||
## 2. 技术栈
|
||
|
||
| 层级 | 技术 | 说明 |
|
||
|------|------|------|
|
||
| 后端 | Python 3 + Flask | REST API 服务 |
|
||
| 前端 | 原生 HTML/CSS/JS | 单文件，响应式布局 |
|
||
| 数据分析 | Pandas + NumPy | 号码统计分析 |
|
||
| 数据存储 | Excel + JSON | 历史数据 + 生成记录 |
|
||
| 部署 | systemd / nohup | Linux 服务部署 |
|
||
|
||
## 3. 目录结构
|
||
|
||
```
|
||
lottoData/
|
||
├── app.py # Flask 主服务（统一入口）
|
||
├── index.html # 前端 UI（响应式，4 Tab 页面）
|
||
├── lottery.py # 号码生成核心逻辑
|
||
├── fetch_data.py # 历史数据抓取脚本
|
||
├── web_console.html # 数据抓取控制台前端
|
||
├── requirements.txt # Python 依赖
|
||
├── 双色球历史数据.xlsx # 历史数据文件
|
||
├── lottery/ # 号码生成结果输出目录
|
||
├── .generation_records.json # 生成记录索引（JSON）
|
||
├── .fetch_status.json # 抓取状态文件
|
||
├── deploy/ # 部署相关文件
|
||
│ ├── DEPLOY.md # 部署说明
|
||
│ ├── lotto-app.service # systemd 服务文件
|
||
│ ├── fetch_daily.sh # 定时抓取脚本
|
||
│ └── backup.sh # 备份脚本
|
||
└── docs/ # 文档目录
|
||
├── PRD-双色球 WebUI-v1.0.md
|
||
└── 开发文档-双色球WebUI-v1.0.md ← 本文件
|
||
```
|
||
|
||
## 4. API 接口
|
||
|
||
### 4.1 接口清单
|
||
|
||
| 接口 | 方法 | 描述 | 认证 |
|
||
|------|------|------|------|
|
||
| `/api/generate` | POST | 生成号码 | 可选 |
|
||
| `/api/history` | GET | 获取历史开奖数据（分页+搜索） | 可选 |
|
||
| `/api/records` | GET | 获取生成记录列表（分页） | 可选 |
|
||
| `/api/records/:id` | DELETE | 删除生成记录 | 可选 |
|
||
| `/api/statistics` | GET | 获取统计分析数据 | 可选 |
|
||
| `/api/download/:filepath` | GET | 下载文件 | 可选 |
|
||
| `/api/status` | GET | 系统状态 | 无 |
|
||
| `/api/config` | GET | 前端配置 | 无 |
|
||
| `/api/fetch/status` | GET | 抓取执行状态 | 无 |
|
||
| `/api/fetch/execute` | POST | 触发数据抓取 | 无 |
|
||
|
||
### 4.2 关键接口参数
|
||
|
||
#### POST /api/generate
|
||
```json
|
||
// 请求
|
||
{
|
||
"num_tickets": 10,
|
||
"strategy": "advanced" // 或 "basic"
|
||
}
|
||
// 响应
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"tickets": [...],
|
||
"total": 10,
|
||
"filename": "lottery/xxx.xlsx",
|
||
"download_url": "/api/download/lottery/xxx.xlsx",
|
||
"record": {...},
|
||
"statistics": {...}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### GET /api/history
|
||
参数: `page` (页码), `page_size` (每页条数), `search` (搜索关键词)
|
||
|
||
#### GET /api/records
|
||
参数: `page` (页码), `page_size` (每页条数)
|
||
|
||
## 5. 前端页面
|
||
|
||
### 5.1 页面结构
|
||
- **Header**: 标题 + 副标题
|
||
- **导航 Tab**: 号码生成 | 历史数据 | 生成记录 | 统计分析
|
||
- **移动端**: 底部固定导航栏
|
||
|
||
### 5.2 功能页面
|
||
|
||
#### 号码生成页（首页）
|
||
- 统计概览（历史期数、常见奇偶比、和值范围等）
|
||
- 策略选择（高级策略/基础策略）
|
||
- 注数输入（1-1000）
|
||
- 生成结果展示（红球+蓝球+统计指标）
|
||
- Excel 下载按钮
|
||
|
||
#### 历史数据页
|
||
- 搜索框（500ms 防抖）
|
||
- 数据表格（期号、日期、红球、蓝球、统计字段）
|
||
- 分页控件
|
||
|
||
#### 生成记录页
|
||
- 记录列表（策略、注数、时间、文件大小）
|
||
- 下载/删除操作
|
||
- 分页控件
|
||
|
||
#### 统计分析页
|
||
- 历史开奖期数
|
||
- 红球热号 TOP15 / 冷号 TOP15
|
||
- 蓝球热号 TOP8
|
||
- 奇偶比/大小比/和值/跨度统计
|
||
|
||
## 6. 关键修复说明
|
||
|
||
### 6.1 数据格式兼容修复（核心 Bug 修复）
|
||
|
||
**问题**: `lottery.py` 期望 Excel 含"号码"列（拼接格式如 `08121821243001`），但 `fetch_data.py` 抓取的 Excel 使用分列格式（"红球 1"~"红球 6"+"蓝球"），导致号码生成器无法加载历史数据。
|
||
|
||
**根因**: Excel 文件包含两行 header：
|
||
- Row 0: 新格式列名（期号、开奖日期、红球 1~6、蓝球、特别号）
|
||
- Row 1: 旧格式列名（开奖时间、期数、号码、开机号、...）
|
||
- Row 2+: 实际数据
|
||
|
||
**修复方案**:
|
||
1. `lottery.py` 的 `load_history_data()`: 添加多格式检测逻辑，识别格式A（双行 header）并自动跳过，使用旧列名作为标准列名
|
||
2. `lottery.py` 的 `parse_numbers()`: 新增对拼接字符串格式（14位无分隔符）的直接解析，避免 `re.findall` 将整个字符串视为一个数字
|
||
3. `app.py` 的 `load_history_dataframe()`: 同步修复多格式兼容逻辑
|
||
|
||
### 6.2 线程安全
|
||
|
||
- 生成记录的读-改-写操作使用 `threading.Lock` 保护
|
||
- 文件写入使用临时文件+原子替换（`os.replace`），防止崩溃导致数据损坏
|
||
|
||
## 7. 部署方式
|
||
|
||
### 7.1 直接运行
|
||
```bash
|
||
cd /home/vincent/Studio/lottoData
|
||
source .venv/bin/activate
|
||
python3 app.py
|
||
# 访问 http://localhost:8085
|
||
```
|
||
|
||
### 7.2 systemd 服务
|
||
```bash
|
||
# 服务文件: deploy/lotto-app.service
|
||
sudo cp deploy/lotto-app.service /etc/systemd/system/
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable lotto-app
|
||
sudo systemctl start lotto-app
|
||
```
|
||
|
||
### 7.3 定时数据抓取
|
||
```bash
|
||
# 添加 cron 任务
|
||
crontab -e
|
||
# 每天 02:30 自动抓取最新数据
|
||
30 2 * * * /home/vincent/Studio/lottoData/deploy/fetch_daily.sh >> /home/vincent/Studio/lottoData/deploy/cron.log 2>&1
|
||
```
|
||
|
||
## 8. 测试验证
|
||
|
||
### 8.1 API 测试结果
|
||
|
||
| 接口 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| GET /api/status | ✅ 通过 | 返回服务状态 |
|
||
| GET /api/statistics | ✅ 通过 | 120条历史数据统计正确 |
|
||
| GET /api/history | ✅ 通过 | 分页+红蓝球解析正确 |
|
||
| POST /api/generate | ✅ 通过 | 5注号码生成成功，含统计 |
|
||
| GET /api/records | ✅ 通过 | 生成记录列表正确 |
|
||
| GET / (前端页面) | ✅ 通过 | HTML 页面正常加载 |
|
||
|
||
### 8.2 数据格式验证
|
||
- 历史数据: 120 条记录全部成功解析 ✅
|
||
- 红球解析: 6个红球正确提取 ✅
|
||
- 蓝球解析: 1个蓝球正确提取 ✅
|
||
- 号码范围校验: 1-33(红) + 1-16(蓝) ✅
|
||
|
||
## 9. 已知限制
|
||
|
||
- 前端为单 HTML 文件，未使用构建工具
|
||
- 无用户登录系统（Token 认证为可选项，默认关闭）
|
||
- 历史数据来源为 55128.cn，如网站改版需更新 `fetch_data.py`
|
||
- 不支持 HTTPS（内网环境）
|
||
|
||
## 10. 后续优化建议
|
||
|
||
| 功能 | 优先级 | 说明 |
|
||
|------|--------|------|
|
||
| 数据可视化图表 | P2 | 走势图、分布图 |
|
||
| 用户登录系统 | P2 | 多用户权限管理 |
|
||
| 定时自动生成 | P2 | 定时生成+推送 |
|
||
| 微信推送 | P3 | 生成结果推送至微信 |
|
||
| 多彩种支持 | P3 | 大乐透、福彩 3D 等 |
|
||
|
||
---
|
||
|
||
**开发完成日期**: 2026-07-03
|
||
**代码仓库**: http://192.168.1.99:12299/vincent/Lottery.git
|
||
**开发人员**: 徐聪（costcodev）
|