Hampass 개발노트: 시험 학습 앱을 운영형 PWA로 다듬기

Hampass는 아마추어 무선기사 시험을 준비하는 사람을 위한 문제은행 기반 학습 앱입니다. 처음의 핵심은 3급 전화급 전파법규 기출문제를 모바일에서 빠르게 반복 학습하는 것이었고, 이후 1급 전 과목까지 지원하면서 앱의 범위가 시험 학습 플랫폼에 가까워졌습니다.

이 노트는 저장소의 README.md, CLAUDE.md, AGENTS.md, MIGRATION_V2_CHECKLIST.md를 기준으로 현재 구조와 개발 흐름을 다시 정리한 기록입니다. README.md는 v1.3.1 기준 설명이지만, 내부 작업 문서는 v1.4.0까지 반영되어 있어 최신 상태는 v1.4.0 기준으로 보는 것이 맞습니다.

왜 이 앱을 먼저 기록하는가

Hampass는 TechJuice Lab의 방향을 가장 잘 보여주는 첫 앱입니다. 취미 생활에서 실제로 막히는 문제를 발견하고, 작게 앱으로 풀어본 뒤, 사용자의 반응과 운영 이슈를 보면서 계속 다듬는 흐름이 모두 들어 있습니다.

처음에는 "문제를 더 편하게 풀 수 있으면 좋겠다"는 단순한 요구에서 출발했습니다. 하지만 개발을 진행할수록 좋은 학습 앱은 문제 개수보다 데이터 품질, 해설의 밀도, 틀린 문제로 다시 돌아오는 흐름, 검색으로 유입되는 사람에게 앱의 목적을 정확히 설명하는 구조가 더 중요하다는 쪽으로 판단이 바뀌었습니다.

제품의 핵심

Hampass의 목표는 단순히 문제를 보여주는 것이 아니라, 시험 직전까지 반복 가능한 학습 루프를 만드는 것입니다. 현재 앱은 로그인 없이 3급과 1급 기출문제를 풀 수 있는 모바일 우선 PWA로 구성되어 있습니다.

주요 학습 흐름은 네 가지입니다.

빈출 문제 집중: 빈출 14개와 비빈출 6개를 섞어 20문제를 구성합니다.
랜덤 모의고사: 실제 시험처럼 무작위 20문제를 풉니다.
카테고리별 학습: 주제별로 20문제씩 진행하며 진행률과 정답률을 추적합니다.
전체 문제 마스터: 전체 문제를 순차적으로 풀고 localStorage에 진도와 통계를 남깁니다.

문제은행 화면도 별도로 두었습니다. 3급은 /level/3/study, 1급은 /level/1/[subject]/study 구조로 접근하고, 문제를 풀지 않아도 전체 기출문제를 주제별로 확인할 수 있습니다.

데이터와 문제 품질

초기 릴리스는 3급 전파법규 558개 기출문제를 기반으로 시작했습니다. 이후 중복 문제 78개를 제거하면서 3급 데이터는 400문제 기준으로 정리되었고, 단순한 배열 데이터에서 학습에 필요한 메타데이터가 있는 구조로 옮겨갔습니다.

v2 데이터 마이그레이션에서 중요한 변화는 다음과 같습니다.

문제 수와 카테고리를 재정리했습니다.
frequency를 단순 숫자가 아니라 level, label, similarCount, similarQuestions를 가진 객체로 바꿨습니다.
해설 구조를 detailed, wrongAnswers, tips 중심으로 바꿨습니다.
questionType을 추가해 긍정형/부정형 문제를 구분했습니다.
빈출 레벨 배지, 부정형 문제 경고, 유사 문제 바로가기, 오답별 해설을 UI에 반영했습니다.

이 구조 덕분에 사용자는 정답만 확인하는 것이 아니라 왜 틀렸는지, 어떤 유사 문제와 연결되는지까지 학습할 수 있습니다.

1급 시험 통합

v1.3.0에서 1급 아마추어 무선기사 시험이 통합되었습니다. 1급은 전파법규, 통신보안, 전파공학, 무선통신술, 영어 다섯 과목으로 나뉘기 때문에 3급과 같은 단일 문제 풀이는 적합하지 않았습니다.

그래서 라우트와 저장 키를 등급/과목 단위로 분리했습니다.

3급: /level/3
1급: /level/1/[subject]
과목 코드: RR, CS, RE, WC, EN
퀴즈 세션: quizSession_L3, quizSession_L1_{subject}
Progressive 결과와 통계도 등급/과목별로 분리

1급 문제에는 수식, 모스부호, 이미지 문제가 포함되어 있습니다. 이를 위해 RichTextRenderer를 중심으로 KaTeX 수식 렌더링, 모스부호 시각 렌더링, 문제/보기 이미지 렌더링을 붙였습니다. 특히 전파공학 문제는 수식 가독성이 학습 경험에 직접 영향을 주기 때문에, 문제 데이터 구조와 렌더러를 함께 설계해야 했습니다.

아키텍처

Hampass는 Clean Architecture를 따릅니다. 도메인 계층은 Next.js나 React에 의존하지 않고, 문제 저장소 인터페이스와 use case를 중심으로 동작합니다.

핵심 구조는 다음과 같습니다.

domain: Question, QuizSession, Result, repository interface, use case
infrastructure: JSON 기반 문제 저장소 구현
presentation: React 컴포넌트와 훅
app: Next.js App Router 페이지와 API route
shared: 셔플, progressive storage, 과목 상수 같은 공용 유틸리티

3급과 1급 저장소도 분리했습니다.

JsonQuestionRepository: 3급 데이터
Level1SubjectRepository: 1급 과목별 데이터
Level1JsonQuestionRepository: 1급 전체 데이터

이 구조는 CQ맵을 만들 때도 참고 기준이 되었습니다. CQ맵의 계획서에서도 Hampass의 Clean Architecture와 Jest 설정, Telegram 제보 패턴을 재사용 대상으로 두고 있습니다.

구현하면서 중요하게 본 기준

Hampass에서 반복해서 확인한 기준은 세 가지입니다.

학습 흐름은 빨라야 합니다. 시험 준비 앱은 사용자가 길게 탐색하는 서비스가 아니라, 열자마자 문제를 풀고 바로 결과를 확인하는 도구에 가깝습니다.
데이터 변경은 추적 가능해야 합니다. 문제 수정, 해설 보강, 신고 반영이 누적될수록 "왜 이 답이 맞는가"를 설명할 수 있어야 합니다.
앱 구조는 다음 시험과 다음 과목을 받아들일 수 있어야 합니다. 3급 전파법규만 보던 구조가 1급 5개 과목으로 확장되면서, 등급/과목/문제 유형을 분리하는 설계가 필요해졌습니다.

이 기준 때문에 일부 기능은 더 천천히 만들고 있습니다. 예를 들어 사용자 계정, 학습 기록 동기화, 개인별 약점 분석은 매력적인 기능이지만, 지금은 문제 데이터와 해설 품질을 먼저 안정화하는 쪽이 더 중요합니다.

운영 기능

v1.3.1에서는 개발자 문의 기능이 추가되었습니다. /contact 페이지와 Telegram Bot API를 연결했고, Footer에도 문의 버튼을 두었습니다.

문제 오류 신고는 Google Sheets API로 수집합니다. 기기당 시간당 100회 제한을 두어 남용을 막고, 사용자 신고를 문제 데이터 개선 루프로 연결했습니다. v1.3.5에서는 사용자 이의제기 20건을 검토해 문제를 수정하고, 후원자 명단과 업데이트 히스토리도 정리했습니다.

이 앱에서 중요한 점은 "한 번 배포하고 끝나는 문제은행"이 아니라, 사용자가 신고하고 개발자가 검토해 데이터 정확도를 계속 올리는 운영형 앱이라는 점입니다.

SEO와 PWA

v1.4.0에서는 SEO와 PWA 기반을 크게 다듬었습니다.

3급과 1급을 모두 반영한 글로벌 metadata
페이지별 generateMetadata
Open Graph, Twitter, canonical URL
WebApplication과 BreadcrumbList JSON-LD
manifest.json
sitemap.ts, robots.ts
퀴즈 실행 페이지 noindex
/updates 페이지 sitemap 포함

퀴즈 페이지는 검색 결과에 노출될 필요가 없고, 문제은행과 앱 소개 페이지가 검색 유입에 더 적합합니다. 그래서 크롤링 제어를 명확히 나누었습니다.

검증과 남은 일

문서 기준으로 Hampass는 Jest와 React Testing Library를 사용합니다. README 기준 테스트는 73개, 13개 suite로 관리되고 있고, v2 마이그레이션 시점에는 41개 테스트가 통과한 기록이 남아 있습니다. 현재 문서에서는 npm run build, npm test, npm run lint, npm run test:coverage를 주요 검증 명령으로 둡니다.

앞으로의 개선 포인트는 명확합니다.

최신 README가 내부 문서의 v1.4.0 상태를 따라오도록 갱신
사용자 신고 기반 문제 수정 내역을 블로그 릴리즈 노트로 연결
1급 과목별 문제 품질과 이미지/수식 렌더링 QA 강화
Search Console, 네이버 서치어드바이저, 다음 검색등록 등 외부 검색 등록 마무리

다음에 남길 기록

다음 Hampass 노트에서는 기능 추가보다 운영 기록을 더 자세히 남기려고 합니다. 어떤 문제 신고가 들어왔고, 실제 데이터는 어떻게 바꿨는지, 1급 과목별 렌더링 이슈는 어떤 식으로 발견했는지, 검색 유입과 앱 설치 흐름은 얼마나 자연스러운지 같은 내용을 쌓아두면 이후 비슷한 학습 앱을 만들 때도 기준점이 됩니다.

또 하나 기록하고 싶은 주제는 "문제은행 앱의 신뢰도"입니다. 공부하는 사람에게는 보기 좋은 UI보다 정답과 해설의 신뢰가 훨씬 중요합니다. Hampass를 계속 운영하면서 이 신뢰를 개발 프로세스 안에 어떻게 넣을지 실험해볼 생각입니다.

Hampass는 "취미 앱"이지만 구현 관점에서는 데이터 품질, 학습 UX, 검색 노출, 운영 피드백 루프가 모두 들어간 꽤 실전적인 앱입니다. 이 블로그에서는 앞으로 Hampass를 기능 목록이 아니라 운영하며 계속 개선하는 학습 제품으로 기록하려고 합니다.