From 56c4623d0c3adc601f41bceaf0626e45ce2d975b Mon Sep 17 00:00:00 2001 From: bizwings Date: Fri, 3 Jul 2026 23:06:18 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20BIZ-75=20=E5=8F=8C=E8=89=B2=E7=90=83Web?= =?UTF-8?q?UI=E5=BC=80=E5=8F=91=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- specs/lottery/开发文档-双色球WebUI-v1.0.md | 214 +++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100644 specs/lottery/开发文档-双色球WebUI-v1.0.md diff --git a/specs/lottery/开发文档-双色球WebUI-v1.0.md b/specs/lottery/开发文档-双色球WebUI-v1.0.md new file mode 100644 index 0000000..e666678 --- /dev/null +++ b/specs/lottery/开发文档-双色球WebUI-v1.0.md @@ -0,0 +1,214 @@ +# 开发文档：双色球 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）