# 10 Minute Planner

Vue 3 + TailwindCSS + Fastify + PostgreSQL 기반의 `10분 플래너 다이어리` 프로젝트다.

## 시작 전에

이 프로젝트는 `Docker`와 `Docker Compose`가 설치된 환경을 기준으로 실행한다.

NAS나 서버에서 처음 올리는 경우 흐름은 아래처럼 생각하면 된다.

1. 프로젝트를 받을 폴더로 이동한다.
2. `git clone`으로 저장소를 내려받는다.
3. 내려받은 프로젝트 폴더로 들어간다.
4. `docker compose`로 컨테이너를 빌드하고 실행한다.

예시:

```bash
cd /volume1/docker
git clone https://git.sori.studio/zenn/planner.sori.studio.git .
cd planner.sori.studio
cp .env.example .env
docker compose up -d --build
```

처음 한 번은 이미지 빌드 때문에 시간이 걸릴 수 있다.
실행 전에 `.env`의 DB와 관리자 계정 환경변수는 운영자만 아는 값으로 반드시 바꾼다.

## 초보자용 빠른 실행

### 1. 프로젝트 받기

원하는 작업 폴더로 이동한 뒤 저장소를 내려받는다.

```bash
cd /원하는/폴더
git clone https://git.sori.studio/zenn/planner.sori.studio.git
cd planner.sori.studio
```

### 2. 배포용으로 바로 실행하기

실제 동작 확인이나 NAS 상시 실행은 아래 명령으로 시작한다.

```bash
cp .env.example .env
# .env에서 POSTGRES_*, DATABASE_URL, ADMIN_ACCOUNT_* 값을 비공개 운영 값으로 수정한다.
docker compose up -d --build
```

의미:

- `up`: 컨테이너를 실행한다.
- `-d`: 백그라운드에서 실행한다.
- `--build`: 이미지가 없거나 코드가 바뀌었을 때 다시 빌드한다.

브라우저 접속 주소:

- 프론트엔드: `http://NAS주소:48081`
- PostgreSQL: `NAS주소:45432`

관리자 계정은 백엔드 시작 시 `.env`의 `ADMIN_ACCOUNT_*` 값으로 자동 생성된다.
관리자 아이디와 비밀번호는 저장소 문서에 적지 말고, 운영자만 접근 가능한 비공개 환경변수 파일에서 관리한다.
일반 사용자는 회원가입 후 이메일 인증을 완료해야 로그인할 수 있다.
운영 서버에서는 비밀번호 재설정/이메일 인증용 미리보기 링크가 API 응답에 노출되지 않도록 유지한다.

현재 `docker-compose.yml` 기준 내부 구성:

- 프론트엔드 nginx
- 백엔드 Fastify
- PostgreSQL

### 3. 실행 상태 확인하기

```bash
docker compose ps
```

로그를 보고 싶으면:

```bash
docker compose logs -f
```

특정 서비스만 보고 싶으면:

```bash
docker compose logs -f frontend
docker compose logs -f backend
docker compose logs -f postgres
```

### 4. 종료하기

```bash
docker compose down
```

데이터베이스 볼륨까지 완전히 지우고 처음부터 다시 시작하고 싶을 때만 아래 명령을 사용한다.

```bash
docker compose down -v
```

주의:

- `-v`는 PostgreSQL 데이터까지 지울 수 있으니 정말 초기화가 필요할 때만 사용한다.

### 5. 코드 수정 후 다시 반영하기

배포용 compose는 코드가 자동 반영되지 않는다.

코드를 수정했다면 프로젝트 폴더 안에서 다시 실행한다.

```bash
docker compose up -d --build
```

즉, NAS에서 배포용으로 돌릴 때는 보통 아래 순서를 반복한다.

```bash
cd /volume1/docker/planner.sori.studio
git pull
docker compose up -d --build
```

## 실행 방법

### 개발용

코드를 수정하면서 자동 새로고침까지 보려면 개발용 compose를 사용한다.

```bash
docker compose -f docker-compose.dev.yml up
```

개발용도 처음 시작할 때는 아래처럼 프로젝트 폴더 안에서 실행하면 된다.

```bash
cd /원하는/폴더
git clone https://git.sori.studio/zenn/planner.sori.studio.git
cd planner.sori.studio
docker compose -f docker-compose.dev.yml up
```

개발용 포트:

- 프론트엔드: `http://localhost:5173`
- 백엔드 API: `http://localhost:3001`
- PostgreSQL: `localhost:5432`

개발용 특징:

- 프론트는 Vite HMR로 저장 즉시 화면이 반영된다.
- 백엔드는 `node --watch`로 파일 변경 시 자동 재시작된다.
- 즉, 개발 중에는 매번 새로 빌드할 필요 없이 `docker compose -f docker-compose.dev.yml up`만 켜두면 된다.

### 배포용

실서비스나 최종 확인용으로는 배포용 compose를 사용한다.

```bash
docker compose up -d --build
```

배포용 포트:

- 프론트엔드: `http://localhost:48081`
- PostgreSQL: `localhost:45432`

배포용 특징:

- 프론트는 빌드 결과물을 nginx로 서빙한다.
- 브라우저에서는 `/api` 경로로 백엔드에 접근한다.
- 수정 사항 반영 시에는 다시 빌드가 필요하다.

## 문서

- 작업 규칙: [`AGENTS.md`](./AGENTS.md)
- 진행 상태 / 체크리스트: [`TODO.md`](./TODO.md)
- 인수인계 메모: [`HANDOFF.md`](./HANDOFF.md)

## 현재 방향

- 기본 UX는 `1페이지 + 우측 정보 패널`
- 보조 모드는 `2페이지 펼침 보기`
- 스타일링은 Vue + TailwindCSS
- 장기적으로는 Docker 기반으로 UGREEN NAS 배포 예정