# Data Management

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

- Skill: `konglr/data-management` (Agent Skill)
- Install (CLI): `npx skillmds@latest add konglr/data-management`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konglr/data-management/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: konglr (https://skillmd.com/u/konglr)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/konglr/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*