fix:更新算法

2026-02-02 11:22:35 +08:00
parent 814b96edb6
commit 58d17fc39f
27 changed files with 3286 additions and 62 deletions
--- a/Reco/modules/content-repository/spec.md
+++ b/Reco/modules/content-repository/spec.md
@@ -0,0 +1,102 @@
+# 子模块：Content Repository（候选查询与数据访问层）｜Spec
+
+## 1. 目标描述
+
+提供推荐算法可注入的、与 ORM/SQL 解耦的数据访问接口：
+
+- 按场景与用户画像拉取候选内容画像（Cᵢ）。
+- 按 `content_id` 批量获取内容画像（去重/重排/补字段）。
+- 对 risk_flags、suitability JSON 等“存储形态”做统一解析与兼容（对上提供稳定结构）。
+
+> 规则口径：risk_flags 命名与语义严格按 `句子文案打分规则`；若历史数据存在旧 flag，需在读取层做一次映射（避免语义漂移）。
+>
+> 存储形态对齐 `modules/db-design/plan.md`：读取层需要将 `contents` + `content_profiles` + `content_risk_flags` 组装为上层稳定的 `ContentProfile` 结构。
+
+---
+
+## 2. 输入 / 输出定义
+
+### 2.1 输入
+
+- `scene`: `feed | push | widget`
+- `user_profile`: 客户端问卷画像（V1.2；字段允许缺失）
+- `fallback_level`: `0|1|2|3`
+- `limit`: 候选条数上限（由引擎配置）
+- （可选）排除集合：`exclude_content_ids`（用于 DB 层先排一部分，减少传输；类型为 `List[int]`，与 MySQL 自增 `content_id` 对齐）
+- 数据库会话/连接（实现层使用 `AsyncSession` 注入）
+
+### 2.2 输出
+
+- `List[ContentProfile]`（稳定字段契约）：
+  - `content_id`：`int`（MySQL 自增主键）
+  - `text`：文案文本
+  - `stage`：`general | expecting | parenting | unknown`
+  - `emotion_score`：`float | None`（约定：`None` 表示 general）
+  - `context_suitability`：`Dict[str, float]`（见 4.1 的 key 集合；值为 `0/0.5/1`）
+  - `need_suitability`：`Dict[str, float]`（见 4.1 的 key 集合；值为 `0/0.5/1`）
+  - `personalization_power`：`float`（对上稳定口径为 `0/0.5/1`；若 DB 存 `0/5/10`，读取层需映射）
+  - `risk_flags`：`List[str]`（已做旧→新映射、去重；命名只允许 `unsafe_for_* / block_* / soft_*`）
+  - 可选：`author_id`、`template_id`、`review_confidence`
+
+### 2.3 数据存储形态（对齐 DB 设计）
+
+> 对齐：`spec_kit/Personalized Reco/modules/db-design/plan.md`
+
+- `contents`：提供 `content_id`、`text`、（可选）`author_id`、`template_id`
+- `content_profiles`：提供 `stage`、`emotion_score`、`context_suitability_json`、`need_suitability_json`、`personalization_power`（推荐存 `0/5/10`）、（可选）`review_confidence`
+- `content_risk_flags`：通过关联表提供风险标记集合（同一 content 下按 `uniq_content_flag(content_id, flag)` 去重）
+
+---
+
+## 3. 接口（建议）
+
+推荐模块对该子模块只依赖抽象接口（Python Protocol/ABC 均可）：
+
+- `fetch_candidates(scene, user_profile, fallback_level, limit, exclude_content_ids=None) -> List[ContentProfile]`
+- `fetch_contents_by_ids(content_ids: List[int]) -> List[ContentProfile]`
+
+---
+
+## 4. 关键规则与实现约束
+
+### 4.1 字段缺失与默认值
+
+- 若 `review_confidence` 缺失：输出时默认按 `0.7`（对齐 `句子文案打分规则` V1.2 约定）。
+- `context_suitability/need_suitability` 若缺失：**读取层必须补齐为“全 0.5 的通用可推”结构**（稳定输出，避免上层分支判断）。
+  - `context_suitability` 必须包含 5 个 key：`family/work/relationship/friends/health`
+  - `need_suitability` 必须包含 5 个 key：`emotional_support/parenting_pressure/self_worth/anxiety_relief/rest_balance`
+  - 补齐时上述 key 的默认值均为 `0.5`
+- `personalization_power`：若 DB 采用 `0/5/10` 存储，读取层必须映射为 `0.0/0.5/1.0` 对上输出。
+
+### 4.2 risk_flags 兼容映射（若存在历史旧数据）
+
+对齐 `句子文案打分规则` 的旧→新映射：
+
+- `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`（读取层默认采用更保守的硬拦截映射；除非未来引入可判定的细分字段再放宽为 `soft_health_sensitive`）
+
+输出约束：
+
+- 输出的 flags 必须已去重，且不得包含任何旧命名。
+
+### 4.3 性能约束
+
+- 不得产生 N+1 查询：候选与字段必须一次或少量批量查询获取。
+- `fetch_candidates` 必须支持 limit，并在 DB 层尽量过滤（减少应用层扫描）。
+- `fetch_contents_by_ids` / `fetch_candidates` 推荐查询形态：
+  - `contents` JOIN `content_profiles`，再 LEFT JOIN `content_risk_flags`（或先批量取 profiles，再批量取 flags 并在应用层聚合），避免按 `content_id` 循环查 flags。
+
+---
+
+## 5. 验收标准（可验证）
+
+- `fetch_contents_by_ids`：
+  - 输入任意 `content_id` 列表，返回包含完整字段的 `ContentProfile` 列表（无重复、可缺省字段按约定兜底）。
+- `fetch_candidates`：
+  - 在不同 `scene` 与 `fallback_level` 下能返回候选（即便画像缺失也不报错）。
+  - risk_flags 映射正确：输出的 flag 名称集合只包含新命名（`unsafe_for_* / block_* / soft_*`）。
+- 性能：
+  - 单次调用不出现按 content_id 循环查库的行为（可通过日志/测试断言查询次数）。
+
--- a/Reco/modules/db-design/plan.md
+++ b/Reco/modules/db-design/plan.md
@@ -0,0 +1,217 @@
+# DB Design & Migrations（数据库设计与迁移）｜Plan
+
+> 对应规范：`spec_kit/Personalized Reco/modules/db-design/spec.md`
+>
+> 前置确认（已对齐）：
+>
+> - `content_id`：MySQL **自增主键**；文案微调时 **content_id 不变**（更新同一条记录）。
+> - `need_suitability/context_suitability`：**JSON** 存储。
+> - `risk_flags`：选择更强扩展性的方案（本计划采用 **关联表**，利于索引与过滤）。
+> - 安全池（L3）：**方式 A**（`is_safe_pool`）。
+> - 迁移：使用 **Alembic**，目录放 `server/alembic/`；dev/pro 两套库均可运行同一套迁移。
+> - 字符集：统一 **utf8mb4**。
+
+---
+
+## 1. 目标与交付物
+
+### 1.1 目标
+
+- 在“库为空”的前提下，落地推荐系统最小可用的数据模型。
+- 保证后续推荐查询可实现：按画像条件召回、按 ID 批量查、按风险标记过滤、支持安全池兜底。
+
+### 1.2 交付物
+
+- `server/alembic/`：Alembic 初始化目录、`alembic.ini`（或等价配置）、迁移脚本。
+- SQLAlchemy ORM 模型（建议放 `server/app/db/models/`）。
+- 初始迁移：创建 `contents`、`content_profiles`、`content_risk_flags`（以及必要索引）。
+
+---
+
+## 2. 技术决策（V1）
+
+### 2.1 表设计原则
+
+- **分离主体与画像**：`contents` 存文本与来源字段；`content_profiles` 存画像字段（便于未来画像重算/回填）。
+- **JSON 存 suitability**：`context_suitability`、`need_suitability` 用 JSON，保持结构与规则文档一致。
+- **risk_flags 关联表**：用 `content_risk_flags(content_id, flag)`，便于：
+  - 快速 Hard Filter（`block_health_medical` 等）
+  - 索引与统计（按 flag 计数）
+  - 兼容旧 flag 映射（在写入/读取层）
+- **emotion_score 的 general 表示**：用 `NULL` 表示 general（与规则文档“可为 general”语义等价）。
+- **personalization_power**：存为 `TINYINT`（0/5/10）或 `DECIMAL(2,1)`（0/0.5/1）。本计划推荐 `TINYINT`（更易索引/更省空间），应用层做映射：
+  - 0 → 0.0
+  - 5 → 0.5
+  - 10 → 1.0
+
+### 2.2 字符集与排序规则
+
+- 数据库与表：`utf8mb4`
+- collation：建议 `utf8mb4_0900_ai_ci`（MySQL 8 默认更常见；若环境不同以实际为准，但必须 utf8mb4）
+
+---
+
+## 3. 表结构（V1 方案）
+
+> 以下为“建议 schema”。实际字段名可调整，但语义必须严格对齐 `句子文案打分规则`。
+
+### 3.1 `contents`（文案主体）
+
+- `content_id` BIGINT UNSIGNED PK AUTO_INCREMENT
+- `text` TEXT NOT NULL
+- `author_id` VARCHAR(64) NULL
+- `template_id` VARCHAR(64) NULL
+- `created_at` DATETIME NOT NULL
+- `updated_at` DATETIME NOT NULL
+
+索引建议：
+
+- `idx_contents_author_id(author_id)`
+- `idx_contents_template_id(template_id)`
+
+### 3.2 `content_profiles`（内容画像）
+
+- `content_id` BIGINT UNSIGNED PK（FK → contents.content_id，ON DELETE CASCADE）
+- `stage` ENUM('general','expecting','parenting','unknown') NOT NULL DEFAULT 'general'
+- `emotion_score` DECIMAL(3,2) NULL
+  - 约定：NULL 表示 general
+- `context_suitability_json` JSON NOT NULL
+- `need_suitability_json` JSON NOT NULL
+- `personalization_power` TINYINT UNSIGNED NOT NULL DEFAULT 0
+  - 约定：只允许 0/5/10
+- `review_confidence` DECIMAL(3,2) NULL
+  - 约定：NULL 由推荐模块按 0.7 兜底（对齐规则文档）
+- `is_safe_pool` BOOLEAN NOT NULL DEFAULT FALSE
+- `updated_at` DATETIME NOT NULL
+
+索引建议：
+
+- `idx_profiles_stage(stage)`
+- `idx_profiles_personalization_power(personalization_power)`
+- `idx_profiles_is_safe_pool(is_safe_pool)`
+
+> 说明：suitability 放 JSON 后，V1 可以先不做 JSON 路径索引；当候选量上来后再加“生成列/函数索引”做加速（见 6.2）。
+
+### 3.3 `content_risk_flags`（风险标记，关联表）
+
+- `id` BIGINT UNSIGNED PK AUTO_INCREMENT
+- `content_id` BIGINT UNSIGNED NOT NULL（FK → contents.content_id，ON DELETE CASCADE）
+- `flag` VARCHAR(64) NOT NULL
+- `created_at` DATETIME NOT NULL
+
+约束与索引：
+
+- UNIQUE：`uniq_content_flag(content_id, flag)`（同一 content 不重复插同 flag）
+- 索引：`idx_flag(flag)`（用于 Hard Filter 与统计）
+- 索引：`idx_content_id(content_id)`（用于按内容批量取 flags）
+
+命名约束（应用层强制，DB 可选）：
+
+- flag 必须以 `unsafe_for_` / `block_` / `soft_` 开头（严格对齐规则文档）
+
+---
+
+## 4. Alembic 迁移落地步骤
+
+### 4.1 依赖与目录
+
+- 后端依赖：`alembic`（加入 `server/requirements.txt`，版本随项目统一管理）
+- 目录：`server/alembic/`（包含 `env.py`、`versions/`）
+- 连接串：复用现有 `DATABASE_URL`（`mysql+aiomysql://...`）
+
+### 4.2 初始化与生成迁移（一次性）
+
+- `alembic init alembic`（在 `server/` 下）
+- 配置 `env.py`：
+  - 从 `app/core/config.py` 读取 `DATABASE_URL`
+  - 引入 ORM Base 与 models，启用 autogenerate
+- 创建初始迁移：
+  - `alembic revision --autogenerate -m "init content tables"`
+  - `alembic upgrade head`
+
+### 4.3 dev/pro 一致性
+
+- 迁移脚本保持同一套；通过不同环境的 `DATABASE_URL` 指向 `mindfulness_dev` 或 `mindfulness`。
+
+---
+
+## 5. 入库流程（写入契约）
+
+### 5.1 一条文案最小入库数据
+
+必须字段（V1 最小可用）：
+
+- `text`
+- `content_profiles.stage`
+- `content_profiles.emotion_score`（可为 NULL 表示 general）
+- `content_profiles.context_suitability_json`（必须包含 5 个 key：family/work/relationship/friends/health，值为 0/0.5/1）
+- `content_profiles.need_suitability_json`（必须包含 5 个 key：emotional_support/parenting_pressure/self_worth/anxiety_relief/rest_balance，值为 0/0.5/1）
+- `content_profiles.personalization_power`（0/5/10）
+- `content_risk_flags`（可为空集合，但若存在必须按命名规范）
+
+强烈建议字段：
+
+- `author_id`、`template_id`
+- `review_confidence`
+- `is_safe_pool`（若要参与 L3 安全池）
+
+### 5.2 写入策略
+
+- 创建文案时：
+  - 先写 `contents` 得到 `content_id`（自增）
+  - 再写 `content_profiles`（同 content_id）
+  - 再批量写 `content_risk_flags`
+- 文案微调时（content_id 不变）：
+  - 更新 `contents.text` 与 `updated_at`
+  - 同步更新 `content_profiles`（若画像变更）
+  - risk_flags 做“全量覆盖”或“差量更新”（plan 实现阶段定）
+
+---
+
+## 6. 查询与性能规划
+
+### 6.1 V1 查询策略（先可用）
+
+- 候选召回：
+  - 先按 `stage`、`personalization_power`、`is_safe_pool` 等可索引字段进行粗过滤
+  - 再在应用层结合 suitability JSON 与 risk_flags 做精过滤/打分
+- Hard Filter：
+  - 通过 `content_risk_flags` join 或子查询排除指定 flags（如 `block_health_medical`）
+- 批量查：
+  - `content_id IN (...)` join `content_profiles` + left join `content_risk_flags`
+
+### 6.2 V1.1 性能增强（候选量上来后再做）
+
+当候选池变大、应用层过滤成本上升时，优先做两类增强：
+
+- **生成列/函数索引**：为常用召回维度（例如 need/context 的某些 key）创建 generated columns（从 JSON_EXTRACT 取值并映射到 TINYINT），再加索引。
+- **风险 flag 位图/派生列**：对 `block_health_medical` 等强规则增加派生布尔列（或维护冗余表），降低 join 成本。
+
+---
+
+## 7. 测试与验收（DB 子模块）
+
+### 7.1 迁移验收
+
+- 在全新库执行 `alembic upgrade head` 成功。
+- 执行 `downgrade`（若实现）可回滚（至少在开发环境可用）。
+
+### 7.2 数据契约验收
+
+插入一条最小文案记录后，能够查询并组装出推荐模块所需的 `ContentProfile` 字段集合：
+
+- `content_id/text/stage/emotion_score/context_suitability/need_suitability/personalization_power/risk_flags`
+
+### 7.3 规则口径验收（写入侧）
+
+- 写入 `risk_flags` 时，若出现旧 flag（如 `block_stage_unknown`）：
+  - 写入层需在入库前映射为新命名（或拒绝写入并提示）
+  - 推荐侧读取层不得再出现旧 flag 名称
+
+---
+
+## 8. 与其他子模块的接口约定
+
+- `Content Repository` 只依赖本模块提供的表与字段语义，不依赖具体迁移实现细节。
+- 推荐引擎/打分模块对 `review_confidence` 的缺省值假设（0.7）在 DB 缺失时依然成立。
+
--- a/Reco/modules/db-design/spec.md
+++ b/Reco/modules/db-design/spec.md
@@ -0,0 +1,91 @@
+# 子模块：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 兜底候选集（不依赖用户画像）。
+
--- a/Reco/modules/db-design/tasks.md
+++ b/Reco/modules/db-design/tasks.md
@@ -0,0 +1,99 @@
+# DB Design & Migrations（数据库设计与迁移）｜Tasks
+
+> 对应计划：`spec_kit/Personalized Reco/modules/db-design/plan.md`
+>
+> 目标：在“库为空”的前提下，落地推荐系统最小可用数据模型 + Alembic 迁移，并通过最小查询/契约验收。
+
+---
+
+## 0. 任务状态约定
+
+- `[ ]`：未开始
+- `[~]`：进行中
+- `[x]`：已完成
+- `[-]`：已取消/不做（需写明原因）
+
+---
+
+## 1. 环境与依赖准备
+
+- [ ] **确认 MySQL 版本与字符集支持**
+  - 验收：MySQL 版本为 8.x；库/表可用 `utf8mb4`（建议 `utf8mb4_0900_ai_ci`）。
+- [x] **后端依赖补齐 Alembic**
+  - 说明：`server/requirements.txt` 已包含 `alembic>=1.13`
+  - 验收：在 `server/.venv` 中可成功 `import alembic`。
+
+---
+
+## 2. ORM 模型落地（推荐最小集合）
+
+- [x] **创建 ORM 模型目录**
+  - 目标路径：`server/app/db/models/`
+  - 验收：目录存在，且可被 Python 正常 import。
+- [x] **实现 `contents` 模型**
+  - 字段：`content_id(PK, 自增)`、`text_en?`、`text_tc?`、`author_id?`、`template_id?`、`created_at`、`updated_at`
+  - 索引：`author_id`、`template_id`
+  - 验收：Alembic autogenerate 能识别表结构。
+- [x] **实现 `content_profiles` 模型**
+  - 字段：`content_id(PK/FK)`、`stage(enum)`、`emotion_score(NULL=general)`、`context_suitability_json(JSON)`、`need_suitability_json(JSON)`、`personalization_power(0/5/10)`、`review_confidence?`、`is_safe_pool`、`updated_at`
+  - 索引：`stage`、`personalization_power`、`is_safe_pool`
+  - 验收：Alembic autogenerate 能识别表结构；`content_id` 具备外键与级联删除。
+- [x] **实现 `content_risk_flags` 模型（关联表）**
+  - 字段：`id(PK)`、`content_id(FK)`、`flag`、`created_at`
+  - 约束：`UNIQUE(content_id, flag)`
+  - 索引：`flag`、`content_id`
+  - 验收：Alembic autogenerate 能识别唯一约束与索引。
+
+---
+
+## 3. Alembic 初始化与迁移生成
+
+- [x] **初始化 Alembic 目录**
+  - 目标位置：`server/alembic/`（含 `versions/`、`env.py`）
+  - 验收：在 `server/` 下可运行 `alembic -h` 且能读取配置。
+- [x] **配置 Alembic 连接串来源**
+  - 要求：复用现有 `DATABASE_URL`（对齐 `server/app/core/config.py`）
+  - 验收：`alembic` 命令可加载 `env.py` 并读取 `DATABASE_URL`（未连 DB 验收留到第 4 章）。
+- [x] **配置 `env.py` 支持 autogenerate**
+  - 要求：引入 ORM `Base` 与 models（确保 metadata 完整）
+  - 验收：Alembic 能识别 `target_metadata`；且已提供初始迁移版本文件。
+- [ ] **生成并执行初始迁移**
+  - 命令：`alembic upgrade head`
+  - 验收：数据库中出现 `contents`、`content_profiles`、`content_risk_flags` 与 Alembic 版本表。
+
+---
+
+## 4. 数据契约验收（最小入库与查询）
+
+- [ ] **准备一条最小文案数据（人工插入或脚本）**
+  - 必须字段（对齐 plan）：`text`、`stage`、`emotion_score(可 NULL)`、`context_suitability_json(5 keys)`、`need_suitability_json(5 keys)`、`personalization_power(0/5/10)`、`risk_flags(可空)`
+  - 验收：可插入成功，不违反约束。
+- [ ] **验证按 `content_id` 批量查询可用**
+  - 目标：能 join 组装出 `ContentProfile` 所需字段集合（含 risk_flags 列表）
+  - 验收：至少验证字段：`content_id/text/stage/emotion_score/context_suitability/need_suitability/personalization_power/risk_flags`。
+- [ ] **验证 Hard Filter 关键 flag 可过滤**
+  - 插入：至少一条带 `block_health_medical` 的记录
+  - 验收：通过 `content_risk_flags` 可在 SQL 层排除该内容（后续供推荐候选召回使用）。
+- [ ] **验证安全池（L3）可用**
+  - 插入：至少一条 `is_safe_pool=true`
+  - 验收：可单独查询出安全池候选集（不依赖画像条件）。
+
+---
+
+## 5. 规则口径验收（risk_flags 严格对齐）
+
+- [ ] **建立 risk_flags 白名单/校验策略（写入侧或读取侧）**
+  - 要求：flag 命名必须以 `unsafe_for_` / `block_` / `soft_` 开头（对齐 `句子文案打分规则`）
+  - 验收：插入非法前缀时被拒绝或被修正（选择其一，并写清策略）。
+- [ ] **旧 flag 兼容映射验收（若存在历史数据导入）**
+  - 覆盖：`block_stage_unknown`→`unsafe_for_stage_unknown` 等（详见 plan）
+  - 验收：系统对外（读出/下游）不再出现旧 flag 名称。
+
+---
+
+## 6. 文档与交接
+
+- [ ] **补齐本子模块 README/说明（可选，但建议）**
+  - 内容：如何初始化 DB、如何跑迁移、如何插入一条最小文案数据、如何验证查询。
+  - 验收：新同学按文档能在 30 分钟内跑通迁移 + 插入 + 查询。
+
--- a/Reco/modules/integration-api-worker/spec.md
+++ b/Reco/modules/integration-api-worker/spec.md
@@ -0,0 +1,59 @@
+# 子模块：Integration（FastAPI API + Celery Worker）｜Spec
+
+## 1. 目标描述
+
+将推荐引擎对外暴露为两种调用方式，满足“API 与任务两者都需要”的集成要求：
+
+- **FastAPI**：同步请求/响应式获取推荐结果（客户端直接请求）。
+- **Celery**：后台任务式生成推荐（用于 Push/Widget 的定时或批处理）。
+
+两种方式都必须调用同一套 `Reco Engine`，确保行为一致、便于回归测试。
+
+---
+
+## 2. 输入 / 输出定义
+
+### 2.1 API 输入（HTTP Request）
+
+- `scene`: `feed | push | widget`
+- `k`（可选；默认按场景）
+- `user_profile`（客户端问卷画像，V1.2）
+- `already_recommended_ids`（数组）
+- `touched_or_viewed_ids`（数组）
+- （可选）`now`（用于可测试性；生产可不传，由服务端生成）
+
+### 2.2 API 输出（HTTP Response）
+
+- `items`: 推荐句子列表
+- `meta`: RecoMeta（候选规模、回退层级、empty_reason 等）
+
+### 2.3 Celery 任务输入/输出
+
+任务输入与 API 输入等价，但建议仅传必要字段并保持 payload 小（避免 Redis 膨胀）：
+
+- 允许只传 `user_profile` 与历史集合；若历史集合很大，建议传引用 ID（后续演进）。
+
+任务输出：
+
+- 可选择“不存结果”（默认忽略结果）并在任务内部将推荐结果写入下游（如消息队列/推送系统/DB）。
+- 或返回 `items/meta`（仅用于开发调试）。
+
+---
+
+## 3. 关键约束
+
+- API 与 Celery **不得复制推荐逻辑**：只能调用 `Reco Engine`。
+- 输入合法性：
+  - 不因字段缺失而报错（画像允许缺失/跳过）。
+  - `already_recommended_ids/touched_or_viewed_ids` 允许为空数组。
+- 可测试性：
+  - 允许注入 `now`（或在 header/参数中提供），便于确定性测试。
+
+---
+
+## 4. 验收标准（可验证）
+
+- **API 可用**：给定合法请求体可返回推荐结果与 meta。
+- **任务可用**：Celery worker 能消费任务并成功调用推荐引擎（至少跑通 ping → reco 的调用链）。
+- **一致性**：相同输入下，API 与任务调用返回结果一致（忽略时间戳字段差异时）。
+
--- a/Reco/modules/observability/spec.md
+++ b/Reco/modules/observability/spec.md
@@ -0,0 +1,45 @@
+# 子模块：Observability（可观测性与打点载荷）｜Spec
+
+## 1. 目标描述
+
+定义推荐模块的统一可观测载荷（meta/event），用于：
+
+- 线上监控覆盖率、回退率、候选规模分布、过滤原因分布。
+- 支撑调参（权重/回退阈值/频控窗口）与风险排查（Hard Filter 命中情况）。
+
+---
+
+## 2. 输入 / 输出定义
+
+### 2.1 输入
+
+- 推荐引擎内部各阶段统计信息：
+  - 候选生成数量、过滤后数量、去重后数量、频控后数量
+  - 回退层级与触发原因
+  - served_k
+  - 缺失字段情况、conf_U
+
+### 2.2 输出
+
+统一的 `RecoMeta`（返回给调用方；调用方负责上报/落库/打点）：
+
+- `scene`
+- `candidate_pool_size_raw`
+- `candidate_pool_size_after_hard_filter`
+- `candidate_pool_size_after_dedup`
+- `candidate_pool_size_after_freqcap`
+- `fallback_level_final`
+- `served_k`
+- `empty_reason`（served_k=0 必填；枚举建议：`hard_filter_all | freqcap_all | pool_empty | unknown`）
+- `conf_U`
+- `missing_fields`：`{ need: boolean; context: boolean; emotion: boolean }`
+- （可选）`risk_filtered_count_by_flag`：`{ flag: count }`
+
+---
+
+## 3. 验收标准（可验证）
+
+- 每次推荐调用都能产出 `RecoMeta`，并随响应/任务结果返回（或被上层打点系统消费）。
+- `served_k=0` 时 `empty_reason` 必不为空，且与实际清空阶段一致。
+- `fallback_level_final` 能真实反映最终回退层级（用于回退率报表）。
+
--- a/Reco/modules/reco-engine/spec.md
+++ b/Reco/modules/reco-engine/spec.md
@@ -0,0 +1,81 @@
+# 子模块：Reco Engine（推荐引擎编排）｜Spec
+
+## 1. 目标描述
+
+实现推荐的主编排器（Orchestrator）：
+
+- 输入用户画像 + 历史集合 + 场景参数。
+- 调用 `Content Repository` 拉取候选。
+- 执行统一 Pipeline：Candidate → Hard Filter → Soft Scoring → Rerank/Freqcap → Fallback Ladder。
+- 输出推荐句子与 `meta`（可观测字段），供 API 或 Celery 上层直接下发。
+
+---
+
+## 2. 输入 / 输出定义
+
+### 2.1 输入
+
+- `scene`: `feed | push | widget`
+- `user_profile`: 客户端问卷画像（V1.2）
+- `already_recommended_ids`: `List[str|int]`
+- `touched_or_viewed_ids`: `List[str|int]`
+- `k`: int（feed 默认 30；push/widget 默认 1）
+- `now`: 时间戳
+- （可选）`constraints`：黑名单 author/template、最大候选量上限等
+
+### 2.2 输出
+
+- `items: List[RecommendedItem]`（长度 ≤ k）
+  - `content_id`、`text`、`final_score`
+  - `fallback_level_final`
+  - `explanations`（可选，便于调参/排查）
+- `meta: RecoMeta`
+  - `candidate_pool_size_raw`
+  - `candidate_pool_size_after_hard_filter`
+  - `candidate_pool_size_after_dedup`
+  - `candidate_pool_size_after_freqcap`
+  - `fallback_level_final`
+  - `served_k`
+  - `empty_reason`（served_k=0 必填）
+  - `missing_fields`（need/context/emotion 的缺失情况）
+  - `scene`、`conf_U`
+
+---
+
+## 3. 缺失字段判定（必须与客户端契约一致）
+
+- `U.need` 为空对象 `{}` 或不存在 → 视为缺失
+- `U.context` 为空对象 `{}` 或不存在 → 视为缺失
+- `U.emotion_score` 为 `null`/不存在 → 视为缺失
+
+当缺失明显或 `conf_U` 偏低时：
+
+- Push：必须启用不确定性惩罚 `P_uncertainty`，并自动降个性化（限制 `personalization_power` 上限）。
+- 任意场景：候选生成至少按 **L1** 处理（降个性化，增加通用安全占比）。
+
+---
+
+## 4. Fallback Ladder（回退梯度，必须实现）
+
+- L0：正常召回配比
+- L1：放宽匹配 + `personalization_power ≤ 0.5`
+- L2：回退通用池 + `personalization_power = 0`
+- L3：仅安全池（白名单/安全池）
+
+触发条件（任一满足即可回退）：
+
+- 候选池为空 / Hard Filter 清空 / 去重清空 / 频控清空
+- served_k < k（feed 可允许部分不足，但需记录并可继续回退补齐，具体由实现配置）
+
+每次回退必须更新 meta 中的候选规模与触发原因。
+
+---
+
+## 5. 验收标准（可验证）
+
+- **稳定性**：任意输入（包括画像字段缺失、历史集合为空/很大）不报错，返回结构稳定。
+- **回退可观测**：当候选不足时能逐级回退，且 `fallback_level_final` 与 `empty_reason` 正确。
+- **去重生效**：输出不包含 `already_recommended_ids` 与 `touched_or_viewed_ids` 中的 content_id。
+- **风险优先**：Hard Filter 始终优先执行（尤其 `block_health_medical` 必挡）。
+- **跨调用复用**：同一引擎既可被 FastAPI API 调用，也可被 Celery 任务调用（无框架耦合）。
+
--- a/Reco/modules/rerank-freqcap/spec.md
+++ b/Reco/modules/rerank-freqcap/spec.md
@@ -0,0 +1,87 @@
+# 子模块：Rerank & Freqcap（重排 / 去重 / 频控）｜Spec
+
+## 1. 目标描述
+
+对 Soft Scoring 后的候选集做最终的“可下发排序”，解决：
+
+- **去重**：避免同一句在短期内反复出现。
+- **多样性**：Feed 场景需要序列多样性（作者/模板/标签）。
+- **频控与冷却**：Push/Widget 必做，按句子/作者/模板维度做窗口期不重复。
+
+> 当前确认：历史集合由客户端在请求时传入（已推荐 ID、已触达/浏览 ID）。
+
+---
+
+## 2. 输入 / 输出定义
+
+### 2.1 输入
+
+- `scene`: `feed | push | widget`
+- `scored_candidates`: `List[{ content_id, score, content_profile... }]`
+- `already_recommended_ids`: `List[str|int]`
+- `touched_or_viewed_ids`: `List[str|int]`
+- （可选）`recent_author_ids` / `recent_template_ids`（若客户端暂不传，可由后续服务端侧补齐）
+- `k`: 目标条数
+- `config`：
+  - Feed：`mmr_lambda`（默认 0.7）
+  - 冷却窗口：`cooldown_sentence_days / cooldown_author_days / cooldown_template_days`
+
+### 2.2 输出
+
+- `ranked_items`: 排好序的候选（长度 ≤ k）
+- `meta`：
+  - `candidate_pool_size_after_dedup`
+  - `candidate_pool_size_after_freqcap`
+  - `freqcap_filtered_counts`（可选，按维度统计）
+
+---
+
+## 3. 规则与算法（V1 最小集合）
+
+### 3.1 去重（必做）
+
+- 过滤 `content_id` ∈ `already_recommended_ids ∪ touched_or_viewed_ids` 的候选。
+- 去重键定义（对齐算法规则的工程约定）：
+  - `sentence_key = content_id`
+  - `author_key = author_id`（可空）
+  - `template_key = template_id`（可空）
+
+### 3.2 Feed：MMR 序列重排（建议）
+
+- Top1：最高分，确保第一眼命中。
+- 后续：使用 MMR 选择序列，最大化与已选内容的差异（作者/模板/need/context/stage）。
+
+MMR 定义：
+
+\[
+MMR(c)=\lambda\cdot Rel(c) - (1-\lambda)\cdot \max_{s\in S} Sim(c,s)
+\]
+
+其中：
+
+- `Rel(c)`：可直接使用 `final_score`
+- `Sim(c,s)`：离散特征版（V1 推荐）：
+  - content_id 相同：1
+  - template_id 相同：+0.6
+  - author_id 相同：+0.3
+  - 标签重合（Jaccard）：+0.1 * Jaccard(tags_c, tags_s)
+  - clamp 到 [0,1]
+
+### 3.3 Push/Widget：频控与冷却（必做）
+
+最小要求：
+
+- 同一句在窗口 X 天内不重复（句子冷却）。
+- 同作者/同模板在窗口期内尽量不重复（可作为硬频控或强降权，plan 阶段定）。
+
+> 当前 V1 输入侧只确认有 content_id 历史；若 author/template 历史暂不具备，可先对 content_id 强硬去重，并将 author/template 频控作为“可选增强”（meta 仍需统计缺失原因）。
+
+---
+
+## 4. 验收标准（可验证）
+
+- **去重正确**：输出不包含 `already_recommended_ids` 与 `touched_or_viewed_ids`。
+- **Feed 序列多样**：在候选足够时，序列中不会出现大量同作者/同模板连续重复（可用统计阈值验收）。
+- **Push/Widget 频控生效**：在冷却窗口内同一句不会再次被推荐（基于传入历史集合验证）。
+- **可观测**：输出 meta 中包含 `after_dedup/after_freqcap` 的候选规模，便于排查 served_k 不足原因。
+
--- a/Reco/modules/scoring/spec.md
+++ b/Reco/modules/scoring/spec.md
@@ -0,0 +1,97 @@
+# 子模块：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 区间外不被硬挡，但分数能明显被压低（可通过断言对比分数验证）。
+- **可调参**：权重与系数可配置，调整不会破坏输出结构。
+