chore: initial commit — existing lottoData codebase

Files: - lottery.py (1189 lines) — DoubleColorBallGenerator core engine - fetch_data.py (131 lines) — history data fetcher from 55128.cn - web_executor.py (216 lines) — data fetch Web console (Flask :5000) - app.py (505 lines) — number generation Web service (Flask :8085) - index.html (1171 lines) — frontend SPA - web_console.html (323 lines) — fetch console frontend - deploy/ — systemd service + cron script + logs BIZ-74 architecture review baseline
2026-07-03 16:39:21 +08:00
commit 13a259b0f8
27 changed files with 5025 additions and 0 deletions
@@ -0,0 +1,361 @@
+# 产品需求文档（PRD）：双色球自动化系统 Web UI
+
+**文档版本**: v1.0  
+**创建日期**: 2026-07-03  
+**产品经理**: 沈路明  
+**状态**: 待评审  
+
+---
+
+## 1. 背景与目标
+
+### 1.1 业务背景
+双色球自动化项目已完成核心功能开发（数据爬取、号码生成、统计分析），但缺乏统一的 Web 界面供用户（刘总及团队成员）便捷访问和使用。现有功能分散在多个 Python 脚本中，需要在网页端整合为一体化服务。
+
+### 1.2 解决的问题
+- **访问门槛高**: 用户需要运行 Python 脚本才能生成号码，操作复杂
+- **数据不可视**: 历史数据、生成记录、统计信息无法直观查看
+- **无法局域网共享**: 缺少监听 0.0.0.0 的 Web 服务，无法在 PC/手机端跨设备访问
+- **功能分散**: 数据抓取、号码生成、历史记录查看分散在不同入口
+
+### 1.3 成功指标（定量）
+| 指标 | 目标值 | 衡量方式 |
+|------|--------|----------|
+| 功能覆盖率 | 100% 核心功能 | PRD 功能清单验收 |
+| 响应式支持 | PC + 移动端 | 主流设备测试通过 |
+| 局域网可访问 | 0.0.0.0:8085 | 网络扫描验证 |
+| API 响应时间 | <2s (P95) | 压力测试 |
+| 用户满意度 | 刘总验收通过 | 评审会议确认 |
+
+---
+
+## 2. 用户故事
+
+| ID | 用户角色 | 故事 | 价值 |
+|----|----------|------|------|
+| US-01 | 刘总（主要用户） | 作为用户，我希望在手机上打开网页就能生成双色球号码，以便随时查看推荐号码 | 便捷性、即时访问 |
+| US-02 | 刘总 | 作为用户，我希望查看历史开奖数据，以便分析号码趋势 | 数据驱动决策 |
+| US-03 | 刘总 | 作为用户，我希望查看历史生成记录并下载 Excel，以便存档和分享 | 数据持久化 |
+| US-04 | 团队成员 | 作为团队成员，我希望在 PC 端大屏查看统计数据，以便进行项目汇报 | 可视化展示 |
+| US-05 | 团队成员 | 作为运维人员，我希望服务监听局域网，以便多人同时访问 | 资源共享 |
+
+---
+
+## 3. 功能需求
+
+### 3.1 功能清单与优先级
+
+| 功能模块 | 功能点 | 描述 | 优先级 | 验收标准 |
+|----------|--------|------|--------|----------|
+| **号码生成** | GEN-01 | 选择生成注数（1-1000） | P0 | 滑块/输入框可调，范围校验正确 |
+| | GEN-02 | 选择策略（基础/高级） | P0 | 下拉选择，高级策略调用热冷号分析 |
+| | GEN-03 | 执行生成并展示结果 | P0 | 点击生成后 3s 内返回结果，展示红球 + 蓝球 |
+| | GEN-04 | 结果页展示和值、奇偶比、大小比、跨度 | P0 | 每个号码下方显示统计指标 |
+| | GEN-05 | 下载 Excel 文件 | P0 | 点击下载可获取完整 Excel |
+| | GEN-06 | 生成记录自动保存 | P0 | 每次生成后记录存入 `.generation_records.json` |
+| **历史数据** | HIS-01 | 查看历史开奖数据列表 | P0 | 分页展示，每页 20 条，支持翻页 |
+| | HIS-02 | 搜索历史数据（按期号/日期） | P1 | 搜索框输入后 500ms 防抖查询 |
+| | HIS-03 | 红球/蓝球高亮显示 | P0 | 红球红色背景，蓝球蓝色背景 |
+| | HIS-04 | 展示和值、奇偶比、大小比、跨度 | P1 | 列表中包含这些统计字段 |
+| **生成记录** | REC-01 | 查看历史生成记录列表 | P0 | 分页展示，显示策略、注数、时间、文件大小 |
+| | REC-02 | 下载生成结果文件 | P0 | 点击下载可获取对应 Excel |
+| | REC-03 | 删除生成记录 | P1 | 删除后同时删除对应文件，列表刷新 |
+| **统计数据** | STA-01 | 展示历史开奖期数 | P0 | 数字准确 |
+| | STA-02 | 红球热号 TOP15 | P0 | 按出现频次降序排列 |
+| | STA-03 | 红球冷号 TOP15 | P0 | 按出现频次升序排列 |
+| | STA-04 | 蓝球热号 TOP8 | P0 | 按出现频次降序排列 |
+| | STA-05 | 最常见奇偶比 | P1 | 显示频次最高的奇偶比形态 |
+| | STA-06 | 最常见大小比 | P1 | 显示频次最高的 大小比形态 |
+| | STA-07 | 和值范围统计 | P1 | 显示最小值、最大值、平均值、标准差 |
+| | STA-08 | 跨度范围统计 | P1 | 显示最小值、最大值、平均值、标准差 |
+| **系统功能** | SYS-01 | 监听 0.0.0.0:8085 | P0 | `netstat -tlnp` 验证 |
+| | SYS-02 | PC/移动端响应式布局 | P0 | 视口宽度 320px-1920px 自适应 |
+| | SYS-03 | 页面导航（4 个 Tab） | P0 | 生成、历史数据、生成记录、统计 |
+| | SYS-04 | API Token 认证（可选） | P2 | 配置项 `auth_enabled` 控制开关 |
+| | SYS-05 | 系统状态接口 | P1 | `/api/status` 返回服务状态 |
+
+### 3.2 核心业务流程
+
+```
+用户访问 → 首页（号码生成） → 选择注数/策略 → 点击生成
+  ↓
+后端调用 lottery.py → 分析历史数据 → 生成号码 → 保存 Excel
+  ↓
+返回结果 → 前端展示（红球 + 蓝球 + 统计指标） → 可下载/查看记录
+```
+
+---
+
+## 4. 非功能需求
+
+### 4.1 性能要求
+| 指标 | 要求 | 说明 |
+|------|------|------|
+| 页面加载时间 | <3s (P95) | 首次加载，含静态资源 |
+| API 响应时间 | <2s (P95) | 不含号码生成（含历史数据查询、统计） |
+| 号码生成时间 | <10s (P95) | 100 注以内，高级策略 |
+| 并发用户数 | ≥10 | 局域网内同时访问 |
+
+### 4.2 兼容性要求
+| 平台 | 浏览器 | 版本要求 |
+|------|--------|----------|
+| PC 端 | Chrome | 90+ |
+| PC 端 | Safari | 14+ |
+| PC 端 | Edge | 90+ |
+| 移动端 | iOS Safari | 14+ |
+| 移动端 | Android Chrome | 90+ |
+| 移动端 | 微信内置浏览器 | 最新版 |
+
+### 4.3 安全要求
+- **API 认证**: 可选 Token 认证（`auth_enabled` 配置项）
+- **目录遍历防护**: 下载接口校验路径，禁止 `..` 和绝对路径
+- **HTTPS**: 内网环境暂不强制，外网部署需配置 SSL
+
+### 4.4 可用性要求
+- **服务可用性**: ≥99%（工作时段 9:00-22:00）
+- **数据持久化**: 生成记录永久保存，除非用户主动删除
+- **错误处理**: 所有 API 失败返回友好提示，不暴露堆栈信息
+
+---
+
+## 5. 原型与界面
+
+### 5.1 页面结构
+```
+┌─────────────────────────────────────────┐
+│           Header（标题 + 副标题）        │
+├─────────────────────────────────────────┤
+│  Nav Tabs: 生成 | 历史数据 | 记录 | 统计  │
+├─────────────────────────────────────────┤
+│                                         │
+│              Page Content               │
+│           （根据 Tab 切换内容）           │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+### 5.2 关键界面描述
+
+#### 5.2.1 号码生成页（首页）
+- **顶部**: 统计概览（历史期数、常见奇偶比、常见大小比、和值范围、跨度范围、热号预览）
+- **中部**: 生成参数配置（滑块选择注数 1-1000，下拉选择策略）
+- **操作区**: 「立即生成」大按钮
+- **结果区**: 号码卡片列表（每注显示红球 6 个 + 蓝球 1 个，下方显示和值、奇偶比、大小比、跨度）
+- **底部**: 「下载 Excel」按钮
+
+#### 5.2.2 历史数据页
+- **顶部**: 搜索框（按期号/日期搜索，500ms 防抖）
+- **列表**: 表格展示（期号、开奖日期、红球 6 个、蓝球 1 个、和值、奇偶形态、大小比、跨度）
+- **底部**: 分页控件（上一页/页码/下一页）
+
+#### 5.2.3 生成记录页
+- **列表**: 卡片式展示（策略、注数、生成时间、文件大小）
+- **操作**: 每条记录含「下载」和「删除」按钮
+- **底部**: 分页控件
+
+#### 5.2.4 统计页
+- **数据卡片**: 历史开奖期数
+- **热号区**: 红球热号 TOP15（红色球）、蓝球热号 TOP8（蓝色球）
+- **冷号区**: 红球冷号 TOP15（红色球，透明度降低）
+- **统计网格**: 最常见奇偶比、最常见大小比、和值范围（min-max-mean-std）、跨度范围（min-max-mean-std）
+
+### 5.3 设计规范
+| 元素 | 规范 |
+|------|------|
+| 主色调 | 红色 #e74c3c（双色球主题） |
+| 辅色 | 蓝色 #3498db（蓝球）、紫色 #8e44ad（渐变） |
+| 字体 | 系统默认（-apple-system, PingFang SC, Microsoft YaHei） |
+| 卡片圆角 | 12px |
+| 阴影 | 0 2px 12px rgba(0,0,0,0.08) |
+| 移动导航 | 底部固定（高度 56px） |
+| PC 导航 | 顶部 Tab（高度 68px，sticky） |
+
+---
+
+## 6. API 接口设计
+
+### 6.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 | 前端配置 | 无 |
+
+### 6.2 关键接口示例
+
+#### POST /api/generate
+**请求**:
+```json
+{
+  "num_tickets": 10,
+  "strategy": "advanced"
+}
+```
+
+**响应**:
+```json
+{
+  "success": true,
+  "data": {
+    "tickets": [
+      {
+        "index": 1,
+        "reds": [3, 12, 18, 23, 27, 31],
+        "blue": 9,
+        "sum_value": 114,
+        "odd_even": "3:3",
+        "size_ratio": "4:2",
+        "span": 28
+      }
+    ],
+    "total": 10,
+    "filename": "lottery/双色球_20260703_142530_高级策略_10 注.xlsx",
+    "download_url": "/api/download/lottery/双色球_20260703_142530_高级策略_10 注.xlsx",
+    "record": {...},
+    "statistics": {...}
+  }
+}
+```
+
+---
+
+## 7. 技术架构
+
+### 7.1 技术栈
+| 层级 | 技术 | 版本 |
+|------|------|------|
+| 后端 | Python + Flask | 3.x + 2.x |
+| 前端 | 原生 HTML/CSS/JS | ES6+ |
+| 数据存储 | Excel + JSON | openpyxl |
+| 号码生成 | NumPy + Pandas | 1.x |
+| 部署 | 直接运行 | `python3 app.py` |
+
+### 7.2 目录结构
+```
+lottoData/
+├── app.py              # Flask 主服务（17KB）
+├── index.html          # 前端 UI（42KB，响应式）
+├── lottery.py          # 号码生成核心逻辑（51KB）
+├── fetch_data.py       # 数据爬取脚本
+├── web_executor.py     # 数据抓取 Web 服务（独立）
+├── web_console.html    # 数据抓取控制台
+├── 双色球历史数据.xlsx   # 历史数据（由 fetch_data.py 更新）
+├── lottery/            # 号码生成结果目录
+├── .generation_records.json  # 生成记录索引
+└── .fetch_status.json  # 抓取状态（web_executor 用）
+```
+
+### 7.3 部署方式
+```bash
+# 进入项目目录
+cd /home/vincent/Studio/lottoData
+
+# 启动服务
+python3 app.py
+
+# 访问地址
+本地：http://localhost:8085
+局域网：http://<本机 IP>:8085
+```
+
+### 7.4 端口与监听
+- **默认端口**: 8085
+- **监听地址**: 0.0.0.0（局域网可访问）
+- **可配置**: `CONFIG['port']` 和 `CONFIG['host']`
+
+---
+
+## 8. 数据埋点与监控
+
+### 8.1 关键事件埋点建议
+| 事件 | 触发时机 | 数据字段 |
+|------|----------|----------|
+| `page_view` | 页面加载 | page_name, user_agent, timestamp |
+| `generate_click` | 点击生成按钮 | num_tickets, strategy |
+| `generate_success` | 生成成功 | num_tickets, strategy, duration_ms |
+| `generate_failure` | 生成失败 | error_message, strategy |
+| `download_click` | 点击下载 | file_name, source (生成结果/记录列表) |
+| `record_delete` | 删除记录 | record_id |
+
+### 8.2 监控指标
+- **服务可用性**: 心跳检测（/api/status）
+- **API 错误率**: 按接口统计 5xx 错误占比
+- **生成成功率**: 成功次数 / 总请求次数
+- **平均响应时间**: 各接口 P95延迟
+
+---
+
+## 9. 排期建议
+
+| 阶段 | 工作内容 | 负责人 | 预估工时 |
+|------|----------|--------|----------|
+| 评审 | PRD 评审 + 架构评审 | 全员 | 2h |
+| 开发 | 已有代码，无需开发 | - | 0h |
+| 测试 | 功能测试 + 兼容性测试 | 测试 | 4h |
+| 部署 | 服务启动 + 防火墙配置 | 运维 | 1h |
+| 验收 | 刘总验收 | 刘总 | 待定 |
+
+**总工时**: 7 小时（主要为测试和验收）
+
+---
+
+## 10. 风险与应对
+
+| 风险 | 影响 | 概率 | 应对措施 |
+|------|------|------|----------|
+| 历史数据文件损坏 | 无法生成号码 | 低 | 定期备份 `.xlsx` 文件 |
+| 局域网网络问题 | 无法访问 | 中 | 检查防火墙，确保 8085 端口开放 |
+| 并发过高导致服务卡顿 | 体验下降 | 低 | 限制单 IP 请求频率，增加超时控制 |
+| Excel 文件过大 | 下载缓慢 | 中 | 单个文件限制 1000 注，超过分批下载 |
+| 移动端适配问题 | 显示错乱 | 低 | 真机测试主流设备 |
+
+---
+
+## 11. 版本历史
+
+| 版本 | 日期 | 修改内容 | 修改人 |
+|------|------|----------|--------|
+| v1.0 | 2026-07-03 | 初始版本，基于现有代码逆向整理 PRD | 沈路明 |
+
+---
+
+## 12. 附件
+
+### 12.1 已有代码文件清单
+1. `app.py` (17KB) - Flask 后端服务
+2. `index.html` (42KB) - 响应式前端 UI
+3. `lottery.py` (51KB) - 号码生成核心逻辑
+4. `fetch_data.py` (3.8KB) - 历史数据抓取
+5. `web_executor.py` (6.4KB) - 数据抓取 Web 服务
+6. `web_console.html` (11KB) - 数据抓取控制台
+7. `双色球历史数据.xlsx` (12KB) - 历史数据文件
+
+### 12.2 Git 仓库
+- **仓库地址**: http://192.168.1.99:12299/vincent/Lottery.git
+- **当前状态**: 代码已完成，待提交至 Git
+
+### 12.3 访问地址
+- **本地访问**: http://localhost:8085
+- **局域网访问**: http://192.168.1.99:8085（示例 IP，以实际为准）
+
+---
+
+## 13. 后续优化建议（非本期）
+
+| 功能 | 描述 | 优先级 |
+|------|------|--------|
+| 用户登录系统 | 多用户权限管理 | P2 |
+| 定时任务调度 | 自动生成 + 推送 | P2 |
+| 数据可视化图表 | 走势图、分布图 | P2 |
+| 微信推送 | 生成结果推送至微信 | P3 |
+| 多彩种支持 | 大乐透、福彩 3D 等 | P3 |
+
+---
+
+**PRD 评审准备就绪，邀请架构师（梁思筑）和开发（徐聪）参与评审。**