MyClass — 튜터 관리 앱

CI

Release

Issues

MyClass는 개인 튜터를 위한 오픈 소스, 자체 호스팅 웹 애플리케이션입니다. 학생 관리, 주간 일정, 세션 청구(billing), 달력 보기, PWA 푸시 알림 기능을 제공하며, 베트남 시간대(Asia/Ho_Chi_Minh)와 VND 통화 형식 기능이 내장되어 있습니다.

단일 튜터를 위해 설계되었습니다 (하나의 계정이 자신의 학생을 소유). 다중 테넌트 마켓플레이스가 아닙니다.

이 프로젝트가 존재하는 이유

대부분의 일정 관리/청구 도구는 다중 교사 센터나 SaaS 구독을 가정합니다. MyClass는 베트남 달력 의미론과 소프트 삭제(soft-delete) 데이터 안전성을 갖추고, 학생 일정 및 청구서를 자체 호스팅하려는 독립 튜터를 위해 구축되었습니다. 만약 개인적으로 가르치며 이미 Docker를 사용하거나 사용할 수 있다면, 전체 스택을 하나의 장치에서 실행할 수 있습니다.

기능 (Features)

• 학생 (Students) — 프로필, 과목, 소프트 삭제 안전성
• 일정 (Schedules) — 반복되는 주간 시간대 (dayOfWeek + HH:MM)
• 청구서 및 세션 (Bills & sessions) — 세션 생성, 지불 여부 표시(paid/unpaid), 세션 메모 편집
• 달력 (Calendar) — 세션 보기 + 고정 주간 일정 보기
• 보고서 (Report) — 월별 및 전체 기간 청구서 합계, 전체 청구 목록, TanStack Charts 시각화
• 설정 (Settings) — 프로필, 알림 환경 설정, 웹 푸시
• PWA — 설치 가능; 오프라인 셸 캐싱 (API는 절대 캐싱하지 않음)
• Docker — Postgres + 앱 + 야간 DB 백업

스택 (Stack)

• Next.js 15 (App Router) · TypeScript · TanStack Query · TanStack Charts
• PostgreSQL · Sequelize · umzug migrations
• NextAuth (이메일 + 비밀번호 / 자격 증명)
• Tailwind CSS · Radix UI · Vitest (순수 로직)

전제 조건 (Prerequisites)

• Docker & Docker Compose (권장)
• 로컬 개발을 위한 Node.js 20+ 및 Yarn

Quick start (Docker)

git clone https://github.com/t1112000/tutor-management-app.git
cd tutor-management-app
cp .env.example .env

.env를 수정하고 최소한 다음 변수를 설정하세요:

docker compose up --build

앱: http://localhost:3000 (포트는 compose 매핑에 따라 다를 수 있습니다).

첫 사용자 생성 (Node가 설치된 머신에서, 동일한 DB를 사용하여):

yarn install
yarn set-password <email> <password> [name]

Bắt đầu nhanh (베트남어)

MyClass를 Docker로 테스트 실행하는 요약 가이드입니다. 환경 변수에 대한 전체 상세 정보가 필요하면 상단의 Quick start (Docker) 및 Environment 섹션을 참조하세요.

1. 레포지토리 클론: git clone https://github.com/t1112000/tutor-management-app.git
2. 프로젝트 디렉터리로 이동: cd tutor-management-app
3. 설정 파일 생성: cp .env.example .env
4. .env를 열고 필수 변수(AUTH_SECRET, NEXT_PUBLIC_APP_URL 등 — 상단 Quick start 섹션의 표 참조)를 채우세요. .env 파일이나 어떤 비밀 값도 커밋하지 마세요.
5. 전체 스택 시작: docker compose up --build
6. http://localhost:3000에서 앱을 엽니다.
7. 첫 계정 생성: yarn install 후, yarn set-password <email> <mat-khau> [ten] 실행합니다.
8. 단계 7에서 만든 이메일과 비밀번호로 처음 로그인합니다.

Local development

cp .env.example .env
# DATABASE_URL을 로컬 Postgres 인스턴스로 지정하세요
yarn install
...

Scripts

Environment

.env.example를 참조하세요. 런타임에 필수인 항목:

• DATABASE_URL
• AUTH_SECRET
• AUTH_TRUST_HOST (일반적으로 리버스 프록시 뒤에 있을 때 true)

웹 푸시(Web push) (선택 사항이지만 기기 알림을 위해 필요):

• NEXT_PUBLIC_VAPID_PUBLIC_KEY (빌드 시점에 내장됨)
• VAPID_PRIVATE_KEY
• VAPID_EMAIL (예: mailto:[email protected])

NEXT_PUBLIC_* 값은 빌드 시 클라이언트 번들에 포함됩니다. Docker를 사용하는 경우, 빌드 인자(build args)로 전달하세요 (docker-compose.yml에 이미 연결되어 있음).

아키텍처 참고 사항 (Architecture notes)

• 소유권 (Ownership): 모든 API 경로는 requireUser()를 사용하며, 데이터는 findOwnedStudent / findOwnedBill을 통해 스코프됩니다 (createdBy + deletedAt: null).
• Soft deletes: Student와 Bill은 소프트 삭제(soft-delete) 처리되며, 쿼리 시 반드시 deletedAt 필터를 적용해야 합니다 (헬퍼가 이를 수행함).
• 시간 (Time): 모든 날짜 로직은 src/lib/time.ts의 헬퍼를 사용합니다 (베트남 시간). 원시 Date 또는 UTC 가정을 사용하는 것보다 이 헬퍼들을 선호하세요.
• 단일 복제본 (Single replica): 일일 알림(node-cron을 사용하여 07:00 VN) 및 인프로세스(in-process) 로그인 제한기(rate limiter)는 하나의 앱 인스턴스를 가정합니다. 여러 복제본이 실행되면 알림이 중복됩니다.

iOS PWA 푸시

iOS에서 웹 푸시는 iOS 16.4 이상과 홈 화면에 추가된 앱을 필요로 합니다. 알림은 Safari 탭에서는 전달되지 않으며, 독립형/PWA 모드에서만 가능합니다.

스크린샷 (Screenshots)

제품 UI는 대시보드 경로(/students, /bills, /calendar, /report) 아래에 있습니다. 커뮤니티 기여 스크린샷(실제 PII 없음)은 docs/screenshots/에 넣을 수 있으며, good first issue 레이블이 붙은 열린 이슈를 참고하세요.

기여 (Contributing)

기여는 환영합니다 — 문서화, 버그 수정, 접근성 개선, 그리고 신중하게 스코프된 기능 추가가 가능합니다. CONTRIBUTING.md를 참조하세요.

첫 작업(first task)을 찾고 있나요? good first issues 또는 docs/good-first-issues.md의 템플릿을 확인하세요.

취약점 보고는 SECURITY.md를, 행동 강령은 CODE_OF_CONDUCT.md를 읽어주세요.

유지 관리자 / Codex

Agent 기반 프로젝트 노트: AGENTS.md, CLAUDE.md.
OSS 준비 및 오픈 소스 체크리스트 (Codex for Open Source): docs/oss-scorecard.md.

라이선스

MIT — 사용, 수정 및 자체 호스팅이 자유롭습니다.