# 子模块：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 兜底候选集（不依赖用户画像）。