o2o-castad-frontend/DEPLOY_REQUEST.md

배포 요청서 — castad 프론트엔드 feature-ssulbox-ado2-ds

요청일	2026-08-20
대상 저장소	gitea.o2o.kr/castad/o2o-castad-frontend
브랜치	feature-ssulbox-ado2-ds (브랜치 최신 커밋을 그대로 배포)
코드 커밋	0ca2140 — 이 문서는 그 위에 문서만 얹은 커밋입니다
대상 환경	dev-ssul.castad.net
연관 저장소	gitea.o2o.kr/castad/o2o-ado2-poster-to-video (신규 연동 대상)

---

0. 한 장 요약

이번 브랜치는 두 덩어리입니다. 서로 독립적이라 나눠서 배포할 수 있습니다.

덩어리	내용	추가 인프라	배포 난이도
A. DS 통일 + 네비게이션	썰박스 디자인 시스템 통일, 진입 화면 탭 개편, 레이아웃 버그 수정	없음	기존과 동일
B. 포스터 파이프라인	무빙 포스터(F1), 포스터 스타일링(F2) 탭	P2V 서버 신규 배포 필요	선행조건 5개

권장: A를 먼저 배포하고, B는 P2V 서버가 준비된 뒤 여는 2단계 진행. A만 배포해도 화면은 깨지지 않습니다. 포스터 탭 2개만 "접근 키 입력" 화면이나 연결 실패로 떨어지고, ADO2·썰박스 탭은 평소대로 동작합니다.

---

1. A안 — DS·네비게이션만 배포 (지금 바로 가능)

필요 작업

git fetch origin
git checkout feature-ssulbox-ado2-ds   # 0ca2140
npm ci
npm run build

환경변수

변수	값	비고
VITE_API_URL	기존 값 유지	castad 백엔드
VITE_P2V_URL	설정하지 않음	미설정 시 포스터 탭만 비활성 상태로 남음

검증

1. 진입 화면에 탭 4개(ADO2 / 썰박스 / 무빙 포스터 / 포스터 스타일링)가 아이콘 타일로 표시
2. 썰박스 탭 — 시나리오 카드에 이모지·시나리오별 색이 없고 선택 시 민트 테두리
3. 모바일(375px)에서 상단 ADO2 로고가 잘리지 않을 것 ← 이번에 고친 버그
4. ADO2 탭 기존 플로우(URL 입력 → 브랜드 분석) 정상

---

2. B안 — 포스터 파이프라인까지 배포

2-1. 선행조건 (P2V 서버 측)

P2V 저장소의 product/DEPLOY.md가 원본 문서입니다. 아래는 castad 연동에 필요한 것만 추린 것입니다.

#	항목	상태	담당
1	P2V 서버(:8010) 배포	미배포	Dev
2	SUNO_CALLBACK_URL — Suno가 결과를 POST할 공개 주소	도메인 확정 필요	Dev
3	Higgsfield CLI 토큰 — 머신에서 사람이 1회 로그인	자동화 불가	담당자
4	P2V를 HTTPS로 서빙	미확인	Dev
5	F2 템플릿 이미지 파일 별도 전달	저장소에 없음	요청자

4번이 이번에 새로 확인된 항목입니다. dev-ssul.castad.net은 HTTPS인데 P2V가 HTTP면 브라우저가 mixed content로 전부 차단합니다. P2V 앞에 리버스 프록시로 TLS를 붙여야 합니다.

5번 주의: P2V 저장소는 templates/*.jpg를 gitignore합니다(영화 포스터 = 저작권). templates.json(메타데이터)만 커밋돼 있어 클론 직후 F2는 썸네일이 전부 깨집니다. compose가 ./server/templates를 호스트 바인드 마운트하므로, 이미지 21개를 서버에 직접 넣어야 합니다. F2를 이관 범위에서 빼는 것도 선택지입니다(F1은 영향 없음).

2-2. P2V 서버 환경변수

product/.env.example을 .env로 복사해 채웁니다.

변수	필수	설명
CHATGPT_API_KEY	✅	영역검출·나레이션·모션선정·TTS·F2
SUNO_API_KEY	✅	BGM 생성
SUNO_CALLBACK_URL	✅	Suno 결과 수신용 공개 URL. 없으면 BGM 단계에서 죽음
P2V_ACCESS_KEY	✅	팀 공용 키 1개. 비우면 무인증 — 배포에서는 반드시 설정
P2V_ALLOWED_ORIGINS	✅	https://dev-ssul.castad.net 추가 필수. 없으면 CORS 차단
P2V_QUEUE_PATH	compose가 지정	큐를 볼륨 위로. 이미지 레이어에 두면 재배포 때 소실

Higgsfield는 환경변수가 아니라 CLI 토큰 인증입니다:

higgsfield auth login && higgsfield workspace set
# 생성된 ~/.config/higgsfield/{credentials,config}.json 을 p2v-higgsfield 볼륨에 주입
# CLI가 토큰을 자동 갱신하며 파일을 다시 쓰므로 :ro 마운트 금지

2-3. castad 프론트엔드 빌드

VITE_P2V_URL="https://<P2V 공개 도메인>" npm run build

Vite는 빌드 시점에 값을 산출물에 박습니다(런타임 주입 아님). 검증했습니다 — 값을 넣으면 번들에 그대로 들어가고 기본값 localhost:8010은 남지 않습니다.

2-4. 알아둘 제약

• api를 스케일아웃하면 안 됩니다. 인메모리 큐 + 파일 상태(data/jobs.json) 구조라 인스턴스가 늘면 큐가 깨집니다. compose에도 명시돼 있습니다.
• 처리 시간 1건 4~6분 (Suno ~2분 + veo ~3분).
• 렌더 비용 veo 22크레딧/편(≈$1.12) + OpenAI·Suno 소액.
• 인증이 단일 팀 키라 사용자별 크레딧 차감이 없습니다. 현재는 내부 시연 범위이고, 대외 공개 시 castad 백엔드에 /p2v/* 프록시를 세워 카카오 인증·크레딧을 얹는 것이 다음 수순입니다. 프론트에서 갈아끼울 지점은 src/utils/p2vApi.ts 한 파일입니다.

2-5. 검증 절차

# 1) 서버 헬스체크 (인증 없이 열려 있는 유일한 경로)
curl -i https://<P2V 도메인>/api/health          # → 200

# 2) 인증 게이트 동작
curl -i https://<P2V 도메인>/api/f2/templates    # → 401
curl -i -H "X-P2V-Key: <키>" https://<P2V 도메인>/api/f2/templates   # → 200 + JSON

브라우저에서:

#	확인 항목	기대 결과
1	무빙 포스터 탭 첫 진입	접근 키 입력창 → 키 입력 후 업로드 화면
2	포스터 업로드	5단계 스텝퍼가 "분석"으로 진행, 진행바·스테이지 라벨 표시
3	1~2분 후	검수 화면 — 나레이션 3문장, 모션 칩, 메타태그, 우측 분석 이미지
4	승인	"생성" 단계로 넘어가고 4~6분 뒤 영상 재생 + MP4 다운로드
5	포스터 스타일링 탭	템플릿 썸네일 표시 (깨지면 5번 선행조건 미이행)
6	모바일(375px) 검수 화면	포스터가 위, 승인 버튼이 하단 탭바 위에 고정

F1은 검수 게이트에서 멈춥니다. 승인 전까지 TTS·BGM·렌더가 시작되지 않으므로, 3번까지만 확인하면 유료 API를 거의 쓰지 않고 연동을 검증할 수 있습니다.

---

3. 롤백

프론트엔드는 이전 커밋으로 되돌려 재빌드하면 끝입니다. P2V는 castad와 별도 서비스라 내려도 castad 본체에 영향이 없습니다 — 포스터 탭만 연결 실패 상태가 됩니다.

---

4. 이번 브랜치에서 고친 기존 버그

배포 후 확인해 두면 좋은 항목입니다. 모두 포스터 기능과 무관하게 A안에 포함됩니다.

1. 진입 화면 세로 잘림 — justify-content: center + overflow: hidden 조합이라 콘텐츠가 뷰포트보다 길면 위로 넘친 부분에 스크롤로도 닿을 수 없었습니다. 자식의 margin: auto 0 중앙정렬로 교체했습니다.
2. 한글 단어 중간 줄바꿈 — word-break: keep-all 적용.
3. 입력·안내·제출 박스 높이 불일치(46/38/48) — 48px로 통일.
4. 카피 어휘 — 가게→업체, 크롤링→수집.