4.6 KiB
4.6 KiB
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）。
- 验收：MySQL 版本为 8.x；库/表可用
- 后端依赖补齐 Alembic
- 说明：
server/requirements.txt已包含alembic>=1.13 - 验收：在
server/.venv中可成功import alembic。
- 说明：
2. ORM 模型落地（推荐最小集合）
- 创建 ORM 模型目录
- 目标路径：
server/app/db/models/ - 验收：目录存在，且可被 Python 正常 import。
- 目标路径：
- 实现
contents模型- 字段：
content_id(PK, 自增)、text_en?、text_tc?、author_id?、template_id?、created_at、updated_at - 索引：
author_id、template_id - 验收：Alembic autogenerate 能识别表结构。
- 字段：
- 实现
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具备外键与级联删除。
- 字段：
- 实现
content_risk_flags模型（关联表）- 字段：
id(PK)、content_id(FK)、flag、created_at - 约束：
UNIQUE(content_id, flag) - 索引：
flag、content_id - 验收：Alembic autogenerate 能识别唯一约束与索引。
- 字段：
3. Alembic 初始化与迁移生成
- 初始化 Alembic 目录
- 目标位置：
server/alembic/（含versions/、env.py） - 验收：在
server/下可运行alembic -h且能读取配置。
- 目标位置：
- 配置 Alembic 连接串来源
- 要求：复用现有
DATABASE_URL（对齐server/app/core/config.py） - 验收：
alembic命令可加载env.py并读取DATABASE_URL（未连 DB 验收留到第 4 章）。
- 要求：复用现有
- 配置
env.py支持 autogenerate- 要求：引入 ORM
Base与 models（确保 metadata 完整） - 验收：Alembic 能识别
target_metadata；且已提供初始迁移版本文件。
- 要求：引入 ORM
- 生成并执行初始迁移
- 命令：
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(可空) - 验收：可插入成功，不违反约束。
- 必须字段（对齐 plan）：
- 验证按
content_id批量查询可用- 目标：能 join 组装出
ContentProfile所需字段集合（含 risk_flags 列表） - 验收：至少验证字段：
content_id/text/stage/emotion_score/context_suitability/need_suitability/personalization_power/risk_flags。
- 目标：能 join 组装出
- 验证 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 命名必须以
- 旧 flag 兼容映射验收（若存在历史数据导入）
- 覆盖：
block_stage_unknown→unsafe_for_stage_unknown等（详见 plan） - 验收：系统对外（读出/下游）不再出现旧 flag 名称。
- 覆盖：
6. 文档与交接
- 补齐本子模块 README/说明（可选，但建议）
- 内容：如何初始化 DB、如何跑迁移、如何插入一条最小文案数据、如何验证查询。
- 验收：新同学按文档能在 30 分钟内跑通迁移 + 插入 + 查询。