第4章：数据采集规范 — 数据源、采集频率、字段定义

数据采集规范是 Metric Evaluation 流程的基石，决定了原始数据的质量、一致性和可用性。本章定义数据采集的全链路标准，包括数据源的认证与接入、采集频率的配置策略、字段的命名与类型约束。

适用场景

• 新评估项目初始化时，需要确定数据从哪里来、多久采集一次、字段如何映射。
• 既有数据源发生变更（如新增指标、表结构调整）后，重新编制采集规范。
• 多数据源合并或替换时，统一字段口径与采集频率。
• 自动化采集脚本 / ETL 任务首次部署前的配置确认。

前置条件

1. 已确定评估目标与指标清单（参见第1章）。
2. 已获取数据源访问凭证（API Key、数据库连接串、文件路径）。
3. 已任命数据采集负责人与数据源接口人（责任边界见后）。
4. 已创建数据存储目标表或中间管道（如 Kafka topic、S3 bucket）。

操作步骤

1. 识别并认证数据源 —— 列出所有原始数据来源（数据库、API、日志文件、埋点事件）。验证可用性与 SLA。
2. 定义字段字典 —— 为每个指标建立标准字段映射，包括字段名、数据类型、允许值、示例值。
3. 确定采集频率 —— 根据数据变更速率与评估时效要求，选择实时/分钟/小时/日/周。
4. 配置采集任务 —— 在采集调度平台（如 Airflow、Crontab）中写入任务配置，设置重试与超时策略。
5. 执行试采集并校验 —— 抽取少量数据，对照字段字典检查格式、范围、空值率。
6. 发布采集规范文档 —— 将数据源信息、频率、字段定义纳入版本控制，通知下游消费方。

输入 / 输出物

责任边界

• 数据采集负责人：维护数据源注册表，编写字段字典，配置调度任务，监控采集健康度。
• 数据源接口人：提供访问权限、元数据变更通知、异常时协助恢复。
• 评估分析师：审核字段字典是否满足指标计算需求，确认采集频率与评估周期匹配。
• 平台运维：保障采集基础设施（连接池、存储容量、网络策略）可用。

记录材料

1. data_sources.yaml —— 数据源注册与凭证引用（不包含明文密钥）
2. field_definitions.yaml —— 字段字典
3. ingestion_schedule.json —— 采集频率配置
4. collector_task_v1.py —— 采集脚本 / DAG 代码
5. data_quality_checklist.md —— 试采集校验清单与结果截图

异常处理

验收标准

• 所有数据源均通过连通性测试，延迟在 SLA 范围内。
• 字段字典中每个字段与源字段一一对应，无缺失、无映射错误。
• 采集频率与评估桶（Evaluation Bucket）对齐，无漏采或过度采集。
• 试采集结果中空值率、异常值比例低于 1%（特殊指标可放宽）。
• 采集任务日志中无 ERROR 级别异常超过连续 3 分钟。

数据采集规范核心流程

metrics:
  - name: "response_time_ms"
    type: "float"
    source_field: "api_response_ms"
    nullable: false
    constraints: [min: 0, max: 60000]
  - name: "error_rate"
    type: "float"
    source_field: "error_count / total_requests"
    nullable: true
    expression: true
  - name: "user_region"
    type: "string"
    source_field: "geo_region"
    allowed_values: ["APAC", "EMEA", "AMERS", "OTHER"]
    default: "OTHER"