docs/v1.0/.archive/server/project-db-extension.md

项目数据库扩展计划

版本：v1.0
日期：2025-01-14
状态：✅ 已完成

---

背景

前端 client/src/types/project.ts 定义了影视项目的核心元数据字段（内容类型、画幅比例、时长、故事梗概等），但后端数据库设计中缺少这些字段。为保证前后端数据结构一致性，需要扩展 projects 表。

---

目标

1. 在 projects 表中新增 7 个影视项目元数据字段
2. 创建必要的 ENUM 类型和索引
3. 更新后端数据模型和 Schema 定义
4. 保持向后兼容（所有新字段均为可选）

---

新增字段清单

字段名	类型	说明	前端对应字段
content_type	project_content_type	项目内容类型	contentType
aspect_ratio	aspect_ratio_type	画幅比例	aspectRatio
planned_duration	INTEGER	计划总时长（秒）	plannedDuration
actual_duration	INTEGER	实际总时长（秒）	actualDuration
tagline	TEXT	一句话概括	tagline
synopsis	TEXT	故事梗概	synopsis
style_and_characters	TEXT	风格和角色描述	styleAndCharacters

---

ENUM 类型定义

project_content_type

CREATE TYPE project_content_type AS ENUM (
    'ad',      -- 广告片
    'movie',   -- 电影
    'series',  -- 剧集
    'anime',   -- 动画
    'short',   -- 短视频
    'concept'  -- 概念片
);

aspect_ratio_type

CREATE TYPE aspect_ratio_type AS ENUM (
    '16:9',    -- 标准宽屏
    '9:16',    -- 竖屏（手机）
    '4:3',     -- 传统电视
    '21:9',    -- 超宽屏
    '1:1',     -- 正方形
    '2.35:1',  -- 电影宽银幕
    '2.39:1'   -- 电影超宽银幕
);

---

索引策略

索引名	字段	类型	用途
idx_projects_content_type	content_type	B-tree	按内容类型筛选
idx_projects_aspect_ratio	aspect_ratio	B-tree	按画幅比例筛选
idx_projects_planned_duration	planned_duration	B-tree	按计划时长排序
idx_projects_actual_duration	actual_duration	B-tree	按实际时长排序
idx_projects_tagline_trgm	tagline	GIN	全文搜索
idx_projects_synopsis_trgm	synopsis	GIN	全文搜索

---

影响范围

✅ 无破坏性变更

• 所有新字段均为 NULL 可选
• 不影响现有数据和查询
• 向后兼容

📝 需要后续配合

1. 后端 API：

   • 更新 ProjectCreate 和 ProjectUpdate Schema
   • 在 API 响应中返回新字段
   • 添加按 content_type、aspect_ratio 筛选的查询参数

2. 前端表单：

   • 添加内容类型选择器
   • 添加画幅比例选择器
   • 添加 tagline、synopsis、style_and_characters 输入框

3. 数据迁移（可选）：

   • 如果 settings 中已存储相关数据，可编写脚本迁移到新字段

---

实施记录

已完成

• ✅ 更新 docs/需求/backend/04-services/project/project-service.md
  • 新增 ENUM 类型定义
  • 扩展 projects 表结构
  • 新增 7 个字段和 6 个索引
  • 更新字段注释
• ✅ 更新 Python 数据模型（Project 类）
  • 新增 ProjectContentType 和 AspectRatioType 枚举
  • 新增 7 个字段定义
• ✅ 更新 Pydantic Schema
  • ProjectCreate：支持创建时传入新字段
  • ProjectUpdate：支持更新新字段
  • ProjectResponse：返回新字段

---

后续建议

1. 优先级 P0：更新后端 API 实现，支持新字段的 CRUD
2. 优先级 P1：前端表单集成新字段输入
3. 优先级 P2：添加按内容类型和画幅比例的筛选功能
4. 优先级 P3：全文搜索支持 tagline 和 synopsis

---

文档版本：v1.0
最后更新：2025-01-14