AWESOMEDEV
169dcfba38
수습생이 README대로 따라 하면 백엔드 실행 첫 줄에서 막히는 상태였다.
- `./mvnw spring-boot:run` → `mvn spring-boot:run`
저장소에 mvnw 래퍼 파일이 없다. 없는 파일을 안내하고 있었다.
(CI도 같은 이유로 Maven을 직접 내려받아 쓴다 — ci.yml 주석 참고)
- 준비물에 Maven 3.9 이상 추가
Docker·Java·Node만 적혀 있고 Maven이 빠져 있었다. 실제로 이것 때문에
막혔다 — "java는 있는데 왜 안 되지?"의 원인이 여기였다.
- 시작 전 확인 명령 4줄 추가(docker -v / java -version / mvn -v / node -v)
준비물이 갖춰졌는지 먼저 확인하는 습관을 들이게 한다.
- 자주 겪는 문제 2건 추가
· mvn: command not found — 래퍼가 없어 직접 설치해야 함을 명시
· mvn package가 커버리지로 실패 — -DskipTests로 돌리면 JaCoCo 라인 30%
게이트에 걸린다. 서버만 띄울 땐 spring-boot:run을 쓰면 된다.
129 lines
7.2 KiB
Markdown
129 lines
7.2 KiB
Markdown
# 미림 앱 (mirim-app) — 어썸데브 학습 플랫폼
|
|
|
|
> **이 저장소는 여러분(수습생)의 것입니다.**
|
|
> 미림마이스터고 수습생 4명이 직접 보고, 배우고, 고치는 학습용 웹 앱입니다.
|
|
> 처음에는 문서를 읽는 곳이지만, 5주차부터는 여러분이 직접 기능을 붙이고 버그를 고치는 실전 연습장이 됩니다.
|
|
> 코드를 읽는 법이 궁금하면 [STUDY.md](./STUDY.md)부터 열어 보세요.
|
|
> 화면을 만들 일이 생기면 [DESIGN.md](./DESIGN.md)(색·글자·여백·폰트)와 [ICONS.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](https://maven.apache.org/download.cgi)에서 받아 PATH에 추가하세요.
|
|
- Node.js 20 이상
|
|
|
|
> 네 개 다 설치됐는지 먼저 확인하세요. `docker -v`, `java -version`, `mvn -v`, `node -v`가 전부 버전을 뱉으면 준비 끝입니다.
|
|
> "command not found"가 나오면 그 도구가 없거나 PATH에 안 잡힌 겁니다 — 설치부터 하고 오세요.
|
|
|
|
### 1. 데이터베이스 켜기
|
|
```bash
|
|
# 프로젝트 루트(mirim-app/)에서
|
|
docker compose up -d
|
|
```
|
|
PostgreSQL이 컨테이너로 뜹니다. `docker ps`로 확인하세요.
|
|
|
|
### 2. 백엔드 켜기
|
|
```bash
|
|
cd backend
|
|
mvn spring-boot:run
|
|
```
|
|
`http://localhost:8080` 에서 API 서버가 돌아갑니다. 첫 실행 시 시드 데이터(문서·체크리스트·과제·계정)가 자동으로 들어갑니다.
|
|
|
|
### 3. 프론트엔드 켜기
|
|
```bash
|
|
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 (어썸데브) · 수습 온보딩 프로그램 학습용 저장소
|