Files

T

vincent 13a259b0f8 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

14 KiB

Raw Permalink Blame History

产品需求文档（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

请求:

{
  "num_tickets": 10,
  "strategy": "advanced"
}

响应:

{
  "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 部署方式

# 进入项目目录
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 已有代码文件清单

app.py (17KB) - Flask 后端服务
index.html (42KB) - 响应式前端 UI
lottery.py (51KB) - 号码生成核心逻辑
fetch_data.py (3.8KB) - 历史数据抓取
web_executor.py (6.4KB) - 数据抓取 Web 服务
web_console.html (11KB) - 数据抓取控制台
双色球历史数据.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

14 KiB Raw Permalink Blame History Unescape Escape