SceneMaker SBS 공개 뷰어 — 분석 완료 영상 탐색 · 클립 편성 · 결과 재생.
cp .env.local.example .env.local # 실값 입력
npm install
npm run dev # http://localhost:3000
npm run build && npm start # 운영
npm run typecheck로컬 개발에서 S3 presigned 발급에 MFA 세션이 필요하다:
source ~/.claude/scripts/aws-mfa-auth.sh # AWS_PROFILE=mfaapp/ App Router 페이지 + API Route(얇게)
components/ 화면 컴포넌트("use client" 는 상호작용이 필요한 것만)
lib/server/ DB·S3·agent 접근 — 전부 "server-only"
lib/domain/ 상태코드·카테고리·길이 선택지 상수
lib/ 공용 타입·포맷터(서버/클라이언트 공용, 순수 함수만)
proxy.ts 접근 통제 자리(현재 통과 — 로그인은 후순위)
sql/ DDL(이미 운영 DB 에 적용된 것들)
페이지 8개: /(대시보드) · /videos · /clips · /v/[vid] · /c/[cid] · /upload
(+ 후순위 /login · /password).
1. is_sbs 는 존재 자체가 비공개다.
노출 대상은 t_video.is_sbs = 1 뿐이고, 이 조건은 lib/server/videos.ts·composes.ts 의
SQL 에서만 적용한다. 어떤 응답 JSON·공유 타입·에러 메시지에도 이 컬럼을 싣지 않는다.
목록뿐 아니라 단건 조회도 걸러야 한다 — 주소창의 v_id·comp_id 는 바꿔 넣을 수 있다.
노출 대상이 아니면 "권한 없음"이 아니라 404 로 답한다.
2. 이 앱은 DB 에 쓰지 않는다.
운영 계정(sm_viewer)이 SELECT 전용이다. lib/server/db.ts 에 쓰기 헬퍼를 두지 않은 것도
그래서다. 렌더 결과(render_datetime·bumper_yn) 기록은 agent-compose 담당이다.
3. 상태 판정은 status_code 로만 한다.
t_video.comment 는 렌더 성공 후에도 옛 에러 문구가 남아 있는 사례가 실측됐다.
4. t_code 문구를 그대로 쓰지 않는다.
"하이라이트"·"자막"·"전광판" 같은 내부 용어가 들어 있다. sanitizeCodeText() 를 통과시키고,
파이프라인 4단계 이름은 lib/domain/status.ts 의 PIPELINE_STAGES 가 소유한다.
5. 재생 시점에 렌더를 호출하지 않는다. worker-render(:8003)는 상시 가동이 아니다. 렌더는 사용자가 렌더 옵션 다이얼로그에서 확인을 누른 경우에만 일어난다. 실패(502)는 정상 시나리오이며 편성은 그대로 남는다.
6. 요청은 서버 큐가 순서대로 보낸다 — 편성 1건 · 렌더 1건.
lib/server/queue.ts 의 두 레인(편성/렌더)이 각각 동시 1건씩 실행한다(서로는 독립).
접수는 항상 202 + 티켓이고, 거절은 대기열 포화(레인별 20건, 503 QUEUE_FULL)뿐이다.
현황은 GET /api/queue — 대기 순번·진행 단계가 여기 있다. 자세한 건 PAGES.md §5.
단일 프로세스 전제(큐가 프로세스 메모리에 있다). PM2 클러스터로 띄우면 무력해진다 —
배포는 systemd 단일 프로세스로 고정한다. 재시작하면 대기분은 사라진다(진행 중 렌더만
t_compose.render_status=1 로 복원).
7. 길이(budget)는 목표가 아니라 상한이다.
900초 요청이 311초로 나온 실측이 있다. 화면 문구는 "최대 N분".
배포 디렉토리는 /usr/service/source/scenemaker/ui/ui-sbs-viwer(sm-pub-01, 소유자 ui) —
이 저장소의 clone 이다. sm-api-01 의 /usr/service/source/scenemaker/agent/<name> 과 같은 규칙이다.
정본은 GitHub main — 로컬 수정은 commit+push 후 서버에서:
deploy/update.sh # origin/main 신규 커밋 있으면 sync+빌드+재기동, 없으면 no-op
deploy/update.sh --force # 강제 재빌드·재기동.env는 미추적이라reset --hard에도 보존된다..cache/thumbs(썸네일)도 마찬가지.- systemd 유닛(
sbs-viewer.service)도deploy/가 정본 — 달라지면 자동 설치된다. npm ci --include=dev로 설치한다.next build에 tailwind·typescript 가 필요하다.- 빌드 실패 시 재기동하지 않는다 — 구 버전이 계속 서비스한다.
- 접속은 SSM Session Manager(22번 미개방). 서버는 read-only deploy key 로 fetch 만 한다.
PAGES.md— 페이지·기능 명세, 결정 사항의 정본RESEARCH.md— 사전 조사(DB·API·인프라 실측)DEPLOY_GUIDE.md— sm-pub-01 구축 가이드INFRA_BUILD.md— sm-pub-01 실제 구축 결과(인프라 좌표)REQUEST_agent-compose.md— agent-compose 수정 요청서design/mockup.pen— 디자인 목업(토큰은app/globals.css와 1:1)