7.7 KiB

Raw Permalink Blame History

分镜资源服务完整实现总结

完成日期：2026-02-03
实现范围：分镜资源管理完整功能

实现概述

基于需求文档 docs/requirements/backend/04-services/project/storyboard-resource-service.md，完成了分镜资源服务的完整实现，包括：

✅ 分镜图片管理（AI 生成的分镜画面）
✅ 分镜视频管理（AI 生成的视频）
✅ 对白管理（分镜的台词文本）
✅ 配音管理（对白的 TTS 音频）
✅ 版本管理（多版本生成和切换）
✅ 数据库迁移脚本

核心功能

1. 版本管理机制

所有生成资源（图片、视频、配音）都支持多版本管理：

版本号递增：每次生成创建新版本
激活版本：用户可选择激活版本
历史保留：保留所有历史版本
唯一约束：每个资源只能有一个激活版本

2. 文件去重机制

通过 checksum 字段实现全局文件去重：

SHA256 校验：所有文件必须提供 checksum
引用计数：通过 FileStorageService 管理
自动清理：引用计数为 0 时自动删除文件
跨表去重：与 attachments、project_resources 共享去重机制

3. 状态跟踪

使用 ResourceStatus 枚举跟踪生成状态：

class ResourceStatus(IntEnum):
    PENDING = 0      # 等待生成
    PROCESSING = 1   # 生成中
    COMPLETED = 2    # 生成完成
    FAILED = 3       # 生成失败

4. 对白类型

使用 DialogueType 枚举区分对白类型：

class DialogueType(IntEnum):
    NORMAL = 1              # 普通对白
    INNER_MONOLOGUE = 2     # 内心OS
    NARRATION = 3           # 旁白

实现文件

1. Model 层

server/app/models/storyboard_resource.py - 数据模型定义

2. Schema 层

server/app/schemas/storyboard_resource.py - 请求/响应 Schema

3. Repository 层

server/app/repositories/storyboard_resource_repository.py - 数据访问层

4. Service 层

server/app/services/storyboard_resource_service.py - 业务逻辑层

5. API 层

server/app/api/v1/storyboard_resources.py - REST API 路由

6. 数据库迁移

server/alembic/versions/20260203_1600_add_storyboard_resources.py - 迁移脚本

API 端点统计

总计 20 个 API 端点：

分镜图片（5 个）

GET /api/v1/storyboards/{storyboard_id}/images
GET /api/v1/storyboards/{storyboard_id}/images/active
POST /api/v1/storyboards/{storyboard_id}/images
POST /api/v1/storyboard-images/{image_id}/activate
DELETE /api/v1/storyboard-images/{image_id}

分镜视频（5 个）

GET /api/v1/storyboards/{storyboard_id}/videos
GET /api/v1/storyboards/{storyboard_id}/videos/active
POST /api/v1/storyboards/{storyboard_id}/videos
POST /api/v1/storyboard-videos/{video_id}/activate
DELETE /api/v1/storyboard-videos/{video_id}

对白（5 个）

GET /api/v1/storyboards/{storyboard_id}/dialogues
POST /api/v1/storyboards/{storyboard_id}/dialogues
PATCH /api/v1/dialogues/{dialogue_id}
DELETE /api/v1/dialogues/{dialogue_id}
POST /api/v1/storyboards/{storyboard_id}/dialogues/reorder

配音（5 个）

GET /api/v1/dialogues/{dialogue_id}/voiceovers
GET /api/v1/dialogues/{dialogue_id}/voiceovers/active
POST /api/v1/dialogues/{dialogue_id}/voiceovers
POST /api/v1/voiceovers/{voiceover_id}/activate
DELETE /api/v1/voiceovers/{voiceover_id}

数据库表结构

1. storyboard_images

主键：image_id (UUID)
外键：storyboard_id
索引：4 个（storyboard_id, status, checksum, ai_prompt_id）
约束：激活版本唯一约束

2. storyboard_videos

主键：video_id (UUID)
外键：storyboard_id
索引：3 个（storyboard_id, status, checksum）
约束：激活版本唯一约束

3. storyboard_dialogues

主键：dialogue_id (UUID)
外键：storyboard_id, character_id
索引：3 个（storyboard_id, character_id, dialogue_type）
约束：顺序号唯一约束

4. storyboard_voiceovers

主键：voiceover_id (UUID)
外键：dialogue_id, storyboard_id
索引：4 个（dialogue_id, storyboard_id, status, checksum）
约束：激活版本唯一约束

技术规范遵循

✅ UUID v7 生成

应用层生成（使用 generate_uuid()）
数据库不使用 DEFAULT

✅ 日志规范

使用 %-formatting 格式化
异常日志添加 exc_info=True
中文日志消息
模块级 logger

✅ 时间戳规范

所有时间字段使用 TIMESTAMPTZ
符合 ADR 006 规范

✅ 枚举类型

数据库使用 SMALLINT
代码使用 IntEnum

✅ API 响应格式

统一使用 SuccessResponse 包装
符合 api-design.md 规范

✅ 异步编程

所有数据库操作使用 async/await
使用 asyncpg 驱动

✅ 依赖注入

Service 通过依赖注入获取
Repository 通过构造函数注入

✅ 错误处理

使用自定义异常（NotFoundError, ValidationError, PermissionError）
统一错误响应格式

与需求文档的对比

✅ 完全实现的功能

分镜图片管理
- ✅ 创建图片
- ✅ 获取所有版本
- ✅ 获取激活版本
- ✅ 设置激活版本
- ✅ 删除图片
分镜视频管理
- ✅ 创建视频
- ✅ 获取所有版本
- ✅ 获取激活版本
- ✅ 设置激活版本
- ✅ 删除视频
对白管理
- ✅ 创建对白
- ✅ 获取所有对白
- ✅ 更新对白
- ✅ 删除对白
- ✅ 重新排序对白
配音管理
- ✅ 创建配音
- ✅ 获取所有版本
- ✅ 获取激活版本
- ✅ 设置激活版本
- ✅ 删除配音
文件存储集成
- ✅ 文件去重机制
- ✅ 引用计数管理
- ✅ 自动清理
数据库设计
- ✅ 表结构完整
- ✅ 索引优化
- ✅ 约束完整
- ✅ 注释完整

📊 实现统计

Model 类：4 个
Schema 类：10 个
Repository 方法：30+ 个
Service 方法：20+ 个
API 端点：20 个
数据库表：4 个
数据库索引：14 个
代码行数：约 1500 行

部署步骤

1. 执行数据库迁移

# 在 Docker 容器中执行
docker exec jointo-server-app python scripts/db_migrate.py upgrade

2. 验证迁移

# 检查当前版本
docker exec jointo-server-app alembic current

# 查看表结构
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "\d storyboard_images"

3. 重启服务

# 重启 FastAPI 应用
docker restart jointo-server-app

测试建议

1. 单元测试

# tests/unit/test_storyboard_resource_service.py
- test_create_image()
- test_set_active_image()
- test_delete_image_validation()
- test_reorder_dialogues()

2. 集成测试

# tests/integration/test_storyboard_resource_api.py
- test_image_version_management()
- test_video_lifecycle()
- test_dialogue_crud()
- test_voiceover_activation()

3. 性能测试

批量创建性能
查询性能
索引效果验证

后续优化

1. 性能优化

批量操作优化
查询缓存
分页查询

2. 功能扩展

批量删除
批量激活
资源统计
导出功能

3. 监控告警

生成失败告警
存储空间监控
API 性能监控

实现人：Kiro AI
完成日期：2026-02-03
状态：✅ 完成

7.7 KiB Raw Permalink Blame History