# AI Photo Organizer — 확정 결정 사항 (Decisions Log)

> PRD([PRD.md] 별도 보관) 기반. 본 문서는 개발 착수 전 확정된 의사결정을 기록한다.
> 최종 갱신: 2026-06-01

## 1. 핵심 결정 (사용자 확정)

| # | 항목 | 결정 | 근거 |
|---|------|------|------|
| 1 | 앱 형태 | **Electron 데스크톱 앱** | face-api.js를 렌더러(브라우저 환경)에서 네이티브 실행 → 빌드 안정. PRD의 실시간 진행률/파일목록 UI 요구 충족. Windows/Mac 크로스플랫폼. |
| 2 | 중복 파일명 정책 | **자동 리네임** (`photo.jpg` → `photo_1.jpg`) | No Data Loss 원칙. 데이터 유실 0. |
| 3 | EXIF 촬영날짜 누락 시 | **파일 수정일(mtime)로 대체**하여 YYYY/MM 추출 | 대부분의 사진을 연/월 구조에 편입 가능. |
| 4 | 다중 인물 사진의 Move 1순위 | **프로필 등록 순서** (1번 인물=이동, 2·3번=복사) | PRD 명세 "첫 번째 프로필 기준 이동 후 복사"와 일치. |

## 1-1. 영상 파일 처리 (2026-06-01 추가)

| 항목 | 결정 |
|------|------|
| 대상 확장자 | `.mp4 .mov .avi .mkv .webm .m4v` |
| 처리 방식 | **얼굴인식 없이** 날짜 기준으로 **이동만** |
| 대상 폴더 | 출력 루트 하위 **`Movie/YYYY/MM/`** |
| 날짜 기준 | 파일 수정일(mtime). 영상은 EXIF 미적용 → mtime 직행 |
| 재처리 방지 | `Movie` 폴더는 스캔 제외 디렉터리에 포함 |
| 향후(비고) | "영상에 누가 나오나"가 필요하면 ffmpeg 프레임 샘플링으로 인물 매칭(phase 2) |

> 근거: 영상은 프레임이 많아 정지 이미지 엔진으로 바로 매칭 불가. v1은 날짜 기준 분리로 안전·신속 처리하고, 사진 정리 결과를 어지럽히지 않도록 전용 `Movie` 폴더로 격리.

## 2. 기본 가정 (Claude 기본값, 이의 없으면 채택)

- **이동(Move) 구현 방식**: `복사 → 무결성 검증 → 원본 삭제` 순서로 수행 (Atomic 보장, 데이터 무결성 0 Error).
- **유사도 임계값**: face-api Euclidean distance `< 0.5`를 매칭으로 간주 (튜닝 가능 파라미터로 노출).
- **Reference 등록**: 인물당 다수 사진 등록 허용 → 평균 descriptor 사용으로 정확도 향상 (KPI ≥98% 대응).
- **미검출/인식 실패 처리**: `Unsorted/YYYY/MM/` 으로 이동 (삭제 금지, Scenario 03). 폴더명은 언어 중립을 위해 영문 `Unsorted` 사용(구 `[미정]`).
- **대상 확장자**: `.jpg .jpeg .png .webp` 자동 감지. (`.heic`는 향후 확장 검토.)
- **프로필 최대 인원**: 3명 (PRD 명세).

## 3. 폴더 출력 구조

```
<출력루트>/
  <프로필명>/YYYY/MM/...      # 인물 매칭 사진
  Unsorted/YYYY/MM/...        # 미검출·인식실패 사진
```

## 4. KPI / 비기능 요구

- 분류 정확도 ≥ 98%
- 데이터 무결성 0 Error (유실·경로오류 0건)
- 모든 파일 I/O 비동기 처리 (UI 프리징 방지)
- face-api.js 모델 로드/해제 최적화 (메모리 누수 방지)

## 5. 범위 외 (Out of Scope)

- 클라우드(Google Photos 등) 실시간 동기화
- (미래) 모바일/태블릿 확장 — descriptor 표준 저장 구조는 설계 시 고려