[기획] 혜택 카드 — 새로 만들기·편집하기 한 판 (명세 10 §2-L)

게시 전 초안입니다. 아래 구분선부터가 GitHub 이슈 본문이고, 받는 사람은 개발(재환님)입니다.

재환님, 안녕하세요. 기획 쪽에서 정리한 혜택 카드 편집 화면 건을 공유드립니다.

바쁘신 와중에 죄송하지만, 시간 나실 때 한 번 봐 주시면 감사하겠습니다. 명세서와 목업에 화면 동작을 모두 반영해 두었습니다. 아래 「계약에 없는 것」 네 가지와 확인 질문 셋(Q-106 · Q-107 · Q-108) 은 여쭙고 싶은 부분입니다. 제안 답을 같이 적어 두었으니, 편하신 쪽으로 정해 주시면 기획 문서를 그에 맞추겠습니다.

명세(정본): https://nlive2-mockup.pages.dev/spec/10-%EC%98%81%EC%83%81%EB%A7%8C%EB%93%A4%EA%B8%B0-%ED%83%80%EC%9E%84%EB%9D%BC%EC%9D%B8.html — §2-L 혜택 카드(행 2-80 ~ 2-96)
목업: https://nlive2-mockup.pages.dev/dist/pages/editing.html — 혜택 카드 막대를 누르고 [편집하기]를 누르거나, [＋ 추가] → 혜택 카드로 들어갑니다.

1. 한 줄 요약

혜택 카드는 요청서 「라이브 혜택」 하나에서 만듭니다. 새로 만들기와 편집하기는 같은 모달 · 같은 순서를 씁니다 — ① 혜택 → ② 틀 → ③ 글 → ④ 꾸밈. 왼쪽에는 9:16 미리 보기가 있고, 카드 요소를 누르면 오른쪽 그 칸으로 스크롤됩니다.

2. 지금 계약과 맞춰 본 결과

대조 기준은 api-v4 feat/nlive2-implementation(2026-10-01 beac0c8)의 다음 두 파일입니다.
- apps/nlive2/src/direction/direction-card.controller.ts
- apps/nlive2/src/direction/direction-card.schema.ts

화면	계약	상태
① 혜택 고르기	`sourceOptions.benefits` · `PATCH …/input` 의 `sourceBinding.benefitId`	✅ 있음
② 틀 고르기(다섯 틀)	`templateOptions` · `sourceBinding.templateRef`(gift · npay · cprice · cdisc · price)	✅ 있음
② 「추천」 틀	혜택 종류 → 틀 매핑	🟡 계약에 매핑이 없습니다. 아래 §4-1 처럼 프런트 상수로 두셔도 됩니다
② 「직접 올리기」(완성 그림)	`references.role` 이 `product_image` · `brand_logo` 둘뿐	❌ 없음 — R1 · Q-106
③ 글 칸	`input.copy`(키 ≤ 40자 · 값 ≤ 180자) · `editableFields`	✅ 있음
③ [AI로 채우기]	다시 채우는 호출	❌ 없음 — R3
④ 로고 · 그림	`references`(`brand_logo` · `product_image`, 최대 2)	✅ 있음
④ 색 · 간격 · 장식 · 배경 투명	—	❌ 없음 — R2
[카드 만들기]	`input` → `render`(202) → `select` → `apply`	✅ 있음(네 호출을 한 버튼으로)
생성 이력(누르면 적용)	`candidates` · `select` · `apply`	✅ 있음
예전 값으로 돌아가기	`restore`(`restoreInputRevision`) · `versions`	✅ 있음
타임라인 아무 자리에 새 카드	카드 계획은 대본 cue(`sourceCueRef`)에서만 생깁니다	❌ 없음 — R4

3. 요청 — 계약에 없는 것 넷 (+ 진입 상태 하나)

R1. 직접 올린 완성 그림을 카드로 받기 (Q-106)
- 제안: references.role 에 card_image 를 하나 더합니다. 이 역할이 있으면 render 는 그 그림을 1080×1920 으로 채워 후보로 만들고, 틀 렌더는 건너뜁니다.
- sourceBinding.benefitId 는 그대로 둡니다. 올린 그림도 그 혜택의 카드입니다.

R2. 꾸밈 값 (원본 배너 에디터 realform5 와 같은 다섯 개)
- 제안: input 에 style: { bg: '#RRGGBB', ac: '#RRGGBB', textSpacing: 0.7~1.4, elementSpacing: 0.7~1.4, decor: boolean, transparent: boolean } 를 둡니다.
- 렌더러 renderBannerHtml(spec) 의 bg · ac · ts · es · decor · transparent 로 그대로 넘깁니다.

R3. [AI로 채우기] — 글 칸 다시 채우기
- 제안: POST …/cards/:cardPlanId/fill-copy(expectedInputRevision). 그 혜택(benefitId 의 text · condition)과 지금 templateRef 로 LLM 이 copy 의 헤드라인 1 · 2, 서브, 라벨, 값을 채우고 inputRevision 을 1 올립니다.
- 가격 값(정가 · 최종가 · 브랜드 · 제품명)은 요청서 사실이므로 덮지 않습니다.
- 여쭙고 싶은 것: 지금 copy 의 첫 값은 카드 계획을 만들 때 누가 채우는지요?

R4. 타임라인 임의 지점에 새 카드 계획 만들기
- 제안: POST …/direction/cards({ startSec, benefitId }). 혜택 카드 길이는 기본 4초입니다(명세 10 행 2-74).
- 겹침과 빈틈 규칙은 명세 10 행 2-71 ~ 2-73 을 그대로 따릅니다.

R5. 진입 상태
- 명세 10 행 2-80: 타임라인에 처음 들어오면 소리가 꺼져 있습니다.
- 지금 /next 타임라인은 켜진 채 시작합니다.

4. 구현 상세 — 이 절은 코딩 에이전트가 그대로 따라 만들 수 있게 적었습니다

4-1. 데이터 흐름

요청서 live_benefits[] ─┐
대본 card_hint cue ─────┼→ 카드 계획(cardPlanId · sourceCueRef · benefitId)
                        └→ ② 추천 틀 = KIND_TPL[혜택 종류] (금액 단위가 % 면 cprice → cdisc)
KIND_TPL = { 첫구매 쿠폰: cprice, 멤버십 쿠폰: cprice, 추가 할인: cprice,
             무료배송: gift, 이벤트 경품: gift, 추첨: gift, 증정: gift }   // N페이는 요청서 칸이 없어 ② 에서 고를 때만
③ copy = LLM(혜택 text · condition, templateRef)   ④ style · references
[카드 만들기] = PATCH input → POST render → (완료) select → apply → 생성 이력 맨 앞 · 「적용됨」

4-2. 화면 — 모달 「혜택 카드 편집하기」 / 새로 만들기는 「어떤 혜택 카드로 할까요 (2/2)」

배치: 왼쪽은 9:16 미리 보기입니다. 높이는 모달 높이에 맞추고 실제 비율을 지킵니다(1440×760 에서 279×495). 오른쪽은 단계 한 열이고 이 열만 스크롤합니다. 모달 폭은 min(880px, 96vw) 입니다.
① 혜택: sourceOptions.benefits 를 카드 목록으로 보입니다(「혜택 N · 종류」 · 내용 · 조건). 누르면 「적용됨」 리본이 붙습니다. 혜택을 바꾸면 ③ 이 그 혜택으로 다시 채워집니다.
② 틀:
그림 6칸 = 다섯 틀 + 「직접 올리기」. 틀 그림은 지금 혜택과 색으로 렌더한 썸네일입니다.
매핑된 틀 이름 옆에 「추천」을 붙입니다. 고르면 「적용됨」이 붙습니다.
틀을 바꾸면 사람이 고친 칸은 남고, 고치지 않은 칸만 새 틀에 맞게 채웁니다.
「직접 올리기」:
누르면 이미지 파일 창이 열리고, 고른 한 장이 바로 적용됩니다. 이때 ③ ④ 는 숨깁니다.
× 로 지우면 앞 틀로 돌아갑니다.
이미지가 아니면 토스트 「지원하지 않는 형식이에요」를 띄웁니다.
③ 글:
틀별 칸 구성:
- gift: 헤드라인 1 · 2 · 서브
- cprice: + 라벨 · 값 + 단위(원 / % / P)
- cdisc: + 라벨 · 할인율 %(단위 고정)
- npay: + 값 + 단위(라벨은 그림에 안 나와서 칸이 없습니다)
- price: 브랜드명 · 제품명 · 정가 · 할인율 · 최종가. 최종가 = round(정가 × (1 − 할인율/100))이고, 최종가를 고치면 할인율을 거꾸로 셈합니다.
칸마다 「AI가 채움」 같은 표시는 두지 않습니다.
③ 머리에 [AI로 채우기] 버튼 하나를 둡니다(R3). 채우는 동안에는 「채우는 중」을 보이고 버튼을 잠급니다.
④ 꾸밈:
색 조합 6개(원본 PRESETS), 배경 · 강조 색(고르개 + #RRGGBB).
로고 칸은 다섯 틀 모두에 있습니다. 그림 칸은 gift 의 사은품 그림, price 의 제품 그림입니다. 업로드 존은 공통 규격 「갈래 B 카드형」을 씁니다.
간격 「글자」 · 「요소」 0.7~1.4, 「장식(빛·글로우·그레인)」, 「배경 투명」.
미리 보기 앵커:
카드 안의 .h1a · .h1b · .subt · .lbl · .ticket .val · .pname · .strike · .pct · .final · .logoplain · .nukkid · .pcard 를 누르면, 오른쪽 해당 칸이 scrollIntoView({block:'center'}) 로 오고 포커스를 받고 잠깐 밝아집니다.
호버하면 테두리를 보입니다.
미리 보기 아래 「안전 영역」을 켜면 빗금 오버레이가 보입니다. 보기 전용이라 카드에는 안 들어갑니다.
발치:
편집하기: [닫기] · [카드 만들기]
새로 만들기: [뒤로] · [카드 만들기]
채운 버튼은 [카드 만들기] 하나입니다. 비용 아이콘은 붙이지 않습니다(코드 렌더 · Q-108).
혜택을 안 고르고 누르면 막지 않고 토스트 「어떤 혜택인지 먼저 골라 주세요」를 띄운 뒤 ① 로 포커스를 옮깁니다.
닫으면 [카드 만들기] 전에 고친 것은 버립니다.

4-3. 우측 패널(막대를 골랐을 때)

「혜택 N · 종류 · 틀」과 혜택 내용을 보입니다.
생성 이력 은 candidates 입니다. 누르면 select → apply 가 되고, 「적용됨」 리본이 옮겨 가며, 막대와 가운데 미리 보기가 그 그림으로 바뀝니다. 앞 장은 남습니다.
발치의 [편집하기] 는 호버 없이 늘 보입니다.

4-4. 완료 기준 (목업 자와 같은 항목)

1036 · 1280 · 1440 × 760 에서 모달 가로 넘침 0, 미리 보기 9:16, ② 6칸이 첫 화면에 보일 것.
편집하기 → 글 고침 → [카드 만들기] → 생성 이력 +1 · 새 장 「적용됨」 · 앞 장 유지.
이력 카드를 누르면 「적용됨」이 이동하고 가운데 미리 보기가 같은 그림이 될 것.
[AI로 채우기] → 헤드라인 1 · 2 · 서브 · 라벨이 새 값으로 바뀌고, 가격 값은 그대로일 것.
미리 보기의 서브 · 값 · 로고 · 최종가를 누르면 해당 칸에 포커스가 가고, 그 칸이 보이는 범위 안에 있을 것.
새로 만들기 2/2 는 ① 만 열려 있고(② ③ ④ 흐림), 혜택을 고르면 추천 틀 적용 → 글이 채워질 것.
혜택 카드 렌더는 이미지 생성 API 를 부르지 않을 것(코드 렌더).

5. 확인 질문

Q-106 혜택 카드 계약이 사람이 올린 완성 그림을 카드로 받는가?
제안: 받습니다. 받는 방법은 위 R1 입니다.
Q-107 렌더 정본(core/banner.py)이 어두운 배경 색 조합(6번 #101C31)에서 멈추는 결함(derive_colors → clamp 입력 형식 불일치)을 고치는가?
제안: 고칩니다. 출시 전에 못 고치면 6번 조합을 뺍니다.
Q-108 [AI로 채우기]를 비용 아이콘이 붙는 행동으로 보는가?
제안: 아닙니다. 글 몇 줄짜리 호출이라 붙이지 않습니다.

번거로우시겠지만 확인 부탁드립니다. 감사합니다.

— Claude Code 정리 · 강형모 확인