199 lines
9.4 KiB
Markdown
199 lines
9.4 KiB
Markdown
# Content Repository（候选查询与数据访问层）｜Tasks
|
||
|
||
> 对应计划：`spec_kit/Personalized Reco/modules/content-repository/plan.md`
|
||
>
|
||
> 本清单已对齐确认点：
|
||
>
|
||
> - `text` 按客户端 **locale** 输出（请求携带）
|
||
> - **不允许语言回退**（缺少目标语言文本的内容直接过滤，不返回）
|
||
> - 需要做 **MySQL（dev）DB 集成测试**
|
||
> - 代码与其他推荐子模块放同一目录：`server/app/features/personalized_reco/`
|
||
> - `fetch_contents_by_ids` 返回顺序必须与输入 `content_ids` **一致**
|
||
>
|
||
> 执行说明：
|
||
>
|
||
> - 本次已在 dev MySQL 环境跑通 `pytest`，且测试不做破坏性操作：
|
||
> - 不清表（不执行 DELETE/TRUNCATE）
|
||
> - 每个用例使用事务并在结束时 rollback
|
||
> - 默认不执行 Alembic 迁移（如需自动迁移需显式设置 `ALLOW_SCHEMA_MIGRATION=1`）
|
||
|
||
---
|
||
|
||
## 0. 任务标记规则
|
||
|
||
- 用勾选框标记执行状态：
|
||
- `[ ]` 未开始
|
||
- `[x]` 已完成
|
||
- 每个任务都要求可独立验收（有明确产出/可运行的检查方式）。
|
||
|
||
---
|
||
|
||
## 1. 文档对齐（先把口径写死，避免实现漂移）
|
||
|
||
- [x] 1.1 更新 `modules/content-repository/spec.md`，加入 locale 相关契约
|
||
- **变更点**：
|
||
- 在输入中新增 `locale`（例如 `en`/`en-US`/`tc`/`zh-TW`/`zh-HK`），声明由客户端请求携带并透传至 repository
|
||
- 在输出字段 `text` 补充语言选择规则：
|
||
- `locale=en*`：必须从 `text_en` 产出；若缺失则该内容不可返回（过滤）
|
||
- `locale=zh-TW|zh-HK`：必须从 `text_tc` 产出；若缺失则该内容不可返回（过滤）
|
||
- 说明：当前仅支持 EN/TC（不做繁转简）；若未来新增 `zh-CN` 再单独设计转换策略
|
||
- 明确：`fetch_contents_by_ids` **返回顺序与入参一致**
|
||
- **验收**：`spec.md` 中输入/输出与接口签名不再缺少 locale，且 `text` 的来源与“不允许语言回退”规则清晰。
|
||
|
||
- [x] 1.2 更新 `modules/content-repository/plan.md`，补齐 locale 选文与“繁转简”技术方案
|
||
- **变更点**：
|
||
- 在“读取层规范化（Normalization）”新增 `text` 规范化章节：语言选择 + 简中转换
|
||
- 说明：当前仅支持 EN/TC（不做繁转简）；若未来新增 `zh-CN` 再单独设计转换策略
|
||
- 明确策略：**不允许语言回退**；缺少目标语言文本的内容视为不可用，必须在候选/按 ID 获取时过滤掉
|
||
- **验收**：`plan.md` 有明确依赖与落地策略（含依赖包/转换时机/兜底策略），不留二义性。
|
||
|
||
---
|
||
|
||
## 2. 目录与骨架（与推荐子模块同级）
|
||
|
||
- [x] 2.1 新建目录 `server/app/features/personalized_reco/content_repository/`
|
||
- **包含**：
|
||
- `__init__.py`
|
||
- `types.py`（DTO：`ContentProfile`、locale 类型等）
|
||
- `interface.py`（`ContentRepository` Protocol/ABC）
|
||
- `normalization.py`（解析与兜底：suitability、risk_flags、power、text）
|
||
- `sqlalchemy_repo.py`（SQLAlchemy 实现）
|
||
- **验收**：可被 `app.features.personalized_reco.content_repository.*` 正常 import。
|
||
|
||
- [ ] 2.2 依赖补齐（如采用 OpenCC）
|
||
- **说明**：当前仅支持 EN/TC，此任务可跳过；若未来新增 `zh-CN` 并需要繁转简，再引入 OpenCC。
|
||
|
||
---
|
||
|
||
## 3. 数据结构与接口（面向引擎注入）
|
||
|
||
- [x] 3.1 定义 `ContentProfile` DTO（稳定字段契约）
|
||
- **字段**：对齐 `modules/content-repository/spec.md`，并补齐 `review_confidence` 输出兜底为 `0.7`
|
||
- **注意**：`text` 为最终对外输出文本（已按 locale 选择/转换）
|
||
- **验收**：DTO 字段齐全；类型清晰；不暴露 ORM 模型。
|
||
|
||
- [x] 3.2 定义 `ContentRepository` 接口（含 locale）
|
||
- **建议签名**（示例，最终以 spec 为准）：
|
||
- `fetch_candidates(scene, user_profile, fallback_level, limit, locale, exclude_content_ids=None) -> List[ContentProfile]`
|
||
- `fetch_contents_by_ids(content_ids, locale) -> List[ContentProfile]`
|
||
- **验收**：推荐引擎可以仅依赖该接口，不依赖 SQLAlchemy/FastAPI Depends。
|
||
|
||
---
|
||
|
||
## 4. 规范化工具函数（可单测）
|
||
|
||
- [x] 4.1 suitability 解析与兜底
|
||
- **规则**：
|
||
- 缺失/NULL/解析失败 → 全 0.5（固定 key 集合）
|
||
- 部分 key 缺失 → 对缺失 key 补 0.5
|
||
- 非法值 → 兜底 0.5
|
||
- **验收**：单元测试覆盖缺失/部分缺失/非法值。
|
||
|
||
- [x] 4.2 risk_flags 映射、去重与排序
|
||
- **规则**：旧→新映射对齐 spec；去重；稳定排序（例如字典序）
|
||
- **验收**：单元测试断言输出不含旧命名且顺序稳定。
|
||
|
||
- [x] 4.3 personalization_power 映射
|
||
- **规则**：`0/5/10 -> 0.0/0.5/1.0`；非法值 -> 0.0
|
||
- **验收**：单元测试覆盖正常/异常值。
|
||
|
||
- [x] 4.4 text 选择与简中转换
|
||
- **输入**：`text_en`、`text_tc`、`locale`
|
||
- **规则**：按 1.1/1.2 写死的策略执行（当前仅支持 EN/TC，不做繁转简）
|
||
- **验收**：单元测试覆盖：
|
||
- `en` 取英文
|
||
- `zh-TW` 取繁中
|
||
- 缺失目标语言文本时的行为：返回“不可用”（例如返回空字符串 + 上层过滤，或直接返回 `None` 由调用方过滤；实现中必须一致）
|
||
|
||
---
|
||
|
||
## 5. SQLAlchemy 实现（无 N+1、顺序可控）
|
||
|
||
> 说明：当前 DB 模型为：
|
||
>
|
||
> - `contents`：`text_en` / `text_tc` / `author_id` / `template_id`
|
||
> - `content_profiles`：JSON、power、stage、is_safe_pool、review_confidence
|
||
> - `content_risk_flags`：关联表（1:N）
|
||
|
||
- [x] 5.1 实现 `fetch_contents_by_ids(content_ids, locale)`
|
||
- **实现要点**：
|
||
- 输入去重，但输出必须按原始输入顺序重排（并忽略不存在的 id 或明确行为：不存在则跳过）
|
||
- 两段式查询避免行膨胀：
|
||
1) `contents` JOIN `content_profiles` 批量取主体与画像
|
||
2) `content_risk_flags` 批量取 flags，再按 `content_id` 聚合
|
||
- 组装 DTO 时执行 normalization（含 text locale 规则）
|
||
- **验收**：
|
||
- 返回顺序与输入一致
|
||
- 缺失目标语言文本的 content_id 不返回（跳过，不做语言回退）
|
||
- 不产生按 id 循环查 flags 的查询（查询次数为常数级）
|
||
|
||
- [x] 5.2 实现 `fetch_candidates(scene, user_profile, fallback_level, limit, locale, exclude_content_ids)`
|
||
- **实现要点**：
|
||
- 计算 `effective_fallback_level`：
|
||
- 若画像 need/context/emotion 任一缺失，则 `effective_fallback_level = max(fallback_level, 1)`
|
||
- DB 粗过滤对齐 plan：
|
||
- L1：`personalization_power <= 5`
|
||
- L2：`personalization_power = 0` 且 `stage = general`
|
||
- L3：`is_safe_pool = true` 且 `stage = general` 且 `personalization_power = 0`（如需更严格可在此明确）
|
||
- 排序（V1）：按 `content_profiles.updated_at DESC` 或 `contents.updated_at DESC`（择一写死并记录）
|
||
- 两段式候选：
|
||
1) 先查候选 id（`LIMIT limit * multiplier`）
|
||
2) 调用 `fetch_contents_by_ids` 补全字段
|
||
- locale 文本存在性过滤：
|
||
- `locale=en*`：`contents.text_en IS NOT NULL`
|
||
- `locale=zh-*`：`contents.text_tc IS NOT NULL`
|
||
- 输出顺序：
|
||
- 返回顺序按候选 id 列表顺序（用于后续引擎打分/重排）；最终截断至 `limit`
|
||
- **验收**：
|
||
- 在不同 `effective_fallback_level` 下能返回候选
|
||
- 不返回缺少目标语言文本的内容（不做语言回退）
|
||
- 查询次数为常数级（不随 `limit` 线性增长）
|
||
|
||
---
|
||
|
||
## 6. DB 集成测试（dev MySQL）
|
||
|
||
- [x] 6.1 建立测试目录与 pytest 配置
|
||
- **目标**：在 `server/` 内新增 `tests/`（或 `app/**/__tests__/`，但建议统一为 `server/tests/`）
|
||
- **内容**：
|
||
- `server/tests/conftest.py`：提供 AsyncEngine/AsyncSession、清库策略、query count 统计工具
|
||
- 测试运行约定：通过 `DATABASE_URL` 指向 dev 测试库（建议单独库名，例如 `mindfulness_dev_test`）
|
||
- **验收**：`pytest` 可在 `server/` 下运行并发现测试。
|
||
|
||
- [x] 6.2 测试库 schema 初始化（用 Alembic）
|
||
- **策略**（二选一写死）：
|
||
- A：测试启动时 `alembic upgrade head`（确保 schema 最新）
|
||
- B：在 CI/本地提前准备库，仅在测试中清表
|
||
- **验收**：测试运行前 schema 可用，且不会污染开发主库数据（推荐使用独立 test 库）。
|
||
|
||
- [x] 6.3 集成测试用例：`fetch_contents_by_ids`
|
||
- **准备数据**：插入最小内容 2~3 条（覆盖 text_en/text_tc 缺失组合）、profiles、flags（含旧 flag）
|
||
- **断言**：
|
||
- 返回顺序与输入一致
|
||
- `en` 不返回 `text_en` 缺失的内容（不回退 `text_tc`）
|
||
- risk_flags 映射后不含旧命名
|
||
- `review_confidence` NULL → 0.7
|
||
- **验收**：测试稳定通过。
|
||
|
||
- [x] 6.4 集成测试用例：`fetch_candidates`
|
||
- **准备数据**：覆盖 `personalization_power` 0/5/10、`is_safe_pool` true/false、不同 stage
|
||
- **断言**：
|
||
- L1/L2/L3 粗过滤生效
|
||
- `exclude_content_ids` 生效
|
||
- 查询次数为常数级（用 before_cursor_execute 计数）
|
||
- **验收**：测试稳定通过。
|
||
|
||
---
|
||
|
||
## 7. 最终自检清单（合入前）
|
||
|
||
- [x] 7.1 文档一致性检查
|
||
- `spec.md` / `plan.md` / 实现接口签名三者一致（尤其是 `locale` 与 `text` 输出规则）
|
||
|
||
- [x] 7.2 性能检查（最小）
|
||
- `fetch_contents_by_ids` / `fetch_candidates` 查询次数断言通过（无 N+1）
|
||
|
||
- [x] 7.3 回归检查
|
||
- 不影响现有 `user_profile_scoring` 模块与迁移脚本（仅新增模块与测试）
|
||
|