# 子模块：Scoring（软打分与惩罚项）｜Spec

## 1. 目标描述

实现推荐排序的打分函数与分解项，严格对齐 `設計說明文檔/個性化推薦算法規則.md` 的公式与 V1.2 缺失字段约定，并与内容画像（Cᵢ）结构对齐 `句子文案打分规则`。

---

## 2. 输入 / 输出定义

### 2.1 输入

- `scene`: `feed | push | widget`
- `user_profile`（U）
- `content_profile`（Cᵢ）
- `now`（用于 freshness/时间衰减，若 V1 暂不实现可先占位）
- `config`（权重与开关）
  - `w_need/w_emotion/w_stage/w_context`
  - `alpha`（个性化加成系数）
  - `beta`（不确定性惩罚系数）
  - `enable_uncertainty_penalty`（push 默认 true）
  - `widget_emotion_soft_range`（0.4~0.8，软降权）

### 2.2 输出

- `final_score: float`
- `breakdown`（用于调参/可观测，V1 可选但建议保留）：
  - `S_need/S_context/S_stage/S_emotion`
  - `S_core/S_personal/S_fresh`
  - `P_fatigue/P_repeat/P_risk/P_uncertainty`
  - `missing_fields`（need/context/emotion）

---

## 3. 计算规则（必须实现的最小集合）

### 3.1 核心结构（线性加权 + 惩罚）

\[
final\_score(U,C_i)=\mathbb{I}[pass]\times\Big(S_{core}+S_{personal}+S_{fresh}-P_{fatigue}-P_{repeat}-P_{risk}-P_{uncertainty}\Big)
\]

\[
S_{core}=w_{need}S_{need}+w_{emotion}S_{emotion}+w_{stage}S_{stage}+w_{context}S_{context}
\]

### 3.2 V1.2 缺失字段的保守计算（必须对齐）

- 若 `U.need` 缺失 → `S_need = 0.5`
- 若 `U.context` 缺失 → `S_context = 0.5`
- 若 `U.emotion_score` 缺失 → `S_emotion = 0.8`
  - 文案为 general 时仍按 0.8（对齐算法规则）

### 3.3 个性化加成（受回退梯度/降个性化约束）

\[
S_{personal}=\alpha \cdot C_i.personalization\_power \cdot \max(S_{need}, S_{context})
\]

当触发降个性化（缺失明显 / 低置信度 / fallback_level≥1）时：

- L1：限制 `personalization_power ≤ 0.5`
- L2/L3：限制 `personalization_power = 0`

### 3.4 不确定性惩罚（Push 默认启用）

\[
P_{uncertainty}=\beta \cdot (1-conf_U)\cdot(1-conf_{C_i})\cdot C_i.personalization\_power
\]

其中：

- `conf_U` 来自 `user_profile.profile_confidence`
- `conf_{C_i}` 来自 `content_profile.review_confidence`（缺省 0.7，对齐 `句子文案打分规则`）

### 3.5 Widget 情绪区间（软降权）

- 若 `scene=widget` 且 `C_i.emotion_score` 可计算（非 general）：
  - 当 `emotion_score` 不在 0.4~0.8：不硬过滤，但需要产生一个降权项（可并入 `P_risk` 或单独 `P_widget_emotion_out_of_range`）。

---

## 4. 场景默认权重（V1 建议，来源算法规则）

- Feed：`w_need=0.35, w_emotion=0.20, w_stage=0.15, w_context=0.30`
- Push：`w_need=0.45, w_emotion=0.35, w_stage=0.15, w_context=0.05`
- Widget：`w_need=0.25, w_emotion=0.25, w_stage=0.30, w_context=0.20`

---

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

- **缺失字段一致性**：当 U 的 need/context/emotion 缺失时，S_need/S_context/S_emotion 按 0.5/0.5/0.8 计算，且不会报错。
- **不确定性惩罚生效**：Push 默认启用，低 `conf_U` 或低 `conf_C` 时，高 `personalization_power` 内容分数降低。
- **Widget 软降权生效**：0.4~0.8 区间外不被硬挡，但分数能明显被压低（可通过断言对比分数验证）。
- **可调参**：权重与系数可配置，调整不会破坏输出结构。

