jp-vocab-reader

일본어 원서/웹소설 학습자를 위한 자동 단어장 생성 웹서비스입니다.

현재 상태와 작업 인계

2026-10-07 기준, 0fb5a0f까지 홈·읽기·복습·단어·덱·학습 계획·통계의 7개 탭 리디자인과 로컬 안정화가 반영되었습니다. 분류 전용 탭은 학습 계획 탭으로 대체되었습니다.

• 현재 구현·검증·남은 위험
• 다음 작업 로드맵
• 학습 계획의 진도·저장·실행 계약
• 클로드·코덱스 공통 작업 인계
• 보존 중인 에셋·QA 자료 정리 후보

이 날짜와 커밋은 문서 작성 기준입니다. 작업을 시작할 때 현재 브랜치와 변경 상태를 다시 확인하세요. 과거 시안·게이트 자료가 로컬에만 있으면 클라우드 작업에서는 보이지 않습니다.

Recommended Production Deployment

• Frontend: Vercel
• Backend: Render
• Database: Neon PostgreSQL

Use the hosting provider environment variable UI for production settings. NEXT_PUBLIC_API_BASE_URL must be the https:// Render backend URL, and CORS_ORIGINS or CORS_ALLOW_ORIGINS must include the Vercel frontend origin with https://. Do not commit .env files or document real DATABASE_URL, JWT_SECRET_KEY, API keys, or service URLs.

Dictionary Data

• Built-in Korean meanings and user-defined terms are checked before JMdict fallback data.
• The committed backend/data/dictionary/jmdict_sample.json is for development and tests.
• The committed backend/data/dictionary/en_ko_sample.json is a small English-to-Korean fallback sample.
• A full local JMdict file can be placed at backend/data/dictionary/jmdict_full.json; it is ignored by Git and should not be committed.
• A full Kaikki/Wiktionary English-to-Korean subset can be built as backend/data/dictionary/en_ko_full.json; it is ignored by Git and should not be committed.
• In production, Render can also download en_ko_full.json (or .gz/.zip) automatically at startup via EN_KO_DICTIONARY_URL, the same way JMDICT_FULL_JSON_URL works for JMdict.
• meaning_ko is limited to 1-3 short, clean Korean candidates; archaic/broken forms are filtered out.
• An optional krdict (한국어기초사전/우리말샘-style) reverse index (backend/data/dictionary/krdict_reverse_sample.json, optionally krdict_reverse_full.json) can boost/rank the Kaikki-based candidates. It is auxiliary-only, built and loaded from a local file with no runtime API calls, and krdict_reverse_full.json is not committed.
• Dictionary data remains file-based. PostgreSQL stores user data, not the full JMdict, Kaikki/Wiktionary, or krdict datasets.

See docs/dictionary-data.md for supported JSON formats, validation scripts, production placement options, and source notice requirements.

단어장 탭 UI

• 단어장 탭 상단은 덱 선택, 검색, 상태 필터, 복습 대상 필터, 정렬, 단어 직접 추가만 기본으로 보여주는 compact toolbar로 정리했습니다.
• 덱 만들기/삭제, 덱 공유 JSON 내보내기/가져오기, CSV 다운로드, 사용자 정의 용어 관리는 덱/공유 관리 접이식 메뉴 안에서 사용합니다.
• CSV는 엑셀 확인용이고, 앱 간 덱 이동은 덱 공유 JSON 파일을 사용합니다.

덱 공유 패키지

• 단어장 탭에서 선택한 덱을 jp_vocab_reader_deck JSON 패키지로 내보내고, 다른 사용자가 같은 JSON을 가져와 새 개인 덱으로 복사할 수 있습니다.
• 덱 공유 파일은 이 앱에서 다시 가져오기 위한 JSON이며, CSV 다운로드는 엑셀 확인용으로 별도로 유지됩니다.
• 공유 패키지에는 덱 이름/설명, 단어, 해당 덱 전용 사용자 정의 용어가 포함됩니다.
• 개인 학습 기록인 status, correct_count, wrong_count, review_level, next_review_at, last_reviewed_at, 내부 id, deck_id, 생성/수정 시각은 포함하지 않습니다.
• 가져오기 시 새 개인 덱이 생성되고, 이름이 겹치면 덱 이름 (가져옴), 덱 이름 (가져옴 2)처럼 중복되지 않게 저장됩니다.
• 가져온 단어의 학습 상태는 unknown, 맞음/틀림 횟수와 복습 레벨은 0, 복습 날짜는 비어 있는 상태로 시작합니다.

서비스형 구조와 기준 문서

여러 사용자가 각자의 덱, 단어장, 사용자 정의 용어, 학습 기록을 분리해 쓰고 공개 덱을 공유/가져오기 할 수 있는 서비스형 구조를 사용한다. docs/service-architecture.md는 이 전환의 **초기 설계 초안(historical)**이며, 이후 실제로 바뀐 부분과 어긋나는 서술이 남아 있다. 현재 기준 문서는 용도별로 다음을 참고한다: 공유덱 lexeme/subscription 정책은 docs/architecture/shared-lexeme-progress-storage.md, 베타/릴리스 점검 항목은 docs/beta-release-checklist.md. 백엔드 DB 접근 로직은 backend/app/repositories의 기능별 repository로 1차 분리했다. 백엔드는 회원가입/로그인 API와 JWT access token을 지원한다. 개발 모드에서는 토큰이 없는 요청이 기존처럼 [email protected] 사용자로 fallback한다. 운영 환경에서 익명 요청의 권한은 별도로 확인해야 하며, 개발 fallback을 운영 정책으로 간주하지 않는다. 토큰을 보내면 해당 사용자 기준으로 개인 덱, 단어장, 사용자 정의 용어를 조회/수정한다. 프론트엔드는 상단 계정 영역에서 로그인/회원가입/로그아웃을 제공하고, 로그인 성공 시 access token만 localStorage에 저장해 이후 API 요청에 사용한다. 저장된 토큰이 만료되었거나 잘못되면 프론트엔드는 현재 토큰에 해당하는 만료 응답인지 확인하고 계정 경계를 초기화한다. 이전 계정의 늦은 조회 응답은 버리고, 복습 세션과 덱 선택도 즉시 비운다. 개발 환경에서는 개발 사용자 데이터를 다시 불러온다. 읽기 원문의 기기 저장은 아직 계정별로 분리되지 않았다.

기본 사용 흐름

1. 홈에서 읽기를 열고, 저장할 덱과 일본어 원문을 선택해 분석합니다.
2. 원문 속 단어를 눌러 한국어 뜻을 확인하고 아는/헷갈림/모름/미분류 상태를 바꿉니다.
3. 모름·헷갈림으로 바꾼 새 단어는 자동 저장됩니다. 필요한 단어는 어휘 노트 담기와 선택 저장으로 따로 모을 수도 있습니다.
4. 단어 탭에서 덱별 검색·필터·수정·파일 내보내기를 하고, 덱 탭에서 공개 덱을 찾아 구독합니다.
5. 학습 계획에서 덱 → 기간 → 하루 신규 단어 권장량을 정해 저장하고 복습으로 이어갑니다.
6. 복습에서 답을 확인한 뒤 다시/어려움/보통/쉬움으로 평가하고, 통계에서 날짜별 기록과 어휘 현황을 확인합니다.

모바일 레이아웃

• 모바일은 홈 2+2+2 파일 트레이, 읽기 종이 지면과 하단 단어창, 복습 지면, 덱 목록 → 상세 → 뒤로 흐름처럼 화면에 맞는 구성을 사용합니다.
• 긴 일본어 단어, 원문, 예문, 공유 덱 설명은 화면 밖으로 넘치지 않도록 줄바꿈과 가로 스크롤 동작을 보강했습니다.

목표

• 일본어 원문 붙여넣기
• 형태소 분석으로 단어 추출
• 중복 단어 제거
• 읽기, 기본형, 품사 표시
• 한국어 뜻 표시
• 원문을 읽으면서 단어 분류
• 아는 단어 / 헷갈리는 단어 / 모르는 단어 / 미분류 상태 관리
• 분류한 단어 저장
• 작품/책/챕터별 덱 관리
• 사용자 정의 용어 사전
• 단어 직접 추가/수정
• 자체 플래시카드 학습 모드
• 복습 스케줄
• 학습 통계와 덱별 진도 표시
• 서울 날짜 기준 학습 기록과 캘린더
• 계정별 기기 저장 학습 계획과 첫 학습 진도
• CSV 내보내기

기술 스택

• Frontend: Next.js
• Backend: FastAPI
• Tokenizer: SudachiPy
• Database: SQLite for local development, PostgreSQL for deployment/production

Backend 실행

cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
$env:DATABASE_URL = "sqlite:///./qa_local_session.db"
$env:APP_ENV = "development"
uvicorn app.main:app --reload

위 환경변수 두 줄은 PowerShell 예시입니다. 로컬 검증에서는 .env에 남은 연결값을 믿지 말고 세션 전용 SQLite를 명시하세요. 로컬에서 Neon/운영 DB에 접근하지 않습니다. 생성한 임시 DB는 서버 종료 후 정리합니다. 데이터 보존이 필요한 개발 DB는 별도로 지정합니다.

Production backend start command, run from backend:

uvicorn app.main:app --host 0.0.0.0 --port $PORT

Before deployment, set environment variables from backend/.env.example in the hosting platform. Do not commit real .env files. See docs/production-deployment.md for production setup details.

This is the beginning of the README. Read the rest at the original. Read the full README ↗