PhotoVault v0.1 - 이미지 정리 시스템

[!note] 수정이력 | 2026-04-26 20:45, 하늘 (hermes) 초기 버전 문서화 - 현재 상태 기록

📊 개요

프로젝트명: PhotoVault (PS.BOT-F-02)
버전: v0.1 (초기 프로토타입)
상태: 기본 기능만 구현 / 메타데이터 분류 미완성
개발기간: 2026-04-25 ~ 2026-04-26

🎯 기획 의도 vs 현재 구현

✅ 구현 완료

기능	상태	비고
사진 스캔	✅	136,826 장 DB 적재
전체 사진 뷰어	✅	썸네일 그리드 표시
FastAPI 백엔드	✅	Tailscale 로 외부 접속 가능
React 프론트엔드	✅	다크모드 UI

❌ 미완성 / 문제

기능	상태	문제점
지도 보기	❌	GPS 데이터 0 장 (메타데이터 추출 안됨)
카테고리 분류	❌	자동 분류 로직 미구현
사람별 보기	❌	얼굴 인식 미구현
타임라인	⚠️	날짜 데이터는 있으나 UI 미연결
통계	⚠️	기본 카운트만 표시

🏗️ 아키텍처

┌─────────────────────────────────────────────────────────┐
│                    PhotoVault v0.1                      │
├─────────────────────────────────────────────────────────┤
│  Frontend (React + Leaflet)                            │
│    - 전체 사진 / 지도 / 카테고리 / 타임라인 / 사람 / 통계  │
│    - dist/ 번들 서빙 (정적 파일)                          │
├─────────────────────────────────────────────────────────┤
│  Backend (FastAPI + SQLite)                            │
│    - REST API: /api/photos, /api/categories, ...       │
│    - DB: photos.db (136,826 레코드)                     │
├─────────────────────────────────────────────────────────┤
│  Data Sources (NAS)                                    │
│    - lightroom: 45,287 장 (GPS 없음 - 2011 년 DSLR)       │
│    - mobilebackup: 46,249 장 (GPS 있음 - 2021 스마트폰)  │
│    - photolibrary: 45,290 장 (미확인)                    │
└─────────────────────────────────────────────────────────┘

📁 프로젝트 구조

~/photo-organizer/
├── backend/
│   ├── app/
│   │   ├── main.py          # FastAPI 앱, 정적 파일 서빙
│   │   ├── database.py      # SQLite 연결 (photos.db)
│   │   ├── models.py        # Photo 테이블 정의
│   │   ├── routes/
│   │   │   ├── photos.py    # 사진 목록 API
│   │   │   ├── categories.py
│   │   │   ├── timeline.py
│   │   │   ├── people.py
│   │   │   └── stats.py
│   │   └── photo_scanner.py # EXIF/GPS 추출 로직 (미사용)
│   ├── parallel_scan.py     # 현재 사용 중인 스캔 스크립트
│   ├── quick_scan.py        # 빠른 스캔 (테스트용)
│   └── photos.db            # 실제 DB (136,826 장)
├── frontend/
│   ├── src/
│   │   ├── App.jsx          # 라우팅 구성
│   │   ├── components/
│   │   │   ├── PhotoGrid.jsx
│   │   │   ├── MapView.jsx  # 리프렛 지도
│   │   │   ├── Timeline.jsx
│   │   │   └── People.jsx
│   │   └── hooks/
│   │       └── useApi.js    # API_BASE = '/api' (수정됨)
│   └── dist/                # 빌드 결과
└── README.md

🔧 기술 스택

영역	기술
Backend	Python 3.10, FastAPI, SQLAlchemy, Pillow
Frontend	React 19, Vite, Leaflet, TailwindCSS
Database	SQLite (WAL 모드)
Deployment	Tailscale, Uvicorn
NAS Mount	SMB (WSL2)

🚨 알려진 문제점

1. 메타데이터 추출 누락

parallel_scan.py 에 EXIF 추출 로직 없음
photo_scanner.py 에는 있으나 호출되지 않음
결과: GPS, 촬영일자, 카메라 정보 DB 에 저장 안됨

2. 카테고리 분류 미구현

CLIP 모델 연동 안됨
메타데이터 기반 자동 분류 로직 없음

3. 얼굴 인식 미구현

face_recognition 라이브러리 미설치
사람별 그룹핑 로직 없음

4. 프론트엔드 캐시 문제

빌드 시 파일명 해시 변경됨 (index-XXXXX.js)
브라우저 캐시로 구형 파일 로드 가능

📊 DB 스키마 (photos.db)

CREATE TABLE photos (
    id INTEGER PRIMARY KEY,
    path TEXT,
    path_hash TEXT UNIQUE,
    source TEXT,           -- 'lightroom', 'mobilebackup', 'photolibrary'
    filename TEXT,
    hash TEXT,             -- SHA-256
    date_taken DATETIME,   -- ❌ 현재 모두 NULL
    latitude REAL,         -- ❌ 현재 모두 NULL
    longitude REAL,        -- ❌ 현재 모두 NULL
    city TEXT,             -- ❌ 현재 모두 NULL
    country TEXT,          -- ❌ 현재 모두 NULL
    camera_make TEXT,      -- ❌ 현재 모두 NULL
    camera_model TEXT,     -- ❌ 현재 모두 NULL
    category TEXT,         -- ❌ 현재 모두 NULL
    face_count INTEGER,    -- ❌ 현재 모두 0
    face_processed BOOLEAN,-- ❌ 현재 모두 0
    is_favorite BOOLEAN,
    is_duplicate BOOLEAN,
    duplicate_group TEXT,
    file_mtime DATETIME,
    created_at DATETIME
);

🌐 접속 정보

항목	값
서버 URL	`http://mh-3900x-wsl.tail437af5.ts.net:8000/`
Tailscale DNS	`mh-3900x-wsl.tail437af5.ts.net`
보조PC	Ryzen 9 3900X (WSL2)
모델	Qwen3.5:cloud (Ollama)

📝 다음 단계 (v0.2 기획 필요)

[!todo] 미미와 상의 필요

메타데이터 추출 우선순위 (GPS 만? 전체 EXIF?)

카테고리 분류 기준 (장소? 객체? 수동?)

얼굴 인식 구현 여부 (시간 소요 큼)

UI/UX 개선 방향

🔗 관련 문서

[[PhotoVault v0.2 기획안]] ← 새로 작성 필요
[[NAS 사진 백업 구조]]
[[Tailscale 설정]]

문서 끝