4. 告警数据结构：标准PSI告警字段定义、字段类型与约束、自定义扩展字段

PSI告警回放验证的核心操作对象是告警事件。告警数据结构定义了规则引擎在回放过程中需要解析、匹配和输出的数据载体。一个标准化的告警数据结构能够确保回放结果的可比性、可追溯性以及跨系统的一致性。

本章将告警数据结构拆解为三个层次：标准必选字段、字段类型与约束、自定义扩展字段。理解这三个层次，是后续进行PSI计算和回放验证的基础。

4.1 标准PSI告警字段定义

标准PSI告警字段是所有参与回放验证的告警事件必须包含的公共属性。这些字段构成了告警的身份标识和时间轴基准。下表列出了核心的标准字段及其语义说明：

4.2 字段类型与约束

字段类型与约束定义了告警数据在规则引擎中的存储格式和合法性校验规则。在回放验证中，字段类型不匹配是导致规则引擎解析异常或PSI计算失败的常见原因。

4.2.1 字段类型分类

• 字符串类型（String）： 用于存储实体ID、规则ID、告警类型等标识性数据。约束：长度上限通常为256字符，禁止包含不可见控制字符。
• 数值类型（Numeric）： 用于存储风险评分、金额、次数等可计算数据。约束：支持整数（Int64）和浮点数（Double），精度需在字段定义中明确。
• 时间类型（Timestamp）： 用于存储事件时间、处理时间等。约束：统一使用UTC时间戳（毫秒级），格式为 yyyy-MM-dd'T'HH:mm:ss.SSS'Z'。
• 枚举类型（Enum）： 用于存储风险等级、状态等有限取值集合。约束：取值必须在预定义枚举列表中，大小写敏感。
• 复合类型（Map / List）： 用于存储键值对或数组结构。约束：Map的Key必须为字符串，Value类型需在Schema中声明。

4.2.2 约束规则示例

// 标准告警字段约束定义（伪代码）
FieldConstraint {
  field: "risk_level"
  type: "Enum"
  allowedValues: ["LOW", "MEDIUM", "HIGH", "CRITICAL"]
  nullable: false
  defaultValue: "LOW"
}

FieldConstraint {
  field: "event_time"
  type: "Timestamp"
  format: "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
  nullable: false
  range: [ "2020-01-01T00:00:00.000Z", "2099-12-31T23:59:59.999Z" ]
}

4.3 自定义扩展字段

标准字段无法覆盖所有业务场景。自定义扩展字段允许业务方在告警中附加业务上下文信息，用于更精细的规则匹配和PSI维度分析。扩展字段的设计应遵循扁平化和类型明确的原则。

4.3.1 扩展字段设计原则

• 前缀命名： 使用业务域缩写作为前缀，避免字段名冲突。例如：txn_amount、device_os、ip_country。
• 类型声明： 每个扩展字段必须在告警Schema中声明类型，禁止动态推断类型。
• 默认值兜底： 对于可选扩展字段，必须提供默认值，防止规则引擎在回放时因空指针异常导致计算中断。
• 版本管理： 扩展字段的增删改需要跟随告警Schema版本号，回放验证时需指定Schema版本。

4.3.2 扩展字段示例

// 自定义扩展字段定义示例
{
  "alert_id": "alert_20250321_001",
  "event_time": "2025-03-21T14:30:00.000Z",
  "rule_id": "rule_high_risk_txn",
  "entity_id": "user_10086",
  "risk_level": "HIGH",
  "alert_type": "transaction_risk",
  // 自定义扩展字段
  "ext_txn_amount": 15000.00,
  "ext_txn_currency": "CNY",
  "ext_device_os": "Android 14",
  "ext_ip_country": "CN",
  "ext_merchant_id": "merchant_9527",
  "ext_risk_tags": ["fast_transaction", "new_device"]
}

4.4 告警数据结构全景图

下图展示了标准字段、类型约束与扩展字段在告警数据结构中的整体关系。该结构是规则引擎进行PSI回放验证时的数据输入模型。

4.5 告警数据校验流程

在将告警数据导入回放验证环境之前，必须经过数据校验环节。校验流程确保告警数据结构符合规则引擎的预期，避免因数据质量问题导致PSI计算失真。

1. Schema校验： 检查告警JSON结构是否与预定义的Schema匹配，包括字段存在性、类型正确性。
2. 约束校验： 检查枚举值是否在允许列表中、时间戳是否在有效范围内、字符串长度是否超标。
3. 扩展字段校验： 检查扩展字段是否已注册、类型是否与声明一致、默认值是否生效。
4. 完整性校验： 检查必选字段是否全部非空，实体ID和规则ID是否有效。