+ BEAT {{ shot.beatNo }} / SHOT {{ shot.shotNo }} + {{ shot.durationSeconds }}s +
+{{ shot.title }}
++ {{ shot.description }} +
++ 视觉重点：{{ shot.visualFocus }} +
+Shot ID · {{ shot.shotId }}
++ 标题与剧情描述取自最近可用 Breakdown 快照；以下设计与状态取自数据库。 +
+
+
+ {{ receipt.title }} · 本次回执
+ ++ 本次存在失败、校验未通过或未保存项。关闭“批量覆盖已有结果”后再补齐，可跳过已完整保存项。 +
+ ++ 共 {{ receipt.result.episodeCount }} 集 · 完成 {{ receipt.result.completedEpisodes }} · 跳过 + {{ receipt.result.skippedEpisodes }} · 失败 {{ receipt.result.failedEpisodes }} +
+
+
+
+
+
+
+
+ | 剧集 | +结果 | +回执数量 / 镜头 | +自动修复 | +诊断 | +
|---|---|---|---|---|
| 第 {{ item.episodeNo }} 集 | ++ {{ { completed: '完成', skipped: '跳过已有', failed: '失败' }[item.status] }} + | +{{ item.directionCount ?? item.visualStateCount ?? 0 }} / {{ item.shotCount }} | ++ {{ item.repairAttempts === undefined ? '—' : item.repairAttempts + ' 次' + }} · 已修复 + | +
+ {{ item.error || '—' }} ++ Beat {{ issue.beatNo ?? '—' }} / Shot {{ issue.shotNo ?? '—' }} + {{ issue.subjectRef }}：{{ issue.message }} + + |
+
+ 共 {{ receipt.result.total }} 个镜头 · 本次目标 {{ receipt.result.targetCount }} · 处理成功 + {{ receipt.result.generated }} · 跳过 {{ receipt.result.skipped }} · 失败 {{ receipt.result.failed }} +
+-
+
-
+
{{ item.shotId }}：{{ item.error }} +
+
+ 当前批量接口不返回成功镜头的 Prompt 正文；选择镜头后点击“读取／生成提示词”，已有内容会直接复用。 +
+ + ++ {{ receipt.result.validation.valid ? '生成校验通过' : '校验失败，未保存本次生成结果' + }} + · 自动修复 {{ receipt.result.repairAttempts }} 次 · + {{ receipt.result.persisted ? '已持久化' : '未持久化' }} +
++ 已请求持久化，数据库实际覆盖率以下方刷新后的数据为准。 +
+-
+
- + 第 {{ issue.episodeNo }} 集 / Beat {{ issue.beatNo ?? '—' }} / Shot {{ issue.shotNo ?? '—' }} + {{ issue.subjectRef }}：{{ issue.message }} + +
回执仅保留在当前浏览器会话中。数据库结果是覆盖率和镜头详情的依据。
+
+
+
+
+
+
+
+
+
diff --git a/src/features/storyboard/components/ShotTools.vue b/src/features/storyboard/components/ShotTools.vue
new file mode 100644
index 0000000..7287b32
--- /dev/null
+++ b/src/features/storyboard/components/ShotTools.vue
@@ -0,0 +1,226 @@
+
+
+
+ + 导演摄影设计 Direction +
+
+ {{ field.label }} · {{ directionLabel(shot.direction[field.key], field.key) }}
+
+ -
+
- 构图 +
- {{ shot.direction.composition }} +
- 机位 +
- {{ shot.direction.cameraPosition }} +
- 视觉意图 +
- {{ shot.direction.visualIntent }} +
此镜头尚无已保存的导演设计。
++ 即时视觉状态 VisualState +
+-
+
- 时间 +
- {{ shot.visualState.timeOfDay || '未指定' }} +
- 天气 +
- {{ shot.visualState.weather || '不适用 / 未指定' }} +
- 氛围 +
- {{ shot.visualState.atmosphere || '未指定' }} +
- 环境变化 +
- {{ shot.visualState.environmentTransientState || '无临时变化' }} +
- 连续性 +
- {{ shot.visualState.continuityNote || '未附说明' }} +
+
+ {{ subject.subjectRef }}{{ subject.formName }}
+ -
+
- {{ field.label }} +
- {{ subject[field.key] || '不适用 / 未指定' }} +
+ 此镜头尚无已保存的即时状态。先补齐本集导演设计，再生成 VisualState。 +
+
+
+
+
+
+
+
+
+
diff --git a/src/features/storyboard/generation-spec.types.ts b/src/features/storyboard/generation-spec.types.ts
new file mode 100644
index 0000000..751b3a6
--- /dev/null
+++ b/src/features/storyboard/generation-spec.types.ts
@@ -0,0 +1,63 @@
+/**
+ * 单个主体的稳定形态与当前镜头即时状态。
+ */
+export interface ShotGenerationSubjectSpec {
+ subjectId: string
+ subjectRef: string
+ subjectName: string
+ module: string
+ subjectFormId: string
+ subjectFormName: string
+ appearancePrompt: string
+ generationPrompt: string
+ expression: string
+ pose: string
+ gaze: string
+ position: string
+ transientState: string
+}
+
+/**
+ * 当前 Shot 的摄影设计。
+ */
+export interface ShotGenerationDirectionSpec {
+ shotSize: string
+ cameraAngle: string
+ cameraMovement: string
+ composition: string
+ cameraPosition: string
+ lensIntent: string
+ depthOfField: string
+ visualIntent: string
+}
+
+/**
+ * 当前 Shot 的环境即时状态。
+ */
+export interface ShotGenerationEnvironmentSpec {
+ timeOfDay: string
+ weather: string
+ atmosphere: string
+ transientState: string
+}
+
+/**
+ * 供后续图片 / 视频生成阶段消费的确定性 Shot Generation Spec。
+ *
+ * 此结构只负责编译已有正式数据，不调用模型，也不重新解释剧情。
+ */
+export interface ShotGenerationSpec {
+ projectId: string
+ episodeNo: number
+ beatNo: number
+ shotId: string
+ shotNo: number
+ title: string
+ description: string
+ visualFocus: string
+ durationSeconds: number
+ subjects: ShotGenerationSubjectSpec[]
+ direction: ShotGenerationDirectionSpec
+ environment: ShotGenerationEnvironmentSpec
+ continuityNote: string
+}
diff --git a/src/features/storyboard/index.ts b/src/features/storyboard/index.ts
new file mode 100644
index 0000000..a98372e
--- /dev/null
+++ b/src/features/storyboard/index.ts
@@ -0,0 +1,3 @@
+/** Storyboard 模块公共入口。 */
+export { storyboardApi } from './api'
+export type { EpisodeDirections, EpisodeVisualStates, ShotDirection, ShotVisualState } from './types'
diff --git a/src/features/storyboard/model.test.ts b/src/features/storyboard/model.test.ts
new file mode 100644
index 0000000..7793461
--- /dev/null
+++ b/src/features/storyboard/model.test.ts
@@ -0,0 +1,64 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { directionLabel, mergeDesignedShots, referenceImageUrl, storyboardPrerequisites } from './model'
+import { directionsResult, episodeShots, storyboardCheckpoint, visualStatesResult } from './testing/fixtures'
+
+afterEach(() => vi.unstubAllEnvs())
+
+describe('分镜正式数据与生成依赖', () => {
+ it('用 Shot ID 关联状态，用 Beat + Shot 编号补充描述，不串同编号镜头', () => {
+ const directions = directionsResult('p')
+ const states = visualStatesResult('p', 1, true)
+ states.beats.reverse()
+ states.beats[0]!.shots[0]!.visualState!.continuityNote = '第二个 Beat'
+ const shots = mergeDesignedShots(directions, states, episodeShots())
+ expect(shots.map(shot => [shot.shotId, shot.title, shot.visualState?.continuityNote])).toEqual([
+ ['shot-db-1-1', '第1集镜头1', '信封始终在右手'],
+ ['shot-db-1-2', '第1集镜头2', '第二个 Beat']
+ ])
+ })
+
+ it('没有 Direction 的正式 Shot 仍可显示，不用 checkpoint 伪造数据库 ID', () => {
+ const rows = mergeDesignedShots(directionsResult('p', 1, false), visualStatesResult('p'), episodeShots())
+ expect(rows).toHaveLength(2)
+ expect(rows[0]?.direction).toBeNull()
+ expect(mergeDesignedShots(null, null, episodeShots())).toEqual([])
+ })
+
+ it('仅最新 Breakdown 决定生成前置条件，不能回退到历史完整快照', () => {
+ const ready = storyboardCheckpoint()
+ expect(storyboardPrerequisites([ready], 1)).toMatchObject({ directionEpisode: true, visualEpisode: true })
+ expect(storyboardPrerequisites([ready], 3)).toMatchObject({ directionEpisode: false, visualEpisode: false })
+ const latest = { ...ready, checkpointId: 'failed', createdAt: '2026-08-28T01:00:00Z', state: {} }
+ expect(storyboardPrerequisites([latest, ready], 1)).toMatchObject({
+ directionProject: false,
+ visualProject: false
+ })
+ expect(storyboardPrerequisites([{ ...latest, workflowName: 'create-drama' }, ready], 1)).toMatchObject({
+ directionProject: true
+ })
+ })
+
+ it('保留后端嵌套 Direction 与顶层 VisualState 的不同依赖', () => {
+ const checkpoint = storyboardCheckpoint()
+ delete checkpoint.state.breakdownResult
+ expect(storyboardPrerequisites([checkpoint], 1)).toMatchObject({ directionEpisode: false, visualEpisode: true })
+ checkpoint.state.subjectForms = []
+ expect(storyboardPrerequisites([checkpoint], 1).visualEpisode).toBe(false)
+ expect(directionLabel('future-camera-mode')).toBe('future-camera-mode')
+ })
+
+ it('参考图只允许 http(s) 或后端 storage 地址，拦截不可信协议和路径逃逸', () => {
+ vi.stubEnv('VITE_API_BASE_URL', 'https://api.example.test/api')
+ expect(referenceImageUrl('/storage/image.png')).toBe('https://api.example.test/storage/image.png')
+ expect(referenceImageUrl('https://images.example.test/a.png')).toBe('https://images.example.test/a.png')
+ for (const value of [
+ 'javascript:alert(1)',
+ 'data:image/svg+xml,anything',
+ '//evil.test/img',
+ '/storage/../api/projects',
+ '/storage/\\evil.test/img'
+ ]) {
+ expect(referenceImageUrl(value)).toBeNull()
+ }
+ })
+})
diff --git a/src/features/storyboard/model.ts b/src/features/storyboard/model.ts
new file mode 100644
index 0000000..6e8aa6c
--- /dev/null
+++ b/src/features/storyboard/model.ts
@@ -0,0 +1,128 @@
+import { reactive } from 'vue'
+import type { EpisodeShots } from '../breakdown/types'
+import type { Checkpoint } from '../workflows/types'
+import { workflowCheckpoints } from '../workflows/selectors'
+import type { DesignedShot, EpisodeDirections, EpisodeVisualStates, StoryboardSession } from './types'
+
+/** 仅保存本会话回执和已返回的 Prompt，切换路由不丢失长请求结果。 */
+const sessions = reactive
+
+ 主体参考图
+ ++ 读取镜头已绑定形态的图片，不生成新图。参考图缺失会影响视频提示词生成。 +
+{{ errors.references }}
+ +
+
+ ![]()
+
+
+ 图片不可用
+
+ -
+
- + {{ item.subjectName }}（{{ item.subjectRef }}）：{{ item.reason }} + +
+ 后端未返回参考图或缺失记录。 +
++ 请先在后端补齐对应形态的图片，再刷新。本页暂不包含主体图生成。 +
+ +
+
+ 镜头生成规格
+ ++ 后端合并主体、形态、摄影设计与即时状态，编译为 GenerationSpec，不调用模型。需要本镜头已有 Direction 和 + VisualState。 +
+{{ errors.spec }}
+
+ {{ spec.subjects.length }} 个主体 · {{ spec.durationSeconds }} 秒
+
+ {{ JSON.stringify(spec, null, 2) }}
+
+ 视频提示词
++ 已有提示词直接读取，没有则调用模型生成。当前后端仍使用镜头描述和参考图生成 Prompt，尚未接入上方 + GenerationSpec；此操作不会生成视频。 +
+
+
+
+
+
+ 本会话已读取的正文
+
+ {{ prompt.videoPrompt }}
+Negative prompt
+{{ prompt.negativePrompt }}
+