# 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

## 迁移指南

### 数据库迁移

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

### 前端适配

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

1. **方案管理相关 API 调用**
   ```typescript
   // 需要删除的代码
   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. **响应数据中的方案字段**
   ```typescript
   // 需要移除的字段引用
   storyboard.defaultPlanId
   image.planId
   video.planId
   ```

3. **方案相关的 UI 组件**
   - 方案选择器
   - 方案列表
   - 方案创建/编辑表单

## 回滚方案

如需回滚，执行：

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

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

## 相关文档

- [ADR 05: 分镜方案表设计](../adrs/05-storyboard-plans-table.md) - 已标记为废弃
- [迁移脚本](../../alembic/versions/20260212_1800_remove_storyboard_plans.py)

## 测试验证

### 数据库验证

```sql
-- 验证表已删除
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 验证

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

## 注意事项

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

## 变更记录

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