# PROJECT_CONTEXT.md

## 프로젝트 개요

| 항목 | 값 |
|---|---|
| 프로젝트명 | 03-로고삽입기 |
| 버전 | 1.0.0-dev |
| 작성일 | 2026-07-03 |
| 상태 | Phase 2: 프로젝트 초기화 |
| 기반 | D:\AI-TOOLS\02-로고삽입\logo_inserter.py (750줄) |

## 목표

기존 검증된 로고삽입 프로그램을 **AI-WORKS 표준**으로 리팩터링합니다.

### 핵심 원칙
- ✅ 기존 핵심 기능 최대 유지
- ✅ 새 프로그램 제작 아님 (리팩터링)
- ✅ 원본 파일 절대 보존
- ✅ 폴더 구조 유지 (평탄화 금지)
- ✅ 다중 로고 지원 (config 배열 구조)

## 표준 프로젝트 구조

```
03-로고삽입기/
├── src/
│   ├── main.py
│   ├── config_handler.py
│   ├── image_handler.py
│   ├── batch_processor.py
│   ├── logo_processor.py
│   └── utils/
│       ├── color_utils.py
│       ├── position_utils.py
│       ├── logger_utils.py
│       └── validator.py
├── source/              # 개발용 입력
├── output/              # 개발용 출력
├── backup/              # 백업
├── logs/                # 로그
├── logo_left.png        # 기본 로고 1
├── logo_right.png       # 기본 로고 2
├── config.json
├── PROJECT_CONTEXT.md
├── RULES.md
├── README.md
├── LOGO_MANAGEMENT.md
├── CHANGELOG.md
├── STATE.json
├── SESSION.md
├── IDEA.md
├── run.bat
└── build_exe.bat
```

---

## TASK CONTRACT — 확정 정책 (2026-07-03 최종 승인)

> 이 섹션은 사용자가 최종 승인한 4가지 핵심 정책입니다.  
> 구현 시 반드시 모두 준수해야 합니다.

### Policy 1. 다중 로고 정책

- `config.json`은 **`logos` 배열 구조**만 사용한다 (`logo` 단일 구조 금지)
- 기본값: `logo_left.png`, `logo_right.png` 2개
- 프로그램은 `logos` 배열을 **순서대로** 읽어 **순서대로** 삽입한다

### Policy 2. 로고 크기 정책

- PNG 원본 픽셀 크기는 **사용하지 않는다**
- 사진 크기를 기준으로 `width_percent` 값으로 **자동 계산**한다
- PNG를 교체해도 항상 **동일한 크기**로 삽입되어야 한다

### Policy 3. 사용자 편의성 정책

- 사용자는 `logo_left.png`, `logo_right.png` **파일 교체만**으로 동작해야 한다
- 전화번호 변경 / 회사 로고 변경 / 지점 로고 변경 — 모두 PNG 교체로 해결
- 프로그램 수정은 필요 없다

### Policy 4. LOGO_MANAGEMENT.md 정책

- **사용자 기준**으로 작성 (기술 용어 최소화)
- 필수 포함 항목:
  - 왼쪽/오른쪽 회사 로고 변경 방법
  - PNG 권장 규격
  - PNG 교체 방법
  - 투명 PNG 권장 안내
  - 로고 크기가 자동으로 맞춰진다는 설명
  - config.json에서 위치·크기 변경 방법
  - 자주 묻는 질문(FAQ)

### 추가 원칙

- 기존 `logo_inserter.py`의 **핵심 기능은 최대한 유지**한다
- 새 기능 제작이 아니라 **AI-WORKS 표준 리팩터링**이 목적이다

---

## 핵심 기능

### 1. 다중 로고 관리 (NEW)
- **logos 배열 구조**: config.json에서 배열로 관리
- **v1.0 기본**: logo_left.png, logo_right.png (2개)
- **확장성**: config.json 수정만으로 무한 확장 가능

### 2. 비율 기반 크기 계산 (NEW)
- **원본 무시**: PNG 픽셀 크기 사용 안 함
- **자동 계산**: 사진 크기의 width_percent(%) 기준
- **동일 크기**: 모든 로고가 항상 같은 크기로 삽입

### 3. 운영 모드 이원화 (NEW)
- **개발 모드**: source/ → output/ 처리
- **배포 모드**: 폴더 선택 → `폴더명_로고삽입완료_YYYYMMDD_HHMMSS`

### 4. 기본 기능 (기존 유지)
- 이미지 방향 감지 (가로/세로/정사각형)
- 9가지 로고 배치 위치
- 투명도 조절
- 테스트 모드 지원
- 배치 처리
- 로그 기록

## 아키텍처 방향

### 모듈화 설계
1. **유틸리티** (utils/): 순수 함수 (기존 코드 추출)
2. **핵심 로직** (logo_processor.py): 다중 로고 처리
3. **배치 처리** (batch_processor.py): 폴더 구조 유지
4. **통합** (main.py): 모드별 실행

### 의존성 관계
```
main.py
├── config_handler.py (로고 배열 관리)
├── batch_processor.py (순차 처리)
│   ├── logo_processor.py (로고 삽입)
│   │   ├── image_handler.py (이미지 처리)
│   │   ├── utils/position_utils.py
│   │   └── utils/color_utils.py
│   └── utils/logger_utils.py
└── utils/validator.py
```

## 의사결정 로그

| 날짜 | 결정 | 근거 |
|---|---|---|
| 2026-07-03 | logos 배열 구조 | 다중 로고 + 확장성 |
| 2026-07-03 | 비율 기반 크기 | 사용자 편의성 |
| 2026-07-03 | 개발/배포 모드 분리 | 01, 02 프로젝트 기준 |
| 2026-07-03 | 리팩터링 방식 | 기존 코드 모듈화 |

## 다음 단계

1. ✅ Task 2-1: AI-WORKS 표준 문서 작성 (진행 중)
2. Task 2-2: config.json 작성
3. Task 2-3: LOGO_MANAGEMENT.md 작성
4. Task 2-4: 라이브러리 확인
5. Phase 3: 모듈 리팩터링 시작