시나브로

글귀를 Unsplash 사진 위에 올려 SNS용 PNG 카드(1:1, 4:5, 9:16)로 저장하는 정적 웹앱입니다. HTML + CSS + 바닐라 JS(빌드 도구 없음)와 Vercel /api 서버리스 함수로 만들었습니다. 자세한 설계는 quote-card-generator-spec.md를 보세요.

주요 기능

• 배경 검색: 키워드 입력(Enter·버튼)과 추천 칩, 방향·색상 필터, 더 보기
• 글귀 입력: 본문 200자, 출처 30자. 가을 글귀 20선을 눌러 채우면 어울리는 배경을 함께 검색
• 스타일: 글꼴 4종, 크기, 줄 간격, 정렬, 글자색 프리셋, 어두운 오버레이(0~80%)
• 위치 조절: 캔버스 드래그, 상·중·하 프리셋, 방향 버튼, 캔버스 포커스 후 방향키
• 규격 선택·PNG 저장: 1080×1080, 1080×1350, 1080×1920. 사진가 크레딧을 화면(UTM 링크)과 PNG 하단에 표시
• 오늘의 문구: 긍정적인 창작 문구 16개 중 하나와 어울리는 랜덤 사진을 한 번에 보여줌 (첫 방문 시 자동 실행)
• 임시저장(하트): 미리보기 사진 우측 상단의 연한 하트를 누르면 현재 카드(사진·글귀·스타일)를 한 번에 저장. 저장 탭의 목록에서 불러오기·PNG 저장·삭제 (최대 20개, 이 브라우저에만 보관)
• 화면 테마: 자동(기기 설정) / 밝게 / 어둡게 중 선택
• 초안 자동 저장: localStorage에 저장하고 새로고침 후 복원, ?text=...&author=...로 글귀 채우기

실행 방법

1. Unsplash Developers에서 앱을 등록하고 Access Key를 발급받습니다.

2. .env.example을 .env.local로 복사하고 UNSPLASH_ACCESS_KEY를 채웁니다. (커밋 금지)

3. 의존성 설치:

   npm install
   

4. 아래 중 하나로 실행합니다.

   # A. Vercel CLI (배포 환경과 가장 비슷함)
   npm i -g vercel
   vercel dev
   
   # B. Vercel CLI 없이 로컬 서버로 실행 (기본 포트 3333, PORT 환경변수로 변경)
   npm run dev:local
   

5. 브라우저에서 http://localhost:3333(B 기준)을 엽니다. /api/health가 {"status":"ok","unsplashKeyConfigured":true}를 돌려주면 키가 잘 들어간 것입니다.

index.html을 파일로 직접 열면 /api 함수가 없어 검색이 동작하지 않습니다. 반드시 위 방법으로 여세요.

이번 작업 내용

1. 명세서 기반 MVP 구현
   • 서버: /api/search(Zod 검증, content_filter=high, 응답 캐시, 한도 헤더 전달), /api/track-download(허용 주소 검사 후 호출), /api/health
   • 화면: 모바일 우선 한 화면(미리보기 + 배경·글·스타일·저장 탭), 데스크톱은 2열, 라이트·다크 지원
   • 렌더: 미리보기와 저장이 같은 renderCard()를 사용하고, 직접 만든 줄바꿈과 폰트 로드 후 재렌더 적용
2. 가을 글귀 20선·추천 키워드 칩 추가 (js/quotes.js): 의미가 나뉘는 지점에 줄바꿈을 미리 넣음
3. 로컬 실행 서버 추가 (dev-server.mjs): Vercel CLI 설치·로그인 없이 같은 /api 함수를 3333 포트에서 실행
4. 사진 개별 링크 표기 시도 후 되돌림: 필요 없다고 판단해 관련 변경을 모두 원복
5. 2차 수정
   • 앱 이름을 "글귀 카드 메이커"에서 시나브로로 변경 (utm_source 기본값도 sinabro)
   • 화면 테마 전환(자동·밝게·어둡게) 추가, 선택은 localStorage에 기억
   • 오늘의 문구 추가: api/random.js(/photos/random, 캐시 없음)와 TODAY_QUOTES
   • 미리보기 우측 상단 하트 임시저장과 저장 탭 목록 추가
   • 검색·랜덤이 같은 사진 변환 함수(mapPhoto)를 쓰도록 api/_lib.js로 정리
6. 로고·파비콘 적용: assets/logo.png(32×32)를 브라우저 탭 아이콘과 헤더의 "시나브로" 옆 로고로 사용. 로컬 서버가 assets/를 서빙하도록 허용 목록에 추가

오류·검증 기록

이번 작업에서 실제 동작 중 발견해 고친 버그는 없습니다. 다음은 확인한 내용과 남은 확인 항목입니다.

• 확인함
  • 서버 함수: 가짜 Unsplash 응답으로 검색·다운로드 추적·오류 코드(400·405) 동작과 키 비노출을 시험
  • downloadLocation 조작 주소 4종이 모두 400이고 Unsplash 호출이 나가지 않음 (SSRF 방어)
  • 줄바꿈 함수, ixid를 유지하는 배경 URL 조작, 위치 제한을 단독 시험
  • 실제 키로 /api/search 검색 성공, 화면에서 배경·글귀·글꼴·크레딧 표시 확인
  • PNG 저장 성공: 저장된 파일이 1080×1350(4:5), 1080×1080(1:1)으로 선택 규격과 정확히 일치. 이미지 CDN CORS 문제 없음
  • 오늘의 문구(/api/random): 실제 키로 사진이 반환되고 호출마다 다른 사진이 나오며, 잘못된 입력은 400으로 거절됨
  • 화면에서 로고·파비콘, 오늘의 문구 버튼, 테마 선택, 미리보기 우측 상단 하트가 표시됨
• 아직 확인하지 않음
  • 하트 임시저장 목록의 불러오기·PNG 저장·삭제, 어두운 테마에서의 로고 가시성
  • 9:16(1080×1920) 저장 파일의 크기
  • 다운로드 추적이 사진당 1회만 나가는지, 모바일(375px) 레이아웃과 터치 드래그
  • 한도 초과 시 Unsplash가 돌려주는 상태 코드
• 검색 응답에 links.download_location이 실제로 포함되는 것을 확인했습니다(https://api.unsplash.com/photos/<id>/download?...). 값이 비어 있으면 추적 호출을 건너뜁니다.

구조

api/          search · random · track-download · health (Access Key는 여기서만 사용)
js/           app · state · api-client · renderer · fonts · export · quotes
assets/       로고·파비콘 (logo.png)
docs/         README 스크린샷
dev-server.mjs  Vercel CLI 없이 쓰는 로컬 서버
index.html, styles.css

• 글꼴은 Pretendard(jsDelivr)와 Google Fonts(Noto Serif KR, Nanum Myeongjo, Nanum Pen Script)를 CDN으로 불러옵니다.
• 가을 글귀는 앱을 위해 만든 창작 문구이며 유명인의 인용이 아닙니다.

알아둘 점

• 검색은 content_filter=high로 고정하지만, 부적절한 사진을 완전히 막지는 못합니다.
• 데모 모드 한도는 시간당 50회입니다. 공개 전에 Unsplash Production 승인을 신청하세요.
• 비영어 검색은 Unsplash에서 베타 기능이라 한국어 검색 결과가 부실할 수 있습니다.
• 키가 한 번이라도 커밋되면 즉시 Unsplash 앱 설정에서 재발급하고 Vercel 값을 교체하세요.