SAT 시험 대비 어휘장: 엄선 고난도 990 단어

이 프로젝트는 SAT 시험을 준비하는 한국인 수험생들을 위해 특별히 설계된 웹 기반 어휘 학습 애플리케이션입니다. 엄선된 고난도 990 단어를 효과적으로 학습하고 관리할 수 있도록 다양한 기능을 제공합니다.

✨ 주요 기능

• 워드카드 학습: 단어, 품사, 뜻을 플래시카드 형태로 학습합니다.
• AI 기반 예문 생성: Gemini API를 활용하여 학습 단어에 대한 SAT 수준의 예문과 클로즈(cloze) 문장을 생성합니다. (설정에서 API 키 필요)
• 강력한 SRS 시스템: 모르는 단어를 효율적으로 관리하고 SM-2-lite 알고리즘 기반의 반복 학습 스케줄링을 통해 장기 기억을 돕습니다.
• 무작위 테스트: 객관식 또는 주관식 형태로 단어 테스트를 진행하여 학습 효과를 측정합니다.
• 학습 진척도 추적: 학습한 단어, 아는 단어, 오답 단어를 기록하고 통계를 제공합니다.
• 사용자 정의 단어장 가져오기: JSON, CSV, TXT 파일을 통해 자신만의 단어장을 앱으로 불러올 수 있습니다. 특히 CSV 가져오기 기능은 RFC4180 표준을 부분적으로 준수하며, 따옴표 처리, 이스케이프된 따옴표, 필드 내 개행 등을 지원하여 견고하게 작동합니다.
• 범위 학습: 특정 범위의 단어만 선택하여 집중적으로 학습할 수 있습니다.
• 모바일 친화적 UI/UX: 스와이프 제스처, 한 손 모드 등 모바일 환경에 최적화된 사용자 경험을 제공합니다.
• TTS (Text-to-Speech): 단어의 정확한 발음을 들을 수 있습니다.
• 무작위/순차 학습: 학습 순서를 무작위 또는 순차적으로 선택할 수 있습니다.

💡 사용 방법

1. 앱 접속:
2. 학습 시작: "학습 (워드카드)" 탭에서 단어를 학습하고, "테스트 (무작위)" 탭에서 실력을 점검하세요.
3. 단어 찾아보기: "찾아보기" 탭에서 전체 단어 목록을 확인하고 검색할 수 있습니다.
4. 사용자 단어 가져오기:
   • "찾아보기" 탭에서 "가져오기" 버튼을 클릭합니다.
   • JSON, CSV, TXT 형식의 파일을 선택합니다.
   • CSV 파일의 경우: id,word,pos,meaning 헤더를 권장합니다. 헤더가 없으면 첫 행부터 데이터로 간주합니다. 따옴표로 감싸진 필드 내 쉼표나 개행도 지원합니다. 가져오기 실패 시 상세한 오류 메시지가 제공됩니다.
   • 가져오기가 완료되면 "사용자 단어장"을 선택하여 가져온 단어들을 학습할 수 있습니다.
5. AI 예문 생성: "설정" 탭에서 Gemini API Key를 입력한 후, 워드카드 학습 중 "예문 생성" 버튼을 클릭하여 AI 기반 예문을 활용할 수 있습니다.

⚙️ 개발 환경 설정

이 프로젝트는 일관된 코드 품질과 개발 환경을 유지하기 위해 다음과 같은 규칙과 도구를 사용합니다.

인코딩 및 파일 형식

• 모든 소스 파일은 UTF-8 without BOM으로 인코딩되어야 하며, LF (Line Feed) 줄바꿈을 사용합니다.
• .editorconfig, .gitattributes, .prettierrc 파일이 이 규칙을 강제합니다.
• 기존 파일에 BOM이 포함되어 있다면, npm run remove-bom 스크립트를 실행하여 제거할 수 있습니다.

코드 품질 및 스타일

• ESLint: 코드의 잠재적 오류를 감지하고 코딩 표준을 준수하도록 돕습니다. 특히 unicode-bom 규칙을 통해 BOM 사용을 금지합니다.
• Prettier: 코드 포맷팅을 자동으로 처리하여 일관된 코드 스타일을 유지합니다.

Git Hooks

• husky를 사용하여 pre-commit 훅을 설정했습니다.
• 커밋 전에 npm run fix:bom, prettier --write ., npm run check:bom 스크립트가 자동으로 실행되어 BOM을 제거하고, 코드 포맷팅을 적용하며, BOM 존재 여부를 검증합니다.

💾 데이터 관리 및 마이그레이션

deckId 정책

• 학습 데이터(Unknown 단어 및 SRS 진행도)는 deckId를 기준으로 로컬 스토리지에 저장됩니다.
• deckId는 단어 목록의 콘텐츠 해시를 기반으로 동적으로 생성됩니다. 이는 단어 목록이 변경될 때만 deckId가 변경되어, 앱 업데이트 시 불필요한 데이터 손실을 방지합니다.
• REACT_APP_DECK_ID_OVERRIDE 환경 변수를 통해 deckId를 수동으로 오버라이드할 수 있습니다 (특수 개발/테스트 목적).

레거시 데이터 마이그레이션

• 이전 버전의 deckId(sat990-v2025-10-30)로 저장된 데이터 및 sat_vocab_unknown_v1, satVocabHelper와 같은 레거시 포맷의 데이터는 앱 초기 로드 시 자동으로 새로운 deckId로 마이그레이션됩니다.
• 마이그레이션은 기존 데이터를 복사한 후 원본을 삭제하는 방식으로 이루어져 안전합니다.

📄 라이선스

© 2025 ARP. 이 소프트웨어는 ARP의 소유이며, 모든 권리는 ARP에 있습니다. 무단 복제 및 배포를 금합니다.