mindfulness/spec_kit/Personalized Reco/modules/db-design/spec.md

子模块：DB Design & Migrations（数据库设计与迁移）｜Spec

1. 目标描述

在当前“数据库尚未设计且为空”的前提下，为个性化推荐提供最小可用的数据存储与索引能力：

• 存储文案及其内容画像（Content Profile，Cᵢ）。
• 能按画像条件进行候选召回（need/context/stage/general、personalization_power、risk_flags 等）。
• 能按 content_id 批量查询（补全候选、去重/重排时取字段）。
• 为后续标注/审核/置信度补齐留出扩展空间。

规则口径：字段语义必须严格对齐 设计说明文档/句子文案打分規則.md。

---

2. 输入 / 输出定义

2.1 输入

• 内容侧提供的文案与画像数据（可由运营导入、AI Reviewer 产出、人审修正等方式写入）。
• 推荐模块对数据访问的需求（召回过滤字段、排序字段、频控字段）。

2.2 输出

• 一套 MySQL 表结构（或视图）满足 ContentProfile 字段契约：
  • content_id（稳定主键）
  • text
  • stage（general/expecting/parenting/unknown）
  • emotion_score（0~1 或 general 的等价表示）
  • context_suitability（每个 context 的 {0,0.5,1}）
  • need_suitability（每个 need 的 {0,0.5,1}）
  • personalization_power（0/0.5/1）
  • risk_flags（命名以 unsafe_for_* / block_* / soft_* 为准）
  • 可选：author_id、template_id、review_confidence
• Alembic 迁移脚本：alembic revision --autogenerate / alembic upgrade head 可创建上述表。
• 推荐查询需要的索引（至少支持按场景召回与按 ID 批量查）。

---

3. 建议表结构（V1，允许后续调整）

说明：本子模块不强制具体表名；但需保证字段语义与索引可用。以下给出一个推荐落地方案，便于后续 plan 直接实现。

3.1 contents（文案主体）

• content_id（PK）
• text
• author_id（可空）
• template_id（可空）
• created_at / updated_at

3.2 content_profiles（内容画像）

• content_id（PK/FK → contents）
• stage（枚举：general/expecting/parenting/unknown）
• emotion_score（可为 NULL 表示 general，或用额外字段 emotion_is_general 表示）
• context_suitability_json（JSON：每个 context -> 0/0.5/1）
• need_suitability_json（JSON：每个 need -> 0/0.5/1）
• personalization_power（DECIMAL(2,1) 或 TINYINT 映射到 0/0.5/1）
• risk_flags_json（JSON 数组：字符串集合）
• review_confidence（DECIMAL(3,2)，缺省可按 0.7 处理，由推荐模块兜底）
• updated_at

3.3 “通用安全池”支持（L3 兜底）

至少提供一种方式能拉到安全池内容：

• 方式 A：content_profiles 增加 is_safe_pool（boolean）
• 方式 B：单独 safe_pool_contents（content_id 列表）

---

4. 索引与查询能力（V1 必需）

• 按 ID 批量查：content_id in (...)
• 按 stage / personalization_power 过滤：支持候选召回与回退梯度
• 按 risk_flags 过滤：
  • 推荐做法：将 risk_flags_json 冗余为可索引的派生列/位图/多表行（plan 阶段定实现）
  • V1 最小可用：允许先在应用层过滤（但需控制候选量，避免全表扫）

---

5. 验收标准（可验证）

• 迁移可运行：全新 MySQL 库上执行 alembic upgrade head 可成功创建表结构。
• 字段契约可满足：能从 DB 读出 ContentProfile 需要的字段（至少 content_id/text/stage/emotion_score/context_suitability/need_suitability/personalization_power/risk_flags）。
• 基本查询可用：
  • 能按 content_id 批量拉取内容画像
  • 能按 stage/general 与 personalization_power 条件召回候选（用于 L0~L3）
• 安全池可用：能稳定拉取 L3 兜底候选集（不依赖用户画像）。