# 11. 부록 (Appendix)

> **문서 버전**: 1.0
> **최종 업데이트**: 2025-11-15

---

## 11.1 용어집

### PSD (Photoshop Document)

Adobe Photoshop의 네이티브 파일 형식입니다. 레이어, 효과, 텍스트 등의 편집 정보를 보존합니다.

**파일 확장자**: `.psd`

**특징**:
- 레이어 기반 편집 지원
- 비파괴 편집 가능
- 최대 크기: 30,000 x 30,000 픽셀

---

### 스마트 오브젝트 (Smart Object)

PSD 내에 포함된 벡터 또는 래스터 데이터로, 원본 품질을 유지하면서 변형 가능합니다.

**종류**:
- **임베디드 스마트 오브젝트**: PSD 파일 내에 데이터 포함
- **링크된 스마트 오브젝트**: 외부 파일 참조

**사용**:
- 비파괴 변형 (크기 조정, 회전)
- 필터 효과 적용
- 여러 인스턴스 동기화

---

### 래스터 레이어 (Raster Layer)

픽셀 기반의 일반 이미지 레이어입니다.

**특징**:
- 픽셀로 구성
- 크기 조정 시 품질 손실 가능
- 직접 편집 가능

---

### 템플릿 메타데이터 (Template Metadata)

템플릿 PSD 파일과 함께 저장되는 JSON 설정 파일입니다.

**파일명**: `{uuid}.json`

**내용**: 머신 이름 이미지 파일명 등

**예시**:
```json
{
  "machine_name_image": "gtwcs.png"
}
```

---

### 머신 이름 이미지 (Machine Name Image)

머신 이름을 사전 렌더링한 PNG 이미지 파일입니다.

**목적**: 폰트 의존성 제거, 렌더링 일관성 보장

**위치**: `/data/machine/{machineId}/machine-text/`

**종류**: gtwcs.png, mtwcs.png, gtwcl.png 등

---

### 로고타입 (Logotype)

포스터의 이벤트 종류를 나타냅니다.

**종류**:
- `grandOpen`: 그랜드오픈
- `renewalOpen`: 리뉴얼오픈
- `newOpen`: 신규 오픈
- `refreshOpen`: 리프레시 오픈
- `newMachineReplacement`: 신기종 교체

---

### 작업 디렉토리 (Working Directory)

각 실행마다 생성되는 고유한 출력 디렉토리입니다.

**명명 규칙**: `{timestamp}-{uuid}`

**예시**: `20250115143022-a1b2c3d4`

**내용**: 생성된 PSD, 로그, 복사된 리소스

---

### Fit-to-bounds

이미지를 대상 영역에 완전히 맞추되 비율을 유지하는 스케일링 방식입니다.

**특징**:
- 가로/세로 비율 유지
- 영역을 벗어나지 않음
- 중앙 정렬

---

### Lanczos 리샘플링

고품질 이미지 스케일링 알고리즘입니다.

**특징**:
- 선명한 결과
- 앨리어싱 최소화
- CPU 사용량 높음

---

## 11.2 파일 명명 규칙

### 11.2.1 템플릿 파일

**PSD 파일**:
- 형식: `{uuid}.psd`
- 예시: `36cc0517-bc80-43b7-9ff6-bd947b2136e7.psd`

**JSON 메타데이터**:
- 형식: `{uuid}.json`
- 예시: `36cc0517-bc80-43b7-9ff6-bd947b2136e7.json`

---

### 11.2.2 머신 이미지 파일

**메인/서브 이미지**:
- `main.png`: 메인 머신 이미지
- `sub1.png`, `sub2.png`, `sub3.png`: 서브 이미지

---

### 11.2.3 머신 이름 텍스트 이미지

**파일명 구조**: `{폰트}{t}{w}{정렬}{s}.png`

#### gtwcs.png

- **g**: Gothic (고딕 폰트)
- **t**: Transparent (투명 배경)
- **w**: White (흰색 텍스트)
- **c**: Center (중앙 정렬)
- **s**: Single-line (단일 라인)

#### mtwcs.png

- **m**: Mincho (명조 폰트)
- **t**: Transparent
- **w**: White
- **c**: Center
- **s**: Single-line

#### gtwcl.png

- **g**: Gothic
- **t**: Transparent
- **w**: White
- **c**: Center (오타, 실제로는 Left의 의미)
- **l**: Left-align (좌측 정렬)
- **s**: Single-line

**정정**: `gtwcl`은 `gtwls`가 올바른 표현이지만, 기존 코드와의 호환성을 위해 `gtwcl` 사용

---

### 11.2.4 작업 디렉토리

**형식**: `{YYYYMMDDHHMMSS}-{uuid-short}`

**예시**: `20250115143022-a1b2c3d4`

**구성**:
- `20250115`: 날짜 (YYYYMMDD)
- `143022`: 시간 (HHMMSS)
- `a1b2c3d4`: UUID 앞 8자

---

## 11.3 에러 코드 및 메시지

### 11.3.1 라이선스 오류

| 코드 | 메시지 | 원인 | 해결 |
|------|--------|------|------|
| `LICENSE_NOT_FOUND` | License file not found | 라이선스 파일 누락 | 파일 배치 확인 |
| `LICENSE_INVALID` | Invalid license file | 라이선스 형식 오류 | 유효한 파일 사용 |
| `LICENSE_EXPIRED` | License has expired | 라이선스 만료 | 라이선스 갱신 |

---

### 11.3.2 파일 I/O 오류

| 코드 | 메시지 | 원인 | 해결 |
|------|--------|------|------|
| `FILE_NOT_FOUND` | File not found: {path} | 파일 없음 | 경로 확인 |
| `PERMISSION_DENIED` | Permission denied: {path} | 권한 부족 | 권한 설정 |
| `DISK_FULL` | Disk full | 디스크 공간 부족 | 공간 확보 |

---

### 11.3.3 PSD 처리 오류

| 코드 | 메시지 | 원인 | 해결 |
|------|--------|------|------|
| `PSD_LOAD_FAILED` | Failed to load PSD: {path} | PSD 파일 손상 | 파일 재생성 |
| `LAYER_NOT_FOUND` | Layer not found: {name} | 레이어 없음 | 템플릿 확인 |
| `SMART_OBJECT_ERROR` | Smart object conversion failed | 변환 오류 | 템플릿 재작성 |

---

### 11.3.4 데이터 검증 오류

| 코드 | 메시지 | 원인 | 해결 |
|------|--------|------|------|
| `TEMPLATE_NOT_FOUND` | Template not found | 템플릿 없음 | 템플릿 추가 |
| `MACHINE_DATA_MISSING` | Machine data missing: {id} | 머신 데이터 없음 | 데이터 추가 |
| `CSV_PARSE_ERROR` | Failed to parse CSV | CSV 형식 오류 | CSV 수정 |
| `JSON_PARSE_ERROR` | Failed to parse JSON | JSON 형식 오류 | JSON 수정 |

---

## 11.4 참고 자료

### 11.4.1 Aspose.PSD 공식 문서

**홈페이지**: [https://products.aspose.com/psd/net](https://products.aspose.com/psd/net)

**API 레퍼런스**: [https://reference.aspose.com/psd/net/](https://reference.aspose.com/psd/net/)

**주요 클래스**:
- `Aspose.PSD.Image`: PSD 이미지 로드/저장
- `Aspose.PSD.FileFormats.Psd.PsdImage`: PSD 문서
- `Aspose.PSD.FileFormats.Psd.Layers.Layer`: 레이어
- `Aspose.PSD.RasterImage`: 래스터 이미지

---

### 11.4.2 PowerShell Core 문서

**홈페이지**: [https://docs.microsoft.com/powershell/](https://docs.microsoft.com/powershell/)

**GitHub**: [https://github.com/PowerShell/PowerShell](https://github.com/PowerShell/PowerShell)

**주요 cmdlet**:
- `Import-Csv`: CSV 파일 읽기
- `ConvertTo-Json`: JSON 변환
- `Test-Path`: 파일 존재 확인
- `Join-Path`: 경로 결합

---

### 11.4.3 관련 GitHub Repository

**프로젝트 Repository**:
```
https://github.com/planitaicojp/poster-ai-create-psd
```

**이슈 트래킹**:
```
https://github.com/planitaicojp/poster-ai-create-psd/issues
```

---

### 11.4.4 외부 도구

#### ImageMagick

**홈페이지**: [https://imagemagick.org/](https://imagemagick.org/)

**용도**: 이미지 변환 및 처리 (Linux 환경 보조)

**설치**:
```bash
sudo apt-get install imagemagick
```

#### Pester (테스트 프레임워크)

**홈페이지**: [https://pester.dev/](https://pester.dev/)

**용도**: PowerShell 유닛 테스트

**설치**:
```powershell
Install-Module -Name Pester -MinimumVersion 5.0 -Force
```

---

## 11.5 변경 이력 (Changelog)

### 버전 1.0 (2025-11-15)

**초기 릴리스**

- ✓ 기본 PSD 포스터 자동 생성 기능
- ✓ 템플릿 선택 메커니즘
- ✓ 머신 이미지 배치
- ✓ 머신 이름 레이어 자동 교체
- ✓ JSON 출력 모드
- ✓ 크로스 플랫폼 지원 (Windows/Linux)
- ✓ 로깅 시스템
- ✓ FastAPI 연동 예제

**문서**:
- 전체 문서 11개 섹션 완성
- 한국어 문서 우선 제공

---

## 연락처 및 지원

### 이슈 보고

GitHub Issues를 통해 버그 리포트 및 기능 요청:

```
https://github.com/planitaicojp/poster-ai-create-psd/issues
```

### 기여

Pull Request를 환영합니다:

```
https://github.com/planitaicojp/poster-ai-create-psd/pulls
```

---

## 라이선스

이 프로젝트는 Aspose.PSD for .NET의 유효한 라이선스가 필요합니다.

**Aspose 라이선스**: 상용 라이선스 (평가판 사용 가능)

**프로젝트 코드**: TBD (라이선스 정책 확인 필요)

---

**[← 목차로 돌아가기](doc_index.md)**

---

**문서 끝**