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 配置示例：**
```bash
# 每天 21:30 执行数据抓取
30 21 * * * cd /home/vincent/Studio/lottoData && /usr/bin/python3 scraper.py >> logs/cron.log 2>&1
```

**Systemd 服务配置（Web 服务）：**
```ini
# /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. 添加结构变更检测<br>2. 建立告警机制<br>3. 定期维护更新 |
| 数据源网站反爬策略 | 被封 IP | 低 | 1. 控制请求频率<br>2. 添加 User-Agent<br>3. 必要时使用代理 |

### 8.2 技术风险

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

### 8.3 安全风险

| 风险 | 影响 | 概率 | 应对方案 |
|------|------|------|----------|
| 未授权访问 | 数据泄露 | 中 | 1. 防火墙限制 IP 范围<br>2. 可选 HTTP 认证<br>3. 访问日志审计 |
| 恶意请求 | 服务崩溃 | 低 | 1. 请求频率限制<br>2. 异常输入过滤<br>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. 依赖包清单

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

### B. 配置文件示例

```python
# 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  
**下次评审日期：** 开发完成后验收评审