docs/v1.0/server/changelogs/2026-02-12-remove-storyboard-plans.md

Changelog: 移除 storyboard_plans 功能

日期: 2026-02-12
类型: Breaking Change
影响范围: 后端 API、数据库结构

---

变更概述

完全移除 storyboard_plans 表及相关功能，包括：

• 删除 storyboard_plans 表
• 移除 storyboards.default_plan_id 字段
• 移除 storyboard_images.plan_id 和 storyboard_videos.plan_id 字段
• 删除所有相关的 API、Service、Repository、Schema、Model 代码
• 删除所有相关的单元测试和集成测试

变更原因

经过架构评审，决定废除分镜方案（storyboard_plans）功能，原因如下：

1. 业务需求变更：产品方向调整，不再需要多方案管理功能
2. 简化架构：减少不必要的复杂度，提升系统可维护性
3. 性能优化：减少关联查询和数据冗余

数据库变更

迁移文件

server/alembic/versions/20260212_1800_remove_storyboard_plans.py

变更内容

1. 删除表

• storyboard_plans - 分镜方案表

2. 删除字段

• storyboards.default_plan_id - 默认方案ID
• storyboard_images.plan_id - 所属方案ID
• storyboard_videos.plan_id - 所属方案ID

3. 删除索引

• idx_storyboards_default_plan
• idx_storyboard_images_plan
• idx_storyboard_videos_plan
• idx_storyboard_plans_storyboard
• idx_storyboard_plans_type
• idx_storyboard_plans_storyboard_order

4. 删除触发器

• update_storyboard_plans_updated_at

代码变更

删除的文件

Model 层

• server/app/models/storyboard_plan.py

Schema 层

• server/app/schemas/storyboard_plan.py

Repository 层

• server/app/repositories/storyboard_plan_repository.py

Service 层

• server/app/services/storyboard_plan_service.py

API 层

• server/app/api/v1/storyboard_plans.py

测试文件

• server/tests/unit/repositories/test_storyboard_plan_repository.py
• server/tests/integration/test_storyboard_plans_api.py

修改的文件

Model 层

• server/app/models/__init__.py - 移除 StoryboardPlan 和 PlanType 导入
• server/app/models/storyboard.py - 移除 default_plan_id 字段
• server/app/models/storyboard_resource.py - 移除 plan_id 字段

API 层

• server/app/api/v1/__init__.py - 移除 storyboard_plans 路由注册

API 变更

删除的端点

所有 /storyboards/{storyboard_id}/plans 相关端点已删除：

• POST /storyboards/{storyboard_id}/plans - 创建分镜方案
• GET /storyboards/{storyboard_id}/plans - 获取分镜的所有方案
• PATCH /storyboards/{storyboard_id}/plans/{plan_id} - 更新分镜方案
• DELETE /storyboards/{storyboard_id}/plans/{plan_id} - 删除分镜方案
• POST /storyboards/{storyboard_id}/default-plan - 设置默认方案

影响的响应结构

Storyboard 响应

移除字段：

• defaultPlanId - 默认方案ID

StoryboardImage / StoryboardVideo 响应

移除字段：

• planId - 所属方案ID

迁移指南

数据库迁移

# 在 Docker 容器内执行迁移
docker exec jointo-server-app alembic upgrade head

前端适配

如果前端代码使用了以下功能，需要移除：

1. 方案管理相关 API 调用

   // 需要删除的代码
   await api.post(`/storyboards/${id}/plans`, data);
   await api.get(`/storyboards/${id}/plans`);
   await api.patch(`/storyboards/${id}/plans/${planId}`, data);
   await api.delete(`/storyboards/${id}/plans/${planId}`);
   

2. 响应数据中的方案字段

   // 需要移除的字段引用
   storyboard.defaultPlanId
   image.planId
   video.planId
   

3. 方案相关的 UI 组件

   • 方案选择器
   • 方案列表
   • 方案创建/编辑表单

回滚方案

如需回滚，执行：

# 在 Docker 容器内执行回滚
docker exec jointo-server-app alembic downgrade -1

注意：回滚会恢复表结构，但不会恢复已删除的数据。

相关文档

• ADR 05: 分镜方案表设计 - 已标记为废弃
• 迁移脚本

测试验证

数据库验证

-- 验证表已删除
SELECT tablename FROM pg_tables WHERE tablename = 'storyboard_plans';
-- 应返回空结果

-- 验证字段已删除
SELECT column_name FROM information_schema.columns 
WHERE table_name = 'storyboards' AND column_name = 'default_plan_id';
-- 应返回空结果

SELECT column_name FROM information_schema.columns 
WHERE table_name = 'storyboard_images' AND column_name = 'plan_id';
-- 应返回空结果

API 验证

# 验证端点已删除（应返回 404）
curl -X GET http://localhost:8000/api/v1/storyboards/{id}/plans

注意事项

1. 不可逆操作：此变更会永久删除 storyboard_plans 表中的所有数据
2. 前端兼容性：前端代码需要同步更新，移除所有方案相关功能
3. 数据备份：执行迁移前建议备份数据库

变更记录

• 2026-02-12: 初始版本，完成功能移除