# ImageFolderCopier - 하위 폴더 이미지 복사기

하위 폴더 이미지 복사기는 사용자가 선택한 입력 폴더 및 모든 하위 폴더에서 이미지 파일을 검색하여 지정된 하나의 출력 폴더로 안전하게 복사하는 Windows 데스크톱 프로그램입니다.

## 주요 기능

1. **폴더 재귀 검색**: 입력 폴더와 모든 하위 폴더를 깊이 우선 탐색하며 지원 이미지 확장자를 수집합니다.
2. **출력 폴더 재검색 방지**: 출력 폴더가 입력 폴더의 하위 경로에 위치할 때, 출력 폴더 영역을 이미지 검색 대상에서 완전히 제외하여 무한 복사 루프를 예방합니다.
3. **폴더 순환 방지**: 심볼릭 링크 및 Windows 디렉터리 정션(Reparse Point)을 따라가지 않아 불필요한 중복 파일 탐색을 방지합니다.
4. **안전 복사 메커니즘**:
   - 임시 파일명으로 먼저 복사 진행 (`shutil.copy2`)
   - 복사가 온전히 완료된 후 최종 파일명으로 원자적 이름 변경 (`os.replace`)
   - 오류 발생 또는 취소 시 임시 파일 즉시 정리
5. **대소문자 구분 중복 파일명 처리**:
   - 출력 폴더에 동일한 파일명이 있을 경우 덮어쓰지 않고 `photo_001.jpg`, `photo_002.jpg` 등 접미사를 부여하여 자동 번호 변경
   - Windows 파일 시스템의 특성을 고려하여 대소문자만 다른 이름(예: `photo.jpg`와 `Photo.jpg`)도 중복으로 간주해 안전하게 충돌 처리
6. **멀티스레드 기반 비선점 GUI**:
   - 검색 및 복사 작업은 백그라운드 스레드에서 수행되며, 대량 작업 중에도 GUI 창이 응답 없음 상태에 빠지지 않습니다.
   - 복사 과정 중 언제든 안전하게 작업을 취소할 수 있습니다.
7. **작업 로그 및 통계**:
   - 검색 개수, 성공, 이름 변경, 건너뜀, 실패 파일 수를 실시간으로 계량하여 표시합니다.
   - 소요 시간, 복사된 총 파일 크기 등의 최종 결과를 작업 완료 팝업으로 제공합니다.

## 지원 확장자

대소문자 구분 없이 다음 이미지 파일 포맷을 탐색하고 복사합니다.

- `.jpg`, `.jpeg`
- `.png`
- `.webp`
- `.gif`
- `.bmp`
- `.tif`, `.tiff`
- `.heic` (이미지 해석 없이 확장자 기준으로 안전하게 복사)
- `.avif` (이미지 해석 없이 확장자 기준으로 안전하게 복사)

## 실행 환경

- **OS**: Windows 10 / 11
- **Python**: Python 3.11 이상
- **외부 라이브러리 의존성 없음** (Python 표준 라이브러리인 Tkinter, pathlib, shutil, threading, queue 등만 사용)

## 실행 방법

프로젝트 루트 폴더(`ImageFolderCopier`)에서 아래 명령을 실행합니다.

```bash
python main.py
```

또는 Python 패키지 형태로 모듈을 직접 구동할 수 있습니다.

```bash
python -m src.main
```
*주의: `main.py`는 패키지 임포트 처리를 위임하는 메인 엔트리 포인트입니다.*

## 테스트 방법

프로젝트 루트 폴더에서 Python 표준 `unittest` 모듈을 사용해 자동 테스트를 구동할 수 있습니다.

```bash
python -m unittest discover -s tests -p "test_*.py"
```

## 안전 원칙

- **원본 보존**: 원본 파일은 절대 삭제, 이동, 수정하지 않습니다. (Read-Only)
- **개별 오류 복구**: 특정 파일 검색 혹은 복사 중 접근 권한이나 파일 잠금 오류가 발생하더라도, 해당 파일만 건너뛰고 오류 로그를 기록한 후 나머지 작업을 끝까지 수행합니다.
- **취소 안전성**: 취소 요청 시 진행 중이던 단일 파일 복사를 안전하게 마친 후 다음 파일 복사를 중단합니다. (이미 복사가 끝난 파일은 보존됨)

## PyInstaller EXE 빌드 안내

본 프로그램은 외부 라이브러리 의존성이 없으므로, 추후 아래 명령을 통해 단일 실행 파일(EXE)로 배패할 수 있습니다. (EXE 빌드 기능은 차기 버전 배포 계획에 포함되어 있습니다.)

```bash
pyinstaller --noconsole --onefile main.py
```

---
*이 프로젝트는 AIWorksManager에 의해 템플릿 기반으로 관리되고 있습니다.*

## Windows 배포 빌드

Windows에서 `build_release.bat`를 더블클릭하거나 명령 프롬프트에서 실행하면 단일 파일과 폴더형 EXE, Portable ZIP과 Folder ZIP을 생성합니다. 빌드 전용 의존성은 `requirements-build.txt`에 분리되어 있습니다.

- 단일 파일: `dist_onefile\ImageFolderCopier.exe`
- 폴더형: `dist_onedir\ImageFolderCopier\ImageFolderCopier.exe`
- 배포 결과: `release\`
- 버전: `VERSION`

실행 파일은 Python 설치 없이 실행할 수 있습니다. 배포 전 `SHA256.txt`를 확인하세요.
