Lottery/docs/开发文档-双色球WebUI-v1.0.md

开发文档：双色球 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

// 请求
{
  "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 直接运行

cd /home/vincent/Studio/lottoData
source .venv/bin/activate
python3 app.py
# 访问 http://localhost:8085

7.2 systemd 服务

# 服务文件: 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 定时数据抓取

# 添加 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）