popcon 개발일지 #11 — 크레딧 시스템, R2 마이그레이션, ToonOut, 그리고 Brutal 리디자인

Thu, 07 May 2026 00:00:00 +0900

개요

이전 글: #10 — 베타 모집, 풍선 인디케이터, 카운트다운을 쓴 뒤로 보름 동안 popcon에는 dev10 한 편으로 묶기 어려운 변화가 들어갔다. 매팅 모델 교체, 결제 인프라(크레딧), Cloudflare R2 스토리지 컷오버, brutal 리디자인, 한국어 i18n까지 — 156개 커밋이 사실상 다섯 개의 독립 마일스톤이다.

graph TD
 Start["popcon dev #10 (594cceb)"] --> M1["매팅 모델 스왑 <br/> ToonOut on gray bg"]
 Start --> M2["크레딧 시스템 <br/> Credits/CreditCode/CreditLedger"]
 Start --> M3["D1 brutal 리디자인 <br/> 토큰/폰트/프리미티브 재작성"]
 Start --> M4["Cloudflare R2 컷오버 <br/> dual-write → backfill → drop"]
 Start --> M5["한국어 i18n <br/> next-intl + locale prefix"]
 M1 --> End["popcon dev #11 (411c5ec)"]
 M2 --> End
 M3 --> End
 M4 --> End
 M5 --> End

이번 글은 다섯 개를 한 번에 다루지만, 각 흐름을 따라가면 결국 같은 질문이 반복된다 — “기존 시스템을 멈추지 않고 어떻게 새 레일로 갈아탈까.”

매팅 모델: BiRefNet → ToonOut

popcon은 캐릭터 이미지에서 배경을 분리해 12개 이모티콘 액션으로 합성한다. 기존 매팅 모델은 일반 사진 기준이라 애니 캐릭터의 머리카락/투명 영역에서 자주 무너졌다.

ToonOut은 BiRefNet을 1,228장의 애니 이미지로 fine-tuning한 모델이다. 픽셀 정확도가 95.3% → 99.5%로 올라간다.

# gpu_worker — ToonOut에 입력하기 전 회색 배경에 합성
# (ToonOut training-time gray = #808080)
def _swap_bg_to_gray(rgba: np.ndarray) -> np.ndarray:
 """Soft white-key compositor: alpha-blend onto #808080."""
 alpha = rgba[..., 3:4] / 255.0
 rgb = rgba[..., :3]
 gray = np.full_like(rgb, 128)
 return (rgb * alpha + gray * (1 - alpha)).astype(np.uint8)

전후 처리에서 두 가지 디테일이 잡혔다.

회색 배경 단일 소스 — bg_color를 백엔드 단일 진리원(single source of truth)으로 만들고 #808080으로 통일 (commit 430f985). 이전에는 프런트엔드와 워커가 각자 다른 톤의 회색을 쓰고 있었다.
Pylette로 캐릭터별 회색 픽 — Rec.709 luminance 규칙으로 캐릭터의 평균 밝기에 맞는 회색을 골라준다 (commit 94544df). Pylette 글에서 다뤘던 라이브러리를 실제로 import해서 쓰게 됐다.

리팩터링 중 동적 indirection을 cargo-cult로 판정해서 걷어냈고, mask-fill threshold도 이름을 줬다 (081ddd6).

크레딧 시스템: 결제 인프라 한 사이클

베타 끝나고 유료화 전환을 위해 크레딧 시스템을 처음부터 깔았다. SQLAlchemy ORM부터 프런트엔드 402 핸들러까지 5일 안에 한 바퀴를 돌렸다.

graph TD
 Code["관리자 CLI mint <br/> CreditCode (POPxxxxx)"] --> Redeem["redeem 모달 <br/> 코드 → 잔액"]
 Redeem --> Ledger["CreditLedger <br/> charge / refund / grant"]
 Action["editor 액션 <br/> (generate/refine/animate)"] --> Quote["pre-flight quote <br/> 잔액 부족 시 gate"]
 Quote --> Ledger
 Ledger -- "402 emit" --> Pill["header 잔액 pill <br/> 글로벌 redeem 모달"]
 Ledger --> Account["/account 페이지 <br/> 잔액/redeem/이력"]

핵심 결정 셋:

Ledger 패턴 — CreditLedger에 모든 변동을 append-only로 기록하고, Credits 테이블의 balance 컬럼은 캐시. 모든 charge/refund는 strict transaction (e28b100).
402 글로벌 이벤트 — 백엔드가 잔액 부족 시 HTTP 402를 던지면, 프런트엔드 useCredits() 훅이 자동으로 잔액을 새로고침하고 글로벌 redeem 모달을 띄운다 (d25739e, 1a32900).
실패 단계 환불 — 이모티콘 생성 중간에 에러가 나면 그 단계의 크레딧을 자동 환불 (6d7cc7f). 사용자가 환불을 직접 요청하지 않게.

중간에 작은 사고가 있었다. Gemini의 image_size 파라미터를 가격 체계와 맞추려고 "0.5K"로 보냈는데, 이건 Gemini가 거부하는 값이다 (b1ac23f revert → 55eda01에서 "512"로 정정). API 요금 계산용 표기와 API 입력 표기가 다른 케이스 — 둘이 같다고 가정한 게 문제였다.

또 360115e 커밋이 흥미롭다. 코드 리팩터링 중에 브랜드 prefix POP을 P0P (영문 O를 0으로)으로 잘못 바꿨던 걸 되돌렸다. AI가 “스타일 통일"을 너무 적극적으로 한 사례.

D1 brutal 리디자인: 토큰부터 페이지까지

기존 popcon은 generic Tailwind 룩이었다. 플라이어/브랜딩과 맞추기 위해 brutal 스타일로 전면 교체했다 — 두꺼운 검정 보더, 강한 그림자, 5색 톤 시스템, 굵은 산세리프.

새 폰트 스택:

Archivo Black — 영문 헤드라인
Black Han Sans — 한글 헤드라인
Jua — 한글 본문
JetBrains Mono — 코드/숫자
Pretendard — 한글 폴백

/* tokens.css — 5톤 brutal 팔레트 */
:root {
 --paper: #fafaf7; /* 본문 배경 */
 --ink: #1a1a1a; /* 본문 텍스트 + border */
 --violet: #7c3aed; /* 브랜드 (P logo, 액션) */
 --yellow: #fbbf24; /* 활성 강조 (ZIP 버튼 등) */
 --pink: #ec4899; /* erase / 경고 */
 --mint: #10b981; /* success */
}

프리미티브를 새로 짰다 — Card, Chip (5톤×2사이즈), StatusDot, Input, Textarea, Button (5 variants × 3 sizes), StepIndicator. 모두 brutal 스타일로 다시 작성 (769df10 ~ 0e013a8).

페이지를 한 장씩 갈아끼우는 방식으로 진행했다 — landing → editor 패널들 → archive → account → auth 모달 → header. 각 commit이 한 페이지/패널이라 리뷰가 쉬웠다.

가장 까다로웠던 건 scrim/모달 배경 처리였다. 기존엔 흰색 베일을 깔았는데 brutal 스타일에선 ink scrim(검정 반투명)이 맞았다. 그런데 SAM2/matte refine 모달에선 ink scrim이 너무 강해서 레퍼런스 이미지가 안 보임 → 모달별로 scrim을 분기 (99b1908, 4096ba7).

WCAG AA 점검도 한 번 돌렸다. 핑크 배경 위 흰색 텍스트가 contrast 미달이어서 ink로 교체 (4827ed4).

Cloudflare R2 컷오버: 4단계 phase 분리

popcon은 생성된 이모티콘 zip/APNG/video를 fly.io 머신의 로컬 디스크에 쓰고 있었다. 머신이 늘면 자산이 분산돼서 다운로드 라우팅이 깨진다. R2(Cloudflare의 S3 호환 객체 스토리지)로 옮기기로 결정.

다운타임 없이 옮기려고 4 phase로 쪼갰다:

Phase	내용	PR
A	R2 클라이언트 + `blob_key` DB 컬럼 추가	#5
B	Worker dual-write — 로컬 디스크 + R2 둘 다 기록	#6
C	백필 스크립트 + 프런트엔드가 R2 URL을 absolute로 패스스루	#7
D	레거시 파일 라우트 제거 + `/download_job` 302 리다이렉트 + scratch GC	#8

각 phase 사이에 트래픽이 정상인지 확인하고 다음으로 넘어갔다. dual-write 단계에선 디스크와 R2 둘 다 쓰니까 비용은 잠깐 늘었지만, 컷오버 안전성을 샀다.

후속 정리 두 개:

Rehydrate URLs from R2 keys (b43e802) — DB에 R2 URL을 그대로 박지 않고 blob_key에서 매번 derive. R2 endpoint가 바뀌어도 마이그레이션 없이 따라간다.
레거시 자산 라우트 복구 (1e08937) — 이전에 시작한 작업물을 가진 사용자를 위해 file 라우트 일부를 다시 살림. R2 URL을 filesystem path 컬럼에 잘못 미러링한 버그도 같이 잡았다 (83d62c4).

한국어 i18n: next-intl + locale-prefixed routes

graph LR
 URL1["/editor"] --> Proxy["proxy.ts <br/> Next 16-style"]
 URL2["/ko/editor"] --> Proxy
 URL3["/en/editor"] --> Proxy
 Proxy --> Locale{"locale 추출"}
 Locale --> Layout["[locale]/layout.tsx <br/> getMessages()"]
 Layout --> Page["페이지 렌더 <br/> useTranslations()"]

next-intl + locale-prefixed routes로 한국어를 추가했다. 핵심 결정 두 개:

page를 [locale] 세그먼트 아래로 이동 — app/page.tsx → app/[locale]/page.tsx. layout도 root layout과 locale layout으로 분리 (fe1eaa3).
Next 16 proxy.ts로 locale 라우팅 — middleware 대신 proxy 패턴 (4f322e2). 정적 라우팅이 가능해서 캐시가 잘 먹는다.

번역은 namespace별로 dictionary 파일을 쪼갰다 — home, editor, archive, account, redeem, actions, picker, … 각 페이지/패널별 commit이 하나씩 있어서 grep 가능하다.

언어 스위처에서 한 가지 버그가 잡혔다. 언어 전환 시 search params가 사라져서 editor에서 진행 중인 job이 끊기는 문제 — Link/router 모두 locale-aware 래퍼로 교체해서 search params 보존 (d644b1b, PR #12).

또 in-app browser(KakaoTalk, Instagram 등)에서 Google 로그인이 차단되는 문제도 발견했다. iab=1 같은 쿼리로 외부 브라우저로 이스케이프하는 가드를 추가 (29cd743).

운영: SKIP_RUNPOD 가드와 sync-pod-id 스크립트

배포는 fly.io(API/프런트엔드) + RunPod(GPU 워커) + GitHub Actions cron 스케줄러 조합이다. 새벽 시간대 RunPod 비용을 줄이려고 스케줄러로 pod를 끄고 켜는데, 수동으로 pod를 띄워두면 스케줄러가 같이 끄는 사고가 났다.

해결: SKIP_RUNPOD 환경 변수 가드 (e3fa9fa). 이 플래그가 켜져 있으면 스케줄러가 pod를 건드리지 않는다. 수동 운영용 escape hatch.

sync-pod-id 스크립트도 추가 (783238b) — 새 RunPod ID를 fly secret에 자동으로 동기화한다. 이전엔 수동으로 fly.io 환경변수를 업데이트해서 까먹기 쉬웠다.

fly(frontend) 한 줄도 의외로 중요했다 (edf3d18, PR #9). frontend 머신을 1대 warm으로 유지하고 메모리 512MB로 고정. 콜드 스타트 1.5초 → 200ms.

인사이트

156개 커밋을 한 글에 묶고 보니 흐름이 직렬이 아니라 병렬이었다. 매팅 모델 교체와 R2 마이그레이션은 백엔드/워커 쪽, brutal 리디자인은 프런트엔드, 크레딧과 i18n은 풀스택. 같은 시간대에 다섯 트랙이 동시에 굴러갔는데 서로 머지 충돌이 거의 없었던 건 모듈 경계가 또렷해서다.

특히 R2 컷오버를 4 phase로 쪼갠 게 회고감이 좋다. dual-write phase에서 비용 잠깐 더 쓰는 대신 롤백 가능성을 샀다 — 만약 phase B에서 문제가 생겼어도 디스크가 truth로 남아 있어서 R2 코드만 끄면 됐다.

크레딧 시스템 ledger 패턴은 다시 써도 같은 선택을 할 것 같다. Credits.balance를 캐시로 두고 CreditLedger를 append-only로 기록하면, 잔액에 의심이 갈 때 ledger를 재연산해서 검증할 수 있다. Stripe도 이 패턴이다.

리디자인은 토큰/프리미티브를 먼저 새로 짠 뒤에 페이지를 한 장씩 갈아끼운 게 결정적이었다. 페이지를 먼저 손대면 새 토큰이 안 박히는 옛 컴포넌트가 계속 남는다.

다음 dev #12에서 다룰 것: 결제 게이트(KG이니시스/PortOne) 연동, ToonOut 매팅 품질 A/B(전 모델 vs ToonOut), 한국어 i18n에서 빠진 미세 영역(에러 토스트, 관리자 CLI 메시지).

Next Intl on ICE-ICE-BEAR-BLOG