data-management

# 彩票数据管理手册 本项目的数据流程分为 **数据同步 (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*