StudyCrew

나와 닮은 공부캐를 만나고, 나만의 공부법을 발견하는 서비스입니다. 서비스명은 StudyCrew, 캐릭터를 부르는 이름은 공부캐입니다. ‘내 공부캐 찾기’에서 첫 캐릭터를 만나고, 공부캐 도감·공부 스킬북·미션으로 이어집니다.

고등학생이 재미로 공부 캐릭터를 만나고 다양한 공부 스타일과 공부법을 탐색하는 웹앱입니다. 성격·능력·성적을 진단하거나 결과에 따라 공부 방법을 제한하지 않습니다. Next.js App Router, React, TypeScript, Vercel, Neon PostgreSQL을 사용합니다. 로그인 없이 테스트·결과·공부법 활동을 이용할 수 있습니다.

실행

Node.js 24 LTS를 권장합니다. Windows PowerShell에서 npm 실행 정책 오류가 나면 npm 대신 npm.cmd를 사용하세요.

npm.cmd ci
npm.cmd run dev

http://127.0.0.1:3000 에서 확인합니다. DB와 카카오 키가 없어도 검사·기기 저장·결과·공부법·링크 복사가 동작합니다. 이때 이용 통계는 저장하지 않으며 카카오 공유는 링크 복사를 안내합니다. 계정 도감 로그인·저장·추천 보상은 아래 서버 설정이 필요하며 미설정 상태에서는 준비 중으로 표시합니다.

구현한 기능

• 22문항(상황형 12: 네 방식 중 하나 고르기, 양극형 10: 두 문장 중 더 가까운 쪽 4단계), 문항별 이전/다음, 미응답 확인, 24시간 이어하기
• 검사 전에 서비스 취지·주의사항·기록 보관 방식을 안내하고 확인 동의 후 설문 시작. 동의 전에는 검사 시작 이벤트와 새 답변 기록을 저장하지 않으며, 새 검사에는 다시 동의 필요. 같은 탭에서 진행 중 검사를 새로고침하면 동의와 답변을 이어감
• 설문 화면은 공통 제목 글꼴·녹색 선택 상태로 통일. 모바일 세로 화면에서는 진행률·질문·이전/다음 버튼·인생교수의 AI 연구소 로고를 한 화면에 배치. 두 문장 비교 도움말은 첫 비교 문항에서 기본으로 펼쳐 표시. 선택지 기본 글자 크기 16px·줄간격 1.5를 유지하고, 작은 화면이나 글자 확대 시에는 질문 본문만 스크롤하여 이동 버튼과 로고를 계속 표시
• 모바일 설문 높이는 화면 높이 이내에서 최대 680px로 제한하고, 남는 공간은 선택지 영역에 분배해 질문 위아래에 큰 빈칸이 생기지 않도록 구성. 문항 전환 시 다음 버튼과 하단 로고의 위치를 유지. 모바일에만 카드 그림과 StudyCrew 글자 로고를 홈 링크로 표시하며, 설문 진행 중에는 공통 푸터를 숨기고 버튼 아래 작은 연구소 로고만 표시
• 16유형 계산(상황형 고른 횟수 + 양극형 합계), 근소한 차이 표시, 큰 유형 동점 시 대표 활동 직접 선택. 보조 축은 홀수 문항·홀수 점수라 동점이 생기지 않음
• 공부캐별 공부법 도구함: 캐릭터마다 이름 있는 공부법 4개(서로 다른 시그니처 1개 + 같은 방식 계열의 개념 이해·용어 암기·문제 풀이 공부법 3개)와 혼자/함께·계획/즉흥별 공부 팁 2개(러버덕 설명법·생각-짝-나누기·간격 반복 일정·누적 복습)
• 공부법 도감(/methods): 이름 있는 공부법 28가지를 과제별로 거르기, 공부법마다 근거 표시(근거 탄탄·근거 있음·정리 도구)와 담긴 원리 표시, 모든 공부캐의 기본기(인출 연습·간격 반복) 안내. 아직 만나지 않은 캐릭터의 시그니처는 이름 대신 방식만 표시
• 공부법마다 10분 실험 페이지(/methods/[공부법 ID]), 방식별 과제 탭 페이지(/methods/visual 등), 수준 맞추기 규칙, 함께하는 공부법의 혼자 버전
• 완료 후 4.4초 응답 분석 연출: 16개 유형 → 공부 방식 4개 → 집중 환경 2개 → 최종 유형 1개, 자동 결과 공개
• 질문 방향별 전환 모션, 유형 카드 등장, 모션 감소 설정 지원
• 유형별 공부 장면 공감 버튼, 공부 습관·막히는 지점·시험 전날 팁·유형 선정 이유
• 개인 결과와 공개 유형 소개 분리, 스타일 도감 필터
• 카카오 로그인으로 첫 캐릭터와 수집 도감 보존, 다른 기기에서 복원
• 캐릭터마다 이름 장식·배경·소품·성향 배지·시그니처 공부법이 완성된 16종 고정 카드에 실제 네 가지 응답 비율과 막대만 합성: 1080×1920 PNG 저장·파일 공유
• 카드 미리보기·저장에 동일한 서버 생성 PNG를 사용. 카카오톡 인앱 브라우저가 처리할 수 있도록 저장 링크는 blob: 대신 /api/result-card의 HTTP 첨부 응답을 사용하며, 별도의 이미지 열기 링크로 원본을 열어 저장 가능. 이미지 생성에는 캐릭터 코드와 네 가지 응답 횟수만 전달하고 계정 정보나 전체 응답은 전달하지 않음
• 로그인한 계정에 완료한 검사 답변·점수 보관, 도감의 검사 기록에서 재조회
• 추천 링크·코드로 친구의 첫 도감 등록 확인, 미보유 캐릭터 무작위 지급과 선물 개봉
• 최초 결과와 재검사 결과 분리, 재검사 캐릭터는 실루엣으로 표시
• 과제별 공부법 예시, 활동 선택·시작·시도 후 평가, 7일 기기 저장
• 링크 복사와 수동 복사 대안, 카카오톡 공유 연동
• 한국어 Open Graph 이미지, QR PNG 내려받기
• 학교 활용·학습 근거·저장 안내, 기기 기록 삭제 확인 팝업
• Neon 최소 통계 API, 중복 제거, 원본 보관 기간 종료 후 집계·삭제
• 자체 호스팅 Pretendard, Solar SVG 아이콘, 모바일·키보드·모션 감소 지원

Vercel + Neon 연결

완료 화면은 기존 점수 계산을 시각화한 연출입니다. 외부 AI API를 호출하거나 생성형 AI가 답변을 분석하지 않습니다. 유형별 설명은 src/lib/type-stories.ts에서 관리하며, 개인 결과에서는 실제 응답 합계와 동점 선택 여부를 함께 표시합니다. 공감 버튼은 해당 화면에서만 유지되고 검사 점수에 영향을 주지 않습니다.

1. .env.example을 .env.local로 복사하고 Neon의 연결 문자열을 DATABASE_URL에 입력합니다. 비밀 값은 Git에 올리지 마세요.
2. npm.cmd run db:migrate를 실행합니다. db/001_analytics.sql, db/002_retention.sql, db/003_collections.sql, db/004_saved_results.sql을 순서대로 적용합니다. Neon SQL Editor에서도 동일한 순서로 실행할 수 있습니다. 기존 계정이나 도감을 초기화하지 않는 추가 마이그레이션입니다.
3. Vercel에 저장소를 연결하고 프레임워크는 Next.js, Node 버전은 24를 선택합니다.
4. Vercel 환경변수에 DATABASE_URL, NEXT_PUBLIC_SITE_URL(운영 HTTPS 주소), CRON_SECRET(무작위 긴 문자열), NEXT_PUBLIC_CONTACT_EMAIL(공개 문의 주소)을 설정합니다.
5. 카카오 공유를 사용하려면 NEXT_PUBLIC_KAKAO_JS_KEY를 추가하고 카카오 Developers에서 JavaScript SDK 도메인과 제품 링크 도메인에 운영 주소를 등록합니다. 개발/미리보기 도메인을 사용할 때도 해당 설정을 확인합니다.
6. 환경변수 설정 후 배포합니다. 공개 변수는 빌드 시 적용되므로 바꾸면 재배포하세요.
7. 운영 도메인에서 QR과 공유 미리보기를 확인한 뒤 포스터에 사용합니다. 이미지 URL은 카카오 서버에서 로그인 없이 접근할 수 있어야 합니다.

카카오 로그인과 수집 도감

1. 카카오 Developers에서 같은 앱의 카카오 로그인을 활성화하고 REST API 키와 Client Secret을 서버 환경변수 KAKAO_REST_API_KEY, KAKAO_CLIENT_SECRET에 설정합니다. 브라우저용 NEXT_PUBLIC_KAKAO_JS_KEY와 혼동하지 마세요. 별도로 최소 32자의 무작위 서버 비밀키 AUTH_IDENTITY_HMAC_SECRET을 준비합니다. 이 키는 탈퇴 식별값 생성에 사용하므로 최초 설정 후 유지·백업하고, 임의로 교체하거나 NEXT_PUBLIC_ 환경변수에 넣지 마세요. 누락되면 로그인과 탈퇴는 제한 정책을 우회하지 않고 실패합니다.
2. 카카오 리다이렉트 URI에 NEXT_PUBLIC_SITE_URL + /api/auth/kakao/callback을 정확히 등록합니다. 로컬에서는 http://127.0.0.1:3000과 http://localhost:3000을 섞지 마세요. 운영 주소는 HTTPS를 사용합니다.
3. 로그인 동의항목에서 이름·이메일·프로필·친구 목록을 요구하지 않도록 설정합니다. 이 앱은 앱 회원번호만 저장하며 제공자 토큰을 보관하지 않습니다. 로그인 요청은 같은 출처 POST, 일회성 OAuth state와 브라우저 쿠키, 10분 유효기간으로 보호합니다.
4. /collection에서 첫 결과 저장, 다른 계정의 추천 가입, 선물 개봉, 같은 계정의 다른 브라우저 복원을 확인합니다. 카카오 전송 웹훅은 보상 조건이 아니므로 설정하지 않습니다.
5. Vercel Preview에서는 운영 DB와 분리된 Neon 브랜치·테스트 카카오 설정을 사용합니다. 외부 OAuth·실제 Neon 연결·카카오 인앱 브라우저 검증은 설정한 배포 환경에서 수행해야 합니다.

공식 사양: 카카오 로그인 REST API, 카카오 로그인 설정.

첫 캐릭터는 로그인 없이 공개합니다. 계정에 최초 등록한 결과는 고정되며 재검사는 캐릭터를 실루엣으로 가리고 유형과 공부법만 보여줍니다. 기기의 최초 결과와 최근 결과를 별도로 7일 보관하므로 재검사 후 로그인해도 최초 결과가 저장됩니다. 기존 유효한 로컬 결과는 최초 결과로 이관합니다. 비로그인 상태에서 기록을 지우면 과거 검사 여부는 알 수 없지만, 동일 계정의 추가 기본 지급은 서버에서 차단합니다.

/result는 로그인 상태에서 현재 계정 API로 확인한 결과만 표시하고, 비로그인 상태에서는 브라우저의 최초·최근 완료 결과를 표시합니다. 기본 선택은 완료 시각이 가장 최근인 결과이며 ?run=은 요청한 기록만 선택합니다. 진행 중인 재검사가 완료된 최초 결과를 가리지 않으며, 특정 기록 없음·계정 조회 실패·로그인 확인 실패를 구분해 안내합니다. 저장 충돌이 난 로컬 결과는 다른 계정 결과로 표시하지 않고, 나머지 정상 결과의 저장은 계속합니다. 과거 결과의 공부법 활동은 다른 로컬 검사의 활동 기록을 덮어쓰지 않습니다. 결과 상단에서 기록을 바꾸면 검사 유형·점수·공부법이 바뀌지만, 다운로드 카드는 최초 캐릭터와 최초 검사의 점수를 유지합니다. 재검사 화면에서도 상단의 카드 저장 바로가기로 미리보기와 PNG 다운로드를 이용할 수 있습니다. 로그인 사용자의 카드 원본은 현재 계정에서 확인한 결과만 사용하며, 도감 조회 실패만으로 다운로드를 숨기지 않습니다.

추천 코드는 10자리 공개 코드이며 인증 수단이 아닙니다. 공유 링크의 ref를 서버가 검증해 첫 유효 추천을 7일간 HttpOnly 쿠키와 연결합니다. 코드가 없으면 첫 등록 화면에서 직접 입력할 수 있습니다. 친구의 첫 검사 완료·카카오 로그인·첫 도감 등록을 모두 마쳤을 때 추천인에게 미보유 캐릭터 한 명을 지급합니다. 자기 추천, 등록 완료 계정, 같은 검사 ID 재사용, 요청 재전송은 보상을 늘리지 않습니다. 여러 카카오 계정이 실제 같은 사람인지까지 증명하는 본인인증 기능은 아닙니다.

register_collection DB 함수에서 계정 및 추천인 행 잠금, 최초 결과 설정, 추천 기록, 무작위 미보유 카드 지급을 하나의 트랜잭션으로 처리합니다. 개봉 전 보상도 이미 서버에서 확정되어 재접속이나 개봉 재시도로 바뀌지 않습니다. 16장 이후에는 추가 카드를 지급하지 않습니다. 개봉 API는 로그인한 계정의 선물만 처리합니다. 도감은 접속·창 복귀·로그인 중 30초 간격으로 갱신합니다.

계정 도감과 개인 검사 결과는 탈퇴 전까지 보관하며 기존 7일 통계 삭제 대상이 아닙니다. 로그인 세션은 30일, 초대 연결은 7일, OAuth 상태·등록 요청 제한은 10분 동안 유효합니다. 만료된 임시 값만 Cron으로 청소합니다. 로그인 후 유효한 로컬 첫 검사·최근 검사를 /api/results로 동기화합니다. 서버가 답변을 검증·재채점하고 계정에 답변·점수·유형·버전·시각을 보관하며 로그로 출력하지 않습니다. 동일 검사 ID는 다른 계정에 등록하거나 다른 답변으로 덮어쓸 수 없습니다. GET은 자신의 최근 100개 검사와 최초 도감 등록 검사를 반환합니다. 기기에만 남아 있다 만료된 옛 답변은 복구할 수 없습니다. 개인정보 안내의 브라우저 기록 삭제·로그아웃은 서버 결과를 유지하며, 계정 삭제는 도감·검사 답변·점수를 함께 삭제합니다. 계정 삭제 후에도 다른 이용자에게 이미 지급한 카드는 유지합니다. 앱 계정 삭제는 카카오 계정 자체의 삭제나 카카오 앱 연결 해제와는 별개입니다.

탈퇴 트랜잭션은 collection_withdrawals에 HMAC 식별값·탈퇴 시각·재가입 가능 시각만 남기고 계정을 삭제합니다. 같은 카카오 계정은 168시간 후에 새로 가입할 수 있습니다. 이 식별 기록은 서비스 운영 기간 동안 유지하며 일반 만료 정리에서 삭제하지 않습니다. 재가입 계정은 referral_eligible=false로 생성되므로 초대 코드를 직접 API로 보내도 초대받은 신규 사용자 보상은 양쪽 모두 지급되지 않습니다. 첫 캐릭터 저장과 진짜 신규 친구 초대는 가능합니다. 정책 적용 전에 이미 탈퇴한 사용자와 서로 다른 카카오 계정의 동일인 여부는 판별하지 못합니다.

적용 순서는 비밀키 설정 → npm run db:migrate로 005_account_lifecycle.sql 적용 → 애플리케이션 배포입니다. 마이그레이션은 기존 계정·도감과 탈퇴 식별 기록을 보존하며 재실행할 수 있습니다. 로그인과 탈퇴 함수는 동일 HMAC 식별값의 트랜잭션 잠금을 사용합니다. 키 교체가 필요하면 기존 식별 기록의 호환성 전략을 먼저 마련해야 합니다.

GET /api/auth/session은 도감 조회 없이 세션 상태만 확인합니다. 헤더와 도감은 공통 인증 상태를 사용하며, 로그아웃 성공 시 재조회 결과를 기다리지 않고 화면의 계정 데이터를 비웁니다. 카카오 로그인 시작은 JSON 요청에 authorizationUrl을 반환하고 기존 폼 요청에는 303 응답을 유지합니다. 매번 재인증하는 prompt=login은 보내지 않습니다. 최초 로그인 확인·이동·로그아웃에는 진행 표시와 10초 요청 제한이 있으며, 오류를 비로그인 성공으로 처리하지 않습니다. 30초 주기·탭 복귀 시 자동 확인은 이미 확인된 로그인/비로그인 화면과 버튼을 유지한 채 백그라운드에서 처리합니다. 이 자동 요청만 일시적으로 실패하면 기존 상태를 유지하고, 정상 응답으로 세션 만료가 확인되면 비로그인 상태를 반영합니다. 다른 탭의 계정 변경과 명시적인 인증 재확인은 기존 확인 절차를 유지합니다. auth_timing 로그는 고정된 단계 이름과 소요 시간만 남깁니다. 실제 카카오 인증, 카카오톡 내부 브라우저 전환, Neon 다중 연결 경쟁은 배포 전 별도 점검합니다.

vercel.json은 매일 UTC 18시(한국 시각 다음 날 03시)에 보관 기간 정리를 실행합니다. 요청에는 Vercel이 CRON_SECRET을 Bearer 토큰으로 전달합니다. 만료된 검사와 이벤트는 하나의 트랜잭션에서 익명 집계로 전환되고 삭제됩니다. 일일 실행으로 삭제까지 최대 약 하루가 더 걸릴 수 있습니다. 다른 호스팅을 사용하면 동일 엔드포인트를 인증해서 매일 호출하도록 예약하세요.

공개 전에는 운영 연락처·호스팅 로그 보관·서비스 제공 지역과 실제 처리 방침을 확인해야 합니다. API의 메모리 요청 제한은 프로세스 단위 보호입니다. 외부 공개 시 Vercel Firewall 등에서 전체 트래픽 한도와 비용 알림을 설정하세요. 실제 외부 계정 생성·Neon 연결·Vercel 배포는 로컬 구현과 별도입니다.

이용 통계

POST /api/events는 허용 목록에 있는 이벤트만 받습니다. 이름·학교·학년·문항 응답·점수·결과 유형·IP를 앱 통계 테이블에 저장하지 않습니다. 임시 검사 ID는 중복 제거와 7일 내 후속 평가 연결에 사용하며, 다음 검사에 재사용하지 않습니다. 별도의 영구 사용자 식별자는 없습니다.

• start, question(번호 1~16), complete
• share(copy/kakao), mission_select, mission_start
• feedback(helpful/mixed/not-yet): 같은 검사의 마지막 평가로 갱신

완료 이후의 공유·활동 이벤트만 기록합니다. DB가 없으면 204로 무시합니다. 통계 실패는 UI를 차단하지 않으며, 후속 행동에서 시작·완료 이벤트를 재시도할 수 있습니다. 영구 전송 큐는 두지 않으므로 네트워크 장애나 차단에 따른 누락이 가능합니다.

db/report.sql을 Neon SQL Editor에서 실행해 확인합니다. study_daily는 시작일 기준 7일 관찰이 끝난 코호트 집계입니다. share_any는 채널 중복을 제거한 공유 시도 검사 건수이고, last_question은 미완료 검사의 마지막 도달 문항입니다. helpful과 mixed를 더하면 실제 시도했다고 응답한 건수입니다. 비교할 분모는 같은 기간·버전·유입 조건의 시작 또는 완료 건수입니다.

완료 300건은 고유 학생 300명과 다릅니다. 공유 클릭은 실제 전송 완료를 뜻하지 않습니다. ‘해봤어요’ 응답이 없다는 이유로 미시도로 단정하지 않습니다. 원본은 약 7~8일, 일별 집계는 90일 기준으로 관리합니다. 호스팅 제공자의 접속 로그는 별도 정책을 따릅니다.

16명 캐릭터와 앞·뒷면 카드

ImageGen으로 제작한 투명 배경 캐릭터 16장을 public/characters/에 저장했습니다. 미공개 캐릭터는 번호·실루엣으로만 보여주며, 비로그인은 첫 캐릭터 미리보기만, 로그인 상태는 계정에 저장·개봉한 카드만 공개합니다. 카드를 누르면 소개가 있는 뒷면으로 뒤집힙니다. 터치·키보드와 동작 줄이기 설정을 지원하고, 숨긴 면은 포커스 대상에서 제외합니다. 재검사는 분석 단계부터 결과까지 캐릭터를 공개하지 않습니다.

16명 모두 Gemini Omni로 제작한 전용 8초 반복 영상을 표시합니다. 기존 15개는 10초 영상의 마지막 정지 구간을 잘라냈고, 모아·토리·바니의 반복 경계는 마지막 0.25~0.5초를 짧게 연결 보정했습니다. 멜로는 두 팔로 수정한 새 원본으로 8초 영상을 다시 제작했습니다. 기존 캐릭터와 소품을 참조해 개념 지도 살펴보기, 귀 기울이기, 종이·퍼즐 조작, 공부 리듬 신호 등 각자의 특성을 담았습니다. 저장된 MP4를 화면에 보이는 앞면에서만 무음 재생하며 별도 재생 버튼 없이 반복 재생하며, 동작 줄이기와 이미지 대체를 지원합니다. 재생 시 생성 API를 호출하지 않습니다. 미공개 실루엣은 영상 파일을 요청하지 않습니다. 멜로 이미지 수정 기록, 전체 동작 설계·프롬프트·비용·검사 기록을 함께 보관합니다. node scripts/preview-character-videos.mjs로 16명 전체를 검토할 로컬 HTML을 만들 수 있습니다.

/types/[typeCode]는 비로그인의 첫 결과 또는 계정에서 공개된 수집 카드에 해당할 때만 상세 내용을 보여줍니다. /share/[typeCode]는 친구가 공유한 한 명을 소개하며 방문만으로 도감에 추가하지 않습니다. 기존 ?from=share 링크도 유지합니다. 유형 메타데이터는 정체를 숨기고 공유 페이지는 해당 캐릭터의 OG 이미지를 사용합니다. 이는 스포일러 방지 UI이며 공개 이미지 파일의 인증 보호는 아닙니다. 기기 기록이 만료되어도 로그인한 계정의 도감은 유지됩니다.

이름·소개·공부 취향은 src/lib/characters.ts, 카드 UI는 src/components/character-card.tsx에 있습니다. 분석 과정과 공유 미리보기에도 해당 캐릭터가 표시됩니다. 도구와 원본 위치, 개별 프롬프트는 캐릭터 제작 기록에 정리했습니다. 기존 코드 기반 학습 도구 그림은 공부법 안내 화면에서 계속 사용합니다.

문항은 src/lib/content.ts, 공부법 28가지와 캐릭터별 라인업은 src/lib/methods.ts, 계산은 src/lib/scoring.ts, 저장 검증은 src/lib/storage.ts로 나뉩니다. 문항 설계 근거와 검증 계획은 로컬 설계 문서 ref/공부캐_검사지_v2.md(Git 추적 제외)에 있습니다. 문항 의미나 채점 규칙을 바꾸면 VERSION을 올려 이전 응답을 다른 문항으로 해석하지 않도록 합니다. 캐릭터별 공부법 설계와 공부법 선정 기준은 로컬 설계 문서 ref/공부캐별_공부법_라인업_제안.md(Git 추적 제외)에 있습니다. 공부법 내용만 바꿀 때는 VERSION을 올리지 않습니다. 활동 기록은 공부법 ID로 저장하며, 예전 방식·과제 기록도 같은 계열 공부법으로 읽습니다.

디자인 기준

내 공부캐 1명에 친구 초대로 15명을 더해 총 16종을 모으면 완성입니다. 화면 수집 수는 저장 전 첫 캐릭터 미리보기도 포함하며, 남은 초대 수에서는 이미 도착한 미개봉 선물을 제외합니다. 추가 초대 없이 선물을 모두 개봉하면 도감 마지막 행의 스페셜 단체사진 카드가 열립니다. 기존 캐릭터 모습을 참조해 제작한 16:9 사진이며 확대 보기와 PNG 저장을 지원합니다. 사진은 공개 정적 경로에 두지 않고 로그인한 계정의 개봉 완료 여부를 API에서 검증합니다. 기기 미리보기만으로 사진을 해금할 수는 없습니다. 단체사진 제작 기록과 프롬프트를 함께 보관합니다.

Supanova taste-skill과 soft-skill의 한국어 타이포그래피, 비대칭 구성, 카드의 깊이, 반응형 원칙을 적용했습니다. 사용자의 웹앱 요구에 맞춰 단일 HTML 출력 규칙은 Next.js 컴포넌트로 대체했습니다. 실제 자료가 없는 후기·사용자 수·긴급성 문구는 만들지 않았습니다.

크림색 배경·초록색 포인트·노란색 카드 표시를 사용하며, 겹쳐진 카드와 눌리는 버튼으로 캐릭터 카드 게임의 느낌을 담았습니다. 기존의 긴 소개 문구, 큰 빈 공간, 흐릿한 보조 문구를 줄이고 캐릭터 발견과 테스트 시작을 중심에 두었습니다. 홈·검사 시작 안내·결과·공유 화면에서 재미로 다양한 공부 스타일과 공부법을 탐색하는 목적을 안내합니다. 모바일에서도 목적 안내를 숨기지 않습니다.

아이콘은 Solar, 글꼴은 Pretendard를 자체 호스팅합니다. 글꼴 라이선스는 public/fonts/LICENSE.txt에 포함했습니다. Solar 아이콘은 CC BY 4.0 라이선스이며 Solar Icons에서 제공됩니다. node scripts/assets.mjs로 npm 패키지의 선별 아이콘과 글꼴 파일을 다시 준비할 수 있습니다. 카카오 로그인은 카카오 공식 디자인 리소스의 버튼 SVG를 public/kakao-login.svg로 저장해 사용합니다.

공부캐 굿즈

/goods에서 16명 × 8종(일상 3종·특별 의상 5종), 총 128장의 앞면과 고유한 뒷면 이야기를 볼 수 있습니다. 내 정보, 공부 스킬북의 지갑, 로그인한 수집노트에서 연결됩니다. 캐릭터·카드 종류·계정 도감의 보유 캐릭터 필터를 지원합니다.

일상 굿즈는 별 1개, 특별 의상은 별 2개로 직접 선택해 교환합니다. 계정 도감에 개봉한 캐릭터의 굿즈만 교환 가능하며, 중복 교환은 다시 차감하지 않습니다. /goods?view=owned에서 내 굿즈만 모아 볼 수 있고, 앞면·뒷면 각각 JPG 저장·이미지 열기·지원 기기에서 사진 공유를 제공합니다. 이미지 API는 매 요청마다 로그인과 해당 굿즈 소유권을 검사합니다.

db/008_goods_stars.sql은 스킬별 첫 10분 실천과 3개 설문 완료에 별 1개, 유형별 4명 개봉 완료에 최초 1회 별 3개를 지급합니다. 하루 단위 반복 보상은 없습니다. 이전 실천 완료 기록과 완성한 유형도 동일하게 한 번 소급 지급하며 기존 하트는 회수하지 않습니다. 카드·설치 하트 보상은 유지되고 이후 실천 보상만 별로 바뀝니다. 계정 행 잠금과 고유 원장 키로 중복·동시 차감을 방지하고, 별·굿즈 데이터는 계정 삭제에 함께 삭제됩니다. 배포 전에 npm run db:migrate를 실행합니다.

db/009_card_stars.sql은 새 카드 개봉 시 하트·시그니처 스킬과 함께 별 1~2개를 각각 같은 확률로 지급합니다. 첫 카드 저장과 초대받은 친구의 즉시 공개 보너스 카드도 포함합니다. 기존 미개봉 카드에는 개봉할 때 지급하며, 마이그레이션 전에 이미 개봉한 카드는 소급 지급하지 않습니다. 추첨 결과는 collection_cards.star_reward에 저장하고 카드별 고유 원장으로 중복 지급을 막습니다. 재개봉, 요청 재시도, 마이그레이션 재실행으로 추첨값이나 소비한 잔액이 초기화되지 않습니다. 유형 완성 별 3개는 별도로 유지됩니다. 새 코드를 배포하기 전에 마이그레이션을 적용해야 실제 별 보상이 지급됩니다.

공개 썸네일은 public/goods, 고해상도 이미지는 art/goods, 카드별 이야기는 src/lib/goods-catalog.json에 있습니다. 별 아이콘은 내장 ImageGen으로 제작했으며 프롬프트는 art/goods-star.json에 보관합니다.

디자인 원본을 보유한 작업 환경에서는 node scripts/prepare-goods.mjs로 ref/goods-collection의 승인본을 다시 준비할 수 있습니다. 일반 빌드에는 Git에 포함된 결과 파일만 필요합니다.

굿즈 검증

npx vitest run tests/unit/goods.test.ts와 로컬 서버에서 npx playwright test tests/e2e/goods.spec.ts를 실행합니다. 128장 구성·고유한 문구·이미지 파일, 로그인/비로그인 필터, 모바일·PC 팝업과 포커스 복귀를 확인합니다.

전체 검증

npm.cmd run typecheck
npm.cmd run lint
npm.cmd test
npm.cmd run build

브라우저 테스트는 서버를 실행한 상태에서 진행합니다.

npx.cmd playwright install chromium
npm.cmd run test:e2e

이미 설치한 Chrome을 사용할 경우 PowerShell에서 $env:PLAYWRIGHT_CHANNEL='chrome'을 설정해 테스트할 수 있습니다. PLAYWRIGHT_BASE_URL로 테스트 대상 주소를 바꿀 수 있습니다. 모바일 프로젝트는 iPhone 화면·터치 환경을 Chromium에서 에뮬레이션하므로 실제 iOS Safari 및 카카오 인앱 브라우저 확인은 별도로 필요합니다.

단위 테스트는 채점·기기 저장 검증·통계 입력을 검사합니다. PGlite의 PostgreSQL로 실제 스키마와 집계 함수를 실행해 중복 제거, 원본 삭제, 재실행 안전성과 미완료 문항 집계를 검증합니다. 계정 테스트는 실제 SQL과 API 핸들러로 최초 결과 고정, 추천 중복 방지, 16장 완성, 선물 소유권·재개봉, OAuth 상태·단회 사용, 로그아웃과 탈퇴를 확인합니다. 카카오 응답과 DB 연결 전송은 테스트 대역을 사용하며, 실제 Neon의 여러 연결 간 경쟁이나 외부 OAuth 연결 시험을 대체하지 않습니다.

브라우저 테스트는 데스크톱·모바일에서 재검사 실루엣, 도감 복원·개봉, 추천 주소 전달, 첫 결과 저장 재시도, 로그인 취소·DB 장애 시 검사 유지, 삭제 확인을 검증합니다. 이때 계정 API 응답은 테스트 대역을 사용하며 운영 서버에 테스트 계정을 만들지 않습니다.

교육 콘텐츠는 자체 제작 초안입니다. 학교 공개 전 학생·교사 파일럿으로 문항 이해도와 활동 실행 가능성을 검토하세요.