# 产品需求文档（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 评审准备就绪，邀请架构师（梁思筑）和开发（徐聪）参与评审。**