# 🏠 Home NAS Web Platform (webpage)

Synology NAS 기반의 개인 웹 플랫폼으로, 로또 분석/추천 서비스와 여행 사진 지도 서비스를 포함합니다.
Frontend, Backend, Travel Proxy, Auto Deployer를 Docker Compose로 통합하여 운영합니다.

---

## 🖥️ NAS 환경 정보

| 항목            | 값                                    |
| --------------- | ------------------------------------- |
| **NAS**         | Synology NAS                          |
| **OS**          | Synology DSM                          |
| **CPU**         | Intel Celeron J4025 (2 Core, 2.0GHz)  |
| **메모리**      | 18 GB                                 |
| **Docker**      | Synology Container Manager            |
| **Reverse Proxy** | Nginx (컨테이너)                     |
| **Git Server**  | Gitea (self-hosted)                   |

---

## 📁 디렉토리 구조

```
/volume1
├── docker/
│   └── webpage/                # 🚀 운영 런타임 (Docker Compose 기준점)
│       ├── backend/             # lotto-backend
│       ├── travel-proxy/        # travel API + thumbnail generator
│       ├── deployer/            # webhook 기반 자동 배포 컨테이너
│       ├── frontend/            # 정적 파일 (Vite build 결과)
│       ├── nginx/
│       │   └── default.conf
│       ├── scripts/
│       │   └── deploy.sh        # webhook이 호출하는 실행기
│       ├── docker-compose.yml
│       └── data/
│           └── lotto.db
│
├── workspace/
│   └── web-page-backend/        # 🧠 Git 레포 (backend + infra)
│       ├── backend/
│       ├── travel-proxy/
│       ├── deployer/
│       ├── nginx/
│       ├── scripts/
│       │   └── deploy-nas.sh    # 실제 운영 반영 로직
│       ├── docker-compose.yml
│       ├── .env.example
│       └── README.md
│
└── web/
    └── images/
        └── webPage/
            └── travel/          # 📷 원본 여행 사진 (RO)
```

---

## 🧩 서비스 구성 개요

```
Internet
  ↓
Nginx (frontend container)
  ├── /            → SPA (React/Vite)
  ├── /api/        → lotto-backend
  ├── /api/travel/ → travel-proxy
  ├── /media/...   → Nginx 직접 파일 서빙
  └── /webhook/    → deployer
```

---

### 🟦 Frontend (lotto-frontend)

-   **역할**: React + Vite 기반 SPA로, 로또 추천 및 여행 지도 UI를 제공합니다.
-   **특징**:
    -   정적 파일만 운영 서버에 배포합니다.
    -   장기 캐시(`assets/`)와 `index.html` 캐시 무효화 전략을 사용합니다.
    -   Backend / Travel API는 Nginx에서 Reverse Proxy로 연결됩니다.
-   **배포 방식**:
    1.  **로컬 개발**:
        -   `.env` 파일 설정 후 `docker compose up`으로 전체 스택 실행 가능
    2.  **운영 배포**:
        -   Code를 Git에 Push
        -   Webhook이 트리거되어 NAS가 자동 Pull & Deploy
        -   (Frontend 빌드 산출물은 별도 업로드 혹은 CI 연동 필요)

---

## 🛠️ 개발 환경 설정 (Local Development)

이 프로젝트는 **Windows/Mac 로컬 환경**과 **Synology NAS 운영 환경**을 모두 지원하도록 구성되었습니다.

### 1. 환경 변수 설정
`docker-compose.yml`은 환경 변수에 의존합니다.
1. `.env.example` 파일을 복사하여 `.env` 파일을 생성하세요.
    ```bash
    cp .env.example .env
    ```
2. `.env` 파일의 경로(`RUNTIME_PATH`, `PHOTO_PATH` 등)를 로컬 환경에 맞게 수정하세요.
    - 기본값은 현재 디렉토리(`.`) 기준으로 설정되어 있어 바로 실행 가능합니다.

### 2. 로컬 실행
```bash
docker compose up -d
```
- Frontend: http://localhost:8080
- Backend API: http://localhost:18000
- Travel API: http://localhost:19000

---

---

### 🟩 Backend (lotto-backend)

-   **역할**: 로또 데이터 수집, 분석, 추천 API를 제공하며 SQLite로 데이터를 관리합니다.
-   **주요 기능**:
    -   최신 및 특정 회차 조회
    -   추천 번호 생성 및 히스토리 관리 (중복 제거)
    -   즐겨찾기, 메모, 태그 관리
    -   배치 추천 기능
-   **기술 스택**: FastAPI, SQLite, APScheduler (정기 수집)
-   **주요 엔드포인트**:
    ```http
    GET  /api/lotto/latest
    GET  /api/lotto/{drw_no}
    GET  /api/lotto/recommend
    GET  /api/lotto/recommend/batch
    GET  /api/history
    PATCH /api/history/{id}
    DELETE /api/history/{id}
    ```

---

### 🟨 Travel Proxy (travel-proxy)

-   **역할**: 여행 사진 API, 지역별 사진 매칭, 썸네일 자동 생성 및 캐시를 담당합니다.
-   **설계 포인트**:
    -   원본 사진은 읽기 전용(RO)으로 마운트합니다.
    -   썸네일은 쓰기/읽기(RW) 전용 캐시 디렉토리를 사용합니다.
    -   사진 메타데이터 변경 시 캐시가 자동으로 무효화됩니다.
-   **데이터 구조**:
    ```
    /data/travel/           # 원본 사진 (RO)
      ├── 24.09.jeju/
      ├── 25.07.maldives/
      └── _meta/
          ├── region_map.json
          └── regions.geojson

    /data/thumbs/           # 썸네일 캐시 (RW)
      ├── 24.09.jeju/
      └── 25.07.maldives/
    ```
-   **주요 엔드포인트**:
    ```http
    GET /api/travel/regions
    GET /api/travel/photos?region=jeju
    GET /media/travel/.thumb/{album}/{file}
    ```

---

### 🟥 Deployer (webpage-deployer)

-   **역할**: Gitea Webhook을 수신하여 Git pull 및 Docker 재기동을 자동화합니다.
-   **흐름**: `Gitea Push` → `Webhook` → `deployer` → `/scripts/deploy.sh` → `docker compose up -d --build`
-   **보안**: HMAC SHA256 서명(`X-Gitea-Signature`)을 `WEBHOOK_SECRET` 환경변수로 검증합니다.
-   **특징**:
    -   Docker socket을 마운트하여 사용합니다.
    -   롤백을 위해 `.releases/` 디렉토리에 자동 백업을 수행합니다.

---

## 🔁 배포 플로우 요약

-   **Backend / Travel / Infra 변경**: `git push`를 통해 Gitea로 푸시하면 Webhook이 트리거되어 자동으로 배포됩니다.
-   **Frontend 변경**: 로컬에서 빌드 후, 생성된 정적 파일만 NAS로 업로드합니다.

---

## 🧪 운영 체크 포인트

-   `/health`: Backend 서비스 상태 확인
-   `/api/travel/photos`: 응답 속도 확인
-   `/media/travel/.thumb`: 썸네일 생성 여부 확인
-   `deployer` 컨테이너 로그 확인

---

## 📝 TODO

### 🔥 로또 서비스 고도화

-   [ ] 추천 결과 통계 시각화 (분포, 합계, 홀짝)
-   [ ] 추천 히스토리 필터 및 검색 기능
-   [ ] 추천 결과 즐겨찾기 UI
-   [ ] 회차 대비 추천 성능 분석

### 🗺️ 여행 지도 UI

-   [ ] 지도 영역 클릭 시 해당 지역 사진 로딩
-   [ ] 사진 지연 로딩 (Lazy Load)
-   [ ] 앨범 및 연도별 필터 기능
-   [ ] 모바일 UX 개선

### ⚙️ 운영/인프라

-   [ ] Docker 이미지 버전 태깅 자동화
-   [ ] 배포 실패 시 자동 롤백 기능
-   [ ] Health check 기반 배포 성공 판단 로직
-   [ ] 로그 수집 및 관리 체계 개선

---

## ✨ 철학

> “NAS는 서버가 아니라 집이다.”
>
> 그래서 안전하고, 단순하며, 복구 가능한 구조를 최우선으로 합니다.

---

## Makefile 설정 사용 예시

-   **배포**: `make deploy`
-   **백엔드 로그**: `make logs S=backend`
-   **전체 로그**: `make logs`
-   **상태**: `make status`