data-management

name	data_management
description	彩票数据管理手册，包含数据抓取、增量更新逻辑及多彩种数据预处理规则。

彩票数据管理手册

本项目的数据流程分为 数据同步 (Sync) 和 数据处理 (Process) 两个核心环节。本手册详细记录了相关的逻辑与规则。

1. 数据同步逻辑 (Data Synchronization)

数据同步主要由 request_data_update.py 负责，采用增量同步与覆盖更新相结合的策略。

1.1 增量/覆盖同步策略

为了解决中奖详情（winnerDetails）可能延迟发布的问题，同步逻辑遵循以下规则：

• 抓取范围：每次同步尝试获取官方接口最近的 100 条记录。
• 期号匹配：对比本地最新期号（local_latest），抓取所有期号 >= local_latest 的数据。
• 覆盖更新：使用 >= 而非 > 是为了确保本地最新的一期能够被重新抓取。如果官方在中奖数据到账后更新了列表，本地记录将被最新的、含完整中奖信息的记录覆盖。
• 去重处理：合并数据后，按期号降序排列并执行 drop_duplicates，确保每期仅保留最新抓取到的版本。

1.2 异常处理

• 接口校验：同步前会对比 local_latest 与系统总期数。如果本地已是最新，则跳过抓取。
• 格式归一化：不同彩种的期号格式（长/短格式）在对比前会进行归一化处理（由 normalize_issue 函数执行）。

---

2. 数据处理规则 (Data Processing Rules)

数据预处理由 request_process_all_data.py 负责，核心目标是将原始 JSON 响应转化为标准化的分析特征。

2.1 奖级映射与归一化

程序根据官方备注（remark）和奖级 ID（awardEtc）进行智能映射：

• 双色球 (SSQ)：
  • 识别 1-6 等奖。
  • 福运奖：第 7 顺位奖项或备注为“福运奖”的记录映射为标准 福运奖 字段。
• 超级大乐透 (DLT)：
  • 支持 1-9 等奖。
  • 追加数据：仅大乐透保留 追加注数 和 追加奖金 字段。
• 福彩3D / 排列三 / 排列五：
  • 映射为 直选 / 单选、组选三、组选六 等特定奖项名称。

2.2 字段自动清理 (Generalized Column Cleanup)

为了保持数据纯净，程序会执行严格的列清理：

• 白名单机制：基于每个彩种定义的 unique_tiers 动态生成允许的列名集合。
• 无用列删除：
  • 自动删除非当前彩种定义的奖级列（如双色球中的 七等奖 或 追加* 相关列）。
  • 自动清理历史遗留的错误列（如 3D 数据中误存的 一等奖 字样列）。
  • 仅保留 注数、奖金 以及（仅限大乐透）追加* 相关后缀的奖项列。

2.3 特征工程

预处理阶段会自动计算以下统计指标：

• 基础指标：和值、跨度、奇偶比、大小比。
• 连号/跳号：二连、三连及以上，二跳、三跳等。
• 形态指标：AC 值、重号、邻号、孤号。
• 区域分布：根据三区划分逻辑计算各区分布情况。

---

3. 运行指南

• 同步最新数据：执行 python request_data_update.py。
• 全局重处理：如果需要重新生成所有历史数据的特征或应用新的清理规则，执行 python request_process_all_data.py。

---

上次更新：2026-03-13