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·네비게이션만 배포 (지금 바로 가능)

### 필요 작업
```bash
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 토큰 인증**입니다:
```bash
higgsfield auth login && higgsfield workspace set
# 생성된 ~/.config/higgsfield/{credentials,config}.json 을 p2v-higgsfield 볼륨에 주입
# CLI가 토큰을 자동 갱신하며 파일을 다시 쓰므로 :ro 마운트 금지
```

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

```bash
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. 검증 절차

```bash
# 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. **카피 어휘** — 가게→업체, 크롤링→수집.