Lottery/docs/PRD-操作界面系统.md

产品需求文档（PRD）：双色球操作界面系统

1. 背景与目标

业务背景

基于已有的 lottery.py 号码生成逻辑，需要开发一个 Web 操作界面系统，让用户可以通过 PC 网页端和手机端方便地操控双色球号码生成、查看历史数据、管理生成记录。系统需支持远程访问，生成的数据可随时读取。

解决的问题

1. 命令行操作门槛高，普通用户难以使用
2. 无法随时随地访问和管理数据
3. 缺少可视化的数据展示和管理界面
4. 生成的 Excel 文件分散，难以统一管理

成功指标

• PC 和手机端均可正常访问操作
• 核心功能（生成号码、查看历史、下载数据）100% 可用
• 内网环境下远程访问响应时间 < 2 秒
• 数据导出成功率 100%

---

2. 用户故事

角色	用户故事	价值
普通用户	作为用户，我希望通过手机浏览器生成双色球号码，以便随时随地选号	移动便利性
数据管理员	作为管理员，我希望查看历史数据和生成记录，以便分析趋势	数据可追溯
分析师	作为分析师，我希望导出 Excel 数据进行深度分析，以便制定策略	数据可复用
运维人员	作为运维，我希望系统监听 0.0.0.0 并避免端口冲突，以便内网多设备访问	部署便利性

---

3. 功能需求

3.1 核心功能模块

模块一：号码生成

功能点	描述	优先级	验收标准
选择策略	用户可选择"高级策略"或"基础策略"	P0	默认选中高级策略，切换无延迟
输入注数	用户输入要生成的注数（1-1000）	P0	有输入验证，超出范围提示错误
立即生成	点击按钮后生成号码并在页面展示	P0	生成时间 < 3 秒（100 注内）
展示结果	以表格形式展示生成的号码，包含和值、奇偶比、大小比、跨度	P0	红球以蓝色圆形展示，蓝球以红色圆形展示
保存 Excel	将生成结果保存为 Excel 文件并提供下载	P0	文件格式正确，包含"生成号码"和"统计信息"两个 sheet

模块二：历史数据查看

功能点	描述	优先级	验收标准
热力图展示	展示红球热号/冷号、蓝球热号	P0	用颜色深浅表示频率，支持排序切换
统计面板	显示最常见奇偶比、大小比、和值范围、跨度范围	P1	数据与 lottery.py 计算结果一致
历史期数列表	展示双色球历史开奖数据列表	P1	支持分页，每页 20 条，支持按期号搜索

模块三：生成记录管理

功能点	描述	优先级	验收标准
记录列表	展示所有历史生成记录（时间、策略、注数、文件）	P0	按时间倒序排列，支持分页
文件下载	提供历史生成文件的下载链接	P0	点击即可下载，文件名包含日期和注数
记录删除	允许用户删除单条或多条生成记录	P2	删除前有二次确认，删除后同步删除文件

模块四：数据导出 API

功能点	描述	优先级	验收标准
RESTful API	提供 GET /api/latest 接口获取最新生成数据	P1	返回 JSON 格式，包含所有字段
API 认证	简单 Token 认证机制	P1	请求需携带 Authorization header
CORS 支持	允许跨域访问	P1	配置 Access-Control-Allow-Origin

3.2 界面设计要求

PC 网页端

• 响应式布局，支持主流浏览器（Chrome、Firefox、Edge、Safari）
• 左侧导航栏：首页（生成）、历史数据、生成记录、系统设置
• 主内容区自适应宽度
• 生成号码页面：上方为策略选择和注数输入，中间为结果展示区，下方为操作按钮

手机端

• 采用移动优先设计，触摸操作友好
• 底部导航栏：首页、数据、记录
• 生成号码页面：顶部为策略选择（下拉框），中间为注数输入（数字键盘），下方为生成按钮
• 结果展示支持横向滑动查看完整信息
• 字体大小适配移动端，关键信息（号码）字号放大

3.3 非功能需求

性能要求

• 页面加载时间 < 2 秒（内网环境）
• 号码生成响应时间 < 3 秒（100 注内）
• 支持并发用户数：5 个同时操作

兼容性要求

• PC 端：Chrome 80+、Firefox 75+、Edge 80+、Safari 13+
• 移动端：iOS Safari 13+、Android Chrome 80+
• 屏幕适配：PC（1280x720 及以上）、手机（375x667 及以上）

安全要求

• 内网访问限制：通过防火墙规则限制仅内网 IP 可访问
• 简单认证：配置文件存储访问 Token，防止未授权访问
• 文件访问控制：仅允许下载 lottery 目录下的文件，防止目录遍历攻击

部署要求

• 监听地址：0.0.0.0（支持内网任意设备访问）
• 端口：提前与运维确认未使用端口（建议 8080-8099 范围内）
• 服务器：192.168.1.99，路径 ~/Studio/lottoData/
• 进程保活：使用 systemd 或 supervisor 确保服务异常后自动重启

---

4. 技术架构

4.1 技术栈选择

层级	技术	理由
后端框架	Flask	轻量级，与现有 lottery.py 兼容性好
前端框架	Vue.js 3 + Element Plus	响应式支持好，组件丰富
移动端适配	Vant UI	移动端组件库，触摸友好
数据存储	本地文件系统	保持现有 Excel 存储方式，无需数据库
API 文档	Swagger/OpenAPI	便于调试和集成

4.2 系统架构图

┌─────────────────────────────────────────────────────────┐
│                    用户设备层                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│  │  PC 浏览器   │    │  手机浏览器  │    │  API 客户端   │  │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘  │
│         │                  │                  │          │
│         └──────────────────┼──────────────────┘          │
│                           │ HTTP/HTTPS                    │
└───────────────────────────┼───────────────────────────────┘
                            │
┌───────────────────────────┼───────────────────────────────┐
│                    应用服务层 (Flask)                      │
│  ┌────────────────────────┴────────────────────────┐     │
│  │                路由控制器                        │     │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐      │     │
│  │  │ 号码生成  │  │ 历史数据  │  │ 记录管理  │      │     │
│  │  └──────────┘  └──────────┘  └──────────┘      │     │
│  └─────────────────────────────────────────────────┘     │
│                           │                               │
│  ┌────────────────────────┴────────────────────────┐     │
│  │              业务逻辑层                           │     │
│  │         (集成 lottery.py 核心逻辑)                │     │
│  └─────────────────────────────────────────────────┘     │
│                           │                               │
│  ┌────────────────────────┴────────────────────────┐     │
│  │                数据访问层                         │     │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐      │     │
│  │  │ Excel 读写│  │ 文件管理  │  │ 缓存管理  │      │     │
│  │  └──────────┘  └──────────┘  └──────────┘      │     │
│  └─────────────────────────────────────────────────┘     │
└───────────────────────────────────────────────────────────┘
                            │
┌───────────────────────────┼───────────────────────────────┐
│                    数据存储层                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐   │
│  │历史数据.xlsx │    │ lottery/   │    │  配置文件   │   │
│  │             │    │ 生成文件    │    │  config.yaml│   │
│  └─────────────┘    └─────────────┘    └─────────────┘   │
└───────────────────────────────────────────────────────────┘

4.3 API 接口设计

4.3.1 号码生成

POST /api/generate
Request:
{
  "num_tickets": 10,
  "strategy": "advanced"  // 或 "basic"
}
Response:
{
  "success": true,
  "data": {
    "tickets": [...],
    "filename": "lottery/双色球模拟号码 -10 注 -20260619-001.xlsx",
    "download_url": "/api/download/lottery/双色球模拟号码 -10 注 -20260619-001.xlsx"
  }
}

4.3.2 获取统计数据

GET /api/statistics
Response:
{
  "success": true,
  "data": {
    "hot_reds": [1, 7, 13, 19, 23, 27, 31, 5, 11, 17],
    "cold_reds": [2, 8, 14, 20, 26, 32, 4, 10, 16, 22],
    "hot_blues": [3, 7, 11, 15, 9],
    "common_odd_even": "3:3",
    "common_size_ratio": "3:3",
    "sum_range": {"min": 73, "max": 148, "mean": 105.5},
    "span_range": {"min": 11, "max": 32, "mean": 23.8}
  }
}

4.3.3 获取生成记录

GET /api/records?page=1&page_size=20
Response:
{
  "success": true,
  "data": {
    "records": [
      {
        "id": "uuid",
        "created_at": "2026-06-19T10:30:00Z",
        "strategy": "advanced",
        "num_tickets": 10,
        "filename": "lottery/双色球模拟号码 -10 注 -20260619-001.xlsx",
        "download_url": "/api/download/..."
      }
    ],
    "total": 150,
    "page": 1,
    "page_size": 20
  }
}

4.3.4 下载文件

GET /api/download/{filepath}
Headers: Authorization: Bearer {token}
Response: 文件流 (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet)

4.3.5 获取最新数据（API 客户端用）

GET /api/latest
Headers: Authorization: Bearer {token}
Response:
{
  "success": true,
  "data": {
    "latest_record": {...},
    "statistics": {...}
  }
}

---

5. 原型与界面设计

5.1 页面流程图

首页
 ├── 选择策略（高级/基础）
 ├── 输入注数
 ├── 点击"生成号码"
 │    └── 加载动画（生成中...）
 │         └── 展示结果表格
 │              ├── 查看前 10 注（默认）
 │              ├── 展开查看全部
 │              ├── 下载 Excel
 │              └── 继续生成
 │
历史数据
 ├── 热力图（红球/蓝球）
 ├── 统计面板
 └── 历史期数列表（分页）
 │
生成记录
 ├── 记录列表（时间倒序）
 ├── 搜索（按期号/日期）
 └── 单条操作：下载 | 删除
 │
系统设置
 ├── 端口配置
 ├── Token 管理
 └── 文件存储路径

5.2 关键界面描述

界面 1：首页 - 号码生成（PC 端）

┌────────────────────────────────────────────────────────┐
│  Logo   双色球号码生成系统          [历史数据] [生成记录]   │
├────────────────────────────────────────────────────────┤
│                                                        │
│  ┌──────────────────────────────────────────────────┐ │
│  │  生成策略：○ 高级策略  ○ 基础策略                  │ │
│  │  生成注数：[____] 注 (1-1000)                     │ │
│  │                                                  │ │
│  │           [   立即生成   ]                        │ │
│  └──────────────────────────────────────────────────┘ │
│                                                        │
│  生成结果                                              │
│  ┌──────────────────────────────────────────────────┐ │
│  │ 序号 │ 红球 1 │ 红球 2 │ ... │ 蓝球 │ 和值 │ 奇偶比│ │
│  │  001 │  05  │  12  │ ... │  09  │  87  │  3:3  │ │
│  │  002 │  08  │  15  │ ... │  14  │  92  │  4:2  │ │
│  │  ... │  ... │  ... │ ... │  ... │  ... │  ...  │ │
│  └──────────────────────────────────────────────────┘ │
│                                                        │
│  [下载 Excel]  [继续生成]                              │
│                                                        │
└────────────────────────────────────────────────────────┘

界面 2：首页 - 号码生成（手机端）

┌─────────────────────────┐
│  双色球号码生成系统      │
├─────────────────────────┤
│                         │
│  策略：[高级策略 ▼]     │
│  注数：[____]           │
│                         │
│    [  立即生成  ]       │
│                         │
│  ┌───────────────────┐ │
│  │ 第 001 注           │ │
│  │ 🔴 05 12 19 23 27 │ │
│  │    31 🔵 09       │ │
│  │ 和值 87 奇偶 3:3   │ │
│  └───────────────────┘ │
│                         │
│  [下载] [继续]          │
│                         │
├─────────────────────────┤
│ 首页 │ 数据 │ 记录      │
└─────────────────────────┘

界面 3：历史数据 - 热力图

┌────────────────────────────────────────────────────────┐
│  红球热力图（出现频次）                                   │
│                                                        │
│  01 [████████] 120 次    17 [██████████] 135 次        │
│  02 [██████]   95 次     18 [████████]   122 次        │
│  03 [████████████] 142 次 19 [██████████]  138 次      │
│  ...                                                 │
│                                                        │
│  蓝球热力图                                            │
│  01 [██████]   88 次     09 [████████]   118 次       │
│  02 [████]     75 次     10 [██████]     92 次        │
│  ...                                                 │
└────────────────────────────────────────────────────────┘

---

6. 排期建议

开发排期（参考历史估算）

阶段	任务	预估工时	负责人
第一阶段	Flask 后端框架搭建 + 集成 lottery.py	4 小时	徐聪
第二阶段	API 接口开发（生成、查询、下载）	6 小时	徐聪
第三阶段	PC 端前端页面开发（Vue3 + Element Plus）	8 小时	苏锦绘
第四阶段	移动端适配（Vant UI）	6 小时	苏锦绘
第五阶段	部署配置 + 端口协调 + 系统测试	4 小时	严维序
第六阶段	产品验收 + Bug 修复	4 小时	沈路明

总预估工时: 32 小时（约 4 个工作日）

关键依赖

• 运维需提前确认 192.168.1.99 服务器上的可用端口
• lottery.py 业务逻辑已审核通过，无需调整
• 历史数据文件路径：~/Studio/lottoData/双色球历史数据.xlsx

---

7. 风险与应对

需求风险

风险	概率	影响	应对方案
移动端适配工作量大	中	中	优先保证核心功能，复杂交互在 PC 端使用
用户对 Excel 格式有特殊要求	低	低	保留配置扩展性，支持自定义列

技术风险

风险	概率	影响	应对方案
端口冲突	中	高	提前与运维确认端口表，配置文件中可调整端口
大文件下载超时	低	中	添加进度条，支持断点续传
并发访问性能瓶颈	低	中	限制单 IP 请求频率，添加请求队列

安全风险

风险	概率	影响	应对方案
内网穿透导致外网访问	低	高	防火墙规则限制，仅允许内网网段
Token 泄露	中	中	定期更换 Token，配置文件权限限制

---

8. 部署与运维

8.1 服务器配置

• 服务器: 192.168.1.99
• 路径: ~/Studio/lottoData/
• 账号: vincent
• 监听: 0.0.0.0:{PORT}（PORT 由运维分配）
• 进程管理: systemd 或 supervisor

8.2 端口分配要求

请运维工程师提前维护各服务器端口使用表，本项目需分配一个未使用的端口（建议范围 8080-8099）。

8.3 防火墙规则

# 仅允许内网访问
iptables -A INPUT -p tcp --dport {PORT} -s 192.168.0.0/16 -j ACCEPT
iptables -A INPUT -p tcp --dport {PORT} -j DROP

8.4 服务启动脚本

# systemd 配置示例
[Unit]
Description=Lottery Web Service
After=network.target

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

[Install]
WantedBy=multi-user.target

---

9. 验收标准

功能验收

• PC 端可正常访问并完成号码生成、查看历史、下载文件
• 手机端可正常访问并完成核心操作
• 数据导出 API 可被远程调用
• 生成的 Excel 文件与 lottery.py 直接运行结果一致

性能验收

• 页面加载时间 < 2 秒（内网）
• 100 注号码生成时间 < 3 秒
• 支持 5 个并发用户同时操作

安全验收

• 外网无法访问服务（防火墙限制）
• 未携带 Token 无法调用 API
• 无法通过路径遍历访问非 lottery 目录文件

---

10. 版本历史

版本	日期	变更内容	作者
v1.0	2026-06-19	初始版本，基于 lottery.py 业务逻辑	沈路明

---

11. 附录

11.1 数据字段定义

生成号码表字段:

• 序号：数字，从 1 开始
• 红球 1-6：数字 1-33
• 蓝球：数字 1-16
• 和值：6 个红球之和
• 奇偶比：格式 "X:Y"，如 "3:3"
• 大小比：格式 "X:Y"，如 "3:3"
• 跨度：最大红球 - 最小红球

统计信息表字段:

• 生成时间：DateTime
• 生成策略：Text ("高级策略" 或 "基础策略")
• 生成注数：Integer
• 红球热号：Text (逗号分隔)
• 红球冷号：Text (逗号分隔)
• 蓝球热号：Text (逗号分隔)
• 最常见奇偶比：Text
• 最常见大小比：Text
• 和值范围：Text ("最小值 - 最大值")
• 跨度范围：Text ("最小值 - 最大值")

11.2 配置文件示例 (config.yaml)

server:
  host: 0.0.0.0
  port: 8085  # 运维分配的端口
  
security:
  api_token: "your-secret-token-here"
  allowed_networks:
    - "192.168.0.0/16"
    
storage:
  history_file: "双色球历史数据.xlsx"
  output_dir: "lottery"
  
display:
  default_tickets: 10
  max_tickets: 1000
  tickets_per_page: 20

---

PRD 完成时间: 2026-06-19
产品经理: 沈路明
状态: 待评审