# Changelog: 时间轴元素进度状态系统

**日期**: 2026-01-28  
**类型**: 功能增强  
**影响范围**: 时间轴组件

## 变更概述

为时间轴元素块添加进度状态系统，通过颜色直观展示制作进度：
- `bg-fill-default`：未开始（与资源轨道块背景色一致）
- 黄色：部分完成
- 绿色：已完成
- 蓝色：分镜默认色（未定稿）

同时统一所有轨道元素块的描边样式，使用 `border border-border-base/80` 与资源轨道块保持一致。

## 新增功能

### 1. 状态类型定义

在所有资源类型中添加 `isFinalized` 字段：
- `Storyboard.isFinalized` - 分镜定稿状态
- `Resource.isFinalized` - 资源定稿状态
- `Video.isFinalized` - 视频定稿状态
- `SoundEffect.isFinalized` - 音效定稿状态
- `Subtitle.isFinalized` - 字幕定稿状态
- `Voiceover.isFinalized` - 配音定稿状态

### 2. 状态计算工具

新增 `utils/timeline-status.ts` 提供：
- `ElementStatus` 类型：`'pending' | 'partial' | 'completed'`
- `statusColors` 颜色映射
- 各轨道类型的状态计算函数
- `getTimelineItemColor()` 统一颜色计算入口

### 3. 智能状态计算

**分镜轨道**：
- 未定稿 → 蓝色（保持原有视觉）
- 已定稿 → 绿色

**资源轨道**（智能计算）：
- 关联资源全部已定稿 → 绿色
- 关联资源部分已定稿 → 黄色
- 关联资源全部未定稿 → `bg-fill-default`

**其他轨道**：
- 已定稿 → 绿色
- 未定稿 → `bg-fill-default`（与资源轨道块背景色一致）

## 技术实现

### 新增文件

```
client/src/utils/timeline-status.ts
```

### 修改文件

```
client/src/types/storyboard.ts
client/src/types/resource.ts
client/src/components/features/timeline/TimelineTrack.tsx
client/src/components/features/timeline/TimelineItem.tsx (添加统一描边样式)
client/src/mocks/storyboards.ts
client/src/mocks/project-resources.ts
client/src/styles/globals.css
```

### 核心代码

```typescript
// 状态计算示例
export function getResourceTrackStatus(
  storyboard?: StoryboardWithUI,
  resources?: Resource[]
): ElementStatus {
  // 收集关联资源
  const relatedResourceIds = new Set<string>();
  storyboard.resources?.characters?.forEach(item => 
    relatedResourceIds.add(item.resourceId)
  );
  // ... 其他资源类型
  
  // 计算定稿比例
  const relatedResources = resources.filter(r => 
    relatedResourceIds.has(r.id)
  );
  const finalizedCount = relatedResources.filter(r => 
    r.isFinalized
  ).length;
  
  // 返回状态
  if (finalizedCount === 0) return 'pending';
  if (finalizedCount === relatedResources.length) return 'completed';
  return 'partial';
}
```

## Mock 数据示例

```typescript
// 分镜定稿示例
createStoryboardWithCompat({
  id: '...',
  title: '五行山全景',
  isFinalized: true, // 已定稿 → 显示绿色
  // ...
})

// 资源定稿示例
{
  id: '...',
  name: '孙悟空-青年形象1',
  type: 'character',
  isFinalized: true, // 已定稿
  // ...
}
```

## 使用示例

### 场景 1: 分镜制作流程

1. 新建分镜 → 蓝色（默认未定稿）
2. 生成图片/视频 → 仍为蓝色
3. 用户确认定稿 → 变为绿色

### 场景 2: 资源制作流程

分镜关联：角色A + 场景B + 道具C

- 初始状态：全部未定稿 → `bg-fill-default`
- 角色A定稿 → 黄色（1/3完成）
- 场景B定稿 → 黄色（2/3完成）
- 道具C定稿 → 绿色（3/3完成）

### 场景 3: 视频生成流程

1. 创建视频任务 → `bg-fill-default`
2. AI 生成完成 → 仍为 `bg-fill-default`
3. 用户审核通过 → 变为绿色

## 视觉效果

### 颜色定义

```css
/* 状态颜色 */
--status-pending: bg-fill-default;  /* 与资源轨道块背景色一致 */
--status-partial: #f59e0b;          /* 黄色 - 部分完成 */
--status-completed: #10b981;        /* 绿色 - 已完成 */
--track-storyboard: #3075c9;        /* 蓝色 - 分镜默认 */
```

### 时间轴效果

```
分镜轨道: [蓝色] [绿色] [蓝色] [绿色]
资源轨道: [bg-fill-default] [黄色] [绿色] [黄色]
视频轨道: [bg-fill-default] [bg-fill-default] [绿色] [bg-fill-default]
音效轨道: [bg-fill-default] [绿色] [绿色] [bg-fill-default]
```

## 后续计划

### 短期（1-2周）

- [ ] 添加右键菜单"标记为已完成"
- [ ] 添加状态图标指示器
- [ ] 悬停显示详细状态信息

### 中期（1个月）

- [ ] 实现后端 API 支持
- [ ] 添加批量操作功能
- [ ] 项目面板显示整体完成度

### 长期（2-3个月）

- [ ] 进度统计报表
- [ ] 自动化状态更新规则
- [ ] 团队协作状态同步

## 兼容性

### 向后兼容

- `isFinalized` 字段为可选，不影响现有数据
- 未设置状态时使用默认颜色
- 不影响现有 API 接口

### 数据迁移

暂无需要，字段为可选且仅前端实现。

## 测试建议

### 手动测试

1. 打开西游记项目
2. 观察时间轴元素颜色
3. 验证状态计算逻辑：
   - 分镜1、2（已定稿）→ 绿色
   - 分镜3（未定稿）→ 蓝色
   - 资源轨道（部分完成）→ 黄色

### 自动化测试（待实现）

```typescript
describe('Timeline Status System', () => {
  it('should show green for finalized storyboard', () => {
    const status = getStoryboardStatus({ isFinalized: true });
    expect(status).toBe('completed');
  });
  
  it('should show yellow for partial resources', () => {
    const storyboard = {
      resources: {
        characters: [{ resourceId: 'char1', displayOrder: 0 }],
        scenes: [{ resourceId: 'scene1', displayOrder: 0 }],
      }
    };
    const resources = [
      { id: 'char1', isFinalized: true },
      { id: 'scene1', isFinalized: false },
    ];
    const status = getResourceTrackStatus(storyboard, resources);
    expect(status).toBe('partial');
  });
});
```

## 相关文档

- [RFC 135: 时间轴元素进度状态系统](../rfcs/135-timeline-element-status-system.md)
- [时间轴性能优化](./2026-01-28-timeline-performance-optimization.md)
- [资源面板性能优化](./2026-01-28-resource-panel-performance-optimization.md)

## 反馈

如有问题或建议，请联系前端团队。