==========================
기술 결정서
==========================

작성일: 2026-07-07
버전: 1.1

1. 사용 기술
==========================

### 선택한 기술

- Python 3.x

### 선택 이유

- Windows 환경에서 개발 및 유지보수가 쉽다.
- 이미지 처리 라이브러리가 풍부하다.

### 다른 후보와 비교

- C++
  - 성능은 우수하지만 개발과 유지보수가 어렵다.
- C#
  - Windows 전용으로는 좋지만 기존 환경과 다르다.

---

2. 라이브러리
==========================

### 선택한 라이브러리

- Pillow

### 선택 이유

- JPG, JPEG, PNG, WEBP를 안정적으로 지원한다.
- WebP 변환 품질이 우수하다.
- 사용법이 간단하고 유지보수가 쉽다.

### 다른 후보와 비교

- OpenCV
  - 기능은 많지만 본 프로젝트에는 과하다.
- ImageMagick
  - 설치와 배포가 복잡하다.

---

3. 출력 정책
==========================

### 최종 출력 정책

- 모든 이미지를 WebP 형식으로 변환하여 저장
- 출력 확장자: 항상 .webp
- 출력 폴더명: 원본폴더명_webp_q품질
- 출력 파일명: 원본파일명_webp_q품질.webp

### WebP 선택 이유

- 용량 감소 효율이 가장 우수함
- 투명 배경(RGBA) 지원
- 홈페이지 업로드에 최적화됨
- 최신 브라우저 지원률 높음

---

4. 배포 방식
==========================

### 선택한 배포 방식

- Windows EXE
- run.bat 실행 지원

### 선택 이유

- Python이 설치되지 않은 PC에서도 실행 가능해야 한다.
- 더블클릭만으로 사용할 수 있어야 한다.

---

5. 출력 정책
==========================

### 입력 규칙

- 기본 입력 폴더는 source이다.
- 사용자는 config.json에서 입력 폴더를 변경할 수 있다.
- 입력 폴더의 모든 하위 폴더를 자동 검색한다.

### 출력 규칙

- 출력 폴더는 입력 폴더와 같은 위치에 생성한다.
- 출력 폴더명은 원본 폴더명 뒤에 _webp_q품질을 붙인다.

예)
입력
D:\사진\liv

출력
D:\사진\liv_webp_q90

---

### 파일명 생성 규칙

- 출력 파일명은 원본 파일명 뒤에 _webp_q품질을 붙인다.
- 확장자는 항상 .webp로 저장한다.

예)
a.jpg
→ a_webp_q90.webp

photo.png
→ photo_webp_q90.webp

하위 폴더도 동일하게 적용한다.

예)
D:\사진\liv\sub\b.jpg

↓

D:\사진\liv_webp_q90\sub\b_webp_q90.webp

---

### 중복 파일 처리 규칙

- 기존 출력 폴더가 존재하면 덮어쓰지 않는다.
- 기존 출력 폴더명 뒤에 자동 번호를 붙여 새 폴더를 생성한다.

예)

source_webp_q90
source_webp_q90_1
source_webp_q90_2

- 출력 파일명이 중복되는 경우에도 자동 번호를 붙인다.

예)

a_webp_q90.webp
a_webp_q90_1.webp
a_webp_q90_2.webp

---

### 로그 파일 규칙

- logs 폴더에 로그를 저장한다.
- 로그 파일명에는 실행 날짜와 화질값을 포함한다.

예)
resize_webp_q90_2026-07-06.log

기록 내용

- 실행 시간
- 입력 폴더
- 출력 폴더
- 화질
- 처리 파일 수
- 성공 수
- 실패 수
- 오류 목록

---

6. 오류 처리 정책
==========================

### 오류 처리 규칙

- 오류가 발생한 파일만 건너뛴다.
- 전체 작업은 계속 진행한다.
- 오류 내용은 로그에 기록한다.
- 손상된 이미지는 실패 목록에 저장한다.

---

7. 화질 선택 정책
==========================

### 화질 선택 규칙

- 프로그램 시작 시 사용자가 화질을 선택할 수 있다.
- 6가지 프리셋을 제공한다: 95, 90, 85, 80, 70 및 사용자 직접 입력.
- 잘못된 입력 시 기본값 90을 자동 적용한다.
- config.json의 기본값은 유지하고, 실행 시 선택값이 우선 적용된다.

### 출력 정책과의 관계

- 선택한 화질에 따라 출력 폴더명과 파일명이 자동 변경된다.
- WebP 기본 정책은 그대로 유지한다.
- 출력 폴더명: `원본폴더명_webp_q품질`
- 출력 파일명: `원본파일명_webp_q품질.webp`

### 선택 이유

- 사용자가 목적에 맞는 화질을 직접 선택할 수 있다.
- 여러 화질 버전을 쉽게 비교할 수 있다.
- config.json을 수정하지 않고도 실행별로 화질을 변경할 수 있다.

---

8. 성능 정책
==========================

### 성능 정책

- 수천 장의 이미지를 안정적으로 처리할 수 있어야 한다.
- 한 번에 하나씩 처리하여 메모리 사용량을 최소화한다.
- 원본 파일은 절대 수정하지 않는다.
- 홈페이지 업로드용으로 용량 감소를 우선한다.

---

9. 향후 확장성
==========================

### 나중에 추가 가능한 기능

- HEIC 지원
- AVIF 지원
- GUI 버전
- 여러 화질 프리셋
- 여러 크기 프리셋
- EXIF 유지 옵션
- 자동 백업 기능

### 현재 제외하는 기능

- AI 업스케일
- GPU 가속
- 클라우드 업로드
- 워터마크

---

10. 최종 기술 결정
==========================

- 핵심:
  Python + Pillow 기반 이미지 WebP 변환 및 용량 최적화

- 배포:
  Windows EXE + run.bat

- 출력:
  입력 폴더명 뒤에 `_webp_q품질`을 붙여 새 폴더 생성

- 파일명:
  원본 파일명 뒤에 `_webp_q품질`을 붙여 .webp 저장

- 로그:
  logs 폴더에 실행 로그 저장

## 상태

| 항목 | 값 |
|---|---|
| 작성일 | 2026-07-07 |
| 상태 | Approved |
| 검증 결과 | PASS |
| 버전 | 1.1 |