jrh
/
docs
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
3 Commits
1 Branch
0 Tags
2.6 MiB
 
Branch: main
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'main'
${ noResults }
docs/v1.0/server/changelogs/2026-02-03-project-service-...

4.9 KiB
Raw Permalink Blame History

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

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

变更概述

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

文档路径

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

涵盖的表

文件夹模块（2 张表）

  1. folders - 文件夹表
  2. folder_members - 文件夹成员表

项目模块（4 张表）

  1. projects - 项目表
  2. project_members - 项目成员表
  3. project_shares - 项目分享表
  4. project_versions - 项目版本表

剧本模块（6 张表）

  1. screenplays - 剧本表
  2. screenplay_versions - 剧本版本表
  3. screenplay_characters - 剧本角色表
  4. screenplay_locations - 剧本场景表
  5. screenplay_props - 剧本道具表
  6. screenplay_element_tags - 剧本元素标签表

分镜模块（3 张表）

  1. storyboards - 分镜表
  2. storyboard_items - 分镜元素关联表
  3. storyboard_resources - 分镜资源关联表（统一关联表）

资源模块（1 张表）

  1. 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 统一管理所有资源类型