CC 배너 제너레이터

구글 시트(ProductMaster / TemplateMaster / HeroMaster / ColorMaster) 데이터로 상세페이지 · 썸네일(1080²) · 인스타 피드(1080×1350) 배너를 브라우저에서 바로 렌더링하고 PNG(ZIP)로 내려받는 사내 도구입니다.

빌드 도구·서버·npm 설치가 필요 없습니다. 파일을 그대로 올리면 동작하는 정적 사이트입니다.

---

1. 폴더 구조

.
├─ index.html            ← 화면 마크업 + 로드 순서만 (13KB)
├─ api/
│  ├─ sheet.js           ← 비공개 구글 시트 → CSV (서비스 계정)
│  └─ img.js             ← 외부 이미지 중계 (같은 출처 + 캐시)
├─ vercel.json           ← 캐시·보안 헤더
├─ robots.txt            ← 검색엔진 색인 차단 (사내용)
├─ assets/
│  ├─ high-summit.woff2  ← 히어로 영문 서체 (자체 호스팅)
│  └─ logo.png           ← dear.cus 로고
├─ styles/               ← 캐스케이드 순서대로 로드
│  ├─ 01-tokens.css        색 변수 · @font-face · 기본 리셋
│  ├─ 02-layout.css        3단 레이아웃 · 헤더 · 리사이저 · 블록
│  ├─ 03-controls.css      인풋 · 세그먼트 · 탭 · 스와치
│  ├─ 04-panels.css        제품군/템플릿/컬러/히어로/가격카드 패널
│  └─ 05-stage.css         미리보기 무대 · 버튼 · 경고 · 이력
└─ scripts/              ← 번호 순서 = 실행 순서
   ├─ 01-sheet-schema.js       시트 스키마 · CSV 파서 · 오류코드 · buildGroups
   ├─ 02-design-tokens.js      캔버스 규격 상수 · THEMES · OPT · LOGO
   ├─ 03-sample-data.js        내장 샘플 데이터(GROUPS)
   ├─ 04-template-meta.js      템플릿 ID ↔ 패밀리/테마 매핑
   ├─ 05-state-utils.js        state · 포맷 유틸 · 이미지 로더(프록시 포함)
   ├─ 06-config-store.js       배포 기본값(PRESET) · localStorage 접속설정
   ├─ 07-sheet-sync.js         시트 불러오기 · 오류 표시 · 데이터소스 UI
   ├─ 08-panel-ui.js           CORS 진단 · 편집 패널 폭 조절 · 상단 바인딩
   ├─ 09-hero-color.js         히어로 이미지 라이브러리 · 컬러 선택
   ├─ 10-group-template-ui.js  제품군/템플릿/테마 선택 UI
   ├─ 11-rows-picker.js        가격 카드 편집 · 제품 선택 패널
   ├─ 12-render-nuvola.js      누볼라 패밀리 렌더러 (상세·썸네일·피드 전부)
   ├─ 13-render-core.js        draw() · 포맷 전환 · 미리보기
   ├─ 14-render-hero.js        기본 패밀리 히어로 01 / 02
   ├─ 15-render-thumb-feed.js  썸네일 · 피드 슬라이드 렌더러
   ├─ 16-render-cards.js       옵션 카드 렌더 · 줄바꿈/높이 계산
   ├─ 17-canvas-helpers.js     trk · cover · roundRect 등 캔버스 헬퍼
   ├─ 18-validate.js           경고/검증 패널
   ├─ 19-export.js             PNG 렌더 · ZIP 다운로드 (JSZip 지연 로드)
   ├─ 20-history-share.js      생성 이력 · 공유 코드
   └─ 21-bindings-boot.js      입력 바인딩 · boot()

어디를 고쳐야 하나

하고 싶은 일	열 파일
시트 컬럼 추가/이름 변경	scripts/01-sheet-schema.js
배포 기본 시트·프록시 URL 교체	scripts/06-config-store.js 의 PRESET
색상 테마 추가	scripts/02-design-tokens.js 의 THEMES
배너 그림이 잘못 나옴 (누볼라)	scripts/12-render-nuvola.js
배너 그림이 잘못 나옴 (기본 01/02)	scripts/14-render-hero.js, 16-render-cards.js
화면 색·여백	styles/01-tokens.css (변수)

---

2. 중요 — 스크립트 순서를 바꾸지 마세요

scripts/*.js 는 모듈이 아니라 일반 스크립트입니다. 전역 스코프를 그대로 공유하기 때문에 원본 단일 파일과 동작이 완전히 같지만, index.html 의 <script defer> 순서가 곧 실행 순서입니다.

• 파일을 새로 추가하면 → index.html 아래쪽 스크립트 목록에도 추가해야 합니다.
• 번호 순서를 섞으면 초기화가 깨집니다.
• type="module" 로 바꾸면 전역 공유가 끊겨 전부 깨집니다.

---

2.5 서버 함수와 환경변수

환경변수	필수	용도
GOOGLE_SA	✅	서비스 계정 JSON 전체 (base64 도 인식)
SHEET_ID	✅	시트 주소의 /d/ 와 /edit 사이 문자열
IMG_HOSTS	선택	이미지 중계를 허용할 도메인. 예 cafe24.com,dearcus.com. 비우면 전체 허용

환경변수를 바꾸면 재배포해야 반영됩니다.

직접 열어서 확인할 수 있습니다:

/api/sheet?tab=ProductMaster        → CSV 텍스트
/api/img?u=<이미지주소 URL인코딩>      → 이미지

실패하면 화면에 한글로 원인이 표시됩니다.

3. Vercel 배포

빌드가 없으므로 설정할 게 거의 없습니다.

1. 이 폴더의 내용을 GitHub 저장소 루트에 올립니다. (index.html 이 저장소 최상단에 보여야 합니다. 폴더 안에 한 겹 더 들어가면 안 됩니다.)
2. vercel.com → Add New… → Project → 해당 저장소 Import
3. 설정 화면에서
   • Framework Preset: Other
   • Build Command: 비움
   • Output Directory: 비움 (또는 .)
   • Root Directory: ./ — 저장소 안에 폴더가 한 겹 더 있다면 그 폴더를 지정
4. Deploy → 30초쯤 뒤 https://프로젝트명.vercel.app 발급

이후에는 GitHub 에 커밋할 때마다 자동 재배포됩니다. (main 브랜치 → 운영, 다른 브랜치 → 미리보기 URL)

배포 후 첫 확인

• 화면 우상단이 "준비됨" 으로 바뀌는지
• ⚙ 데이터 소스 를 열어 시트가 자동으로 불러와지는지 (06-config-store.js 의 PRESET 에 게시 CSV URL 이 들어 있어 자동 로드됩니다)
• 전체 다운로드(ZIP) 가 되는지

도메인이 바뀌면 생기는 일

접속 설정(시트 URL·프록시 URL)은 도메인별로 브라우저에 저장됩니다. github.io → vercel.app 으로 옮기면 저장된 값이 안 보입니다. 다만 코드에 PRESET 기본값이 있어 처음 열어도 자동으로 시트를 불러옵니다.

---

4. 이번 최적화에서 바뀐 것

항목	이전	이후
파일 구성	index.html 1개 (320KB, 6,786줄)	HTML 13KB + CSS 5 + JS 21 + 에셋 2
첫 화면 HTML 전송량	320KB (매번 전부)	13KB
High Summit 폰트	HTML 안에 base64 (50KB, 매번 재다운로드)	.woff2 37KB, 1년 캐시
로고	JS 안에 base64 16KB	logo.png 12KB, 1년 캐시
JSZip 94KB	첫 화면에서 동기 로드(파싱 차단)	다운로드 버튼 누를 때만 로드
한 줄 수정 시 재다운로드	320KB 전부	해당 파일만

렌더링 코드는 한 글자도 바꾸지 않았습니다. 캔버스 드로잉 4,786개 명령과 화면 DOM 을 원본과 비교해 완전히 동일함을 확인했습니다.

---

5. 알려진 제약

• 이미지 서버(카페24 EC 등)가 CORS 를 안 열어주면 Apps Script 프록시를 거쳐야 합니다. 좌측 ⚙ 데이터 소스 → 이미지 프록시 URL 에 설정합니다.
• Pretendard · Playfair Display · GmarketSans 는 외부 CDN 에서 받아옵니다. 오프라인이면 대체 서체로 표시됩니다.
• 저장소를 Public 으로 두면 PRESET 의 시트·프록시 URL 이 공개됩니다. 민감하면 저장소를 Private 으로 두세요. (Vercel 은 Private 저장소도 무료로 배포합니다)

---

6. 피그마 대조 (tools/figma-check.mjs)

피그마와 코드가 어긋난 곳을 찾아 표로 보여줍니다. 고치지는 않습니다.

export FIGMA_TOKEN=figd_xxxxx          # 최초 1회
node tools/figma-check.mjs

토큰은 figma.com → 프로필 → 설정 → 보안 → 개인 액세스 토큰에서 만듭니다.

• 구조 검사는 설정 없이 자동입니다 (섹션 중복, 이름 오염, 슬라이드 누락, 테마 커버리지)
• 좌표 대조는 tools/figma-check.config.json 의 checks 를 봅니다. expect 숫자는 코드가 쓰는 값이므로, 코드 상수를 고치면 여기도 같이 고쳐야 합니다
• 어긋난 게 있으면 종료 코드 1 — CI 에 붙일 수 있습니다

오프라인 검사:

node tools/figma-check.mjs --json fig.json   # 받아서 저장
node tools/figma-check.mjs --from fig.json   # 저장한 걸로 검사