mindfulness/spec_kit/Personalized Reco/modules/observability/spec.md

子模块：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 能真实反映最终回退层级（用于回退率报表）。