# 开发文档：双色球 Web UI 系统

**版本**: v1.0  
**开发人员**: 徐聪（costcodev）  
**日期**: 2026-07-03  
**Issue**: BIZ-75  

---

## 1. 项目概述

双色球自动化系统 Web UI，提供号码生成、历史数据查看、生成记录管理和统计分析功能。支持 PC 端和移动端响应式访问，监听 0.0.0.0:8085，局域网可访问。

## 2. 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| 后端 | Python 3 + Flask | REST API 服务 |
| 前端 | 原生 HTML/CSS/JS | 单文件，响应式布局 |
| 数据分析 | Pandas + NumPy | 号码统计分析 |
| 数据存储 | Excel + JSON | 历史数据 + 生成记录 |
| 部署 | systemd / nohup | Linux 服务部署 |

## 3. 目录结构

```
lottoData/
├── app.py                    # Flask 主服务（统一入口）
├── index.html                # 前端 UI（响应式，4 Tab 页面）
├── lottery.py                # 号码生成核心逻辑
├── fetch_data.py             # 历史数据抓取脚本
├── web_console.html          # 数据抓取控制台前端
├── requirements.txt          # Python 依赖
├── 双色球历史数据.xlsx        # 历史数据文件
├── lottery/                  # 号码生成结果输出目录
├── .generation_records.json  # 生成记录索引（JSON）
├── .fetch_status.json        # 抓取状态文件
├── deploy/                   # 部署相关文件
│   ├── DEPLOY.md             # 部署说明
│   ├── lotto-app.service     # systemd 服务文件
│   ├── fetch_daily.sh        # 定时抓取脚本
│   └── backup.sh             # 备份脚本
└── docs/                     # 文档目录
    ├── PRD-双色球 WebUI-v1.0.md
    └── 开发文档-双色球WebUI-v1.0.md  ← 本文件
```

## 4. API 接口

### 4.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 | 前端配置 | 无 |
| `/api/fetch/status` | GET | 抓取执行状态 | 无 |
| `/api/fetch/execute` | POST | 触发数据抓取 | 无 |

### 4.2 关键接口参数

#### POST /api/generate
```json
// 请求
{
  "num_tickets": 10,
  "strategy": "advanced"  // 或 "basic"
}
// 响应
{
  "success": true,
  "data": {
    "tickets": [...],
    "total": 10,
    "filename": "lottery/xxx.xlsx",
    "download_url": "/api/download/lottery/xxx.xlsx",
    "record": {...},
    "statistics": {...}
  }
}
```

#### GET /api/history
参数: `page` (页码), `page_size` (每页条数), `search` (搜索关键词)

#### GET /api/records
参数: `page` (页码), `page_size` (每页条数)

## 5. 前端页面

### 5.1 页面结构
- **Header**: 标题 + 副标题
- **导航 Tab**: 号码生成 | 历史数据 | 生成记录 | 统计分析
- **移动端**: 底部固定导航栏

### 5.2 功能页面

#### 号码生成页（首页）
- 统计概览（历史期数、常见奇偶比、和值范围等）
- 策略选择（高级策略/基础策略）
- 注数输入（1-1000）
- 生成结果展示（红球+蓝球+统计指标）
- Excel 下载按钮

#### 历史数据页
- 搜索框（500ms 防抖）
- 数据表格（期号、日期、红球、蓝球、统计字段）
- 分页控件

#### 生成记录页
- 记录列表（策略、注数、时间、文件大小）
- 下载/删除操作
- 分页控件

#### 统计分析页
- 历史开奖期数
- 红球热号 TOP15 / 冷号 TOP15
- 蓝球热号 TOP8
- 奇偶比/大小比/和值/跨度统计

## 6. 关键修复说明

### 6.1 数据格式兼容修复（核心 Bug 修复）

**问题**: `lottery.py` 期望 Excel 含"号码"列（拼接格式如 `08121821243001`），但 `fetch_data.py` 抓取的 Excel 使用分列格式（"红球 1"~"红球 6"+"蓝球"），导致号码生成器无法加载历史数据。

**根因**: Excel 文件包含两行 header：
- Row 0: 新格式列名（期号、开奖日期、红球 1~6、蓝球、特别号）
- Row 1: 旧格式列名（开奖时间、期数、号码、开机号、...）
- Row 2+: 实际数据

**修复方案**:
1. `lottery.py` 的 `load_history_data()`: 添加多格式检测逻辑，识别格式A（双行 header）并自动跳过，使用旧列名作为标准列名
2. `lottery.py` 的 `parse_numbers()`: 新增对拼接字符串格式（14位无分隔符）的直接解析，避免 `re.findall` 将整个字符串视为一个数字
3. `app.py` 的 `load_history_dataframe()`: 同步修复多格式兼容逻辑

### 6.2 线程安全

- 生成记录的读-改-写操作使用 `threading.Lock` 保护
- 文件写入使用临时文件+原子替换（`os.replace`），防止崩溃导致数据损坏

## 7. 部署方式

### 7.1 直接运行
```bash
cd /home/vincent/Studio/lottoData
source .venv/bin/activate
python3 app.py
# 访问 http://localhost:8085
```

### 7.2 systemd 服务
```bash
# 服务文件: deploy/lotto-app.service
sudo cp deploy/lotto-app.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable lotto-app
sudo systemctl start lotto-app
```

### 7.3 定时数据抓取
```bash
# 添加 cron 任务
crontab -e
# 每天 02:30 自动抓取最新数据
30 2 * * * /home/vincent/Studio/lottoData/deploy/fetch_daily.sh >> /home/vincent/Studio/lottoData/deploy/cron.log 2>&1
```

## 8. 测试验证

### 8.1 API 测试结果

| 接口 | 状态 | 说明 |
|------|------|------|
| GET /api/status | ✅ 通过 | 返回服务状态 |
| GET /api/statistics | ✅ 通过 | 120条历史数据统计正确 |
| GET /api/history | ✅ 通过 | 分页+红蓝球解析正确 |
| POST /api/generate | ✅ 通过 | 5注号码生成成功，含统计 |
| GET /api/records | ✅ 通过 | 生成记录列表正确 |
| GET / (前端页面) | ✅ 通过 | HTML 页面正常加载 |

### 8.2 数据格式验证
- 历史数据: 120 条记录全部成功解析 ✅
- 红球解析: 6个红球正确提取 ✅
- 蓝球解析: 1个蓝球正确提取 ✅
- 号码范围校验: 1-33(红) + 1-16(蓝) ✅

## 9. 已知限制

- 前端为单 HTML 文件，未使用构建工具
- 无用户登录系统（Token 认证为可选项，默认关闭）
- 历史数据来源为 55128.cn，如网站改版需更新 `fetch_data.py`
- 不支持 HTTPS（内网环境）

## 10. 后续优化建议

| 功能 | 优先级 | 说明 |
|------|--------|------|
| 数据可视化图表 | P2 | 走势图、分布图 |
| 用户登录系统 | P2 | 多用户权限管理 |
| 定时自动生成 | P2 | 定时生成+推送 |
| 微信推送 | P3 | 生成结果推送至微信 |
| 多彩种支持 | P3 | 大乐透、福彩 3D 等 |

---

**开发完成日期**: 2026-07-03  
**代码仓库**: http://192.168.1.99:12299/vincent/Lottery.git  
**开发人员**: 徐聪（costcodev）