사무엘학교 사이트

사무엘 학교 과정별 성경 구절을 퀴즈, 오답노트, 복습, 학습계획으로 반복 암송할 수 있도록 만든 프론트엔드/백엔드 분리형 웹 서비스입니다.
단순 열람형 학습이 아니라, 문제 풀이와 복습 루프를 중심으로 학습자가 스스로 암송을 반복할 수 있도록 설계했습니다.

1. 프로젝트 소개

사무엘학교 사이트는 성경 암송 학습을 보다 체계적으로 돕기 위해 제작한 웹서비스입니다.
학습자는 단순히 구절을 읽는 데서 끝나지 않고,

다양한 퀴즈 모드로 문제를 풀고
틀린 문제를 오답노트에 저장하고
오답만 다시 복습하고
D-Day 학습계획을 세우고
랭킹과 통계를 통해 학습 흐름을 확인할 수 있습니다.

또한 관리자용 운영 화면도 포함되어 있어, 랭킹 권한 승인, 방문 통계 확인, 사용자 관리 등 서비스 운영 기능까지 함께 제공하는 구조입니다.

주요 사용자

사무엘 학교 학습자: 성경 구절 암송, 복습, 오답 관리, 학습계획 활용
관리자: 랭킹 권한 승인, 방문 통계 확인, 사용자 관리, 관리자 전용 기능 운영

2. 개발 배경

기존 성경 암송 학습은 구절을 반복해서 읽거나 수동으로 점검하는 방식이 많아, 학습자가 자신의 취약 구절을 체계적으로 관리하기 어렵다는 한계가 있었습니다.

이 프로젝트는 다음 문제를 해결하기 위해 시작되었습니다.

성경 암송 학습을 문제 풀이 중심으로 바꾸고 싶었다.
틀린 구절을 자동으로 저장하고, 오답 위주로 복습할 수 있게 만들고 싶었다.
시험일까지 남은 기간에 맞춰 학습계획을 자동으로 분배하고 싶었다.
암송 학습의 동기 유지를 위해 랭킹, 학습통계, 캘린더 기능을 함께 제공하고 싶었다.
학습자용 기능뿐 아니라 운영자 관점의 관리자 화면도 포함한 서비스 구조를 만들고 싶었다.

3. 주요 기능

3-1. 사용자 인증 및 계정 기능

회원가입
로그인 / 로그아웃
JWT 기반 사용자 인증
닉네임 변경
랭킹 조회 권한 요청 및 관리자 승인

3-2. 5가지 학습 모드

학습자는 성경 구절을 여러 방식으로 반복 학습할 수 있습니다.

전체 구절 쓰기
빈칸 채우기
키워드 모드
주제 모드
훈련 모드(플래시카드)

또한,

1~4과정 선택
시험일 1~4일차 / 전체 범위 필터링
빈칸 모드 난이도 1~4 조절

이 가능하도록 구성했습니다.

3-3. 정답 채점 및 피드백

공백 및 문장부호를 정규화해 정답을 비교합니다.
문자 단위 차이를 분석해 오답 위치를 피드백으로 보여줍니다.
빈칸 모드에서는 난이도에 따라 구절 주소 숫자까지 빈칸 처리할 수 있습니다.

3-4. 오답노트

오답 시 자동으로 오답노트에 저장
즐겨찾기 설정
메모 작성
과정별 필터링
일괄 삭제
오답 구절만 다시 시험 보기
오답 구절만 훈련 모드로 이동

3-5. 훈련 모드

플래시카드 방식으로 반복 학습 가능
진행 위치 저장
헷갈리는 카드 수동 오답노트 추가

3-6. D-Day 학습계획

시험일 기준 학습계획 생성
오늘의 목표 자동 분배
암송 완료 체크
완료 이력 조회

3-7. 랭킹 및 통계

월간 / 누적 랭킹
점수 랭킹 / 학습시간 랭킹
랭킹 조회 권한 요청 기능
마이페이지에서 일별 학습 통계 그래프 제공
월별 학습 캘린더 확인

3-8. 문의 기능

문의 등록
내 문의 확인
관리자 답변 확인
읽지 않은 문의 / 답변 배지 표시

3-9. 관리자 기능

방문 통계
방문 로그 확인
랭킹 권한 관리
랭킹 초기화
관리자 페이지 전용 데이터 관리 기능
AI 문제 관리 관련 탭(UI 확인, 실제 운영 여부는 확인 필요)

4. 기술 스택

Frontend

React 19
TypeScript
Vite
Axios
Recharts
CSS

Backend

FastAPI
Python
SQLAlchemy
Pydantic
python-jose (JWT 인증)

Database

SQLite (로컬 fallback)
PostgreSQL 호환 DB 지원 (DATABASE_URL 기반)

Deployment

Vercel 배포 흔적 확인
프론트엔드 / 백엔드 분리형 구조

Data / Utility

pypdf
python-dotenv
localStorage 토큰 저장
쿠키 기반 방문자 ID 처리

AI / Extension

OpenAI 연동 서비스 파일 존재
현재 실제 라우트 연결 여부는 확인 필요

5. 프로젝트 구조

frontend/
 ┣ src/
 ┃ ┣ api/
 ┃ ┣ components/
 ┃ ┃ ┣ quiz/
 ┃ ┃ ┣ Admin/
 ┃ ┃ ┣ Ranking/
 ┃ ┃ ┣ Study/
 ┃ ┃ ┣ Inquiry/
 ┃ ┃ ┣ MyPage/
 ┃ ┃ ┗ WrongNotes/
 ┃ ┣ lib/
 ┃ ┗ App.tsx
backend/
 ┣ app/
 ┃ ┣ api/v1/endpoints/
 ┃ ┣ services/
 ┃ ┣ db/
 ┃ ┗ data/raw/
 ┣ make_admin.py
 ┗ fix_db.py

구조 설명

frontend/
Vite 기반 프론트엔드 프로젝트입니다.
frontend/src/api
인증, 퀴즈, 문의, 관리자 관련 API 래퍼를 관리합니다.
frontend/src/components/quiz
학습 모드별 퀴즈 UI를 구성합니다.
frontend/src/components/Admin|Ranking|Study|Inquiry|MyPage|WrongNotes
기능별 화면 컴포넌트를 구성합니다.
frontend/src/lib
Axios 인스턴스, 모바일 훅 등 공통 유틸을 포함합니다.
backend/app/api/v1/endpoints
FastAPI 라우트가 위치합니다.
backend/app/services
구절 로딩, 채점, 랭킹, 오답노트, 학습계획 등 핵심 비즈니스 로직이 위치합니다.
backend/app/db
DB 연결 및 SQLAlchemy 모델을 관리합니다.
backend/app/data/raw
사무엘 학교 1~4과정.txt, 통합.pdf 등 원본 학습 데이터가 위치합니다.
backend/make_admin.py
일반 가입 사용자를 관리자 권한으로 승격하는 스크립트입니다.
backend/fix_db.py
구 DB 컬럼 보정용으로 보이는 스크립트입니다.

6. 실행 방법

1) 백엔드 실행

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload

2) 프론트엔드 실행

cd frontend
npm install
npm run dev

환경변수

Frontend

VITE_API_BASE_URL=http://127.0.0.1:8000

Backend

DATABASE_URL=your_database_url
OPENAI_API_KEY=your_openai_api_key

기본 동작 방식

프론트엔드는 VITE_API_BASE_URL을 읽고, 없으면 개발 시 http://127.0.0.1:8000을 기본값으로 사용합니다.
백엔드는 DATABASE_URL이 없으면 sqlite:///./samuel.db로 실행됩니다.
백엔드 시작 시 필요한 테이블을 자동 생성합니다.

관리자 계정 승격

cd backend
python make_admin.py <username>

7. 화면 구성

이 프로젝트는 React Router 기반 다중 페이지 구조보다는, App.tsx에서 탭을 전환하는 단일 SPA 구조에 가깝습니다.

주요 화면

메인 학습 화면
- 모드 선택
- 과정/시험일/난이도 설정
- 퀴즈 본문 출력
인증 화면
- 로그인 / 회원가입
- 로그아웃
- 닉네임 변경 모달
오답노트 화면
- 오답 목록
- 즐겨찾기
- 메모
- 일괄 삭제
- 오답 재시험
- 훈련 모드 이동
문의 화면
- 문의 작성
- 내 문의 조회
- 관리자 답변 확인
마이페이지
- 성장 그래프
- 월별 학습 캘린더
D-Day 학습계획 화면
- 목표 설정
- 오늘의 목표
- 완료 이력
랭킹 화면
- 월간/누적 랭킹
- 점수/시간 랭킹
- 권한 요청
관리자 페이지
- 데이터 관리
- AI 문제 관리 탭
- 사용자 관리 탭
- 방문 로그 모달

8. API 및 서버 기능

인증

/api/v1/auth/signup
/api/v1/auth/login
/api/v1/auth/me
/api/v1/auth/nickname
/api/v1/auth/request-ranking
/api/v1/auth/users
/api/v1/auth/users/{id}/permission

퀴즈 문제 생성

/api/v1/quiz/write-all-question
/api/v1/quiz/fill-blank-question
/api/v1/quiz/keyword-question
/api/v1/quiz/topic-question
/api/v1/quiz/training/verses

퀴즈 채점

/api/v1/quiz/write-all-check
/api/v1/quiz/fill-blank-check
/api/v1/quiz/keyword-check
/api/v1/quiz/topic-check

결과 저장 / 랭킹

/api/v1/quiz/results
/api/v1/quiz/time-ranking

오답노트

/api/v1/quiz/wrong-notes
/api/v1/quiz/wrong-notes/ids
/api/v1/quiz/wrong-notes/remove
/api/v1/quiz/wrong-notes/delete-batch
/api/v1/quiz/wrong-notes/{id}/favorite
/api/v1/quiz/wrong-notes/{id}/memo
/api/v1/quiz/wrong-notes/manual

훈련 진행 저장

/api/v1/quiz/training/progress

학습계획

/api/v1/study/plan
/api/v1/study/history
/api/v1/study/check

문의

/api/v1/inquiry/
/api/v1/inquiry/my
/api/v1/inquiry/{id}
/api/v1/inquiry/{id}/read
/api/v1/inquiry/{id}/answer
/api/v1/inquiry/{id}/answer-read
/api/v1/inquiry/unread-count

방문 추적 / 관리자 기능

/api/v1/quiz/visitor-id
/api/v1/quiz/visit
/api/v1/quiz/admin/stats
/api/v1/quiz/admin/visit-log
/api/v1/admin/reset-ranking
/api/v1/admin/ai-quizzes*

9. 구현 포인트

9-1. 학습 루프 중심 서비스 설계

이 프로젝트는 단순 문제 풀이만 제공하는 것이 아니라,

퀴즈 → 오답노트 → 훈련 → 학습계획 → 랭킹 / 마이페이지

로 이어지는 반복 학습 구조를 하나의 서비스 안에 통합했습니다.

9-2. 암송형 학습에 맞춘 채점 UX

한글 성경 본문의 특성을 고려해

공백 / 문장부호 정규화
문자 단위 비교
오답 위치 피드백

을 제공하도록 설계했습니다.

9-3. 도메인 데이터 기반 문제 생성

원본 TXT/PDF 학습 자료를 직접 파싱해 문제 풀을 만드는 구조를 통해, 도메인 특화 학습 서비스로 확장할 수 있는 기반을 마련했습니다.

9-4. 프론트 / 백엔드 분리형 서비스 구조

프론트엔드는 React + TypeScript, 백엔드는 FastAPI + SQLAlchemy 기반으로 분리해, UI와 비즈니스 로직을 나누어 관리할 수 있도록 구성했습니다.

9-5. 운영 기능 포함

학습자 기능뿐 아니라,

랭킹 권한 승인
방문 통계 확인
사용자 관리
관리자 전용 기능

까지 포함해 실제 운영 가능한 서비스에 가깝게 확장했습니다.

10. 트러블슈팅 및 회고 포인트

1) 상태 관리 집중 문제

frontend/src/App.tsx에 상태와 탭 로직이 많이 몰려 있어, 모드 간 상태 전환과 버그 추적이 까다로웠을 가능성이 있습니다.

2) 한국어 텍스트 채점 정규화

성경 본문의 공백, 문장부호, 숫자 표기를 어떻게 정규화할지 결정하는 과정이 핵심 구현 포인트였습니다.

3) 사용자 상태가 여러 기능에 연결되는 구조

오답노트, 랭킹, 문의, 학습계획 등 여러 기능이 사용자 상태와 연결돼 있어, 데이터 모델과 흐름을 일관되게 유지하는 것이 중요했습니다.

4) DB 구조 보정 및 마이그레이션 이슈

레거시 DB 보정 코드와 수정 스크립트가 존재해, DB 구조가 바뀌는 과정에서 데이터 호환성을 맞추는 이슈가 있었을 가능성이 있습니다.

5) 프론트엔드 번들 크기 및 구조 최적화

단일 청크가 커지는 문제와 코드 스플리팅 필요성이 있어, 향후 성능 최적화 포인트로 볼 수 있습니다.

11. 스크린샷

메인 학습 화면

![메인 학습 화면](docs/images/samuel-main.png)

퀴즈 진행 화면

![퀴즈 진행 화면](docs/images/samuel-quiz.png)

오답노트 화면

![오답노트 화면](docs/images/samuel-wrong-notes.png)

마이페이지 / 학습 통계 화면

![마이페이지](docs/images/samuel-mypage.png)

관리자 화면

![관리자 화면](docs/images/samuel-admin.png)

12. README에 넣으면 좋은 내 역할

역할 예시

기획 및 기능 설계 참여
프론트엔드 구현
FastAPI 기반 백엔드 API 구현
퀴즈 / 오답노트 / 학습계획 로직 개발
관리자 기능 및 운영 화면 구현

네 실제 역할 비중에 맞게 나중에 수정하면 됩니다.

13. 아쉬운 점 및 개선 방향

StoryboardSection과 OpenAI 기반 생성 기능은 현재 연결 여부를 명확히 정리할 필요가 있습니다.
관리자 페이지의 AI 문제 관리 탭은 실제 운영 기능 여부를 구분해 정리할 필요가 있습니다.
JWT SECRET_KEY는 운영 환경에서 환경변수로 분리하는 것이 더 안전합니다.
.env.example, Docker, CI/CD, 테스트 코드, LICENSE 파일이 보완되면 프로젝트 완성도가 더 높아질 수 있습니다.
프론트엔드 상태 분리와 코드 스플리팅을 통해 유지보수성과 성능을 더 개선할 수 있습니다.

14. 확인 필요 항목

OpenAI 기반 ai_generator.py의 실제 라우트 연결 여부
관리자 페이지 AI 문제 관리 탭의 실제 운영 여부
실제 배포 구조 (프론트 / 백엔드 / DB 분리 방식)
운영 DB가 Neon인지, 다른 PostgreSQL인지
fix_db.py 기준 DB 파일과 실제 런타임 DB 기준 정리
JWT SECRET_KEY 운영 환경 분리 여부
MIT 배지가 실제 라이선스 파일과 일치하는지 여부

15. 프로젝트 정보

GitHub: inhadissolve
프로젝트 유형: 성경 암송 학습 웹서비스
주요 키워드: React, TypeScript, FastAPI, JWT, SQLAlchemy, 오답노트, 학습계획, 관리자 페이지

16. 배포 및 링크

서비스 링크: (https://samuel-school.vercel.app/)
GitHub Repository: (https://github.com/inhadissolve/samuel-school)
API 서버 주소: (https://samuel-school-api.vercel.app/)

17. 한 줄 회고

사무엘학교 사이트는 성경 암송 학습을 단순 열람형 서비스가 아니라,
퀴즈, 오답노트, 복습, 계획, 통계로 이어지는 반복 학습 플랫폼으로 구현해본 프로젝트였습니다.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
docs/images		docs/images
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

사무엘학교 사이트

1. 프로젝트 소개

주요 사용자

2. 개발 배경

3. 주요 기능

3-1. 사용자 인증 및 계정 기능

3-2. 5가지 학습 모드

3-3. 정답 채점 및 피드백

3-4. 오답노트

3-5. 훈련 모드

3-6. D-Day 학습계획

3-7. 랭킹 및 통계

3-8. 문의 기능

3-9. 관리자 기능

4. 기술 스택

Frontend

Backend

Database

Deployment

Data / Utility

AI / Extension

5. 프로젝트 구조

구조 설명

6. 실행 방법

1) 백엔드 실행

2) 프론트엔드 실행

환경변수

Frontend

Backend

기본 동작 방식

관리자 계정 승격

7. 화면 구성

주요 화면

8. API 및 서버 기능

인증

퀴즈 문제 생성

퀴즈 채점

결과 저장 / 랭킹

오답노트

훈련 진행 저장

학습계획

문의

방문 추적 / 관리자 기능

9. 구현 포인트

9-1. 학습 루프 중심 서비스 설계

9-2. 암송형 학습에 맞춘 채점 UX

9-3. 도메인 데이터 기반 문제 생성

9-4. 프론트 / 백엔드 분리형 서비스 구조

9-5. 운영 기능 포함

10. 트러블슈팅 및 회고 포인트

1) 상태 관리 집중 문제

2) 한국어 텍스트 채점 정규화

3) 사용자 상태가 여러 기능에 연결되는 구조

4) DB 구조 보정 및 마이그레이션 이슈

5) 프론트엔드 번들 크기 및 구조 최적화

11. 스크린샷

메인 학습 화면

퀴즈 진행 화면

오답노트 화면

마이페이지 / 학습 통계 화면

관리자 화면

12. README에 넣으면 좋은 내 역할

역할 예시

13. 아쉬운 점 및 개선 방향

14. 확인 필요 항목

15. 프로젝트 정보

16. 배포 및 링크

17. 한 줄 회고

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Packages