미림 앱 (mirim-app) — 어썸데브 학습 플랫폼

이 저장소는 여러분(수습생)의 것입니다. 미림마이스터고 수습생 4명이 직접 보고, 배우고, 고치는 학습용 웹 앱입니다. 처음에는 문서를 읽는 곳이지만, 5주차부터는 여러분이 직접 기능을 붙이고 버그를 고치는 실전 연습장이 됩니다. 코드를 읽는 법이 궁금하면 STUDY.md부터 열어 보세요. 화면을 만들 일이 생기면 DESIGN.md(색·글자·여백·폰트)와 ICONS.md(아이콘)를 먼저 보세요. 앱에서 /design을 열면 재료를 눈으로 보고 클릭해서 복사할 수 있습니다.

무엇을 하는 앱인가?

• 수습 기간(8주, 9월~10월) 동안 필요한 학습 문서(가이드·커리큘럼·수업자료·과제·실습가이드)를 한곳에서 봅니다.
• 학습 센터에서 수습 트랙 강좌 83개(컴퓨터 기초~앱 개발)와 수준별 과정(초급·중급·고급·특급) 48개를 순서대로 배우고, 각 코스 끝에서 퀴즈로 확인합니다.
• 코딩 문제 25개(JavaScript·SQL·Java)를 브라우저에서 직접 풀고 자동 채점받습니다.
• 주차별 체크리스트로 오늘 할 일을 확인하고, 과제를 제출하면 멘토가 피드백을 남깁니다.
• 멘토는 학생별 진도·제출물·인적사항을 한 화면에서 관리합니다.

기술 스택

영역	기술	비고
프론트엔드	React + Vite	frontend/ — 브라우저에서 돌아가는 화면
백엔드	Spring Boot 3 + Java 21	backend/ — API 서버
데이터베이스	PostgreSQL 17	Docker 컨테이너로 실행
인프라	Docker Compose	로컬에서 DB를 띄우는 용도

폴더 구조

mirim-app/
├── README.md            ← 지금 읽는 파일 (프로젝트 소개·실행법)
├── STUDY.md             ← 수습생용 "이 코드로 배우는 법"
├── docker-compose.yml   ← PostgreSQL을 띄우는 설정
├── backend/             ← Spring Boot API 서버
│   ├── pom.xml          ← 자바 의존성(라이브러리) 목록
│   └── src/main/
│       ├── java/dev/awesomedev/mirim/
│       │   ├── MirimApplication.java  ← 앱 시작점
│       │   ├── domain/     ← 엔티티(DB 테이블과 짝이 되는 클래스)
│       │   ├── repository/ ← DB를 읽고 쓰는 계층
│       │   ├── service/    ← 비즈니스 로직(규칙) 계층
│       │   ├── web/        ← HTTP 요청을 받는 계층(컨트롤러들)
│       │   └── config/     ← 보안·시드 등 설정
│       └── resources/
│           ├── application.yml  ← 서버 설정(DB 접속 정보 등)
│           └── seed/            ← 초기 데이터 JSON (문서·체크리스트·과제·퀴즈·코딩문제)
└── frontend/            ← React 화면
    ├── package.json     ← JS 의존성 목록
    ├── index.html       ← 브라우저가 처음 여는 파일
    ├── public/docs/     ← 학습 문서 HTML 19개 (앱이 iframe으로 보여줌)
    └── src/
        ├── pages/       ← 화면 단위 컴포넌트 (로그인, 대시보드, 문서, 과제…)
        │   └── courses/ ← 학습 센터의 강좌 페이지들 (코스 하나당 파일 하나)
        ├── components/  ← 여러 화면에서 재사용하는 조각 컴포넌트
        └── api/         ← 백엔드 API를 부르는 함수 모음

로컬 실행법 (3단계)

0. 준비물

• Docker Desktop
• Java 21 (JDK)
• Maven 3.9 이상 — mvn -v로 확인. 없으면 maven.apache.org에서 받아 PATH에 추가하세요.
• Node.js 20 이상

네 개 다 설치됐는지 먼저 확인하세요. docker -v, java -version, mvn -v, node -v가 전부 버전을 뱉으면 준비 끝입니다. "command not found"가 나오면 그 도구가 없거나 PATH에 안 잡힌 겁니다 — 설치부터 하고 오세요.

1. 데이터베이스 켜기

# 프로젝트 루트(mirim-app/)에서
docker compose up -d

PostgreSQL이 컨테이너로 뜹니다. docker ps로 확인하세요.

2. 백엔드 켜기

cd backend
mvn spring-boot:run

http://localhost:8080 에서 API 서버가 돌아갑니다. 첫 실행 시 시드 데이터(문서·체크리스트·과제·계정)가 자동으로 들어갑니다.

3. 프론트엔드 켜기

cd frontend
npm install                   # 최초 1회
npm run dev

브라우저에서 http://localhost:5173 을 열면 로그인 화면이 보입니다.

초기 계정

시드로는 멘토 계정(mentor1) 하나만 만들어집니다. 학생은 첫날 각자 회원가입으로 등록해요 (개인정보를 본인이 입력하는 게 정확하고, "받은 비밀번호를 바꾸는 것이 첫 일"을 배우니까요).

아이디	비밀번호	역할
mentor1	MENTOR_INITIAL_PASSWORD 환경변수, 없으면 부팅 로그에 1회 출력되는 랜덤값	멘토 (MENTOR)

⚠️ 소스에 박힌 기본 비밀번호는 없습니다 — 첫 부팅 로그에서 멘토 비밀번호를 확인하고, 로그인 후 즉시 변경하세요.

환경변수

기본값이 로컬 개발에 맞춰져 있어서, 그냥 실행하면 대부분 그대로 동작합니다.

변수	기본값	설명
DB_HOST	localhost	PostgreSQL 호스트
DB_PORT	5432	PostgreSQL 포트
DB_NAME	mirim	데이터베이스 이름
DB_USER	mirim	DB 사용자
DB_PASSWORD	(docker-compose.yml 참고)	DB 비밀번호
SERVER_PORT	8080	백엔드 포트

🔒 시크릿(비밀번호·키)은 절대 커밋하지 마세요. 로컬 기본값은 학습 편의를 위한 것이고, 실제 배포용 비밀번호·키는 .env 같은 별도 파일에 두고 .gitignore에 등록합니다. "일단 코드에 박아 두고 나중에 지우지"는 통하지 않습니다 — git 이력에 영원히 남습니다.

자주 겪는 문제

• 백엔드가 DB에 못 붙어요 → docker compose up -d를 먼저 했는지, docker ps에 postgres가 있는지 확인.
• 5173 화면은 뜨는데 로그인이 안 돼요 → 백엔드(8080)가 켜져 있는지 확인. 프론트는 API를 백엔드로 보냅니다.
• 포트가 이미 사용 중이래요 → 이전에 켜 둔 서버가 남아 있을 수 있어요. 터미널을 확인하고 종료하세요.
• mvn: command not found → Maven이 없거나 PATH에 없습니다. 준비물 0번을 확인하세요. (이 저장소에는 mvnw 래퍼가 없어서 Maven을 직접 설치해야 합니다.)
• mvn package가 커버리지 때문에 실패해요 → 테스트를 건너뛰면(-DskipTests) JaCoCo 커버리지 게이트(라인 30%)에 걸립니다. 서버를 띄우기만 할 거면 mvn spring-boot:run을 쓰세요. 패키징이 목적이면 테스트를 포함해 mvn package를 그대로 돌리면 통과합니다.

---

AWESOMEDEV (어썸데브) · 수습 온보딩 프로그램 학습용 저장소