TAPLE Docs

custom-card-image-prd

6 min read

PRD: 주문형 커스텀 명함 이미지

  • 상태: In progress (2026-07-25)
  • 작성자: / 리뷰어:
  • 관련 문서: frontmatter related: 참조

1. 배경과 문제 정의

물리 NFC 카드를 커스텀 디자인(인쇄 시안)으로 주문하는 고객이 있다. 지금 디지털 명함은 색상 테마 5종만 지원해서, 물리 카드와 디지털 명함의 모습이 일치하지 않는다. 주문받은 디자인 이미지를 디지털 명함에도 그대로 보여줘야 한다.

2. 목표

  • 관리자가 NFC 카드 발행 시점에 커스텀 이미지(앞면·뒷면)를 카드에 등록할 수 있다. 발행 시점에는 아직 회원·명함 연결이 없으므로 이미지는 NFC 카드에 귀속된다.
  • 이미지가 등록된 카드를 명함에 연결한 유저는 명함 커스텀 시트의 색상 칩 맨 왼쪽에서 이미지 테마를 선택할 수 있다.
  • 이미지 테마 선택 시 내 명함·공개 명함 등 모든 뷰에서 명함이 등록 이미지(앞/뒷면)로 통째로 렌더된다. 프로필 텍스트·로고 오버레이 없음(이미지가 완성본).

3. 비목표

  • 유저 직접 이미지 업로드(추후), 관리자 웹 화면(당분간 API 운영), PDF 서버 파싱(관리자가 PNG/JPG 2장으로 변환해 업로드), OG/공유 미리보기 이미지 교체.

4. 정책·도메인 결정

  • 1인 1 NFC 카드 정책 전제 → “내 명함의 커스텀 이미지”는 연결된 카드 한 장으로 유일하게 결정된다. 이미지 선택에 카드 ID 참조 불필요.
  • 테마 선택 필드는 cardColorTheme → cardTheme으로 개명하고 CUSTOM_IMAGE 값을 추가한다. 색상과 이미지는 둘 다 “카드 면을 무엇으로 그리는가”의 답이라 한 축(단일 선택)이 정직한 모델. 클라이언트가 tapple-fe 하나뿐인 지금이 개명 비용 최저점.
  • cardTheme=CUSTOM_IMAGE인데 이미지가 없어진 경우(어드민 이미지 삭제·카드 연결 해제)는 기본 테마로 렌더 폴백만 하고 저장값은 유지 — 이미지가 복구되면 자동 복귀. 카드 분실(LOST)은 명함 연결이 유지되므로 이미지도 유지된다.
  • 이미지 존재 확인용 별도 API는 두지 않는다 — 명함 조회 응답의 customCardImage 필드(null 가능)로 대체.

5. 직무별 관점

직무핵심 관심사·제약관련 문서
기획물리 카드와 디지털 명함의 디자인 일치가 주문 상품의 가치
디자인이미지 칩 썸네일=앞면, 선택 UX는 기존 색상 칩과 동일
FEcardTheme 개명 전역 반영, 이미지 모드에서 “이미지 저장”은 원본 다운로드
BE공개 응답에 이미지 URL만 노출(내부 ID 금지), CUSTOM_IMAGE 저장 시 이미지 보유 검증business-card

6. 시스템 흐름과 API 연결

주문 접수 → NFC 발행(기존) → 어드민 화면(/admin)에서 이미지 2장 업로드·등록 → 배정·배송 → 유저 연결 → 칩 노출 → 유저 선택.

어드민 이미지 다이얼로그는 신용카드 규격(ISO ID-1, 85.60×53.98mm) 비율 미리보기·크롭(비율 고정)과 시안 PDF 다운로드를 제공한다 — 흰 A4 세로 1페이지에 앞면(위)·뒷면(아래)을 카드 비율로 크게 배치, 사용자가 받은 인쇄 시안 초안과 같은 모양, 도련 없음.

PDF는 서버가 요청 시마다 생성한다 (GET /v1/admin/nfc-cards/{cardId}/card-image/pdf). 외주 발주 산출물이라 브라우저·라이브러리 버전에 따라 달라지면 안 되고(재현성), PDF는 등록 이미지의 파생물이라 저장하지 않는다 — 이미지 교체 후 옛 PDF가 외주에 나가는 사고 경로를 차단. 발주 시점 스냅샷 보관은 “발주” 도메인이 생길 때 재검토.

API역할
PUT /v1/admin/nfc-cards/{cardId}/card-image발행된 카드에 앞/뒷면 이미지 등록·교체 (DELETE 동일 경로)
PATCH /v1/me/business-card/stylecardTheme(개명)에 CUSTOM_IMAGE 허용, 이미지 없으면 400
GET /v1/me/business-card · GET /v1/public/business-cards/{slug}customCardImage: { frontUrl, backUrl } | null 추가

계약 상세는 tapple-be openapi.yaml 참조.

7. 열린 질문

  • 유저 직접 업로드 개방 시 검수(부적절 이미지) 정책.
  • 물리 카드 재발급 시 이미지 이관 자동화(현재는 새 카드에 재등록).

8. 변경 이력

날짜변경 내용변경자
2026-07-25최초 작성AI
2026-07-25어드민 등록 화면·카드 규격 미리보기·PDF 다운로드 반영AI

Graph View

Backlinks