# 项目数据库扩展计划

> **版本**：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

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

### aspect_ratio_type

```sql
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