# Project 服务数据库初始化设计文档创建

> **日期**: 2026-02-03  
> **类型**: 文档创建  
> **影响范围**: Project 服务所有表

---

## 变更概述

创建 Project 服务的数据库初始化设计文档，整合 16 个服务文档中的所有表结构设计，标准化为统一的数据库初始化方案。

## 文档路径

`docs/requirements/backend/04-services/project/database-init.md`

## 涵盖的表

### 文件夹模块（2 张表）
1. **folders** - 文件夹表
2. **folder_members** - 文件夹成员表

### 项目模块（4 张表）
3. **projects** - 项目表
4. **project_members** - 项目成员表
5. **project_shares** - 项目分享表
6. **project_versions** - 项目版本表

### 剧本模块（6 张表）
7. **screenplays** - 剧本表
8. **screenplay_versions** - 剧本版本表
9. **screenplay_characters** - 剧本角色表
10. **screenplay_locations** - 剧本场景表
11. **screenplay_props** - 剧本道具表
12. **screenplay_element_tags** - 剧本元素标签表

### 分镜模块（3 张表）
13. **storyboards** - 分镜表
14. **storyboard_items** - 分镜元素关联表
15. **storyboard_resources** - 分镜资源关联表（统一关联表）

### 资源模块（1 张表）
16. **project_resources** - 项目资源表

## 技术栈符合性

✅ **完全符合 jointo-tech-stack 规范**:
- PostgreSQL 17
- UUID v7 主键（应用层生成）
- TIMESTAMPTZ 时间字段
- SMALLINT + IntEnum 枚举类型
- 禁止物理外键约束
- 应用层验证引用完整性
- snake_case 命名规范
- 触发器自动更新 updated_at
- 完整的表和字段注释

## 文档结构

1. **技术栈符合性检查** - 列出所有符合项和注意事项
2. **数据库设计标准化** - 表命名规范和字段类型标准
3. **表结构定义** - 每个表的详细字段、索引、约束定义
4. **关联关系** - 表关联图和应用层验证规则
5. **初始化脚本** - 完整的 SQL 建表语句
6. **迁移建议** - 首次部署顺序和后续演进建议

## 关键设计点

### 1. 父子项目关系
- 父项目：`parent_project_id = NULL`
- 子项目：`parent_project_id = 父项目ID`，关联剧本（`screenplay_id`）
- 子项目继承父项目权限和配置

### 2. 文件夹分类
- `folder_category` 字段区分"我的项目"（1）和"协作项目"（2）
- 子文件夹自动继承父文件夹分类（触发器实现）
- 前端虚拟显示分类视图

### 3. 统一资源关联表
- `storyboard_resources` 表统一管理分镜与各类资源的关联
- 支持图片、视频、对话、配音、音效等多种资源类型
- 使用 `resource_type` 字段区分资源类型

### 4. 标签系统
- `screenplay_element_tags` 表管理剧本元素标签
- 支持角色、场景、道具、镜头、运镜等多种标签类型
- 标签值使用 SMALLINT 存储，代码层枚举映射

### 5. 权限继承
- 文件夹成员权限可继承（`inherited` 字段）
- 项目继承文件夹权限
- 子项目继承父项目权限

## 后续工作

1. **创建 Alembic 迁移文件** - 根据初始化脚本生成迁移
2. **实现 Model 层** - 定义所有表的 SQLModel 模型
3. **实现 Repository 层** - 实现数据访问逻辑
4. **实现 Service 层** - 实现业务逻辑和应用层验证
5. **编写单元测试** - 测试所有表的 CRUD 操作

## 参考文档

- `docs/requirements/backend/04-services/user/database-init.md` - User 服务参考格式
- `docs/requirements/backend/04-services/resource/database-init.md` - Resource 服务参考格式
- `docs/architecture/tech-stack.md` - 技术栈规范
- `docs/architecture/adrs/001-uuid-v7-migration.md` - UUID v7 迁移决策

---

## 文档状态

- ✅ 技术栈符合性检查完成
- ✅ 表命名规范完成
- ✅ 字段类型标准完成
- ✅ 表结构定义完成（16/16 张表）
- ✅ 关联关系完成
- ✅ 初始化脚本完成
- ✅ 迁移建议完成

## 完成时间

**2026-02-03** - 文档创建完成，已通过技术栈符合性检查

## 文档位置

`docs/requirements/backend/04-services/project/database-init.md`

## 使用说明

1. **查看文档**: 打开 `database-init.md` 查看完整的数据库设计
2. **执行初始化**: 复制"初始化脚本"章节的 SQL 语句执行建表
3. **创建迁移**: 根据 SQL 脚本创建 Alembic 迁移文件
4. **实现代码**: 参考表结构定义实现 Model、Repository、Service 层

## 技术亮点

1. **完全符合技术栈规范** - 100% 遵循 jointo-tech-stack 约束
2. **无物理外键** - 所有关联通过应用层验证，提升性能
3. **完整的索引策略** - 覆盖所有查询场景
4. **枚举值标准化** - 使用 SMALLINT + IntEnum 模式
5. **软删除支持** - 所有核心表支持 deleted_at 软删除
6. **触发器自动化** - updated_at 自动更新，path/level 自动计算
7. **权限继承设计** - 文件夹、项目、子项目权限自动继承
8. **统一资源关联** - storyboard_resources 统一管理所有资源类型