276 lines
11 KiB
Markdown
276 lines
11 KiB
Markdown
# Content Repository（候选查询与数据访问层）｜Plan
|
||
|
||
> 对应规范：`spec_kit/Personalized Reco/modules/content-repository/spec.md`
|
||
>
|
||
> 依赖对齐：
|
||
>
|
||
> - DB 设计：`spec_kit/Personalized Reco/modules/db-design/plan.md`
|
||
> - 回退梯度与场景口径：`spec_kit/Personalized Reco/spec.md`（Fallback Ladder + 场景默认参数）
|
||
|
||
---
|
||
|
||
## 1. 目标与交付物
|
||
|
||
### 1.1 目标
|
||
|
||
- 为推荐引擎提供**与 ORM/SQL 解耦**的数据访问接口：候选召回与按 ID 批量获取。
|
||
- 将 DB 内部存储形态（JSON、关联表、NULL 语义等）统一“规范化”为上层稳定的 `ContentProfile` 结构。
|
||
- 在候选不足时支持按 `fallback_level (L0~L3)` 进行**可控降级**（降个性化/回退通用池/安全池），并且不产生 N+1 查询。
|
||
|
||
### 1.2 交付物
|
||
|
||
- `modules/content-repository/plan.md`：本技术计划（本文件）。
|
||
- 代码实现（后续 tasks 阶段落地）建议位置：
|
||
- `server/app/features/personalized_reco/content_repository/`（或等价目录）
|
||
- 需要包含：
|
||
- 抽象接口 `ContentRepository`（Protocol 或 ABC）
|
||
- SQLAlchemy 实现 `SqlAlchemyContentRepository`
|
||
- `ContentProfile`（DTO/数据结构）与规范化工具函数
|
||
- 单元测试与最小集成测试（后续 tasks 阶段落地）：
|
||
- risk_flags 映射与去重
|
||
- suitability 缺失兜底
|
||
- personalization_power 映射
|
||
- 查询不出现按 `content_id` 循环查 flags（避免 N+1）
|
||
|
||
---
|
||
|
||
## 2. 关键技术决策（V1）
|
||
|
||
### 2.1 存储形态（来自 DB Design 的已对齐结论）
|
||
|
||
- `content_id`：MySQL 自增主键（`int`）。
|
||
- `context_suitability_json / need_suitability_json`：JSON 存储。
|
||
- `risk_flags`：关联表 `content_risk_flags(content_id, flag)`（同一 content 下 `uniq_content_flag` 去重）。
|
||
- `emotion_score`：`NULL` 表示 general。
|
||
- `review_confidence`：DB 可为 `NULL`；读取层输出时按 `0.7` 兜底（对齐规则口径）。
|
||
- `personalization_power`：DB 推荐存 `0/5/10`；读取层输出稳定为 `0.0/0.5/1.0`。
|
||
|
||
### 2.2 职责边界（避免耦合）
|
||
|
||
- `Content Repository` **不负责** Hard Filter/Soft Scoring/Rerank/Freqcap（这些由引擎编排与打分子模块完成）。
|
||
- `Content Repository` **负责**：
|
||
- 按 `fallback_level` 对候选池做“降级约束”（例如限制 `personalization_power`、回退通用池/安全池）
|
||
- 输出稳定结构（JSON 解析、默认值兜底、旧 flag 映射）
|
||
|
||
---
|
||
|
||
## 3. 接口与数据结构（V1）
|
||
|
||
### 3.1 接口定义（与 spec 对齐）
|
||
|
||
- `fetch_candidates(scene, user_profile, fallback_level, limit, locale, exclude_content_ids=None) -> List[ContentProfile]`
|
||
- `fetch_contents_by_ids(content_ids: List[int], locale) -> List[ContentProfile]`
|
||
|
||
### 3.2 `ContentProfile`（输出契约的推荐形态）
|
||
|
||
稳定字段（必须输出）：
|
||
|
||
- `content_id: int`
|
||
- `text: str`
|
||
- `stage: "general" | "expecting" | "parenting" | "unknown"`
|
||
- `emotion_score: float | None`（`None` 表示 general）
|
||
- `context_suitability: Dict[str, float]`
|
||
- `need_suitability: Dict[str, float]`
|
||
- `personalization_power: float`（`0/0.5/1`）
|
||
- `risk_flags: List[str]`
|
||
|
||
可选字段（尽量输出）：
|
||
|
||
- `author_id: str | None`
|
||
- `template_id: str | None`
|
||
- `review_confidence: float`（缺失/NULL 按 `0.7` 输出）
|
||
|
||
---
|
||
|
||
## 4. 读取层规范化（Normalization）
|
||
|
||
### 4.1 text 选文案与多语言策略（不允许回退）
|
||
|
||
数据来源（当前 DB/ORM 约定）：
|
||
|
||
- `contents.text_en`：英文
|
||
- `contents.text_tc`：繁体中文
|
||
|
||
规则（**不允许语言回退**）：
|
||
|
||
- `locale=en*`：仅允许返回存在 `text_en` 的内容；输出 `text = text_en`
|
||
- `locale=tc/zh-TW/zh-HK`：仅允许返回存在 `text_tc` 的内容；输出 `text = text_tc`
|
||
|
||
若内容缺少目标语言文本（例如 `locale=en*` 但 `text_en` 为空）：该内容视为不可用，必须在候选/按 ID 获取时过滤掉。
|
||
|
||
### 4.1 suitability JSON 解析与缺失兜底
|
||
|
||
固定 key 集合（对齐 DB Plan 的最小入库契约）：
|
||
|
||
- `context_suitability`：`family/work/relationship/friends/health`
|
||
- `need_suitability`：`emotional_support/parenting_pressure/self_worth/anxiety_relief/rest_balance`
|
||
|
||
规则：
|
||
|
||
- 若 DB 字段缺失/为 `NULL`/解析失败：**补齐为全 0.5**（以上所有 key 均为 `0.5`）。
|
||
- 若 DB JSON 存在但缺少部分 key：对缺少 key 补 `0.5`，其余按原值。
|
||
- 值域约束：期望值为 `0/0.5/1`；若出现其他值（例如字符串、越界浮点），按 `0.5` 兜底并记录告警日志（V1 可先打 debug，后续接入可观测模块）。
|
||
|
||
### 4.2 `review_confidence` 兜底
|
||
|
||
- DB `review_confidence` 为 `NULL` 或缺失：输出 `0.7`。
|
||
|
||
### 4.3 `personalization_power` 映射
|
||
|
||
若 DB 存 `0/5/10`：
|
||
|
||
- `0 -> 0.0`
|
||
- `5 -> 0.5`
|
||
- `10 -> 1.0`
|
||
|
||
若读到其他值：按 `0.0` 兜底并记录告警日志。
|
||
|
||
### 4.4 risk_flags 旧→新映射与输出约束
|
||
|
||
映射表（对齐 spec）：
|
||
|
||
- `block_stage_unknown` → `unsafe_for_stage_unknown`
|
||
- `block_stage_parenting` → `unsafe_for_stage_parenting`
|
||
- `block_emotion_low` → `unsafe_for_emotion_low`
|
||
- `block_health_sensitive` → `block_health_medical`（V1 保守硬拦截）
|
||
|
||
输出约束：
|
||
|
||
- 输出 `risk_flags` 必须去重。
|
||
- 输出不得包含旧命名。
|
||
- 输出建议稳定排序（便于测试与可观测）：按字典序排序或按严重等级排序（V1 可先字典序）。
|
||
|
||
---
|
||
|
||
## 5. 查询策略（V1）
|
||
|
||
> 原则：DB 层先做“粗过滤”，应用层再做“精过滤/打分”。避免在 V1 过早依赖 JSON 路径查询索引。
|
||
|
||
### 5.1 `fetch_contents_by_ids`（按 ID 批量获取）
|
||
|
||
目标：
|
||
|
||
- 输入任意 `content_id` 列表，返回无重复的 `ContentProfile` 列表。
|
||
- 避免 N+1：不得按 `content_id` 循环查 `content_risk_flags`。
|
||
- 返回顺序：必须与输入 `content_ids` 一致（对“缺记录/缺语言文本”的 id 采取跳过策略，见下）。
|
||
|
||
缺记录/缺语言文本的处理（V1 约定）：
|
||
|
||
- 若某个 `content_id` 在 DB 中不存在，或按 `locale` 规则无法产出 `text`：该 id 在返回列表中**跳过**（不返回占位对象）。
|
||
|
||
推荐实现形态（两段式，避免 JOIN 导致重复行）：
|
||
|
||
1. **批量拉主体与画像**（`contents` JOIN `content_profiles`），限制 `content_id IN (...)`。
|
||
2. **批量拉 risk_flags**：`SELECT content_id, flag FROM content_risk_flags WHERE content_id IN (...)`，在应用层按 `content_id` 聚合为集合，再做旧→新映射与去重。
|
||
|
||
备注：
|
||
|
||
- 由于 `content_risk_flags` 是 1:N，直接三表 JOIN 容易导致行膨胀；两段式更便于组装与去重。
|
||
|
||
### 5.2 `fetch_candidates`（候选召回，支持 L0~L3）
|
||
|
||
输入：
|
||
|
||
- `scene: feed | push | widget`
|
||
- `user_profile`（允许字段缺失）
|
||
- `fallback_level: 0|1|2|3`
|
||
- `limit`
|
||
- `exclude_content_ids`（可选）
|
||
|
||
#### 5.2.1 fallback_level 约束（对齐大规范 Fallback Ladder）
|
||
|
||
从 `spec_kit/Personalized Reco/spec.md` 对齐：
|
||
|
||
- **L0**：正常召回配比（不在读取层实现复杂配比，读取层只保证候选池足够大且不过度放宽）
|
||
- **L1**：放宽匹配 + 降个性化：限制 `personalization_power ≤ 0.5`
|
||
- **L2**：回退通用池 + 进一步降个性化：限制 `personalization_power = 0`，且优先 `stage=general`
|
||
- **L3**：兜底安全池：限制 `is_safe_pool = true`（安全池字段来自 DB Design）
|
||
|
||
缺失字段的最小处理（对齐大规范 Candidate Generation 口径）：
|
||
|
||
- 若 `user_profile` 缺失明显（need/context/emotion 任一缺失）：读取层按**至少 L1** 的约束执行（即使入参 fallback_level=0）。
|
||
|
||
#### 5.2.2 stage 粗过滤策略（V1）
|
||
|
||
读取层可做的最小粗过滤（不引入复杂业务判断）：
|
||
|
||
- **L2/L3**：只取 `stage=general`（L3 额外 `is_safe_pool=true`）。
|
||
- **L0/L1**：
|
||
- 优先取 `stage=用户匹配阶段` + `stage=general`
|
||
- 若无法从 `user_profile` 明确阶段，则仅取 `stage=general`（避免误推）
|
||
|
||
> 说明：更细粒度的阶段/跨维度规则（例如 unknown+parenting_pressure 的禁推）由 Hard Filter 子模块实现；读取层仅做粗过滤以减少扫描与传输。
|
||
|
||
#### 5.2.3 查询形态（避免 JOIN 行膨胀 + 保证 limit）
|
||
|
||
推荐采用“两段式候选召回”：
|
||
|
||
1. **先只查候选 ID 列表**（`contents` JOIN `content_profiles`），应用粗过滤（stage / personalization_power / is_safe_pool / exclude_content_ids），并增加 **locale 文本存在性过滤**（不允许语言回退），再用 `LIMIT limit * multiplier` 拉一批候选 ID（`multiplier` 例如 3~5，避免后续去重/过滤后不足）。
|
||
2. **再用 `fetch_contents_by_ids` 批量补全字段**（主体+画像+risk_flags），最终在应用层去重并截断到 `limit`。
|
||
|
||
排序（V1）：
|
||
|
||
- 若没有更明确的排序字段：使用 `updated_at DESC` 或随机抽样（需谨慎，MySQL `ORDER BY RAND()` 在大表会慢）。
|
||
- 推荐：V1 先用 `content_profiles.updated_at DESC` 或 `contents.created_at DESC`，后续由打分模块决定最终排序。
|
||
|
||
---
|
||
|
||
## 6. 性能与可观测（V1）
|
||
|
||
### 6.1 性能约束
|
||
|
||
- 单次调用不得出现按 `content_id` 循环查库（避免 N+1）。
|
||
- `fetch_candidates` 必须在 DB 层支持 `limit`，并尽量通过粗过滤减少扫描。
|
||
|
||
### 6.2 建议打点/日志（为 observability 子模块预留）
|
||
|
||
在 Repository 层建议输出 debug 级日志（或埋点字段，供上层汇总）：
|
||
|
||
- `scene`
|
||
- `fallback_level`（入参）与 `effective_fallback_level`（考虑缺失字段自动至少 L1 后的实际约束级别）
|
||
- `limit`、`exclude_content_ids_count`
|
||
- `candidate_ids_size_raw`（第 1 段查到的候选 ID 数）
|
||
- `candidate_size_returned`（最终返回数量）
|
||
|
||
---
|
||
|
||
## 7. 测试计划（V1）
|
||
|
||
### 7.1 单元测试（纯函数）
|
||
|
||
- risk_flags 映射：
|
||
- 输入包含旧 flag，输出只包含新命名
|
||
- 去重与稳定排序
|
||
- suitability 兜底：
|
||
- DB 字段缺失/NULL/解析失败 → 全 0.5
|
||
- 部分 key 缺失 → 补齐 0.5
|
||
- personalization_power 映射：
|
||
- 0/5/10 → 0.0/0.5/1.0
|
||
- 异常值 → 0.0 兜底
|
||
- review_confidence：
|
||
- NULL/缺失 → 0.7
|
||
|
||
### 7.2 最小集成测试（含数据库）
|
||
|
||
- `fetch_contents_by_ids`：
|
||
- 输入多个 id 返回无重复
|
||
- flags 聚合正确（同一 content 多条 flag 行能聚合成 list）
|
||
- 查询次数断言（避免 N+1）：
|
||
- `fetch_contents_by_ids`：固定 2 次查询（主体+画像一次，flags 一次）
|
||
- `fetch_candidates`：固定 3 次查询（候选 id 一次 + `fetch_contents_by_ids` 两次），或实现允许的常数级次数
|
||
|
||
---
|
||
|
||
## 8. 风险与后续演进
|
||
|
||
### 8.1 已知风险
|
||
|
||
- V1 不做 JSON 路径索引：候选量变大后，粗过滤不足可能导致候选池拉取过多、应用层过滤成本上升。
|
||
- `ORDER BY RAND()` 的性能风险：候选大表下不可用，需要替代策略（时间窗口抽样/预生成候选池）。
|
||
|
||
### 8.2 V1.1 优化方向（与 DB Plan 对齐）
|
||
|
||
- 为常用 need/context key 增加生成列/函数索引（从 JSON_EXTRACT 提取到 TINYINT）以加速召回。
|
||
- 为强规则风险（如 `block_health_medical`）增加派生布尔列或缓存表，减少 JOIN 成本。
|
||
|