feat(api): add script-to-shot planner baseline for sprint-05

Author: echowang1

apps/api/src/domain/script/scene-shot-planner.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { InMemorySceneShotPlanner } from "./scene-shot-planner";
+
+describe("scene shot planner", () => {
+  it("is idempotent for unchanged scene payload", () => {
+    const planner = new InMemorySceneShotPlanner();
+    const first = planner.plan("p1", [{ sceneId: "s1", content: "角色走进房间。镜头推近。" }]);
+    const second = planner.plan("p1", [{ sceneId: "s1", content: "角色走进房间。镜头推近。" }]);
+
+    expect(first[0].changed).toBe(true);
+    expect(second[0].changed).toBe(false);
+    expect(second[0].version).toBe(first[0].version);
+    expect(second[0].shotDrafts.map((x) => x.shotId)).toEqual(first[0].shotDrafts.map((x) => x.shotId));
+  });
+
+  it("increments version and replaces old shots when forced regenerate", () => {
+    const planner = new InMemorySceneShotPlanner();
+    const first = planner.plan("p1", [{ sceneId: "s2", content: "角色回头。" }]);
+    const forced = planner.plan("p1", [{ sceneId: "s2", content: "角色回头。" }], new Set(["s2"]));
+
+    expect(forced[0].changed).toBe(true);
+    expect(forced[0].version).toBe(first[0].version + 1);
+    expect(forced[0].replacedShotIds).toEqual(first[0].shotDrafts.map((x) => x.shotId));
+  });
+});

apps/api/src/domain/script/scene-shot-planner.ts

@@ -0,0 +1,120 @@
+import crypto from "node:crypto";
+
+export interface ScenePlanInput {
+  sceneId: string;
+  content: string;
+  targetShotCount?: number;
+}
+
+export interface ShotDraft {
+  shotId: string;
+  prompt: string;
+  sourceSceneId: string;
+  index: number;
+}
+
+export interface ScenePlanRecord {
+  sceneId: string;
+  version: number;
+  fingerprint: string;
+  shotDrafts: ShotDraft[];
+  updatedAt: string;
+}
+
+export interface PlannedSceneResult extends ScenePlanRecord {
+  changed: boolean;
+  replacedShotIds: string[];
+}
+
+function normalizeText(text: string): string {
+  return text
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function computeFingerprint(input: ScenePlanInput): string {
+  const normalized = normalizeText(input.content);
+  const payload = `${input.sceneId}::${normalized}::${input.targetShotCount ?? "auto"}`;
+  return crypto.createHash("sha256").update(payload).digest("hex");
+}
+
+function splitBeats(content: string): string[] {
+  const normalized = normalizeText(content);
+  const chunks = normalized
+    .split(/[。！？.!?;；]+/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+  if (chunks.length > 0) return chunks;
+  return [normalized || "scene beat"];
+}
+
+function normalizeCount(value: number | undefined, fallback: number): number {
+  if (!value || value <= 0) return fallback;
+  return Math.max(1, Math.min(8, Math.floor(value)));
+}
+
+function buildShotDrafts(sceneId: string, version: number, content: string, targetShotCount?: number): ShotDraft[] {
+  const beats = splitBeats(content);
+  const count = normalizeCount(targetShotCount, Math.min(4, Math.max(1, beats.length)));
+
+  const drafts: ShotDraft[] = [];
+  for (let i = 0; i < count; i += 1) {
+    const beat = beats[i % beats.length];
+    drafts.push({
+      shotId: `scene-${sceneId}-v${version}-s${i + 1}`,
+      prompt: `${beat} [scene:${sceneId} shot:${i + 1}]`,
+      sourceSceneId: sceneId,
+      index: i + 1,
+    });
+  }
+  return drafts;
+}
+
+export class InMemorySceneShotPlanner {
+  private readonly byProject = new Map<string, Map<string, ScenePlanRecord>>();
+
+  plan(projectId: string, scenes: ScenePlanInput[], regenerateSceneIds: Set<string> = new Set()): PlannedSceneResult[] {
+    const sceneMap = this.byProject.get(projectId) ?? new Map<string, ScenePlanRecord>();
+    this.byProject.set(projectId, sceneMap);
+
+    const results: PlannedSceneResult[] = [];
+
+    for (const input of scenes) {
+      const previous = sceneMap.get(input.sceneId);
+      const fingerprint = computeFingerprint(input);
+      const shouldRegenerate = regenerateSceneIds.has(input.sceneId);
+      const unchanged = previous && previous.fingerprint === fingerprint && !shouldRegenerate;
+
+      if (unchanged && previous) {
+        results.push({
+          ...previous,
+          changed: false,
+          replacedShotIds: [],
+        });
+        continue;
+      }
+
+      const version = (previous?.version ?? 0) + 1;
+      const next: ScenePlanRecord = {
+        sceneId: input.sceneId,
+        version,
+        fingerprint,
+        shotDrafts: buildShotDrafts(input.sceneId, version, input.content, input.targetShotCount),
+        updatedAt: new Date().toISOString(),
+      };
+      sceneMap.set(input.sceneId, next);
+
+      results.push({
+        ...next,
+        changed: true,
+        replacedShotIds: previous ? previous.shotDrafts.map((shot) => shot.shotId) : [],
+      });
+    }
+
+    return results;
+  }
+
+  get(projectId: string, sceneId: string): ScenePlanRecord | undefined {
+    return this.byProject.get(projectId)?.get(sceneId);
+  }
+}

apps/api/src/http/app.ts

@@ -36,6 +36,7 @@ import {
   PromptTemplateVersionConflictError,
 } from "../domain/template/prompt-template";
 import { InMemoryUsageGuardrail } from "../domain/usage/usage-guardrail";
+import { InMemorySceneShotPlanner } from "../domain/script/scene-shot-planner";
 import { ProviderAdapterRegistry } from "../providers/adapter-registry";
 import { type ProviderName } from "../providers/types";
 import { InMemoryProviderKeyStore } from "../security/provider-key-store";
@@ -75,6 +76,7 @@ interface PromptTemplateRefs {
 export interface ApiState {
   readonly projects: Map<string, Map<string, ShotRecord>>;
   readonly shotToProject: Map<string, string>;
+  readonly shotToScene: Map<string, string>;
   readonly taskRepo: InMemoryGenerationTaskRepository;
   readonly callbackEventStore: InMemoryCallbackEventStore;
   readonly deadLetterStore: InMemoryDeadLetterStore;
@@ -85,6 +87,7 @@ export interface ApiState {
   readonly providerProfileStore: InMemoryProjectProviderProfileStore;
   readonly promptTemplateStore: InMemoryPromptTemplateStore;
   readonly usageGuardrail: InMemoryUsageGuardrail;
+  readonly sceneShotPlanner: InMemorySceneShotPlanner;
 }
 
 const importSchema = z.object({
@@ -95,6 +98,22 @@ const importSchema = z.object({
     }),
   ),
 });
+const scriptScenePlanSchema = z
+  .object({
+    scenes: z
+      .array(
+        z
+          .object({
+            sceneId: z.string().min(1),
+            content: z.string().min(1),
+            targetShotCount: z.number().int().positive().max(8).optional(),
+          })
+          .strict(),
+      )
+      .min(1),
+    regenerateSceneIds: z.array(z.string().min(1)).optional(),
+  })
+  .strict();
 
 const generateSchema = z.object({
   provider: z.enum(["runway", "kling"]).optional(),
@@ -252,6 +271,7 @@ export function createApiState(): ApiState {
   return {
     projects: new Map(),
     shotToProject: new Map(),
+    shotToScene: new Map(),
     taskRepo: new InMemoryGenerationTaskRepository(),
     callbackEventStore: new InMemoryCallbackEventStore(),
     deadLetterStore: new InMemoryDeadLetterStore(),
@@ -262,6 +282,7 @@ export function createApiState(): ApiState {
     providerProfileStore: new InMemoryProjectProviderProfileStore(),
     promptTemplateStore: new InMemoryPromptTemplateStore(),
     usageGuardrail: new InMemoryUsageGuardrail(),
+    sceneShotPlanner: new InMemorySceneShotPlanner(),
   };
 }
 
@@ -309,6 +330,7 @@ export function createApp(state = createApiState()) {
         mjAssets: [],
       });
       state.shotToProject.set(input.id, projectId);
+      state.shotToScene.delete(input.id);
     }
 
     state.projects.set(projectId, existing);
@@ -320,6 +342,64 @@ export function createApp(state = createApiState()) {
     });
   });
 
+  app.post("/projects/:id/script-scenes/plan", (req: Request, res: Response) => {
+    const parsed = scriptScenePlanSchema.safeParse(req.body);
+    if (!parsed.success) return res.status(400).json({ message: "Invalid request", errors: parsed.error.issues });
+
+    const projectId = routeId(req);
+    const projectShots = state.projects.get(projectId) ?? new Map<string, ShotRecord>();
+    state.projects.set(projectId, projectShots);
+    state.providerProfileStore.ensure(projectId);
+
+    const planned = state.sceneShotPlanner.plan(projectId, parsed.data.scenes, new Set(parsed.data.regenerateSceneIds ?? []));
+
+    for (const scene of planned) {
+      for (const oldShotId of scene.replacedShotIds) {
+        projectShots.delete(oldShotId);
+        state.shotToProject.delete(oldShotId);
+        state.shotToScene.delete(oldShotId);
+      }
+      for (const draft of scene.shotDrafts) {
+        const base = createShotCandidateState(draft.shotId);
+        projectShots.set(draft.shotId, {
+          ...base,
+          shotId: draft.shotId,
+          status: "draft",
+          prompt: draft.prompt,
+          promptTemplateRefs: {},
+          mjPrompts: [],
+          mjAssets: [],
+        });
+        state.shotToProject.set(draft.shotId, projectId);
+        state.shotToScene.set(draft.shotId, scene.sceneId);
+      }
+      appendActivityEvent(state, {
+        projectId,
+        type: "script_scene_planned",
+        source: "user",
+        payload: {
+          sceneId: scene.sceneId,
+          version: scene.version,
+          shotCount: scene.shotDrafts.length,
+          changed: scene.changed,
+        },
+      });
+    }
+
+    return res.status(200).json({
+      projectId,
+      plannedSceneCount: planned.length,
+      generatedShotCount: planned.reduce((acc, scene) => acc + scene.shotDrafts.length, 0),
+      plans: planned.map((scene) => ({
+        sceneId: scene.sceneId,
+        version: scene.version,
+        changed: scene.changed,
+        updatedAt: scene.updatedAt,
+        shotDrafts: scene.shotDrafts,
+      })),
+    });
+  });
+
   app.post("/providers/callbacks", (req: Request, res: Response) => {
     const parsed = providerCallbackSchema.safeParse(req.body);
     if (!parsed.success) return res.status(400).json({ message: "Invalid request", errors: parsed.error.issues });
@@ -585,6 +665,7 @@ export function createApp(state = createApiState()) {
     const projectId = routeId(req);
     const shots = [...(state.projects.get(projectId)?.values() ?? [])].map((shot) => ({
       shotId: shot.shotId,
+      sceneId: state.shotToScene.get(shot.shotId) ?? null,
       status: shot.status,
       prompt: shot.prompt,
       promptTemplateRefs: shot.promptTemplateRefs,

apps/api/src/http/script-shot-planner.test.ts

@@ -0,0 +1,43 @@
+import request from "supertest";
+import { describe, expect, it } from "vitest";
+import { createApp } from "./app";
+
+describe("script to shot planner api", () => {
+  it("creates plans from scenes and keeps unchanged scenes idempotent", async () => {
+    const app = createApp();
+
+    const first = await request(app).post("/projects/p-s5/script-scenes/plan").send({
+      scenes: [
+        { sceneId: "scene-1", content: "男主推门进入酒吧。镜头跟随到吧台。" },
+        { sceneId: "scene-2", content: "女主回头，沉默两秒后开口。", targetShotCount: 3 },
+      ],
+    });
+    expect(first.status).toBe(200);
+    expect(first.body.plannedSceneCount).toBe(2);
+    expect(first.body.generatedShotCount).toBeGreaterThanOrEqual(4);
+
+    const firstScene1ShotIds = first.body.plans[0].shotDrafts.map((shot: { shotId: string }) => shot.shotId);
+    expect(first.body.plans[0].version).toBe(1);
+
+    const second = await request(app).post("/projects/p-s5/script-scenes/plan").send({
+      scenes: [{ sceneId: "scene-1", content: "男主推门进入酒吧。镜头跟随到吧台。" }],
+    });
+    expect(second.status).toBe(200);
+    expect(second.body.plans[0].changed).toBe(false);
+    expect(second.body.plans[0].version).toBe(1);
+    expect(second.body.plans[0].shotDrafts.map((shot: { shotId: string }) => shot.shotId)).toEqual(firstScene1ShotIds);
+
+    const regenerated = await request(app).post("/projects/p-s5/script-scenes/plan").send({
+      scenes: [{ sceneId: "scene-1", content: "男主推门进入酒吧。镜头跟随到吧台。" }],
+      regenerateSceneIds: ["scene-1"],
+    });
+    expect(regenerated.status).toBe(200);
+    expect(regenerated.body.plans[0].changed).toBe(true);
+    expect(regenerated.body.plans[0].version).toBe(2);
+
+    const list = await request(app).get("/projects/p-s5/shots");
+    expect(list.status).toBe(200);
+    expect(list.body.shots.some((shot: { sceneId: string | null }) => shot.sceneId === "scene-1")).toBe(true);
+    expect(list.body.shots.every((shot: { shotId: string }) => !firstScene1ShotIds.includes(shot.shotId))).toBe(true);
+  });
+});

apps/api/src/index.ts

@@ -11,6 +11,7 @@ export * from "./domain/quality/quality-score";
 export * from "./domain/provider/provider-profile";
 export * from "./domain/template/prompt-template";
 export * from "./domain/usage/usage-guardrail";
+export * from "./domain/script/scene-shot-planner";
 export * from "./providers/types";
 export * from "./providers/runway-adapter";
 export * from "./providers/kling-adapter";

docs/spec/execution-ledger.md

@@ -4,8 +4,8 @@ Use this file as the progress ledger during delivery.
 
 ## Snapshot
 - Last updated: 2026-02-23
-- Current phase: Sprint 05 planning
-- Current sprint: Sprint 05 (not started)
+- Current phase: Sprint 05 execution
+- Current sprint: Sprint 05 (active)
 - Overall status: in_progress
 
 ## Milestones
@@ -20,6 +20,7 @@ Use this file as the progress ledger during delivery.
 | M6 | Sprint 04 execution start | done | Eng | 2026-02-22 | Sprint 04 issues #33-#40 implemented |
 | M7 | Sprint 04 closeout | done | Eng | 2026-02-23 | Integrated validation completed and issue set closed |
 | M8 | Sprint 05 planning kickoff | done | Eng | 2026-02-23 | Sprint 05 backlog and issue drafts prepared |
+| M9 | Sprint 05 execution start | in_progress | Eng | 2026-02-23 | S5-01 implemented locally, remote issue state sync pending |
 
 ## Decision Log
 | Date | Decision | Owner | Rationale |
@@ -37,8 +38,8 @@ Use this file as the progress ledger during delivery.
 | Tooling positioning | done | Keep adapter contracts aligned |
 | Master roadmap | done | Execute by phase gates |
 | Executable task list | done | 14 issues created and assigned |
-| Sprint backlog | done | Sprint 04 Issue #33-#40 closed |
-| Engineering implementation | in_progress | Create Sprint 05 issues and start #41 |
+| Sprint backlog | in_progress | Sprint 05 Issue #41-#48 active |
+| Engineering implementation | in_progress | Continue with Sprint 05 #42 after remote issue sync |
 
 ## Change Log (execution)
 | Date | Change | Commit / Link |
@@ -117,3 +118,4 @@ Use this file as the progress ledger during delivery.
 | 2026-02-23 | Add Sprint 04 integrated scale validation test flow (#40) | `e37e46b` |
 | 2026-02-23 | Sprint 04 scope fully completed in code/tests; Issue #40 remote close pending CLI auth | pending remote update |
 | 2026-02-23 | Prepare Sprint 05 backlog, issue drafts, and execution order | pending commit |
+| 2026-02-23 | Implement Script-to-Shot planner API baseline with idempotent scene planning tests (#41) | pending commit |

docs/sprints/sprint-05-issue-index.md

@@ -2,8 +2,8 @@
 
 ## Status Snapshot (2026-02-23)
 - Closed: none
-- In progress: none
-- Todo: #41, #42, #43, #44, #45, #46, #47, #48
+- In progress: #41 (local implemented, remote issue creation pending auth)
+- Todo: #42, #43, #44, #45, #46, #47, #48
 
 ## Issue Links
 41. [#41 [BE] Script-to-shot planner API baseline](https://github.com/demshine/cineweave-platform/issues/41)
@@ -16,4 +16,4 @@
 48. [#48 [QA] Sprint 05 integrated creator flow validation](https://github.com/demshine/cineweave-platform/issues/48)
 
 ## Next Task
-- Create Sprint 05 issues #41-#48, assign to `@echowang1`, and start #41.
+- Sync remote issue states, then start #42 Midjourney character consistency registry.