JenaLab Technical Blog

원탭 생성과 건당 결제 — 구독 모델에서 단건 결제로

Mon, 23 Mar 2026 23:00:00 +0900

동화책은 매달 만들지 않는다

월 구독 모델에는 전제가 있다. 사용자가 매달 반복적으로 서비스를 쓴다는 것. AI 동화 생성은 이 전제에 맞지 않았다. 생일, 기념일, 특별한 순간에만 만든다. 연 2~3회.

구독에서 건당 결제로 전환했다. 동시에, 생성의 진입장벽을 낮추기 위해 원탭 모드를 설계했다.

원탭 “오늘의 동화” — 이름 하나로 시작

기존 생성 플로우는 설정 항목이 많았다. 스타일, 프롬프트, 캐릭터, 장면 수, 글자 수. UX 간편화로 핵심 3개로 줄였지만, 더 극단적인 경로가 필요했다. 이름만 입력하면 끝나는 모드.

원탭 모드의 설계 원칙은 하나. 사용자가 결정하지 않는 것은 서버가 결정한다.

사용자 입력: 아이 이름 (1개)
서버 결정:
  - 상황 → 템플릿 풀에서 랜덤 선택
  - 작문 스타일 → 랜덤 선택
  - 그림 스타일 → 랜덤 선택
  - 장면 수: 3 (고정)
  - 장면당 글자 수: 150 (고정)

상황 템플릿은 시스템 설정 테이블에 JSON 배열로 저장한다. 코드 배포 없이 관리자가 추가·수정할 수 있다. 템플릿에는 `` 플레이스홀더가 들어간다. 서버가 치환한 뒤 기존 생성 파이프라인에 그대로 전달한다.

프론트엔드 변경은 최소화한다. 기존 생성 API에 mode 파라미터 하나를 추가한다. mode: 'quick'이면 서버가 나머지를 채운다. 클라이언트는 이름만 보내면 된다.

생성 페이지 상단:
┌──────────────────────────────────────┐
│ "오늘 밤, 아이에게 이야기를 들려주세요" │
│                                      │
│ [아이 이름 입력]  [오늘의 동화 ▶]     │
│                                      │
│ ↓ 아래로 스크롤하면 상세 설정         │
└──────────────────────────────────────┘

상세 설정은 그대로 유지한다. 원탭 모드는 진입점이지, 기존 기능의 대체가 아니다.

건당 결제 — 빌링키가 아닌 단건 승인

기존 구독 결제는 빌링키 방식이다. 카드를 등록하면 매월 자동 청구된다. 건당 결제는 다르다. 매번 사용자가 결제를 승인한다. 1회성이다.

토스페이먼츠 기준, 두 방식의 차이는 명확하다.

항목	구독 (빌링키)	건당 (단건결제)
카드 등록	필수 (authKey → billingKey)	불필요
결제 승인	서버가 자동 (billingKey 사용)	사용자가 직접
API	빌링키 발급 + 빌링키 결제	confirm (paymentKey + orderId)
반복	매월 자동	매번 수동

기존 구독 결제에서 사용하던 토스 API 호출 로직을 공통 유틸로 추출했다. 빌링키 발급, 빌링키 결제, 단건 승인, 결제 취소를 하나의 클라이언트 클래스에 모은다. 구독 서비스와 토큰 구매 서비스가 동일한 클라이언트를 공유한다.

토큰 상품 설계

건당 결제의 단위는 “토큰 상품”이다. 상품 테이블을 두고, 관리자가 가격과 토큰 수량을 설정한다.

예시 상품 구성:

상품	토큰	가격	의미
동화 1편	750	₩3,900	기본 단위
동화 3편	2,250	₩9,900	묶음 할인
동화 10편	7,500	₩29,900	대량 할인

상품 목록은 공개 API로 제공한다. 인증 없이 조회 가능해야 한다. 비로그인 사용자도 가격을 먼저 확인할 수 있어야 하기 때문이다.

결제 흐름

결제는 3단계로 나뉜다.

1단계 — Checkout: 사용자가 상품을 선택하면 서버에 주문을 생성한다. 서버는 주문 ID, 금액, 결제 클라이언트 키를 반환한다.

2단계 — 결제 위젯: 토스 결제 위젯이 화면에 표시된다. 사용자가 카드 정보를 입력하고 결제를 승인한다. 성공 시 paymentKey가 반환된다.

3단계 — Confirm: 클라이언트가 paymentKey를 서버로 전송한다. 서버가 토스 승인 API를 호출한다. 성공하면 토큰이 즉시 반영된다.

사용자 → 상품 선택 → POST checkout → orderId 수신
       → 토스 위젯 결제 → paymentKey 수신
       → POST confirm → 토큰 충전 완료

기존 토큰 시스템의 addon_tokens 필드를 재사용한다. 토큰 히스토리에 source: 'addon_purchase'로 기록한다. 구독 토큰과 별도로 관리되므로 차감 순서도 기존 로직(애드온 먼저 → 구독 토큰)을 따른다.

기존 코드 재사용 전략

신규 기능이지만 새로운 패턴은 없다.

결제: 토스 클라이언트를 공통 유틸로 추출. 구독/건당 모두 동일 클라이언트.
토큰: addon_tokens와 token_history를 그대로 사용. 새 테이블은 상품 목록 1개만.
생성: mode 파라미터 추가. 나머지 파이프라인 변경 없음.
결제 위젯: 구독 결제에서 이미 사용 중인 토스 SDK를 재사용.

아키텍처 변경 없이 기존 패턴을 따라 기능을 추가하는 것이 원칙이다.

결론

동화책 생성의 빈도는 구독 모델과 맞지 않는다. 건당 결제가 사용자의 행동 패턴에 맞다. 원탭 모드는 “설정 피로”를 없앤다. 이 둘이 합쳐지면 진입장벽이 최소가 된다. 이름 입력 → 결제 → 동화 완성. 세 단계.

소셜 공유 파이프라인 설계 — SSR 공유 페이지에서 바이럴 루프까지

Mon, 23 Mar 2026 19:00:00 +0900

갤러리는 있는데 사용자가 없다

AI 동화 생성 파이프라인은 완성되어 있다. 공개 갤러리도 구축했다. 빠진 것은 하나. 결과물이 다음 사용자를 데려오는 구조. 소셜 공유 파이프라인을 설계했다.

구현은 4개 트랙으로 나뉜다. 공유 페이지(SSR), 카카오 SDK 연동, 프리셋 체인, 레퍼럴 쿠폰. 각 트랙의 의존성을 분석해 병렬 작업을 최대화했다.

1. SSR 공유 페이지 — 동적 OG의 설계

공유 링크를 받은 사람이 카카오톡에서 보는 것은 OG 미리보기다. 이 미리보기가 클릭을 결정한다. 정적 메타 태그로는 불가능하다. 작품마다 제목, 표지, 설명이 다르기 때문이다.

Next.js App Router의 Server Component로 해결한다.

/book/[id] 접근 시:
서버에서 작품 데이터 fetch (SSR)
비공개 또는 미존재 → 404
generateMetadata()로 동적 OG 태그 생성
opengraph-image 핸들러로 1200×630 이미지 생성
캐싱: revalidate 3600 (1시간)

OG 이미지는 표지 이미지 + 제목 + 브랜드 로고를 조합한다. 별도 이미지 서버 없이 Next.js의 ImageResponse로 동적 생성한다.

핵심은 공유 페이지가 단순 뷰어가 아니라 전환 장치라는 점이다. 하단에 “이 스타일로 만들기” CTA를 배치한다. 이 버튼이 바이럴 루프의 시작점이다.

2. 카카오 SDK — 3단계 폴백 전략

한국 사용자의 주요 공유 채널은 카카오톡이다. 카카오 SDK의 sendDefault로 피드형 공유를 구현한다.

공유 버튼은 3단계 폴백 구조를 가진다.

우선순위	방식	조건
1	카카오 SDK	`window.Kakao` 존재
2	Web Share API	`navigator.share` 존재 (모바일)
3	클립보드 복사	나머지 (데스크톱)

카카오 SDK는 lazyOnload 전략으로 로드한다. 페이지 로드를 차단하지 않는다. 초기화는 로드 완료 후 1회.

공유 버튼 컴포넌트는 범용으로 설계한다. title, description, imageUrl, shareUrl을 props로 받는다. 공유 페이지, 갤러리 프리뷰, 카드 오버레이 어디서든 동일한 컴포넌트를 재사용한다.

3. 프리셋 체인 — 공유에서 생성까지

공유 페이지의 CTA를 클릭하면 생성 페이지로 이동한다. 이때 원본 작품의 스타일과 프롬프트가 URL 파라미터로 전달된다.

/create?style_id=X&writing_prompt_id=Y

생성 페이지의 상태 관리 훅이 이 파라미터를 수신한다. 우선순위는 3단계다.

URL 프리셋 > localStorage 이전 설정 > 시스템 기본값

URL 프리셋이 있으면 해당 스타일과 프롬프트가 미리 선택된 상태로 페이지가 열린다. 사용자는 이름만 입력하면 된다. 마찰을 최소화한다.

이 패턴의 장점은 변경 범위가 작다는 것이다. 생성 페이지 자체를 수정하지 않는다. 상태 초기화 로직에 initialPreset 인자를 하나 추가하면 끝이다. 이후 갤러리의 “이 스타일로 만들기” 버튼도 동일한 URL 패턴을 사용한다.

4. 레퍼럴 쿠폰 — 공유에 인센티브 부여

공유만으로는 부족하다. 수신자에게 인센티브가 필요하다.

쿠폰 시스템의 흐름은 두 단계다.

생성: 사용자가 공유 버튼을 클릭하면 서버가 고유 코드를 발급한다. 이 코드가 공유 URL에 ref 파라미터로 붙는다.

적용: 수신자가 공유 링크로 접속하면 ref 값이 로컬 스토리지에 저장된다. 가입 완료 후 자동으로 쿠폰이 적용되어 무료 토큰이 지급된다.

검증 규칙은 4가지다.

만료 여부 확인 (발급 후 30일)
미사용 상태 확인
자기 자신의 쿠폰 사용 불가
(선택) 사용자당 횟수 제한

5. 의존성 기반 구현 순서

4개 트랙의 의존성을 분석하면 병렬 작업을 최대화할 수 있다.

Week 1 ─────────────────────────────
├─ Track A (독립): UX 개선 3건
├─ Track B (순차): 공유 페이지 → 프리셋 → 카카오 버튼
│
Week 2 ─────────────────────────────
├─ Track C (독립): 건당 결제 + 원탭 생성
│
Week 3~4 ───────────────────────────
├─ Track D (B 완료 후): 복제 기능 + 쿠폰

Track A와 B는 완전 병렬이다. Track C도 병렬 가능하지만 Week 1 이후 시작이 안정적이다. Track D만 B의 완료를 기다린다. 복제 기능은 공유 페이지와 프리셋이 선행되어야 하기 때문이다.

결론

소셜 공유는 기능 하나가 아니다. SSR 페이지, 동적 OG, 카카오 SDK, 프리셋 체인, 쿠폰 시스템이 하나의 파이프라인으로 연결된다. 각 부분은 독립적으로 동작하지만, 전체가 모여야 바이럴 루프가 완성된다. 결과물이 다음 사용자를 데려오는 구조. 그것이 이 설계의 목적이다.

설정 9개를 3개로 — AI 생성 페이지 UX 간편화 설계

Sat, 21 Mar 2026 19:00:00 +0900

설정이 9개면 아무도 생성하지 않는다

AI 동화 생성 페이지에 설정 항목이 9개 있었다. 작문 스타일, 그림풍, 캐릭터 3명, 콘텐츠 타입, 이미지 비율, 이미지 모드, 장면 수, 장면당 글자 수, 상황 입력. 모든 항목이 같은 가중치로 화면에 나열되어 있었다.

문제는 수량이 아니다. 계층이 없었다.

핵심 발견: “보이냐 숨기냐”가 아니라 “언제 결정하게 하느냐”

세 가지 관점으로 토론했다. 질문자, 방어자, 재구성자. 5라운드에 걸쳐 설정 노출 전략을 설계했다.

질문자의 핵심 지적

사용자가 “작품을 만들겠다”고 결심한 순간, 머릿속에 있는 것은 이야기 상황 하나다. “숲에서 길을 잃은 강아지 이야기.” 이야기를 구상하기도 전에 이미지 비율, 장면당 글자 수, 이미지 모드를 묻고 있었다. 출판 단계의 결정을 창작 단계에서 요구한 것이다.

방어자의 반론

이 서비스는 토큰 기반 과금이다. 설정을 숨기면 사용자가 원치 않는 결과에 토큰을 낭비한다. 재생성은 추가 비용이다. “나중에 바꾸세요”는 무료 서비스의 사고방식이다.

재구성자의 전환

“설정이 많다”가 문제가 아니다. “모든 설정이 같은 시점에 동시에 보인다”가 문제다. 성공적인 생성형 AI 서비스는 설정이 적은 게 아니라 점진적 공개(Progressive Disclosure)를 잘 한다.

설정의 계층 분류

토론을 통해 9개 설정을 4개 계층으로 분류했다.

계층	항목	사용자 행동
매번 변경	상황 입력	핵심 입력 — 가장 큰 공간
자주 변경	작문 스타일, 그림풍	드롭다운 — 눈에 보이되 공간 적게
가끔 변경	장면 수, 캐릭터	보조 입력 — 상황 입력 근처에 작게
거의 안 변경	이미지 비율, 이미지 모드, 글자 수	요약 바 — 기본값으로 충분

콘텐츠 타입(동화/일반)은 독립 토글에서 제거했다. 작문 스타일을 선택하면 자동으로 결정된다. 9개에서 8개로, 실질적으로 사용자가 보는 것은 3개 + 요약 바 1줄이다.

토큰 비용 투명성이 전제 조건

설정을 숨기되, 비용을 숨기면 안 된다. 생성 버튼 옆에 예상 토큰 소모량을 실시간 표시한다. 장면 수를 바꾸면 예측치가 즉시 변한다. 요약 바를 펼쳐 글자 수를 조정하면 토큰도 변한다. 비용이 투명하면 기본값을 신뢰할 수 있다.

리디자인 결과

┌──────────────────────────────────────────┐
│  [작문 스타일 ▾]      [그림풍 ▾]         │  핵심 스타일
├──────────────────────────────────────────┤
│  "이야기를 들려주세요..."                │  상황 입력
│                                          │
│  장면: [3 ▾]   + 캐릭터 추가             │  보조 설정
├──────────────────────────────────────────┤
│  16:9 펼침 · 100자/장면      [설정 ▾]   │  요약 바 (접힘)
├──────────────────────────────────────────┤
│  [ 생성하기 ]           예상 ~750 토큰   │  제출 + 토큰 예측
└──────────────────────────────────────────┘

변경 사항 요약

변경 전	변경 후
콘텐츠 타입 토글	작문 스타일 선택 시 자동 결정
캐릭터 슬롯 3개	“+캐릭터 추가” 인라인 링크
이미지 비율·모드·글자 수 나열	요약 바로 그룹핑 (접힘 기본)
장면 수 별도 영역	상황 입력 바로 아래
토큰 소모량 미표시	생성 버튼 옆 실시간 표시
CreationWizard + MainScreen 이중 패턴	MainScreen으로 통합

스마트 기본값

기본값은 3단계로 결정된다.

시스템 기본값 — 첫 사용자에게 적용
이전 설정 복원 — 반복 사용자의 마지막 설정을 기억
요금제 제약 반영 — 플랜별 최대값을 초과하지 않도록 조정

고정 항목(예: Start 플랜 3장면)은 잠금 아이콘으로 표시한다. “추천”이라는 모호한 라벨 대신, 값 자체를 보여주고 변경 불가 사유를 툴팁으로 안내한다.

결론

설정을 줄이는 것이 아니라 계층을 만드는 것이다. 매번 바뀌는 것은 크게, 거의 안 바뀌는 것은 요약으로. 비용은 숨기지 않는다. 이 원칙이 9개 설정을 3개처럼 느끼게 만든다.

토론 전문 보기 (Socratic Dialogue 5 Rounds)

Agents: Questioner, Defender, Reframer — 5 Rounds

현재 상태 (Before)

MainScreen의 설정 항목 9개가 동일한 가중치로 나열:

Writing Style (작문 스타일 드롭다운)
Art Style (그림풍 드롭다운)
Character Selection (캐릭터 최대 3명 + 각각 커스텀 이름)
Content Type (동화/일반 토글)
Image Size (16:9, 3:2, 9:16, 1:1)
Image Mode (펼침/삽화 토글)
Scene Count (장면 수)
Chars Per Scene (장면당 글자 수)
Story Prompt (상황 텍스트)

Round 1

Questioner (Round 1)

사용자가 “작품을 만들겠다”고 결심한 순간, 머릿속에 있는 것은 무엇인가? 대부분의 사용자는 “이런 이야기를 만들고 싶다”는 상황(Story Prompt)만 가지고 있을 것이다. 그런데 이야기를 쓰기도 전에 이미지 비율, 장면당 글자 수, 이미지 모드 같은 출판 단계의 결정을 요구하고 있다. 이것은 사용자의 멘탈 모델과 일치하는가?
Scene Count와 Chars Per Scene은 사용자가 직관적으로 판단할 수 있는 값인가? “장면당 150자”가 어떤 결과를 만드는지 사용자가 예측할 수 있는가? 이것은 전문가 설정이지 일반 사용자 설정이 아니다.
Content Type(동화/일반)이 왜 사용자 선택인가? Writing Prompt 자체가 이미 스타일을 정의하고 있다면, content type은 writing prompt에 귀속되어야 하는 메타데이터가 아닌가?

Defender (Round 1)

출판 설정이 앞에 있는 이유: 동의한다 — 이미지 비율, 이미지 모드는 “결과물의 형태”에 대한 결정이고, 이야기 구상 단계에서 필수가 아니다. 하지만 Scene Count는 다르다. 장면 수는 이야기 구조(3장면 짧은 이야기 vs 10장면 긴 이야기)에 직접 영향을 주므로 AI에게 지시하기 전에 결정되어야 한다.
Chars Per Scene의 필요성: 전문가 설정이라는 점은 인정한다. 하지만 이 서비스는 토큰 기반 과금이다. 글자 수는 토큰 소모에 직접 영향을 주므로, 비용에 민감한 사용자에게는 제어권이 필요하다. 다만, 기본값을 제공하고 고급 설정으로 숨기는 것은 합리적이다.
Content Type 분리 이유: Writing Prompt를 content type으로 필터링하고 있기 때문에 기술적으로는 content type이 먼저 선택되어야 한다. 하지만 UX적으로는 Writing Prompt 선택 시 자동으로 content type이 결정되게 할 수 있다는 점은 동의한다.

Reframer (Round 1)

두 에이전트 모두 “어떤 설정을 줄일까”에 집중하고 있지만, 질문 자체를 재구성해야 한다.

핵심 재구성: “설정이 많다”가 문제가 아니라, “모든 설정이 같은 시점에 동시에 보인다”가 문제다.

ChatGPT, Midjourney, Canva 등 성공적인 생성형 AI 서비스는 설정이 적은 게 아니라 점진적 공개(Progressive Disclosure) 를 잘 한다.

Storida의 경우:

생성 전 필수: Story Prompt + Writing Style (이 두 가지가 AI의 핵심 입력)
생성 전 선택: Character, Art Style (시각적 선호)
생성 후 조정 가능: Image Size, Image Mode, Scene Count, Chars Per Scene

“생성 후 조정 가능”이 기술적으로 가능한지가 핵심이다 — Scene Count를 바꾸면 재생성이 필요하므로 진짜 “조정”이 되는지 따져봐야 한다.

Round 2

Questioner (Round 2)

“생성 후 조정”이라는 개념이 Storida에서 성립하는가? 이 서비스는 토큰을 소모하는 유료 생성이다. Scene Count를 바꾸면 재생성 = 추가 토큰 소모다. “나중에 바꾸면 된다”는 무료 서비스의 사고방식이고, 유료 서비스에서는 한 번에 원하는 결과를 만드는 것이 사용자 기대다. 그렇다면 설정을 숨기는 것이 오히려 “돈을 낭비하게 만드는 UX”가 아닌가?
“기본값 + 고급 설정”에 동의하지만, 기본값의 품질이 관건이다. 기본값이 충분히 좋다면 사용자는 건드리지 않는다. 그런데 현재 기본값이 사용자의 요금제에 따라 달라진다(plans 테이블의 제한). 이것은 기본값의 의미를 흐린다 — “추천값”인가, “최대 허용값”인가?
Character 선택이 0~3명 사이인데, “없음” 선택 시 AI가 자동 생성한다. 그렇다면 Character 선택은 왜 메인 화면에 있는가? 대부분의 신규 사용자는 캐릭터 없이 시작할 텐데, 빈 슬롯 3개가 화면에 노출되는 것이 첫인상을 복잡하게 만들지 않는가?

Defender (Round 2)

토큰 소모와 설정 숨기기의 긴장: 핵심적인 지적이다. 재생성 비용이 존재하므로 “나중에 바꾸세요”는 위험하다. 그러나 반대 관점도 있다 — 설정이 9개 보이면 사용자가 결정 피로(Decision Fatigue) 로 이탈한다. 생성을 한 번도 못 해보고 떠나는 사용자가, 기본값으로 한 번 생성해보고 다음부터 조정하는 사용자보다 더 큰 손실이다.

제안: 핵심 설정(Prompt, Writing Style, Art Style)만 보여주되, 예상 토큰 소모량을 실시간 표시한다. 고급 설정을 열면 토큰 예측치가 변하는 것을 보여주면 “숨겨진 비용” 문제를 해결할 수 있다.
기본값의 정의: 기본값은 “요금제 내 최적값”이어야 한다. Start 플랜은 3장면 고정이므로 기본값 = 최대값이다. Basic 이상은 “가장 인기 있는 선택”을 기본값으로 설정하는 것이 맞다.
Character 슬롯: 동의한다. 빈 슬롯 3개는 불필요한 복잡성이다. “캐릭터 추가” 버튼 하나로 시작하고, 클릭 시 선택 패널이 열리는 방식이 낫다.

Reframer (Round 2)

Questioner가 “토큰 비용 때문에 모든 설정을 미리 보여줘야 한다”고 주장하고, Defender가 “결정 피로 때문에 숨겨야 한다”고 반론했다. 둘 다 유효하지만 이분법에 갇혀 있다.

재구성: “보이냐 숨기냐”가 아니라, “언제 결정하게 하느냐”의 문제다.

대안 프레임: 2단계 흐름

Step 1 “뭘 만들까”: Prompt + Writing Style + Character (선택) → 이야기의 내용
Step 2 “어떻게 만들까”: Art Style + Image Size + Image Mode + Scene Count + Chars Per Scene → 이야기의 형태

하지만 이 2단계가 현재 CreationWizard와 다른 점은 무엇인가? 단계를 나누는 것 자체가 아니라 각 단계에서 무엇을 묻느냐의 분류 기준이 핵심이다.

Decision Point 1

설정 노출 전략

Agent	Position
Questioner	유료 서비스에서 설정을 숨기면 사용자가 원치 않는 결과에 토큰을 낭비한다
Defender	결정 피로로 인한 이탈이 더 큰 손실이다, 기본값 + 토큰 예측 표시로 해결 가능
Reframer	보이냐/숨기냐가 아니라 “내용 결정 → 형태 결정”으로 단계를 재분류해야 한다

Options:

A) 단일 화면 유지 + 고급 설정 접기 — 핵심 3개만 노출, 나머지 토글 뒤로
B) 2단계 흐름 (내용 → 형태) — 논리적이지만 한 번 더 클릭 필요
C) 스마트 기본값 + 인라인 확장 — 모든 항목에 강한 기본값, 각 항목 옆에 개별 편집 버튼

→ 선택: C

Round 3

Questioner (Round 3)

“스마트 기본값”의 기준은 무엇인가? 신규 사용자의 첫 생성과, 10번째 생성은 다르다. 첫 생성에는 “가장 보편적인 값”이 맞지만, 반복 사용자에게는 “이전에 사용한 값”이 최적의 기본값이다.
“인라인 확장” 버튼이 9개 항목 각각에 붙으면, 그것 자체가 시각적 노이즈가 아닌가? 결국 같은 복잡성을 다른 형태로 포장한 것 아닌가?
9개 중 사용자가 실제로 변경하는 비율은? 데이터 없이 UX를 설계하고 있다.

Defender (Round 3)

스마트 기본값의 3단계 전략:
- Tier 1 — 시스템 기본값 (최초 사용자)
- Tier 2 — 사용자 히스토리 기반 (localStorage 마지막 설정 복원)
- Tier 3 — 요금제 최적값 (플랜별 제약 반영)
시각적 노이즈 해결 — 그룹핑:
- 항상 보이는 영역: Prompt + Writing Style + Art Style + Character (핵심 4개)
- 요약 바(Summary Bar): 나머지 5개를 한 줄로 — "3장면 · 100자 · 16:9 펼침 · 동화" — 클릭 시 펼쳐짐
- 편집 진입점이 1개(요약 바 클릭)이므로 시각적 노이즈 최소화
사용 데이터 수집을 위한 analytics 이벤트 필요성 인정

Reframer (Round 3)

설정의 본질적 분류:

범주	항목	성격
AI 지시	Prompt, Writing Style, Character	창작 의도 — 매번 달라짐
출력 포맷	Art Style, Image Size, Image Mode, Scene Count, Chars Per Scene	제작 사양 — 한 번 정하면 유지
메타 분류	Content Type	Writing Style에 귀속 가능

Content Type을 Writing Style에 흡수하면 9개 → 8개로 줄고, “출력 포맷” 5개가 요약 바로 들어가면 사용자가 보는 것은 3개 + 요약 바 1줄.

단, Art Style은 “출력 포맷”이 아니라 창작 의도에 가깝다 — 핵심 영역에 남겨야 한다.

Round 4

Questioner (Round 4)

Character 선택이 “핵심 영역”에 있어야 하는가? “없음”이 유효한 기본값이라면 핵심이 아니라 선택적 확장이다. 신규 사용자에게 빈 슬롯 3개가 첫인상을 복잡하게 만든다.
요약 바의 한 줄 표시가 처음 쓰는 사용자에게 읽히는가? "3장면 · 100자 · 16:9 펼침" — 각 항목이 뭔지 이미 알아야 의미가 전달된다.
Scene Count의 위치: Prompt와 밀접하다. “긴 모험 이야기”에 3장면은 부족하고, “짧은 잠자리 동화”에 10장면은 과하다. Prompt 바로 아래에 놓으면 요약 바에는 순수 포맷 설정만 남는다.

Defender (Round 4)

Character 절충안: 핵심 영역에 기본 숨김 상태로 “+캐릭터 추가” 링크만 배치. 한 번이라도 사용한 적 있으면 이전 캐릭터 자동 제안.
첫 사용자 vs 반복 사용자: 두 UI 대신 같은 UI에서 상태에 따라 기본값과 노출 수준을 조정 — 첫 사용: “추천 설정” 라벨, 반복 사용: 이전 값 복원.
Scene Count 이동 동의: Prompt + Scene Count를 한 묶음으로.

Reframer (Round 4)

재구성된 레이아웃 제안:

┌─────────────────────────────────────────┐
│  [Writing Style ▾]    [Art Style ▾]     │  ← 핵심 스타일 (2개 드롭다운)
├─────────────────────────────────────────┤
│  "이야기를 들려주세요..."               │  ← Story Prompt (textarea)
│                                         │
│  장면 수: [3 ▾]  (+캐릭터 추가)         │  ← Prompt 보조 설정
├─────────────────────────────────────────┤
│  📐 16:9 펼침 · 100자/장면   [설정 ▾]  │  ← 요약 바 (클릭 시 확장)
├─────────────────────────────────────────┤
│           [ ✨ 생성하기 ]               │  ← 제출 + 예상 토큰
└─────────────────────────────────────────┘

Decision Point 2

Character 선택의 위치와 기본 상태

Agent	Position
Questioner	반복 사용자가 발견하는 기능이므로 핵심 영역에서 빼야 한다
Defender	차별화 기능이므로 “+캐릭터 추가” 링크로 존재감을 유지해야 한다

Options:

A) 완전 숨김 — 요약 바 안에 포함
B) 인라인 링크 — Prompt 근처에 “+캐릭터 추가” 텍스트 링크
C) 조건부 노출 — 캐릭터 1개 이상 등록 사용자에게만 표시

→ 선택: B

Round 5

Questioner (Round 5)

Writing Style에 Content Type을 흡수하면, Writing Style 목록을 어떻게 보여줄 것인가? 전체를 보여주되 동화/일반을 탭으로 구분하는가, 섞어서 보여주는가?
요약 바의 기본값 라벨 — “추천”이라는 단어의 문제: Start 플랜에서 3장면 고정인데 “추천”이라고 쓰면 선택의 여지가 없는 것을 마치 추천인 양 포장하는 셈이다.
리디자인 후 MainScreen과 CreationWizard 두 패턴을 모두 유지할 것인가?

Defender (Round 5)

Content Type 통합: API 레벨은 유지, UI에서만 흡수. Writing Style 드롭다운 내 탭으로 동화/일반 구분, 선택 시 자동 세팅.
“추천” 라벨 제거: 값 자체로 보여주기. 고정 항목은 자물쇠 아이콘 + 툴팁(“Start 플랜에서는 3장면 고정”).
CreationWizard 제거, MainScreen 통합: 이중 패턴 유지보수 비용 제거.

Reframer (Round 5)

핵심 발견: “설정이 많다”가 아니라 “설정의 계층이 없었다”는 것이다.

계층	항목	사용자 행동
매번 변경	Story Prompt	핵심 입력 — 가장 큰 공간
자주 변경	Writing Style, Art Style	드롭다운 — 눈에 잘 보이되 공간 적게
가끔 변경	Scene Count, Character	보조 입력 — Prompt 근처에 작게
거의 안 변경	Image Size, Image Mode, Chars Per Scene	요약 바 — 기본값으로 충분
제거 가능	Content Type (독립 토글)	Writing Style에 흡수

예상 토큰 표시는 필수 전제 조건이다.

Synthesis

Established Facts:

9개 설정의 문제는 수량이 아니라 계층 부재
Content Type은 Writing Style에 흡수 가능 (9개 → 8개)
Scene Count는 Prompt 근처에 배치
Character는 “+캐릭터 추가” 인라인 링크로 선택적 노출
토큰 비용 투명성이 설정 간편화의 전제 조건
CreationWizard와 MainScreen 이중 패턴은 통합 대상

Open Questions:

Writing Style 드롭다운 내 동화/일반 탭 구분 vs 혼합
사용자 히스토리 기본값 저장 위치 (localStorage vs DB)
요약 바 펼침 시 애니메이션/레이아웃
Analytics 이벤트 설계

User Decisions Made:

#	Decision Point	Choice	Rationale
1	설정 노출 전략	C) 스마트 기본값 + 인라인 확장	—
2	Character 위치	B) 인라인 링크	—

Actionable Output — 리디자인 구현 계획:

┌──────────────────────────────────────────┐
│  [Writing Style ▾]      [Art Style ▾]    │  핵심 스타일 선택
├──────────────────────────────────────────┤
│  "이야기를 들려주세요..."                │  Story Prompt (auto-height)
│                                          │
│  장면: [3 ▾]   + 캐릭터 추가             │  보조 설정
├──────────────────────────────────────────┤
│  📐 16:9 펼침 · 100자/장면  [설정 ▾]    │  요약 바 (접힘 상태)
│  ┌─ 펼침 시 ──────────────────────────┐  │
│  │ 이미지 비율: ◻16:9 ◻3:2 ◻9:16 ◻1:1│  │
│  │ 이미지 모드: ◻펼침  ◻삽화          │  │
│  │ 장면당 글자: [100]                  │  │
│  └────────────────────────────────────┘  │
├──────────────────────────────────────────┤
│  [ ✨ 생성하기 ]     예상 ~750 토큰      │  제출 + 토큰 예측
└──────────────────────────────────────────┘

구현 항목:

Content Type 토글 제거 → Writing Style 선택 시 자동 결정
Character 슬롯 3개 제거 → “+캐릭터 추가” 인라인 링크 + 팝오버
Image Size, Image Mode, Chars Per Scene → 요약 바로 그룹핑
Scene Count → Prompt 영역 하단으로 이동
예상 토큰 소모량 실시간 계산 표시
스마트 기본값 로직 (시스템 기본 → localStorage 이전 설정 복원)
CreationWizard 코드 제거, MainScreen으로 통합

콘텐츠 타입 확장 설계 — 동화 전용에서 범용 창작 플랫폼으로

Thu, 19 Mar 2026 19:00:00 +0900

문제: 30곳에 하드코딩된 “동화”

“어린이 동화” 전용 서비스로 시작했다. “동화”, “아이들”, “children’s book”이 30곳 이상에 박혀 있었다. 성인 에세이를 생성해도 “어린이가 이해하기 쉬운 단어”가 적용된다. 부적절한 결과가 나왔다.

하드코딩 위치	내용
scheduler/src/context.ts	“어린이 동화를 JSON 형식으로…”
scheduler/src/image-regen.ts	“children’s book illustration”
src/db/seed.ts	시스템 프롬프트, 평가 기준
src/modules/generation.service.ts	폴백 제목 “생성된 동화”
src/modules/prompt.routes.ts	“동화 샘플”, “어린이 콘텐츠 적합성”

설계 원칙

5가지 원칙으로 확장을 설계했다.

원칙	적용
하위 호환 100%	`content_type` 기본값 `fairytale` → 기존 코드 무변경 시 동일 동작
기존 패턴 준수	Feature-based 구조, Drizzle ORM, Express, Zod 그대로
단일 진실 원천	프롬프트는 DB에서 조회, 하드코딩 폴백은 타입별 분기
점진적 확장	`content_type`을 text 타입 → 추후 `essay`, `poem` 등 추가 용이
최소 변경	기존 테이블에 컬럼 추가 우선, 새 테이블은 `writings`만

콘텐츠 타입 정의

값	라벨	대상	어휘 제한
`fairytale`	동화	어린이	쉬운 어휘, 교육적
`general`	일반	성인	제한 없음, 자유 문체

기본값은 fairytale이다. 기존 사용자는 아무 변경 없이 동일한 경험을 유지한다.

핵심 아키텍처: PromptResolver

문제

30곳을 각각 if (contentType === 'fairytale') ... else ...로 분기하면 코드가 2배로 늘어난다.

해결: 중앙 프롬프트 해석기

                    ┌──────────────────┐
 context.ts ───────▶│  PromptResolver  │
 image-regen.ts ───▶│                  │
 generation.svc ───▶│  resolve(key,    │──▶ app_config DB
 prompt.routes ────▶│    contentType)  │──▶ 폴백 상수 맵
                    └──────────────────┘

PromptResolver는 하나의 진입점으로 모든 프롬프트 조회를 통합한다. content_type에 따라 적절한 프롬프트를 반환하되, DB에 없으면 폴백 상수를 사용한다.

PromptResolver는 콘텐츠 타입에 따라 적절한 프롬프트를 반환한다.

// 조회 우선순위:
// 1. 캐시 확인
// 2. DB 설정 테이블에서 타입별 키로 조회 (fairytale은 기존 키, general은 접미사 추가)
// 3. 폴백 상수 맵에서 조회

폴백 상수 맵 설계

폴백 프롬프트는 콘텐츠 타입별로 분리된다. 동화 타입은 아동 친화적 어휘와 교육적 톤을, 일반 타입은 자유로운 문체를 사용한다. 작문 시스템 프롬프트, 이미지 생성 프롬프트, 평가 프롬프트 각각에 타입별 폴백이 존재한다.

DB 설정이 없을 때 폴백이 작동하므로, 새 콘텐츠 타입을 추가할 때 DB 시드를 먼저 넣지 않아도 서비스가 중단되지 않는다.

DB 스키마 변경

기존 테이블 확장

기존 테이블(contents, prompt_templates, characters)에 타입 구분 컬럼을 추가한다. 기본값 설정으로 기존 데이터는 자동 호환된다.

모든 기본값이 기존 동작과 동일하므로, 롤백 시 코드만 되돌리면 DB는 그대로 작동한다.

신규 테이블: writings (글쓰기)

글쓰기 테이블은 사용자가 작성한 글 본문, 콘텐츠 타입, 상태(초안/사용됨)를 저장한다. 글쓰기 기능은 “아이디어를 먼저 글로 정리한 뒤, 나중에 책으로 만드는” 2단계 워크플로우를 지원한다. 글에서 생성된 콘텐츠에 대한 참조로 글에서 책으로의 전환을 추적한다.

기능 범위 (F1~F10)

#	기능	설명
F1	콘텐츠 타입 선택	생성 시 “동화”/”일반” 선택 UI
F2	타입별 프롬프트 분기	PromptResolver 기반 자동 전환
F3	DB 스키마 확장	`contents.content_type` 컬럼
F4	하드코딩 제거	30곳 → DB 설정 또는 타입 분기
F5	글쓰기 기능	독립 글 작성·저장
F6	글 → 책 전환	저장된 글을 “상황” 입력으로 활용
F7	자동 캐릭터 프로파일링	글 생성 후 등장인물 시각 프로파일 자동 추출
F8	캐릭터 이미지 타입 분류	인물/풍경/사물 자동 분류
F9	작문 프롬프트 타입 연동	content_type별 프롬프트 분류
F10	이미지 모드	펼침(16:9) vs 삽화 선택

F7: 자동 캐릭터 프로파일링

캐릭터를 지정하지 않아도 이미지 일관성을 확보하는 기능이다.

텍스트 생성 완료
    │
    ▼
Claude가 등장인물 시각 프로파일 자동 추출
(캐릭터별 외형 묘사: 나이, 머리색, 복장 등)
    │
    ▼
이미지 생성 시 프로파일을 프롬프트에 주입

기존 멀티 캐릭터 시스템은 관리자가 등록한 캐릭터에 의존했다. F7은 텍스트에서 자동 추출한다. 사용자가 캐릭터를 선택하지 않아도 일관성을 확보한다.

변경 영역 매핑

packages/db        → schema 확장 (컬럼 추가, writings 테이블)
        ↓
src/modules        → generation 검증, writings CRUD, prompts 타입 분기
        ↓
scheduler/src      → PromptResolver, character-profiler, image 크기 분기
        ↓
web/src            → content_type 선택 UI, 글쓰기 기능
admin/src          → prompts content_type 필드, characters image_type 뱃지

설계의 핵심: 확장 가능성

content_type을 text 타입으로 설계했다. 향후 essay, poem, novel을 추가할 때 DB 마이그레이션이 필요 없다. 새 값만 추가하면 된다.

새 타입 추가 시 폴백 프롬프트 추가, DB 설정 시드, UI 옵션 추가만 하면 된다. DB 스키마 변경은 필요 없다.

PromptResolver의 resolve(baseKey, contentType) 패턴이 이를 가능하게 한다. 새 타입의 프롬프트가 DB에 없으면 폴백을 사용하고, 점진적으로 DB에 최적화된 프롬프트를 추가하면 된다.

결론

“동화 전용”에서 “범용 창작 플랫폼”으로의 확장은 if-else를 추가하는 일이 아니다. 중앙 프롬프트 해석기라는 추상 레이어를 도입하고, 하위 호환 100%를 보장하는 마이그레이션 전략을 세워야 한다.

기존 사용자에게는 아무것도 바뀌지 않는다. 새로운 가능성만 열린다.

JenaImage — Finder와 Preview 사이를 없앤 macOS 이미지 뷰어

Wed, 18 Mar 2026 19:00:00 +0900

이미지를 관리하려면 앱 두 개가 필요하다

폴더를 탐색한다. Finder. 이미지를 본다. Preview. 다른 폴더로 옮긴다. 다시 Finder. 포맷을 변환한다. 또 다른 앱.

이미지 작업은 항상 앱 사이를 오간다. JenaImage는 이 이동을 없앤다. 폴더 사이드바, 썸네일 그리드, 이미지 뷰어, 동영상 재생, 포맷 변환이 한 창에 있다.

설계 결정

AppKit을 선택한 이유

이 앱은 세 가지 핵심 컴포넌트를 사용한다.

컴포넌트	AppKit	SwiftUI
폴더 트리	NSOutlineView — 안정적	OutlineGroup — 대규모 트리에서 불안정
이미지 그리드	NSCollectionView — 성능 검증됨	LazyVGrid — 스크롤 끊김 보고
줌/팬 뷰어	NSScrollView magnification	ScrollView — 세밀한 제어 어려움

세 컴포넌트 모두 AppKit이 우위다. macOS 14 이상을 타겟으로 해도 SwiftUI의 이 영역은 성숙하지 않았다.

Swift Concurrency, GCD가 아닌 이유

이미지 뷰어는 비동기 작업이 많다. 폴더 탐색, 썸네일 생성, 대용량 이미지 로딩, 포맷 변환. 모두 백그라운드에서 처리해야 한다.

GCD 대신 Swift Concurrency(async/await)를 택했다. 이유는 하나다. 작업 취소. 폴더를 전환하면 이전 폴더의 썸네일 생성을 즉시 중단해야 한다. GCD에서는 취소 로직을 직접 구현해야 한다. Swift Concurrency는 Task.isCancelled로 해결된다.

아키텍처: 한 창 안의 세 영역

┌──────────────────────────────────────────────────────┐
│  MainWindowController (NSSplitViewController)        │
├──────────┬───────────────────────────────────────────┤
│ Sidebar  │  Browser (그리드) ←→ Viewer (상세)        │
│ 폴더 트리 │  ┌─────────────────────────────────────┐  │
│          │  │ 폴더 + 이미지 썸네일                  │  │
│ 폴더 선택 │  │ 또는                                │  │
│ 드래그    │  │ 이미지 뷰어 + 썸네일 스트립            │  │
│ 앤 드롭   │  └─────────────────────────────────────┘  │
└──────────┴───────────────────────────────────────────┘

NSSplitViewController가 전체를 관리한다. 왼쪽은 폴더 사이드바. 오른쪽은 브라우저(그리드)와 뷰어(상세)를 전환한다. MainWindowController가 중재자다.

의존성 규칙

UI (ViewController) → Service → Model

역방향 의존은 금지한다. 기능 간 통신은 Delegate 패턴만 사용한다. NotificationCenter나 Combine은 쓰지 않는다. 타입 안전성을 보장하고 추적 가능한 흐름을 유지한다.

파일 구조

Sources/
├── app/        메인 윈도우, 메뉴, 설정, 도움말
├── sidebar/    폴더 트리 (NSOutlineView)
├── browser/    이미지 그리드 (NSCollectionView)
├── viewer/     이미지 뷰어, 줌, 썸네일 스트립, 동영상
├── services/   파일 관리, 이미지 처리, 캐시, 보안
└── models/     폴더 노드, 이미지 파일, 포맷 정의

썸네일 캐시: 메모리만, 디스크 없음

1,000장 이상의 이미지를 스크롤할 때 버벅이면 안 된다. 썸네일 캐시가 필요하다.

NSCache 기반 메모리 캐시를 사용한다. 500MB 상한. LRU 정책으로 자동 해제한다. macOS가 메모리 부족을 감지하면 NSCache가 알아서 비운다.

디스크 캐시는 두지 않았다. ImageIO의 썸네일 생성이 충분히 빠르다. 디스크 캐시를 추가하면 무효화 로직이 복잡해진다. 파일이 이동되거나 삭제되면 캐시와 불일치가 생긴다. 그 복잡도를 감수할 만큼 디스크 캐시의 이득이 크지 않았다.

줌과 팬: NSScrollView의 magnification

이미지 뷰어는 10%에서 500%까지 확대한다. 확대하면 드래그로 이동한다.

NSScrollView의 magnification 프로퍼티를 사용한다. 트랙패드 핀치, Cmd+/-, 키보드 단축키가 모두 이 하나의 프로퍼티를 조작한다. 별도 확대 로직을 구현하지 않았다.

단축키	동작
Cmd++	확대
Cmd+-	축소
Cmd+0	원본 크기 (100%)
Cmd+9	창에 맞춤

포맷 변환: ImageIO 양방향

JPEG, PNG, WebP, HEIC, HEIF, AVIF, TIFF, BMP, GIF를 지원한다. 입력과 출력 모두.

변환은 ImageIO 프레임워크가 처리한다. CGImageSource로 원본을 읽고, CGImageDestination으로 대상 포맷에 쓴다. 외부 라이브러리 없이 시스템 프레임워크만으로 9개 포맷을 처리한다.

파일 관리: Finder를 열지 않아도

삭제는 휴지통으로 보낸다. 영구 삭제가 아니다. 이동은 사이드바의 폴더로 드래그한다. 이름 변경은 인라인 편집이다. 클립보드 복사도 된다.

모든 파일 작업은 Result 타입을 반환한다. 실패하면 에러를 명시한다. “권한이 없습니다”, “파일이 이미 존재합니다”. 사용자에게 실패 이유를 숨기지 않는다.

동영상 재생

이미지 뷰어에서 동영상도 재생한다. MP4, MOV, M4V, AVI, MKV. AVKit의 인라인 플레이어를 사용한다. 별도 창을 열지 않는다. 이미지와 동영상이 같은 폴더에 섞여 있어도 자연스럽게 탐색한다.

샌드박스와 보안

macOS 앱은 사용자가 허용한 폴더만 접근할 수 있다. 처음 폴더를 선택하면 보안 범위 북마크를 저장한다. 앱을 재시작해도 같은 폴더에 접근할 수 있다.

북마크가 없는 폴더에는 접근하지 못한다. 이것은 제약이 아니다. macOS 보안 모델을 따르는 것이다.

빌드: Makefile + swiftc

JenaLab의 macOS 앱 빌드 방식과 동일하다.

make run      # 빌드 + 실행
make build    # .app 번들 생성
make install  # ~/Applications에 설치
make dmg      # 배포용 디스크 이미지
make pkg      # 패키지 인스톨러

28개 Swift 파일. 외부 의존성 0개. Xcode 프로젝트 0개.

정리

이미지 관리에 앱 두 개는 불필요하다. 폴더 트리, 썸네일 그리드, 줌 뷰어, 파일 관리, 포맷 변환. 한 창에 담는다.

NSOutlineView, NSCollectionView, NSScrollView. AppKit의 기본 컴포넌트가 각자의 역할을 한다. 위에 얹은 것은 Delegate 패턴으로 연결한 중재자뿐이다.

JenaImage는 MIT 오픈소스다.

GitHub · DMG 다운로드

JenaNote — NSDocument로 만드는 WYSIWYG 마크다운 에디터

Mon, 16 Mar 2026 19:00:00 +0900

마크다운 기호가 보이지 않는 에디터

**굵게**를 입력하면 **가 사라지고 굵게만 남는다. # 제목을 입력하면 #이 사라지고 큰 글씨만 보인다. 저장하면 .md 파일이다. 다른 마크다운 뷰어에서 열어도 서식이 일치한다.

JenaNote는 이 동작을 수행하는 macOS 네이티브 에디터다.

문제: 기존 도구의 틈

마크다운 에디터는 두 부류로 나뉜다.

기호 노출형 (Obsidian, VS Code). 마크다운 문법을 알아야 한다. #, **, - 기호가 화면에 그대로 보인다.
서식 에디터 (TextEdit, Notes). WYSIWYG이지만 .md로 저장하지 못한다.

Typora가 이 틈을 메웠지만, 유료 전환 후 대안이 필요해졌다. JenaNote는 그 자리를 MIT 오픈소스로 채운다.

기준	JenaNote	Typora	Obsidian	TextEdit
WYSIWYG	O	O	X	O
.md 저장	O	O	O	X
기호 숨김	O	부분	X	해당없음
macOS 네이티브	O	O	X	O
오픈소스	MIT	유료	유료	시스템 앱

설계의 출발점: NSDocument

macOS에는 문서 기반 앱을 위한 표준 패턴이 있다. NSDocument다. 이 클래스를 상속하면 다음이 공짜로 따라온다.

저장 / 다른 이름으로 저장 대화상자
창 제목의 변경 표시 점(●)
닫기 전 “저장하시겠습니까?” 확인 시트
앱 종료 후 재시작 시 문서 복원
Undo / Redo 스택

직접 구현하면 이 목록만으로 수백 줄이다. NSDocument를 쓰면 0줄이다.

결정: NSDocument를 상속하고, 커스텀 파일 관리 코드를 작성하지 않는다.

3레이어 아키텍처

┌─────────────────────────────────────────┐
│  UI Layer                               │
│  텍스트 뷰 · 서식 툴바 · 뷰컨트롤러      │
└────────────────┬────────────────────────┘
                 │ NSAttributedString 읽기/쓰기
┌────────────────▼────────────────────────┐
│  Document Layer                         │
│  마크다운 문서 (NSDocument 서브클래스)     │
└────────────────┬────────────────────────┘
                 │ 직렬화 / 역직렬화
┌────────────────▼────────────────────────┐
│  Infrastructure Layer                   │
│  마크다운 시리얼라이저                    │
│  (NSAttributedString ↔ CommonMark .md)  │
└─────────────────────────────────────────┘

의존성은 위에서 아래로만 흐른다. 세 가지 규칙을 정했다.

UI는 시리얼라이저를 직접 호출하지 않는다
Document는 AppKit UI 컴포넌트에 의존하지 않는다
시리얼라이저는 순수 함수다. 상태가 없다

핵심 결정: 내부 표현으로 NSAttributedString

마크다운 에디터를 만들 때 내부 표현의 선택이 아키텍처 전체를 결정한다.

선택지	장점	단점
마크다운 AST	CommonMark 완전 지원	NSTextView와 별도 동기화 필요
NSAttributedString	NSTextView 직접 통합, Undo 자동	복잡한 중첩 구조에 한계

NSAttributedString을 선택했다. NSTextView가 이 형식을 네이티브로 처리한다. 볼드, 이탤릭, 제목, 목록을 속성(attribute)으로 저장하면 화면에 즉시 반영된다. Undo/Redo도 NSUndoManager가 자동 처리한다.

트레이드오프는 있다. 마크다운의 복잡한 중첩 구조(리스트 안의 코드 블록 안의 볼드)를 완벽하게 표현하기 어렵다. 메모 앱의 범위에서는 허용 가능한 제약이다.

데이터 흐름

파일 열기

Finder에서 .md 더블클릭
  → NSDocumentController가 Document 인스턴스 생성
  → 시리얼라이저: 마크다운 텍스트 → NSAttributedString
  → 뷰컨트롤러가 텍스트 뷰에 로드
  → 기호 없이 서식 적용된 상태로 표시

서식 적용

Cmd+B 또는 툴바 B 클릭
  → 뷰컨트롤러가 서식 명령 호출
  → 텍스트 스토리지에 속성 변경 (Undo 등록)
  → 화면 즉시 반영. 기호는 보이지 않는다.

저장

Cmd+S
  → NSDocument가 저장 처리 (AppKit 자동)
  → 시리얼라이저: NSAttributedString → CommonMark 텍스트
  → .md 파일로 디스크 기록
  → 창 제목의 ● 표시 제거

시리얼라이저: 양방향 변환

시리얼라이저는 두 가지 일을 한다.

파싱: .md 파일의 마크다운 텍스트를 받아 NSAttributedString으로 변환한다. **텍스트**는 볼드 속성이 적용된 “텍스트”가 된다.

직렬화: NSAttributedString의 속성을 읽어 CommonMark 텍스트로 변환한다. 볼드 속성이 있으면 **로 감싼다.

이 모듈은 순수 함수다. 입력을 받아 출력을 반환한다. 상태를 저장하지 않는다. Foundation만 import한다. 테스트가 쉬운 이유다.

macOS 표준을 따르는 이유

메뉴와 단축키

macOS의 Responder Chain을 그대로 사용한다. 별도 메뉴 관리 코드가 필요 없다.

파일 메뉴(저장, 열기) → NSDocument가 자동 처리
편집 메뉴(Undo, 복사, 붙여넣기) → NSTextView가 자동 처리
서식 메뉴(Bold, Italic) → 커스텀 액션만 연결

커스텀 코드가 필요한 곳은 서식 적용뿐이다. 나머지는 AppKit이 처리한다.

미저장 경고

변경 사항이 있는 상태에서 창을 닫으면 확인 시트가 뜬다. “저장”, “저장 안 함”, “취소”. 이 동작도 NSDocument가 자동 제공한다. 직접 구현하면 닫기, 종료, 새 문서 열기 등 모든 경로에서 경고를 호출해야 한다. 빠뜨리면 데이터 손실이다.

빌드: Xcode 없이

jenaMemory와 같은 방식이다. Makefile + swiftc.

make run      # 빌드 + 실행
make build    # .app 번들 생성
make install  # ~/Applications에 설치
make dmg      # 배포용 디스크 이미지
make pkg      # 패키지 인스톨러

Swift 파일을 하나의 바이너리로 컴파일한다. Xcode 프로젝트 파일이 없으므로 Git diff가 깨끗하다. 설정 변경이 Makefile 한 줄에 담긴다.

정리

WYSIWYG 마크다운 에디터를 만드는 데 필요한 것은 세 가지다.

NSDocument — 파일 관리를 macOS에 맡긴다
NSAttributedString — 내부 표현과 화면 표시를 일치시킨다
양방향 시리얼라이저 — .md 파일과의 변환을 담당한다

나머지는 AppKit이 처리한다. 플랫폼이 제공하는 것을 다시 만들지 않는다. 이것이 네이티브 앱의 설계 원칙이다.

JenaNote는 MIT 오픈소스다.

GitHub · DMG 다운로드

jenaMemory — Xcode 없이 만드는 macOS 메뉴바 앱

Sat, 14 Mar 2026 19:00:00 +0900

메뉴바에 메모리 사용량을 띄운다

macOS 메뉴바 오른쪽에 숫자 하나가 뜬다. 현재 여유 메모리 퍼센트다. 2초마다 갱신된다. 클릭하면 상세 통계가 나온다. 한 번 더 클릭하면 캐시를 비운다.

jenaMemory는 이 동작을 수행하는 경량 유틸리티다. Swift 파일 8개, Xcode 프로젝트 없이 swiftc로 빌드한다.

왜 직접 만들었나

메모리 모니터 앱은 App Store에 넘친다. 대부분 두 가지 문제가 있다.

무겁다. 메모리를 감시하는 앱이 메모리를 잡아먹는다.
팝업이 많다. 구독 유도, 프리미엄 잠금, 광고.

필요한 건 숫자 하나와 버튼 하나다. 그래서 직접 만들었다.

설계 결정

AppKit, SwiftUI가 아닌 이유

SwiftUI는 macOS 13부터 안정적이다. 하지만 메뉴바 앱에서는 AppKit이 더 적합하다.

기준	SwiftUI	AppKit
NSStatusItem 제어	래핑 필요	네이티브
메뉴 동적 갱신	번거로움	직관적
번들 크기	더 큼	최소
macOS 12 이하 지원	불안정	안정

메뉴바 앱은 UI가 단순하다. SwiftUI의 선언적 장점이 발휘되지 않는다. AppKit으로 직접 제어하는 편이 가볍고 예측 가능하다.

Xcode 없이 빌드하는 이유

swiftc -framework AppKit -O Sources/*.swift -o jenaMemory

한 줄이면 빌드된다. Xcode 프로젝트 파일(.xcodeproj)은 Git diff가 읽기 어렵다. 설정 변경이 XML 안에 묻힌다. Makefile로 빌드하면 모든 설정이 텍스트로 추적된다.

make run      # 빌드 + 즉시 실행
make build    # .app 번들 생성
make install  # ~/Applications에 설치
make pkg      # .pkg 인스톨러 생성
make dmg      # .dmg 배포 이미지 생성

아키텍처: 8개 파일, 역할 분리

┌──────────────────────────────────────────────┐
│  main.swift → AppDelegate                    │
│       │                                      │
│       ▼                                      │
│  MenuBarController (메인 컨트롤러)             │
│       │                                      │
│       ├── MemoryMonitor (시스템 메모리 조회)    │
│       ├── PrivilegedExecutor (권한 실행)       │
│       ├── SettingsWindowController (설정)      │
│       ├── AboutWindowController (정보)         │
│       └── Localization (9개 언어)              │
└──────────────────────────────────────────────┘

파일 수가 8개다. 의도적이다. 메뉴바 유틸리티에 레이어드 아키텍처나 MVVM은 과잉이다. 역할별로 파일을 나누되, 추상화 계층은 만들지 않았다.

MenuBarController — 모든 것의 중심

이 파일이 앱의 중심이다. NSStatusItem을 생성하고, 2초 타이머로 메모리를 갱신하고, 메뉴를 구성한다.

메뉴바 아이콘은 RAM 칩 모양이다. 메모리 사용률에 따라 채워지는 비율이 달라진다. 라이트/다크 모드에 자동 대응한다. 16x18 픽셀에 이 모든 정보를 담는다.

MemoryMonitor — Darwin Mach API 직접 호출

메모리 통계를 Foundation이 아닌 Darwin Mach API로 조회한다. vm_statistics64를 직접 호출한다. Foundation을 거치면 불필요한 오버헤드가 생긴다. 2초마다 호출되는 함수에서 오버헤드는 누적된다.

메모리 계산 모델은 macOS Activity Monitor와 일치시켰다.

항목	계산
사용 중	Wired + Active + Compressed
캐시	Inactive (필요 시 회수 가능)
여유	Free + Inactive
사용률	사용 중 ÷ 전체 × 100

Inactive 메모리를 “여유”에 포함한다. macOS는 Inactive를 캐시처럼 관리하며, 새 프로세스가 요청하면 즉시 회수한다.

PrivilegedExecutor — 2단계 권한 상승

메모리 최적화는 시스템의 purge 명령을 실행한다. 관리자 권한이 필요하다.

첫 실행:
  AppleScript → 시스템 암호 입력창 → sudoers 규칙 설치 → purge 실행

이후 실행:
  sudoers 규칙 확인 → 암호 없이 purge 실행

첫 실행에서 한 번만 암호를 입력하면, 이후에는 묻지 않는다. sudoers 규칙을 설치하여 해당 명령만 무암호로 허용한다. 전체 sudo 권한을 열지 않는다.

임시 파일은 defer로 자동 삭제한다. 권한 관련 코드에서 임시 파일이 남으면 보안 위험이다.

자동 최적화

여유 메모리가 설정한 임계값 이하로 떨어지면 자동으로 최적화를 실행한다. 60초 쿨다운을 둔다. 이 쿨다운이 없으면 임계값 근처에서 최적화가 반복 실행된다.

2초마다 메모리 확인
  │
  ├── 여유 > 임계값 → 대기
  └── 여유 ≤ 임계값
       ├── 마지막 실행 후 60초 미경과 → 대기
       └── 60초 경과 → 자동 최적화 실행

다국어 지원: 9개 언어

한국어, 영어, 중국어, 일본어, 스페인어, 독일어, 프랑스어, 러시아어, 힌디어를 지원한다.

.strings 파일이나 .lproj 번들을 쓰지 않았다. Swift enum으로 모든 문자열을 관리한다. 메뉴바 앱에서 Xcode 로컬라이제이션 시스템은 과잉이다.

언어를 변경하면 메뉴, 설정 창, 정보 창이 즉시 갱신된다. 앱 재시작이 필요 없다. NotificationCenter로 변경 이벤트를 전파하고, 각 컨트롤러가 UI를 다시 그린다.

Dock에 아이콘이 없다

LSUIElement = true 설정으로 Dock에서 숨긴다. 메뉴바 앱은 Dock에 있을 이유가 없다. 항상 메뉴바에 있고, 설정 창을 열 때만 포커스를 받는다. macOS의 시스템 유틸리티들이 따르는 패턴이다.

배포: DMG와 PKG

make dmg    # 디스크 이미지 (.dmg)
make pkg    # 패키지 인스톨러 (.pkg)

두 형식 모두 Makefile 한 줄로 생성한다. 코드 서명과 노터라이제이션은 별도 처리가 필요하지만, 빌드 자체는 자동화되어 있다.

정리

메뉴바 유틸리티에 필요한 것은 많지 않다. AppKit, Mach API, Makefile. 8개 파일. 외부 의존성 0개. Xcode 프로젝트 0개.

복잡한 도구가 필요하지 않을 때, 도구를 줄이는 것도 설계다.

jenaMemory는 MIT 오픈소스다.

GitHub · DMG 다운로드

Cloudflare R2 마이그레이션과 Scheduler 모듈화 리팩토링

Fri, 06 Mar 2026 19:00:00 +0900

Part 1: Supabase Storage에서 Cloudflare R2로

마이그레이션 동기

Supabase Storage는 초기 개발에 편리했다. 서비스가 성장하면서 한계가 드러났다.

기준	Supabase Storage	Cloudflare R2
비용	무료 티어 한정, 이후 급증	10GB 무료, 이후 $0.015/GB
Egress 비용	있음	무료
CDN	Supabase CDN	Cloudflare 글로벌 CDN 자동
커스텀 도메인	제한적	자유 설정
Presigned URL	미지원	S3 호환 API 완전 지원

Egress 비용이 결정적이었다. 동화책 서비스는 이미지 트래픽이 많다. 페이지당 이미지가 있고, 사용자가 반복 열람한다. R2는 Egress가 무료다.

R2 구성

환경	버킷	공개 URL
개발	`myapp-dev`	`cdn-dev.example.com`
운영	`myapp`	`cdn.example.com`

디렉토리 구조를 Supabase 버킷과 1:1 매핑하여 마이그레이션의 복잡도를 최소화했다.

기존 Supabase 버킷	R2 디렉토리	용도
`media`	`media/`	장면 이미지, PDF, 미리보기
`shared`	`shared/`	폰트, 공지 이미지
(신규)	`assets/`	캐릭터 이미지

Presigned URL 워크플로우

기존에는 클라이언트가 Supabase SDK로 직접 업로드했다. R2에서는 Presigned URL 패턴으로 전환했다.

Client → POST /api/upload/presign
         { bucket: "assets", path: "abc.jpg", contentType: "image/jpeg" }
       ← { uploadUrl: "https://...(서명된 URL)", publicUrl: "https://cdn.example.com/assets/abc.jpg" }

Client → PUT uploadUrl (파일 바이너리 전송)

Client → publicUrl로 접근

이 패턴의 장점:

Backend가 파일을 중계하지 않음: 대역폭 절약
권한 검증을 Backend에서 수행: Presign 요청 시 인증 확인
클라이언트 SDK 불필요: 표준 HTTP PUT으로 업로드

레거시 URL 호환 전략

기존 DB에는 Supabase Storage URL이 저장되어 있다. 한꺼번에 바꾸면 위험하다. 점진적 전환을 택했다.

기존 Supabase URL: 유지 (Supabase Storage public 설정 유지)
새 업로드: R2 URL로 저장
deleteFile: R2 URL만 삭제, Supabase URL은 warn 로그만 출력

시간이 지나면서 자연스럽게 R2 URL 비율이 높아지고, 충분히 전환된 후 Supabase Storage를 제거한다.

변경 범위

앱	변경 사항
Backend	`supabase-storage.ts` → `r2-storage.ts` (동일 인터페이스)
Scheduler	Supabase SDK 제거, `uploadToR2()` 함수 추가
Admin	Supabase 직접 업로드 → Presigned URL 방식
Web	PDF 생성 시 Presigned URL 사용

r2-storage.ts는 기존 supabase-storage.ts와 동일한 함수 시그니처를 유지한다. uploadImage, downloadImage, deleteFile — import 경로만 바꾸면 된다.

Part 2: Scheduler 모듈화 리팩토링

문제: 638줄 단일 파일

R2 마이그레이션을 진행하면서 Scheduler의 src/index.ts가 638줄이라는 사실을 직면했다. DB 스키마, Lock 관리, 토스페이먼츠 API, 자동 결제, 공지 발행, Job 복구, Job 처리 루프가 모두 하나의 파일에 있었다.

모듈화 원칙

역할 단위 분리와 의존성 주입 두 가지 원칙으로 리팩토링했다.

변경 전

scheduler/src/
├── constants.ts
├── index.ts              # 638줄 — 모든 로직
└── services/
    └── generation.service.ts

변경 후

scheduler/src/
├── constants.ts
├── index.ts              # ~100줄 — 메인 루프만
├── db/
│   ├── schema.ts         # Drizzle 테이블 정의
│   └── client.ts         # DB 연결 팩토리
├── utils/
│   └── lock.ts           # Lock 파일 관리
└── services/
    ├── payment-gateway.ts    # 결제 API 유틸
    ├── publisher.service.ts  # 예약 발행
    ├── billing.service.ts    # 자동 결제 (3개 함수)
    ├── recovery.service.ts   # Stale Job 복구
    ├── job.service.ts        # Job 처리 루프
    └── generation.service.ts # AI 생성 파이프라인

DB 클라이언트 팩토리 패턴

모듈 스코프 변수를 캡처하는 대신, 팩토리 함수로 DB 클라이언트를 생성하고 각 서비스에 주입한다.

DB 클라이언트 팩토리 함수가 연결을 생성하고, 메인 엔트리에서 이를 각 서비스에 주입한다. 모든 서비스 함수가 DB 클라이언트를 첫 번째 파라미터로 받는다. 테스트 시 Mock DB를 주입할 수 있고, 함수가 외부 상태에 의존하지 않는 순수한 구조가 된다.

토스 API 시그니처 변경

기존에 모듈 스코프 변수를 클로저로 캡처하던 방식을 명시적 파라미터로 전환했다.

기존에는 모듈 스코프 변수를 클로저로 캡처하여 암묵적으로 사용했다. 리팩토링 후 모든 외부 의존성을 명시적 파라미터로 전달한다. 결제 API 키, DB 클라이언트 등이 함수 시그니처에 드러난다.

index.ts의 역할

리팩토링 후 index.ts는 오케스트레이터 역할만 한다.

index.ts 담당:
1. 환경변수 검증 (DATABASE_URL 필수)
2. Lock 획득 (중복 실행 방지)
3. Signal 핸들러 등록 (SIGTERM, SIGINT)
4. DB 클라이언트 생성
5. 3개 타이머 등록:
   - 30초: Job 처리
   - 60초: 공지 발행 + Job 복구
   - 1시간: 자동 결제

무변경 보장

동작 변경은 없다. 로직 자체는 그대로이며 파일 구조만 변경했다. tsup이 단일 번들로 컴파일하므로 배포에도 영향 없다. yarn build:scheduler로 빌드 검증 후 배포했다.

두 작업의 연관성

R2 마이그레이션과 모듈화를 같은 날 진행했다. 638줄 파일에서 Storage 코드를 찾아 교체하려니 비효율적이었다. 모듈을 먼저 분리하니 변경 범위가 명확해졌다.

리팩토링은 미루면 영원히 하지 않는다. 필요한 시점에 필요한 만큼 하는 편이 낫다.

다음 글은 콘텐츠 타입 확장 설계를 다룬다.

토큰 기반 요금제 설계 — AI SaaS의 과금 모델

Wed, 04 Mar 2026 19:00:00 +0900

문제: AI 비용은 변동적이다

동화 3장면과 20장면의 AI API 비용은 7배 차이가 난다. “월 N권”으로 요금제를 설계하면 1권의 정의가 모호해진다. 사용자도 서비스도 손해를 본다.

토큰 기반 과금으로 이 문제를 풀었다.

토큰 단위 설계

AI 실사용 토큰과의 관계

Storida 토큰 = AI API 실사용 토큰 ÷ 10

AI API가 소비하는 토큰을 10으로 나눈 값이다. 10으로 나누면 사용자가 다루기 편한 숫자가 된다.

장면당 소모 토큰

항목	AI 토큰	Storida 토큰
이미지 생성 (Gemini)	~1,800	~180
작문 생성 (Claude)	~500~700	~50~70
장면당 합계	~2,500	~250

이 수치를 바탕으로 역산하면:

장면 수	토큰 소모
3장면 (최소)	750
5장면	1,250
10장면	2,500
20장면	5,000
30장면 (최대)	7,500

요금제 플랜 구성

	Start	Basic	Standard	Artist
가격	무료	9,900원/월	19,900원/월	39,900원/월
월 토큰	2,500	15,000	40,000	120,000
최대 장면	3 (고정)	10	20	30
3장면 기준	~3권	~20권	~53권	~160권
10장면 기준	—	~6권	~16권	~48권

설계 원칙

Start 플랜 = 체험: 2,500 토큰으로 3장면 3권(750 × 3 = 2,250) + 여유. 3장면 고정으로 과도한 토큰 소모 방지
Basic = 입문 유료: 10장면까지 허용, 6권 분량. 커스텀 캐릭터 개방
Standard = 주력: 20장면, PDF 다운로드, POD 신청 가능
Artist = 프로: 30장면, 커스텀 작문 스타일 개방

토큰 관리 정책

이월 없음

매월 구독 갱신 시 구독 토큰 잔액이 초기화된다. 미사용 토큰은 소멸한다.

구독 갱신 시 보유 토큰을 플랜의 월간 토큰으로 초기화하고, 다음 갱신일을 기록한다.

이월을 허용하면 토큰이 축적된다. 한꺼번에 소진되면 AI 비용이 급증한다. 월간 사용량을 예측 가능하게 유지하기 위해 이월을 차단했다.

단건 구매 토큰 — 영구 유효

구독 토큰이 부족할 때 추가로 구매하는 단건 토큰은 만료 없이 영구 유효하다.

사용자 테이블에는 두 종류의 토큰 잔액이 존재한다. 구독 토큰(매월 초기화)과 단건 구매 토큰(영구 유효)이다.

차감 순서

생성 시 단건 구매 토큰을 먼저 차감하고, 부족분은 구독 토큰에서 차감한다.

단건 구매 토큰을 먼저 소진한다. “돈을 주고 산 토큰이 먼저 사용된다”는 사용자 기대에 맞다. 구독 토큰은 어차피 매월 초기화된다. 단건 토큰을 아끼는 편이 사용자에게 유리하다.

DB 스키마

credit_logs — 모든 변동 추적

크레딧 이력은 모든 충전과 사용을 추적한다. 각 변동마다 유형(충전/사용), 출처, 변동량, 변동 후 잔액 스냅샷을 기록한다. 생성된 콘텐츠나 구매 건에 대한 참조도 선택적으로 포함된다.

source	type	발생 시점
`subscription_reset`	charge	매월 구독 갱신
`subscription_signup`	charge	신규 구독 가입
`addon_purchase`	charge	단건 토큰 구매
`book_generation`	usage	동화 생성
`admin_adjustment`	charge/usage	관리자 수동 조정

설계 결정: 잔액 스냅샷

balance_after와 addon_balance_after 필드는 변동 시점의 잔액 스냅샷이다. 이렇게 설계한 이유:

시계열 잔액 조회: 특정 시점의 잔액을 DB 한 번 조회로 확인 가능
불일치 감지: balance_after의 연속성으로 토큰 누락/이중 차감을 감지 가능
감사(audit): CS 문의 시 정확한 토큰 변동 이력 제공

비즈니스 로직: 생성 가능 여부 검증

// 검증 로직
// 1. 필요 토큰 = 장면당 토큰(250) × 장면 수
// 2. 보유 토큰 = 구독 잔여 + 추가 구매
// 3. 부족하면 부족량과 함께 에러 반환

부족 시 클라이언트에 부족량(shortfall)을 반환하여, 단건 구매 유도 팝업에서 정확한 필요 토큰 수를 표시한다.

토큰 선차감 전략

토큰은 생성 요청 시 즉시 차감한다. 생성 완료 후 차감하면, 요청과 완료 사이(2~4분)에 다른 요청이 같은 토큰을 사용하는 이중 소진 문제가 발생한다.

요청 시: 토큰 차감 → Job 등록 → 즉시 응답
생성 실패 시: 토큰 환불 (credit_logs에 refund 기록)

이 방식의 트레이드오프는 생성 실패 시 환불 로직이 필요하다는 점이지만, 이중 소진 방지가 더 중요하다.

결론

3장면은 750 토큰, 10장면은 2,500 토큰. 단순한 공식이 사용자의 비용 예측을 돕고, 서비스의 수익성을 보장한다.

다음 글은 Cloudflare R2 스토리지 마이그레이션과 Scheduler 모듈화 리팩토링을 다룬다.

멀티 캐릭터 시스템 — Claude Vision으로 이미지 일관성 확보하기

Wed, 18 Feb 2026 19:00:00 +0900

문제: 페이지마다 달라지는 캐릭터

1페이지에서 갈색 머리의 소녀가 3페이지에서 금발이 된다. 5페이지에서는 완전히 다른 사람이다. AI 이미지 생성의 고질적 문제다.

기존 시스템은 캐릭터 이미지를 “참조 이미지”로 전달했다. Gemini가 이미지에서 무엇을 봐야 하는지 가이드가 없었다.

해결 전략: 이미지 분석 → 텍스트 설명 → 프롬프트 주입

관리자 이미지 업로드 (최대 5장)
         │
         ▼
Claude Vision 분석 ──────▶ 구조화된 설명 (영문)
                           │
                           ▼
이미지 생성 시 프롬프트에 주입 ──▶ Gemini 이미지 생성

이미지를 텍스트로 변환한다. Claude Vision이 캐릭터 이미지를 분석하여 영문 설명을 생성한다. 이 설명을 Gemini 이미지 프롬프트에 주입한다.

DB 스키마 변경

characters 테이블

캐릭터 테이블에 분석 결과(한국어/영문 설명)를 JSONB로 저장하는 컬럼을 추가했다.

content_assets 테이블

콘텐츠-캐릭터 연결 테이블에 커스텀 이름과 주인공 여부 컬럼을 추가했다. 이 테이블이 콘텐츠와 캐릭터의 N:M 관계를 관리하며, 주인공/보조 캐릭터를 구분한다.

Claude Vision 분석 API

POST /api/assets/analyze
// 1~5장의 이미지 URL을 전달
// 한국어/영문 캐릭터 외형 설명을 반환

분석 프롬프트

Claude에게 캐릭터 이미지를 전달한다. 이미지 생성 AI가 일관되게 재현할 수 있는 시각적 특징을 추출하도록 지시한다.

분석 결과 예시:

{
  "description_ko": "갈색 곱슬머리의 소녀, 큰 갈색 눈,
    둥근 볼, 분홍색 원피스, 운동화 착용",
  "description_en": "A young girl with curly brown hair,
    large brown eyes, round cheeks, wearing a pink dress
    and sneakers, approximately 6-7 years old"
}

한국어 설명은 관리자가 확인·편집할 수 있고, 영문 설명은 Gemini 프롬프트에 직접 사용된다.

멀티 캐릭터 생성 요청

변경 전

단일 캐릭터 ID만 전달하는 방식이었다.

변경 후

최대 3개 캐릭터를 전달하며, 각 캐릭터에 커스텀 이름과 주인공 여부를 지정한다. Zod validation으로 정확히 1명의 주인공이 포함되어야 함을 검증한다. 1~3개 캐릭터 범위도 함께 검증한다.

Scheduler: 프롬프트에 캐릭터 정보 주입

텍스트 생성 (Claude)

작문 프롬프트 템플릿에 캐릭터 정보 변수를 추가했다.

### 주인공 캐릭터
- 이름: {{주인공_이름}}
- 종류: {{캐릭터_종류}}
- 외형: {{캐릭터_외형_설명}}

### 보조 캐릭터
{{보조_캐릭터_정보}}

{{캐릭터_외형_설명}}에 analysis_report.description_ko가, 보조 캐릭터 정보에 각 보조 캐릭터의 이름과 설명이 들어간다.

이미지 생성 (Gemini)

Main character: A young girl with curly brown hair,
  large brown eyes, round cheeks, wearing a pink dress
  and sneakers. Her name is "토토".

Supporting character: A small white rabbit with long ears
  and a blue ribbon. Name: "미미".

[참조 이미지 첨부]

Style: watercolor illustration, soft and gentle...

Scene: 토토와 미미가 숲 속에서 나비를 쫓아갔어요.

analysis_report.description_en이 텍스트로 주입된다. 이미지 AI가 매 페이지에서 동일한 시각적 특징을 재현한다. 참조 이미지만 전달할 때와 차이가 뚜렷하다.

Web UI: 멀티 선택 인터페이스

┌─────────┐  ┌─────────┐  ┌─────────┐
│ ★ 토토  │  │ ✓ 미미  │  │ ✓ 뭉치  │
│  (주인공) │  │  (보조)  │  │  (보조)  │
│ 노란 ring│  │ 파란 ring│  │ 파란 ring│
└─────────┘  └─────────┘  └─────────┘

첫 번째 선택 = 자동으로 주인공(★ + 노란색 ring)
추가 선택(최대 2개) = 보조 캐릭터(✓ + 파란색 ring)
토글 방식: 클릭으로 선택/해제

이미지 분석의 한계와 대응

Claude Vision 분석에는 한계가 있다.

추상적 캐릭터: 캐릭터가 실제 사물이 아닌 판타지 존재일 때 설명이 모호해짐
다중 이미지 불일치: 5장의 이미지가 서로 다른 앵글이나 스타일이면 통합 설명이 어려움
색상 정확도: 미묘한 색상 차이를 텍스트로 정확히 전달하기 어려움

분석 결과를 관리자가 편집할 수 있도록 Textarea를 제공한다. AI 분석은 초안이다. 관리자가 최종 검수한다.

성과

지표	개선 전	개선 후
캐릭터 일관성	페이지별 외모 변동 빈번	핵심 특징(머리색, 의상) 유지
캐릭터 수	1명만 가능	최대 3명
프롬프트 품질	참조 이미지만 전달	텍스트 설명 + 이미지 병행
관리자 작업	수동 특징 입력	AI 분석 + 편집

다음 글에서는 토큰 기반 요금제 시스템 설계를 다룬다.