From 40895207eee0e88473c69927bac7204a037937fd Mon Sep 17 00:00:00 2001 From: Haewon Kam Date: Thu, 20 Aug 2026 13:07:43 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EB=B0=B0=ED=8F=AC=20=EC=9A=94=EC=B2=AD?= =?UTF-8?q?=EC=84=9C=EB=A5=BC=20=EB=B8=8C=EB=9E=9C=EC=B9=98=EC=97=90=20?= =?UTF-8?q?=EB=82=A8=EA=B8=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 이 브랜치를 dev-ssul 에 올릴 때 필요한 것을 한 곳에 모았다. A(DS·네비게이션)와 B(포스터 파이프라인)를 나눠 배포할 수 있다는 점, B 의 선행조건 5개, P2V 환경변수, 검증 절차를 담았다. 특히 두 가지는 문서 없이는 배포에서 반드시 걸린다: - P2V 를 HTTPS 로 서빙해야 한다 — dev-ssul 이 HTTPS 라 HTTP 면 mixed content 로 전부 차단된다 - P2V 저장소가 templates/*.jpg 를 gitignore 해서, 서버에서 클론하면 F2 썸네일이 전부 깨진다 Co-Authored-By: Claude Opus 5 --- DEPLOY_REQUEST.md | 157 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 DEPLOY_REQUEST.md diff --git a/DEPLOY_REQUEST.md b/DEPLOY_REQUEST.md new file mode 100644 index 0000000..dcd728f --- /dev/null +++ b/DEPLOY_REQUEST.md @@ -0,0 +1,157 @@ +# 배포 요청서 — 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://" 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:///api/health # → 200 + +# 2) 인증 게이트 동작 +curl -i https:///api/f2/templates # → 401 +curl -i -H "X-P2V-Key: <키>" https:///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. **카피 어휘** — 가게→업체, 크롤링→수집.