Lottery/docs/PRD-20260619-双色球数据抓取系统.md

产品需求文档（PRD）：双色球数据抓取系统

版本历史

版本	日期	变更内容	作者
v1.0	2026-06-19	初始版本	沈路明

---

1. 背景与目标

1.1 业务背景

• 双色球作为中国最受欢迎的彩票类型，用户需要及时了解历史开奖数据进行分析和参考
• 目前数据依赖人工查看，效率低且无法进行数据分析
• 需要建立自动化数据抓取和展示系统，支持日常数据分析和研究

1.2 解决的问题

1. 数据获取效率低：人工访问网站查看开奖结果耗时且容易遗漏
2. 数据难以分析：网页数据无法直接用于 Excel 或其他分析工具
3. 无法实时监控：无法及时获取最新开奖数据
4. 访问不便：需要在局域网内便捷访问数据和管理工具

1.3 成功指标（可量化）

• 数据准确性：抓取数据与官方网站一致率 100%
• 更新及时性：开奖后 30 分钟内完成数据更新
• 系统可用性：Web 服务月可用性 ≥ 99%
• 用户体验：页面加载时间 < 2 秒（局域网环境）

---

2. 用户故事

角色	用户故事	价值
数据分析员	作为数据分析员，我希望每天自动获取最新的双色球开奖数据，以便进行趋势分析	节省手动收集数据的时间，确保数据完整性
普通用户	作为普通用户，我希望通过网页界面手动触发数据抓取并实时查看结果，以便确认系统正常运行	透明化系统运行状态，增强信任感
系统管理员	作为系统管理员，我希望配置定时任务和时间，以便控制数据抓取的频率	灵活管理系统负载，避免频繁请求
局域网用户	作为局域网用户，我希望能在家中任何设备上访问 Web 界面，以便随时随地查看数据	提升访问便利性，支持多设备使用

---

3. 功能需求

3.1 数据抓取模块

功能点	描述	优先级	验收标准
数据源接入	从 https://www.55128.cn/kjh/fcssq-history-120.htm 抓取近 120 期双色球开奖数据	P0	能正确解析 HTML 并提取所有开奖数据，无遗漏
增量更新	对比本地 Excel 文件，仅添加缺失的期数数据	P0	不产生重复数据，新增数据准确率 100%
数据校验	抓取后进行数据完整性校验（期数连续性、号码格式等）	P1	发现异常数据时记录错误日志并告警
错误重试	网络异常时自动重试（最多 3 次，间隔 5 秒）	P1	临时网络故障下成功抓取率 ≥ 95%

3.2 数据存储模块

功能点	描述	优先级	验收标准
Excel 存储	数据以 Excel 格式存储，文件名为「双色球历史数据.xlsx」	P0	文件格式正确，可用 Excel 正常打开
字段定义	包含以下字段（见 4.1）	P0	所有字段完整，格式正确
数据导出	支持导出为 CSV 格式（可选）	P2	导出数据与 Excel 一致，编码为 UTF-8

3.3 Web 界面模块

功能点	描述	优先级	验收标准
手动触发抓取	提供"立即抓取"按钮，点击后执行抓取脚本	P0	按钮点击后 3 秒内响应，显示执行状态
实时日志展示	显示抓取过程的实时日志（包括开始时间、抓取期数、完成时间等）	P0	日志自动滚动，支持暂停查看，颜色区分正常/警告/错误
数据概览	展示最新一期开奖号码（红球 6 个 + 蓝球 1 个）	P0	号码以球状展示，颜色正确（红球红色，蓝球蓝色）
历史数据表	展示 Excel 中的数据，支持分页和搜索	P1	支持按期数搜索，分页加载（每页 20 条）
抓取状态监控	显示最近一次抓取时间、下次计划抓取时间、抓取状态（成功/失败）	P1	状态更新时间 < 5 秒延迟
定时任务配置	提供界面配置定时任务的执行时间	P0	配置后立即生效，无需重启服务
响应式布局	支持桌面端和移动端访问	P1	在主流手机浏览器上正常显示和操作

3.4 定时任务模块

功能点	描述	优先级	验收标准
Cron 定时任务	使用 Linux cron 实现每天自动抓取	P0	任务配置正确，日志中可查到执行记录
执行时间配置	默认为每天 21:30（开奖后 15 分钟）	P0	可通过 Web 界面修改执行时间
任务开关	提供启用/禁用定时任务的开关	P1	开关状态立即生效，界面显示当前状态

---

4. 非功能需求

4.1 数据字段定义

Excel 文件字段：

字段名	类型	说明	示例
开奖日期	Date	开奖日期	2026-06-18
期数	String	双色球期号	2026069
红球 1	Integer	第 1 个红球号码（1-33）	12
红球 2	Integer	第 2 个红球号码（1-33）	14
红球 3	Integer	第 3 个红球号码（1-33）	16
红球 4	Integer	第 4 个红球号码（1-33）	17
红球 5	Integer	第 5 个红球号码（1-33）	18
红球 6	Integer	第 6 个红球号码（1-33）	32
蓝球	Integer	蓝球号码（1-16）	08
和值	Integer	6 个红球号码之和	109
奇偶比	String	红球奇偶比例	1:5
大小比	String	红球大小比例（1-16 为小，17-33 为大）	3:3
开机号	String	开机号（如有）	07,13,19,24,27,31+05
跨度	Integer	红球最大值 - 最小值	20

4.2 性能要求

指标	要求	说明
抓取耗时	< 30 秒	完成 120 期数据抓取和更新的总耗时
页面加载	< 2 秒	Web 界面在局域网环境下的加载时间
并发支持	≥ 5 个并发用户	支持至少 5 个用户同时访问 Web 界面
内存占用	< 200MB	Python 进程常驻内存占用

4.3 兼容性要求

维度	要求
操作系统	Ubuntu 20.04+ / macOS 12+
Python 版本	Python 3.8+
浏览器	Chrome 90+、Firefox 88+、Safari 14+、Edge 90+
移动端	iOS Safari 14+、Android Chrome 90+

4.4 安全要求

局域网访问安全：

安全项	方案	说明
访问控制	仅监听 0.0.0.0，通过防火墙限制访问来源	只允许内网 IP 段访问（如 192.168.0.0/16）
身份验证	可选配置基本 HTTP 认证（用户名 + 密码）	防止未授权访问，密码通过配置文件管理
日志记录	所有访问和操作记录日志	包含时间、IP、操作类型、结果
命令注入防护	Web 界面不接受任何命令行输入	防止用户通过界面执行任意命令

4.5 可靠性要求

指标	要求	说明
服务可用性	≥ 99%	月累计不可用时间 < 7.2 小时
数据持久化	100%	已抓取数据不丢失，异常情况自动备份
断电恢复	自动恢复服务	系统重启后服务自动拉起（通过 systemd）

---

5. 系统架构设计

5.1 技术选型

模块	技术栈	选型理由
数据抓取	Python + requests + BeautifulSoup4	成熟的网页抓取方案，社区支持好
数据存储	openpyxl	原生支持 Excel 读写，无需安装 Office
Web 服务	Flask	轻量级，易部署，适合内部工具
定时任务	Linux Cron	系统原生支持，稳定可靠
前端	HTML + CSS + JavaScript (jQuery)	简单直接，无需构建流程
日志	Python logging	标准库支持，灵活配置

5.2 目录结构

/home/vincent/Studio/lottoData/
├── lottery.py              # 号码生成器（现有）
├── 双色球历史数据.xlsx      # 数据存储（现有）
├── scraper.py              # 数据抓取脚本（新建）
├── app.py                  # Flask Web 应用（新建）
├── config.py               # 配置文件（新建）
├── templates/              # HTML 模板（新建）
│   └── index.html
├── static/                 # 静态资源（新建）
│   ├── css/
│   └── js/
├── logs/                   # 日志目录（新建）
│   └── lottery.log
└── requirements.txt        # Python 依赖（新建）

5.3 定时任务配置

Cron 配置示例：

# 每天 21:30 执行数据抓取
30 21 * * * cd /home/vincent/Studio/lottoData && /usr/bin/python3 scraper.py >> logs/cron.log 2>&1

Systemd 服务配置（Web 服务）：

# /etc/systemd/system/lottery-web.service
[Unit]
Description=Lottery Data Web Service
After=network.target

[Service]
Type=simple
User=vincent
WorkingDirectory=/home/vincent/Studio/lottoData
ExecStart=/usr/bin/python3 app.py
Restart=always

[Install]
WantedBy=multi-user.target

5.4 页面流程图

用户访问 Web 界面
    ↓
加载首页（显示最新开奖数据 + 历史数据）
    ↓
┌──────────────┬──────────────┬──────────────┐
│              │              │              │
▼              ▼              ▼              ▼
手动触发抓取    查看历史数据    配置定时任务    监控抓取状态
    ↓              ↓              ↓              ↓
显示执行日志    分页/搜索查看   修改执行时间    查看上次抓取结果
    ↓              ↓              ↓              ↓
更新数据表      导出数据        保存配置        显示下次执行时间

---

6. 接口设计

6.1 Web 接口

接口路径	方法	描述	请求参数	返回格式
/	GET	首页 - 数据展示	无	HTML
/api/scrape	POST	手动触发抓取	无	JSON {"status": "success", "message": "..."}
/api/status	GET	获取系统状态	无	JSON {last_scrape_time, next_scheduled_time, status}
/api/history	GET	获取历史数据	page, limit, search	JSON {"data": [...], "total": N}
/api/config	GET	获取定时任务配置	无	JSON
/api/config	POST	更新定时任务配置	enabled, cron_expr	JSON {"status": "success"}

6.2 日志格式

[2026-06-19 21:30:01 INFO] 开始抓取数据...
[2026-06-19 21:30:02 INFO] 成功访问数据源页面
[2026-06-19 21:30:05 INFO] 解析到 120 条数据
[2026-06-19 21:30:06 INFO] 本地现有数据：118 条
[2026-06-19 21:30:06 INFO] 新增数据：2 条 (2026069, 2026068)
[2026-06-19 21:30:07 INFO] 数据保存到 Excel 成功
[2026-06-19 21:30:07 INFO] 抓取完成，耗时 6.2 秒

---

7. 排期建议

7.1 开发阶段划分

阶段	任务	预计耗时	依赖
阶段 1	数据抓取脚本开发（scraper.py）	2 小时	无
阶段 2	Web 服务开发（app.py + templates）	3 小时	阶段 1 完成
阶段 3	定时任务配置和系统部署	1 小时	阶段 2 完成
阶段 4	测试和优化	2 小时	阶段 3 完成

总预计耗时：8 小时

7.2 关键依赖

1. 服务器访问权限：需要能访问目标网站（55128.cn）
2. Python 环境：需要安装 Python 3.8+ 和依赖包
3. 局域网网络：确保局域网内设备可以访问服务端口

---

8. 风险与应对

8.1 需求风险

风险	影响	概率	应对方案
数据源网站结构变化	抓取脚本失效	中	1. 添加结构变更检测 2. 建立告警机制 3. 定期维护更新
数据源网站反爬策略	被封 IP	低	1. 控制请求频率 2. 添加 User-Agent 3. 必要时使用代理

8.2 技术风险

风险	影响	概率	应对方案
Excel 文件被占用	写入失败	低	1. 写入前检查文件锁 2. 使用临时文件 + 原子替换 3. 失败后重试
网络不稳定	抓取失败	中	1. 实现重试机制 2. 记录失败原因 3. 邮件/消息告警
端口冲突	Web 服务启动失败	低	1. 启动前检查端口占用 2. 支持配置端口 3. 日志明确提示

8.3 安全风险

风险	影响	概率	应对方案
未授权访问	数据泄露	中	1. 防火墙限制 IP 范围 2. 可选 HTTP 认证 3. 访问日志审计
恶意请求	服务崩溃	低	1. 请求频率限制 2. 异常输入过滤 3. 服务监控

---

9. 验收标准

9.1 功能验收

• 数据抓取：能从 55128.cn 成功抓取近 120 期数据
• 增量更新：不产生重复数据，仅添加缺失期数
• Web 界面：能手动触发抓取并实时查看日志
• 数据展示：首页展示最新开奖号码和历史数据表
• 定时任务：配置 cron 后每天自动执行
• 局域网访问：其他设备能访问 Web 服务

9.2 质量验收

• 数据准确性：与官方网站数据 100% 一致
• 性能达标：页面加载时间 < 2 秒（局域网）
• 日志完整：所有关键操作都有日志记录
• 错误处理：异常情况有明确提示和日志

9.3 文档验收

• README 文档：包含安装、配置、使用说明
• 依赖清单：requirements.txt 完整列出 Python 依赖
• 部署文档：Systemd 服务配置说明

---

10. 后续优化建议

10.1 短期优化（1 个月内）

1. 数据可视化：增加号码分布图、冷热号统计等图表
2. 告警通知：抓取失败时通过邮件/微信通知
3. 数据备份：每天自动备份 Excel 文件到云存储

10.2 中期优化（3 个月内）

1. 数据库升级：使用 SQLite/MySQL 替代 Excel，支持更复杂查询
2. API 开放：提供 REST API 供其他系统调用
3. 多彩种支持：扩展支持大乐透、福彩 3D 等其他彩票

10.3 长期优化（6 个月内）

1. 数据分析平台：集成数据分析工具，提供智能预测
2. 移动端 App：开发 iOS/Android 应用
3. 多用户系统：支持多个用户独立配置和使用

---

附录

A. 依赖包清单

# requirements.txt
requests==2.31.0
beautifulsoup4==4.12.2
openpyxl==3.1.2
flask==3.0.0
lxml==4.9.3

B. 配置文件示例

# config.py
import os

# 系统配置
BASE_DIR = os.path.dirname(os.path.abspath(__file__))
DATA_FILE = os.path.join(BASE_DIR, '双色球历史数据.xlsx')
LOG_FILE = os.path.join(BASE_DIR, 'logs', 'lottery.log')

# 数据源
DATA_SOURCE_URL = 'https://www.55128.cn/kjh/fcssq-history-120.htm'

# Web 服务配置
WEB_HOST = '0.0.0.0'
WEB_PORT = 5000
DEBUG = False

# 定时任务配置
CRON_ENABLED = True
CRON_EXPR = '30 21 * * *'  # 每天 21:30

# 安全配置（可选）
AUTH_ENABLED = False
AUTH_USERNAME = 'admin'
AUTH_PASSWORD = 'your_password_here'  # 建议通过环境变量设置

C. 数据来源说明

• 数据源：彩吧助手 (www.55128.cn)
• 数据更新时间：每周二、四、日 21:15 开奖
• 建议抓取时间：开奖后 15 分钟（21:30）

---

PRD 评审人： 承哥
PRD 创建日期： 2026-06-19
下次评审日期： 开发完成后验收评审