2026년 7월 변경 이력
2026-07-24 (금)
📚 Film 서비스 계층형 데이터 모델 문서화
Film Service문서 카테고리를 신설하고, AI 영화 제작 워크스페이스의 제품 정의와 사용자 흐름,Project -> Sequence -> Scene -> Beat/Shot계층 모델,Beat-Shot MappingM:N 계약을 정리- 독립 Asset Library와 Project/Sequence/Scene/Beat/Shot별
Asset Usage,Asset State,Asset Reference구분, 에셋 버전과 연속성 검토의 기준을 문서화 - Scene 레벨의 Concept Frame, Scene Layout, Blender의 Physical/World State 역할 및 Beat/Sequence의 Narrative State 역할을 분리해 정의
- Prompt/Reference Composer, 모델 Adapter, Generation Attempt, Selected Clip, 후속 편집 단계의 목표 계약과 현재 구현되지 않은 범위를 명시
- 현재 평면도 에디터 MVP와 장기 계층형 서비스 모델을 구분하고, 구현 우선순위와 미결정 설계 과제를 기록
📚 Film Context Director·Edit Relation·2단계 생성 설계 추가
- 데이터 상속과 Renderer Prompt 주입을 분리하고, 전후 Shot·활성 Beat·연속성·편집 의도를 해석하는
Context Director AI와 실제 화면을 구현하는Shot Renderer의 역할을 구분 director_private,generator_visible,validator_only,editor_visibleField Routing과 미래·숨김 정보 차단, 긍정형 현재 상태 중심 Renderer Brief 원칙을 문서화- 기본 3-Shot Context Window, 생성 전 Brief 작성과 생성 후 맥락 QA 기준을 추가
- 쿨레쇼프 효과와 Shot 연결의 관객 추론을 표현하는
Edit Relation모델, 순서 변경 시needs_review, Timeline/Edit Relation UI 요구사항을 정의 - Shot을
Frame Design과Motion Design으로 확장하고 Start Image 생성과 시작 이미지 기반 Video 생성을 분리하며, Video Prompt가 기존 프레임 정보를 반복하지 않는 원칙을 반영
2026-07-20 (월)
✅ film — 평면도 프롬프트 동적화 + 배치 경고 배지
- 없는 조명 묘사 방지: 평면도 프리픽스가 씬에 실제로 존재하는 타입만 설명하도록 동적화 — 조명이 없는 씬인데도 "small glowing dot" 문구 때문에 출력에 조명이 그려지던 문제 해소. 조명은 "광원 위치를 표시하는 점"으로만 서술
- 인물 방향 지시도 동적화: 인물이 없는 씬에서는 틱 마크/방향 지시 문장 자체를 프롬프트에서 제외
- 배치 경고 배지: 오브젝트끼리 너무 가까우거나(도형 반경 기준 0.8배 이내) 인물이 카메라 FOV 안 바로 앞(110 월드 단위 이내)에 있으면 캔버스 상단에 작은 경고 배지 표시. 정보 제공 전용이라 생성 요청을 막지 않으며, ✕로 닫을 수 있고 경고 구성이 바뀌면 다시 표시됨 (
sceneWarnings.ts+SceneWarnings.tsx) - frontend-vivid-film lint/build 통과 (커밋 8268cf3)
✅ film — 캡처 정제(그리드 숨김·레이블 확대) + 단일 캐릭터 지시
- 캡처 시 배경 그리드 레이어(
gridLayer)를 숨겨 평면도에 그리드가 찍히지 않도록 함 - 캡처 전용으로 레이블 텍스트를 12px → 22px(폭 200)로 확대해 AI 모델이 라벨을 더 잘 읽도록 하고, 캡처 후 원래 크기로 복원
- 캐릭터 패널 지시 강화: "각 패널은 정확히 한 명의 캐릭터만 담고(한 패널에 같은 캐릭터의 여러 뷰가 있을 수 있음), 출력에서 어떤 캐릭터도 중복 생성하지 말 것"을 명시 — 4-way 시트가 여러 명으로 오인되는 문제 완화
- frontend-vivid-film lint/build 통과 (커밋 40bb884)
✅ film — 카메라 방향 기준 회전 캡처 + 참조 프롬프트 정제
- 회전 캡처: 생성 요청 시 스테이지 전체를 회전해 대상 카메라가 캡처 이미지의 위쪽을 바라보게 함(1인칭 배치와 동일한 직관). 텍스트 레이블은 역변환으로 수평·오브젝트 하단 유지, 캡처 후 원상 복구 (커밋 f798a20)
- 동물/크리처 참조 개선: 인물 지시를 'facial identity/hairstyle/outfit' 같은 사람 전제 표현에서 "정체성과 고유 특징 유지, 동물·크리처는 절대 사람으로 바꾸지 말 것"으로 교체
- 중복 프롬프트 정리: 패널 지시를 타입별 그룹(character/light/prop/wall)으로 묶어 한 번만 서술, 동일 참조 이미지를 쓰는 오브젝트는 패널 하나로 합치고 라벨은 alias로 표기(분리 참조 미디어에는 라벨별로 각각 기록)
- 조명 도형 변경: 카메라 FOV 삼각형과 헷갈리지 않도록 삼각 웨지 제거, 글로우 점 + 광선으로 표시
- 평면도 프리픽스에 회전 방향(카메라가 이미지 위쪽을 봄), 조명 점 표기, 색상-JSON 매칭 설명 추가
- frontend-vivid-film lint/build 통과
✅ 인물별 방향 지시 강화 + 상세 모달 메인 이미지 인라인 줌
- film: 평면도 프리픽스에 인물의 방향 틱(tick mark) 설명과 "각 인물은 자기 틱이 가리키는 방향을 바라봐야 하며, 틱이 카메라를 향하지 않는 한 카메라를 바라보게 하지 말 것"이라는 지시를 추가 — 모두가 카메라를 바라보는 문제 완화 (커밋 c867b72)
- frontend-vivid-ai: 갤러리/관리자 상세 모달의 메인 결과 이미지에 인라인 줌 적용 —
useMainImageZoom훅 신설(휠/트랙패드 핀치 줌, 포인터 기준 확대, 드래그 패닝, 클릭 3배 토글, 줌 배율 배지), 참조 이미지와 동일한 조작감을 별도 모달 없이 메인 패널에서 제공 (커밋 a2879133) - frontend-vivid-film lint/build, frontend-vivid-ai eslint/tsc 통과
✅ film 에디터 — 평면도 가독성·카메라별 생성 컨텍스트 + 상세 보기 합성 참조 표시
- 회전 중심 고정: 레이블을 회전/스케일 그룹에서 분리(외곽 드래그 그룹 + 내부 도형 그룹 구조)해 트랜스포머 박스와 회전 중심이 도형에만 고정. 레이블은 항상 수평·오브젝트 아래 유지
- 카메라별 컨텍스트 분리: 생성 요청한 카메라 외의 카메라는 JSON(
buildObjectNotes)에서 제외하고,captureFloorPlan(cameraId)가 다른 카메라를 숨긴 채 스크린샷 캡처(범위 계산도 제외) - 프리셋 컬러 20색: 오브젝트 생성 시 씬에서 가장 적게 쓰인 색을 자동 배정, Inspector에 스와치 팔레트 추가, JSON에 정확한 color hex 포함 — AI가 라벨 텍스트 대신 색으로도 오브젝트를 매칭 가능
- 도형 식별성 개선: 카메라(바디+렌즈 배럴+뷰파인더), 조명(광선), 벽(해치), 소품(대각선 상자) 등 타입별 글리프 강화
- 샷 패널 공간 확보: 패널 높이를 clamp(240px, 32vh, 380px)로 늘리고 카드 내부 스크롤 + 프롬프트 영역 최소 높이 고정
- 관리자/갤러리 상세: 분리된 참조 미디어와 함께 모델에 실제 전달된 합성 참조 이미지(snapshot refs)도 맨 앞에 '합성 참조 이미지' 라벨로 표시
- frontend-vivid-film lint/build 통과 (커밋 036a678), frontend-vivid-ai eslint/tsc 통과 (커밋 b9fb6f61)
✅ film 에디터 — 레이블 가독성 + 프롬프트 정적화
- 평면도 레이블의 불투명 배경 태그 제거(텍스트+그림자만 표시)해 오브젝트·레이블끼리 서로 가리는 문제 해소
- 레이블이 오브젝트 회전/스케일에 따라 돌아가지 않도록 역변환을 적용, 항상 오브젝트 아래쪽에 수평으로 고정 — 생성용 스크린샷에서도 AI가 라벨을 읽기 쉬워짐
buildShotPrompt에서 배치 연동 동적 문구(프레임 내 좌/우 위치, 원근, 카메라를 바라본다는 지시, 샷 사이즈 추정)를 전부 제거 — 평면도 이미지와 충돌하던 facing/position 지시 소거, 구도와 무관한 스타일 지시(cinematic film still, shallow depth of field, film grain, dramatic lighting)만 유지- frontend-vivid-film lint/build 통과 (커밋 f1b055f)
✅ film 에디터 — 모든 오브젝트 타입에 참조 이미지 첨부
- Inspector의 참조 이미지 첨부 UI를 인물 외 조명·소품·벽에도 확장(인물은 '캐릭터 시트', 그 외는 '참조 이미지' 섹션으로 표기)
collectObjectsWithRefs: 참고 이미지가 있는 씬 전체 오브젝트를 역할 우선순위(인물→조명→소품→벽)로 최대 9개까지 수집- 합성 프리픽스가 패널을 타입별로 서술(character/light/prop/wall 지시문 분기)하고, 전원 인물이면 character reference sheet / 혼합이면 scene reference sheet로 명칭 분기
- ShotPanel이 FOV 내 인물만이 아니라 씬 전체의 참조 오브젝트를 합성 시트·
recipe_reference_input_images에 반영(FOV 밖 조명 분위기도 참조 가능) - frontend-vivid-film lint/build 통과 (커밋 5b66958)
✅ 참조 이미지 합성 상한 4장 → 9장 확대
- gpt-image 합성 참조 모드의 패널 상한을 4장에서 9장으로 확대: 5
9장은 3x3 그리드(768px 셀, 캔버스 2304x2304)로 합성하고 14장 레이아웃은 기존 그대로 유지 - frontend-vivid-ai: 시트 빌더 3개(
personaStudioReferenceSheet·personaReferenceSheet·styleCreationReferenceSheet)와 생성 호출부(PersonaCreatePanelReferenceGeneration.utils·styleCreationGeneration.helpers)의slice(0, 4)상한을 9로 조정, 프리픽스 패널 수 표기를 nine까지 확장 - frontend-vivid-film:
referenceSheetMAX_PANELS 4→9, 인물 5~9명 시 좌측 절반을 3x3 그리드로 합성하고 프리픽스에 그리드 읽기 순서 명시 - 상세 보기의 분리 참조 미디어 표시는 이미 상한 없이 동작(갤러리 상세 모달·페르소나/스타일 히스토리)함을 확인해 최대 9개까지 그대로 표시
- frontend-vivid-ai
tsc --noEmit·eslint, frontend-vivid-filmlint/build통과
2026-07-19 (일)
✅ 생성물 상세 보기 — 분리된 참조 미디어 + 확대(줌/패팅) 프리뷰
GalleryItemDetailModal(관리자 AI 생성·페르소나 스튜디오·스타일링 허브 공용)이snapshot.referenceInputImages를 우선 사용해 합성 이미지 대신 분리된 참조 미디어를 라벨과 함께 표시(기존 4개 제한 제거, 비디오/오디오 참조도 타입에 맞게 타일 표시)- 참조 썸네일 클릭 시 이미지는
ImagePreviewModal(휠/터치패드 줌·드래그 패팅 지원), 비디오/오디오는ReferenceMediaPreviewModal로 확대 표시 - 관리자 생성기(
useGeneratorSubmit)가 업로드한 이미지 입력을recipe_reference_input_images로 기록해 신규 생성물도 분리 표시 - film ShotPanel도 인물 참고 이미지와 평면도 스크린샷을 개별 업로드해
recipe_reference_input_images로 기록(합성 시트는 그대로image_1으로 전달) - frontend-vivid-ai
tsc --noEmit·해당 파일 eslint, frontend-vivid-filmlint/build통과
✅ film.surfai.org 에디터 디테일업 — 평면도 스크린샷 + 오브젝트 메모 AI 전달
- 생성 시 Konva 캔버스 전체를 자동 스크린샷(
stageCapture.ts, 선택 해제 후 캡처·복원, 최대 1600px PNG)해 참고 이미지로 활용 - 매핑 워크플로우(gpt-image)가 참고 이미지 1장만 지원하므로 캐릭터 시트와 평면도를 2048x1024 한 장으로 합성(좌: 인물 세로 스택 / 우: 평면도)해
image_1으로 전달, 어떤 카메라 라벨로 렌더링할지 프리픽스에 명시(createShotReference) - 모든 오브젝트에
description필드 추가(카메라: 샷 타입/연출 의도). 작성된 오브젝트만buildObjectNotes가 JSON으로 만들어 프롬프트 뒤에 부착 — 위치/회전/색상은 스크린샷에 담기므로 JSON에서 제외 - 캔버스에 모든 오브젝트(벽 포함) 이름 태그를 어두운 배경 라벨로 상시 표시해 AI가 이미지 속 오브젝트와 JSON을 라벨로 매칭 가능
- film
lint/build통과
문서 반영
service-planning/09-film-subdomain-plan.md
✅ film.surfai.org 씬 서버 저장 413 수정 — 참고 이미지 S3 외부화
- 씬 doc에 인물 참고 이미지가 base64 dataUrl로 포함돼 기본 body 크기 제한을 넘던 413(
request entity too large) 수정 - 백엔드에
POST /v1/storage/presigned-get추가(s3Path → presigned GET URL) frontend-vivid-film: 서버 저장 시 refImage를 S3(permanent)에 업로드하고 doc에는 s3Path만 저장, 불러오기 시 presigned-get +/v1/storage/download프록시로 dataUrl 복원(새scenePersistence.ts). 이미 업로드된 이미지는 s3Path 재사용- backend
tsc --noEmit, filmlint/build통과
문서 반영
service-planning/09-film-subdomain-plan.md
✅ film.surfai.org 씬 서버 저장/불러오기 API 및 FILM_SHOT_IMAGE_GEN 프리셋 추가
- 백엔드에
film모듈 신설:film_scenes테이블(마이그레이션CreateFilmScenes1772910000000)과GET/POST /v1/film/scenes,GET/PUT/DELETE /v1/film/scenes/:id제공(JwtAuthGuard + 소유자 검증, 목록은 doc 본문 제외) frontend-vivid-film에디터에 서버 저장(최초 POST·이후 PUT, 마지막 저장 시각 툴팁)과 서버 불러오기(씬 목록 모달에서 로드/삭제) 추가 — 로컬스토리지 자동 저장은 스크래치 용도로 유지- 백엔드/본프론트
FEATURE_KEYS와 관리자 워크플로우 매핑 프리셋에FILM_SHOT_IMAGE_GEN(Film Shot Image) 추가 - backend
tsc --noEmit, filmlint/build통과 (백엔드 재시작 시 마이그레이션 자동 실행)
문서 반영
service-planning/09-film-subdomain-plan.md
✅ film.surfai.org Phase 0~1 구현 및 Shot Designer 분석 반영
film.surfai.org 계획의 Phase 0(백엔드 쿠키 도메인)과 Phase 1(레포/인프라 기반)을 구현하고, 레퍼런스 툴 분석을 설계 문서에 반영했습니다.
- 백엔드
getAuthCookieOptions()에AUTH_COOKIE_DOMAIN환경변수 기반 쿠키Domain속성을 추가(서브도메인 SSO 기반) frontend-vivid-filmNext.js 앱 스캐폴드, Dockerfile, GitHub 레포/submodule 등록,docker-compose.dev.yml에frontend-film서비스(포트 4100) 추가- Shot Designer(Hollywood Camera Work) 분석을 설계 문서에 반영하고 film 프론트엔드 서브모듈을 9개로 확장
문서 반영
service-planning/09-film-subdomain-plan.md
✅ film.surfai.org Phase 2 구현 및 운영 도메인 기준 반영
frontend-vivid-film에 인증 연동(axioswithCredentials+ 401 refresh 인터셉터,useUser훅), 로그인 화면, 포인트 잔액 표시를 구현(lint/빌드 통과)- 실제 운영이
dev.surfai.org가 아닌surfai.org단일 환경(비용 절약)임을 반영해, 쿠키 도메인.surfai.org/ film 도메인film.surfai.org기준을 설계 문서에 명시 docker-compose.dev.yml의 film 앱 기본 API URL을https://film.surfai.org/api로 조정
문서 반영
service-planning/09-film-subdomain-plan.md
✅ film.surfai.org Phase 3 평면도 에디터 MVP 구현 (로컬)
frontend-vivid-film에 Konva 기반 평면도 에디터 코어 구현: 카메라(FOV 표기)/인물/조명/소품/벽 오브젝트 배치·이동·회전·스케일, 그리드/스냅, 줌/팬, z-order,/editor라우트 신설- 실행 취소/다시 실행 히스토리, 로컬스토리지 자동 저장, 씬 JSON(v1) 내보내기/가져오기 추가(서버 저장 API는 후속)
- lint/빌드 통과
문서 반영
service-planning/09-film-subdomain-plan.md
✅ film.surfai.org 로컬 로그인 404 수정 및 에디터 속성 패널(Inspector) 추가
- 로컬 환경에서 film(:4100)의 로그인 요청이 Next.js 자신에게 향하던 404 수정 —
NEXT_PUBLIC_API_BASE_URL미설정 시 브라우저가http://localhost:3000/api로 직접 호출(운영은 same-origin/api프록시 방식 유지). surfai.org → film SSO 정상 동작 확인 - 평면도 에디터 우측에 속성 패널 추가: 선택 오브젝트의 이름/위치/회전/크기/색상 편집, 카메라 FOV(10~120°) 설정, 미선택 시 레이어 목록에서 클릭 선택
- 필드 편집은 포커스 세션당 1회만 히스토리에 쌓이도록
beginTransientEdit스토어 액션 추가(실행 취소 단위 개선) - lint/빌드 통과 (
frontend-vivid-film25425ab)
문서 반영
service-planning/09-film-subdomain-plan.md
✅ film.surfai.org 새로고침 버그 수정 및 Phase 4 샷리스트·생성 연동 (로컬)
- 새로고침 시 캔버스가 빈 상태로 남던 버그 수정 —
hydrated=false동안 ResizeObserver가 컨테이너에 붙지 못해 Stage가 마운트되지 않던 문제 (b8e3a79) - Phase 4 구현 (
9f983e8): 카메라 1개 = 샷 1개 자동 매핑, FOV 내 오브젝트를 피사체로 분석(프레임 내 좌/우·원근·인물이 카메라를 보는 방향·조명 위치), 영어 시네마틱 프롬프트 자동 생성(샷별 편집 가능) - 하단 샷 패널에서 워크플로우(IMAGE·레퍼런스 불필요 그룹)/화면비(16:9 기본)/품질(HD·FHD) 선택 후
POST /v1/generation/from-template호출,/v1/creations폴링으로 완료 시 결과 썸네일 표시, 예상 VT 비용 표기 - 실제 생성 E2E는 로컬 AI 노드(ai-server) 연결 상태에서 사용자 확인 예정
문서 반영
service-planning/09-film-subdomain-plan.md
✅ film.surfai.org 캐릭터 시트 참고 이미지 생성 및 복수 인물 프롬프트 개선 (로컬)
- 생성 실패 원인 진단:
Worker timeout (300s without terminal event)는 ComfyUI 컨테이너가 작업 도중 재시작(18:30:56, WS 502)되며 종료 이벤트가 유실된 인프라 이슈였음을 확인. 워크플로우 자체는 VAE 디코드까지 정상 실행되어 film → 백엔드 → ai-node-agent → ComfyUI 파이프라인은 정상 동작 - 인물 오브젝트에 캐릭터 시트 이미지 첨부 지원(최대 768px JPEG 데이터 URL로 씬 JSON에 저장). 생성 시 참조 인물들을 한 장의 합성 시트(1·2·3·4패널 레이아웃, personaStudioReferenceSheet와 동일 방식)로 만들어
/v1/storage/presigned-put업로드 후image_1로 전달 — gpt-image처럼 참고 이미지 1장 제한 워크플로우와 호환 - 복수 인물 프롬프트 개선: 인원수 명시("two people") + 인물별 위치/방향 절, 캐릭터 라벨과 시트 패널 매핑. 샷 요약에 프레임 밖 인물 수 표시, 워크플로우 선택에 참고이미지 지원 여부 표기, 미지원 워크플로우는 경고 후 시트 없이 생성
frontend-vivid-film66df8eb, lint/빌드 통과
문서 반영
service-planning/09-film-subdomain-plan.md
✅ film.surfai.org 생성 실패 원인 확정 및 해상도 기본값 조정 (로컬)
- 동일 증상(
Worker timeout 300s) 재발 원인을 로그/DB로 확정: 로컬 ComfyUI가 CPU 전용(pytorch+cpu, VRAM DISABLED)인데 FHD(1920×1088) 작업 시 KSampler 1스텝 약 100초 후 VAE 디코드 구간에서 컨테이너가 재시작(2회 연속 동일 패턴, 종료 이벤트 유실 → agent 300초 타임아웃) - 대조 확인: 같은 시각 gpt-image 워크플로우 FHD 16:9 작업은 118초로 COMPLETED — film → 백엔드 → agent → ComfyUI 파이프라인 및 gpt-image 경로는 정상
- 로컬 SD 기본 워크플로우는 KSampler steps=1 테스트 구성, 백엔드가 variant 입력 min/max를 강제하지 않아 HD(1344×768)도 검증 통과 확인
- 조치: film 샷 패널 품질 기본값 FHD→HD (
948334d),docker-compose.dev.yml의 ai-node-agent에JOB_WAIT_TIMEOUT_SECONDS(기본 900) 추가. 실행 중인 agent 컨테이너는 별도 설정으로 띄운 상태라 재생성 시 반영 안내
문서 반영
service-planning/09-film-subdomain-plan.md
✅ film.surfai.org feature key 매핑 + 실시간 완료 수신 전환 (로컬)
- 생성 요청을 하드코딩된 workflowId 방식에서 본서비스와 동일한 feature key 매핑 방식으로 전환:
FILM_SHOT_IMAGE_GEN키로 요청하면 백엔드가 매핑된 워크플로우 그룹/variant를 자동 해석. 신규 feature key는 문자열 검증만 통과하면 되므로 백엔드 코드 변경 없이 등록 가능 - 로컬 DB에
FILM_SHOT_IMAGE_GEN → gpt-image 그룹(38c35fa5)매핑 등록(visibility PUBLIC — PRIVATE/ADMIN_ONLY는 일반 유저 생성 불가). jaytsol 계정은 user 권한이라 admin API 대신 DB 직접 등록했으며, 운영은 관리자가POST /v1/workflows/mappings로 등록 필요 - 완료 수신을
/v1/creations반복 폴링에서 본서비스와 동일한/ai-realtimeSocket.IO 이벤트(prompt_progress_update) 방식으로 전환 — 진행률 % 표시, 종결 시 결과를 한 번만 조회, 10분 이벤트 대기 폴백.resolveRealtimeOrigin의 로컬 폴백이 Next.js 오리진으로 향하던 버그도 함께 수정 frontend-vivid-film6bedfc8, lint/빌드 통과
문서 반영
service-planning/09-film-subdomain-plan.md
2026-07-18 (토)
✅ film.surfai.org 서브도메인 서비스 설계 확정
영화적 연출을 위한 촬영 평면도(부감도) 제작 및 영상 생성 연동 서비스를 별도 서브도메인으로 분리하는 설계를 정리했습니다.
- film 프론트엔드는 신규 독립 컨테이너로 분리하고, 백엔드·DB·포인트(VT)는 기존 서비스를 공유하는 것으로 정리
- 서브도메인 SSO는 인증 쿠키의
Domain속성 공유 방식으로 확정하고, 환경변수AUTH_COOKIE_DOMAIN(dev:.dev.surfai.org, prod:.surfai.org)으로 환경별 격리를 명시 - 도메인별 same-origin
/api프록시를 유지해 CORS 변경 없이 연동하는 것으로 정리 - 전체 로드맵에 film.surfai.org 단계(1~4단계) 추가
문서 반영
service-planning/09-film-subdomain-plan.mdproject-overview/02-planning/ROADMAP.md