README.md 현 스펙 정리

README.md

@@ -1,5 +1,207 @@
-Makefile 설정 사용 예시
+# 🏠 Home NAS Web Platform (webpage)
-- 배포: make deploy
+
-- 백엔드 로그: make logs S=backend
+Synology NAS 기반의 개인 웹 플랫폼으로, 로또 분석/추천 서비스와 여행 사진 지도 서비스를 포함합니다.
-- 전체 로그: make logs
+Frontend, Backend, Travel Proxy, Auto Deployer를 Docker Compose로 통합하여 운영합니다.
-- 상태: make status
+
+---
+
+## 🖥️ NAS 환경 정보
+
+| 항목            | 값                                    |
+| --------------- | ------------------------------------- |
+| **NAS**         | Synology NAS                          |
+| **OS**          | Synology DSM                          |
+| **CPU**         | (예: Intel / AMD / ARM – 필요 시 기입) |
+| **메모리**      | (예: 8GB / 16GB)                      |
+| **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로 연결됩니다.
+-   **배포 방식**:
+    ```bash
+    # 로컬 PC에서 실행
+    npm run build
+    npm run deploy:nas
+    ```
+
+---
+
+### 🟩 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`