# 子模块：Observability（可观测性与打点载荷）｜Spec

## 1. 目标描述

定义推荐模块的统一可观测载荷（meta/event），用于：

- 线上监控覆盖率、回退率、候选规模分布、过滤原因分布。
- 支撑调参（权重/回退阈值/频控窗口）与风险排查（Hard Filter 命中情况）。

---

## 2. 输入 / 输出定义

### 2.1 输入

- 推荐引擎内部各阶段统计信息：
  - 候选生成数量、过滤后数量、去重后数量、频控后数量
  - 回退层级与触发原因
  - served_k
  - 缺失字段情况、conf_U

### 2.2 输出

统一的 `RecoMeta`（返回给调用方；调用方负责上报/落库/打点）：

- `scene`
- `candidate_pool_size_raw`
- `candidate_pool_size_after_hard_filter`
- `candidate_pool_size_after_dedup`
- `candidate_pool_size_after_freqcap`
- `fallback_level_final`
- `served_k`
- `empty_reason`（served_k=0 必填；枚举建议：`hard_filter_all | freqcap_all | pool_empty | unknown`）
- `conf_U`
- `missing_fields`：`{ need: boolean; context: boolean; emotion: boolean }`
- （可选）`risk_filtered_count_by_flag`：`{ flag: count }`

---

## 3. 验收标准（可验证）

- 每次推荐调用都能产出 `RecoMeta`，并随响应/任务结果返回（或被上层打点系统消费）。
- `served_k=0` 时 `empty_reason` 必不为空，且与实际清空阶段一致。
- `fallback_level_final` 能真实反映最终回退层级（用于回退率报表）。