# poster-ai-create-psd 문서 목차

> **프로젝트**: PowerShell 기반 PSD 포스터 자동 생성 시스템
> **대상 독자**: 개발자, DevOps 엔지니어
> **버전**: 1.0 (초안)
> **최종 업데이트**: 2025-11-15

---

## 문서 구성

이 문서는 poster-ai-create-psd 프로젝트의 **기술 문서**, **사용자 가이드**, **개발자 온보딩 문서**를 통합하여 제공합니다.

---

## 1. 시작하기 (Getting Started)

### 1.1 프로젝트 개요
- **1.1.1** 프로젝트 소개
- **1.1.2** 주요 기능
  - 템플릿 기반 PSD 자동 생성
  - 머신 이름 레이어 자동 교체
  - JSON 출력 모드 및 API 연동
- **1.1.3** 시스템 요구사항
- **1.1.4** 대상 사용자

### 1.2 빠른 시작 (Quick Start)
- **1.2.1** 5분 안에 첫 포스터 생성하기
- **1.2.2** 기본 명령어 예제
- **1.2.3** 출력 결과 확인

---

## 2. 설치 및 설정 (Installation & Configuration)

### 2.1 사전 요구사항 (Prerequisites)
- **2.1.1** PowerShell Core 7.0+ 설치
  - Windows 환경
  - Linux 환경
- **2.1.2** .NET Runtime 설치
- **2.1.3** Aspose.PSD 라이선스 준비 ⭐

### 2.2 설치 가이드
- **2.2.1** Repository Clone
- **2.2.2** 필수 DLL 파일 배치
  - Aspose.PSD.dll
  - Aspose.Drawing.dll
  - System.Text.Encoding.CodePages.dll
  - Newtonsoft.Json.dll
  - System.Drawing.Common.dll
- **2.2.3** Aspose.PSD 라이선스 파일 설정 ⭐
  - 라이선스 획득 방법
  - 라이선스 파일 배치
  - 라이선스 유효성 검증

### 2.3 환경 설정 (Configuration)
- **2.3.1** Create-PSD-config.ps1 설정 파일
- **2.3.2** 디렉토리 구조 설정
- **2.3.3** 크로스 플랫폼 설정 ⭐
  - **Windows 개발 환경** (d:\, e:\ 경로)
  - **Linux 운영 환경** (/data/ 경로)
- **2.3.4** 로그 및 디버그 설정

---

## 3. 데이터 준비 (Data Preparation)

### 3.1 poster.csv 데이터 구조 ⭐
- **3.1.1** CSV 파일 개요
- **3.1.2** 컬럼 정의 및 데이터 타입
  - 필수 필드
  - 선택 필드
  - 데이터 제약사항
- **3.1.3** 샘플 데이터 예제
- **3.1.4** CSV 파일 작성 가이드

### 3.2 템플릿 준비
- **3.2.1** 템플릿 디렉토리 구조
  - `/data/psd_template/vertical/`
  - `/data/psd_template/horizontal/`
- **3.2.2** 템플릿 파일 명명 규칙
- **3.2.3** 템플릿 메타데이터 JSON
  - JSON 파일 구조
  - `machine_name_image` 필드
  - 기본값 및 자동 생성

### 3.3 머신 데이터 준비 ⭐
- **3.3.1** 머신 데이터 디렉토리 구조
  - `/data/machine/{machineId}/`
- **3.3.2** 머신 이미지 파일
  - 이미지 파일 요구사항
  - 파일 형식 및 해상도
- **3.3.3** machine-text 디렉토리
  - 머신 이름 이미지 파일
  - 파일명 규칙: gtwcs.png, mtwcs.png, gtwcl.png
  - 폰트 및 정렬 옵션

---

## 4. 사용 가이드 (User Guide)

### 4.1 기본 사용법
- **4.1.1** 단일 머신 포스터 생성
- **4.1.2** 다중 머신 포스터 생성
- **4.1.3** 방향 설정 (horizontal / vertical)
- **4.1.4** 로고타입 설정
  - grandOpen
  - newMachineReplacement
  - newOpen
  - refreshOpen
  - renewalOpen

### 4.2 고급 사용법
- **4.2.1** JSON 출력 모드
  - `-json` 플래그 사용
  - JSON 응답 구조
  - 에러 처리
- **4.2.2** FastAPI 연동
  - Python 스크립트 예제
  - 응답 파싱
- **4.2.3** 커스텀 템플릿 제작
- **4.2.4** 배치 처리

### 4.3 CLI 파라미터 레퍼런스
- **4.3.1** `-orientation`
- **4.3.2** `-logotype`
- **4.3.3** `-machineIds`
- **4.3.4** `-datetime`
- **4.3.5** `-userphrase`
- **4.3.6** `-json`

---

## 5. 시스템 아키텍처 (Architecture)

### 5.1 전체 시스템 개요
- **5.1.1** 시스템 아키텍처 다이어그램
- **5.1.2** 컴포넌트 구성
- **5.1.3** 데이터 흐름

### 5.2 디렉토리 구조
- **5.2.1** 프로젝트 디렉토리 구조
- **5.2.2** 데이터 디렉토리 구조
- **5.2.3** 작업 디렉토리 (working directory)

### 5.3 기술 스택
- **5.3.1** PowerShell Core 7.0+
- **5.3.2** Aspose.PSD for .NET
- **5.3.3** 의존성 라이브러리
- **5.3.4** 크로스 플랫폼 호환성

### 5.4 주요 스크립트
- **5.4.1** Create-PSD.ps1 (메인 오케스트레이터)
- **5.4.2** PSD-Functions.ps1 (핵심 처리 함수)
- **5.4.3** PSD-Utilities.ps1 (유틸리티 함수)
- **5.4.4** Load-AsposePSD.ps1 (라이브러리 로더)
- **5.4.5** Create-PSD-config.ps1 (설정 파일)

---

## 6. 핵심 기능 상세 (Core Features)

### 6.1 PSD 포스터 자동 생성
- **6.1.1** 기능 개요
- **6.1.2** 템플릿 선택 메커니즘
- **6.1.3** 이미지 배치 프로세스
- **6.1.4** 스마트 오브젝트 처리

### 6.2 머신 이름 레이어 자동 교체 ⭐
- **6.2.1** 기능 개요 및 배경
- **6.2.2** 동작 원리
- **6.2.3** 이미지-레이어 매핑 전략
  - 레이어 명명 규칙: `machine-name_g{order} #1`
  - 레이어 탐색 알고리즘
- **6.2.4** JSON 메타데이터 활용
- **6.2.5** 이미지 스케일링 알고리즘
  - Fit-to-bounds 방식
  - 중앙 정렬
  - Lanczos 리샘플링
- **6.2.6** Edge Cases 처리
  - 이미지 파일 누락
  - 레이어 미존재
  - 크기 불일치

### 6.3 JSON 출력 모드
- **6.3.1** Success Response 스키마
- **6.3.2** Error Response 스키마
- **6.3.3** 확장 필드
  - `machine_name_layer_replacements`
  - `template_metadata`

---

## 7. API 레퍼런스 (API Reference)

### 7.1 PowerShell 함수 - PSD-Functions.ps1
- **7.1.1** `Get-TemplateMetadataJson`
- **7.1.2** `Get-ScaledImageDimensions`
- **7.1.3** `Find-MachineNameLayer`
- **7.1.4** `Load-MachineNameImage`
- **7.1.5** `Replace-LayerWithImage`
- **7.1.6** `Copy-MachineNameImages`
- **7.1.7** 기타 함수 목록

### 7.2 PowerShell 함수 - PSD-Utilities.ps1
- **7.2.1** 로깅 함수
- **7.2.2** 파일 처리 함수
- **7.2.3** 유틸리티 함수

### 7.3 설정 파라미터
- **7.3.1** 템플릿 디렉토리 경로
- **7.3.2** 머신 데이터 디렉토리 경로
- **7.3.3** 작업 디렉토리 경로
- **7.3.4** 로깅 설정
- **7.3.5** 디버그 옵션

---

## 8. 개발자 가이드 (Developer Guide)

### 8.1 개발 환경 설정
- **8.1.1** 개발 도구 설치
- **8.1.2** 로컬 개발 환경 구축
- **8.1.3** 디버그 모드 사용법

### 8.2 코드 구조
- **8.2.1** 코드 구조 및 모듈화
- **8.2.2** 에러 처리 전략
- **8.2.3** 코드 스타일 가이드

### 8.3 기능 확장 가이드
- **8.3.1** 새로운 기능 추가 절차
- **8.3.2** 함수 작성 가이드라인
- **8.3.3** 문서 업데이트

### 8.4 Git 워크플로우
- **8.4.1** 브랜치 전략
- **8.4.2** 커밋 메시지 규칙
- **8.4.3** Pull Request 프로세스

### 8.5 테스트
- **8.5.1** 테스트 구조 개요
- **8.5.2** 기본 테스트 실행 방법

---

## 9. 운영 가이드 (Operations Guide)

### 9.1 배포
- **9.1.1** 프로덕션 환경 요구사항 (Linux)
- **9.1.2** 배포 절차
- **9.1.3** 환경 변수 설정
- **9.1.4** 보안 고려사항 ⭐
  - Aspose.PSD 라이선스 파일 관리
  - 파일 권한 설정
  - 민감 정보 보호

### 9.2 로깅 및 모니터링
- **9.2.1** 로그 파일 위치 및 구조
- **9.2.2** 로그 레벨
- **9.2.3** 로그 분석 방법
- **9.2.4** 성능 모니터링

### 9.3 트러블슈팅
- **9.3.1** 일반적인 오류 및 해결 방법
  - Module Loading Errors
  - License Issues
  - Template Not Found
  - JSON Parse Errors
  - Machine Data Missing
  - 디스크 공간 부족
- **9.3.2** 디버그 모드 활용
- **9.3.3** 로그 기반 문제 진단
- **9.3.4** FAQ

### 9.4 성능 최적화
- **9.4.1** 대용량 처리 최적화
- **9.4.2** 리소스 사용량 관리
- **9.4.3** 병렬 처리 고려사항

---

## 10. 데이터 스키마 레퍼런스 (Data Schema Reference)

### 10.1 poster.csv 스키마 ⭐
- **10.1.1** 전체 컬럼 목록
- **10.1.2** 각 필드 상세 설명
  - 필드명
  - 데이터 타입
  - 필수 여부
  - 제약사항
  - 용도
- **10.1.3** 샘플 데이터

### 10.2 템플릿 메타데이터 JSON 스키마
- **10.2.1** 필드 정의
- **10.2.2** 기본값
- **10.2.3** 예제

### 10.3 머신 데이터 구조
- **10.3.1** 디렉토리 레이아웃
- **10.3.2** 파일 명명 규칙
- **10.3.3** 메타데이터

---

## 11. 부록 (Appendix)

### 11.1 용어집
- PSD (Photoshop Document)
- 스마트 오브젝트
- 래스터 레이어
- 템플릿 메타데이터
- 머신 이름 이미지
- 로고타입

### 11.2 파일 명명 규칙
- 템플릿 파일
- 머신 이미지 파일
- 머신 이름 텍스트 이미지
  - gtwcs.png: Gothic Transparent White Center Single-line
  - mtwcs.png: Mincho Transparent White Center Single-line
  - gtwcl.png: Gothic Transparent White Center Left-align

### 11.3 에러 코드 및 메시지
- 라이선스 오류
- 파일 I/O 오류
- PSD 처리 오류
- 데이터 검증 오류

### 11.4 참고 자료
- Aspose.PSD 공식 문서
- PowerShell Core 문서
- 관련 GitHub Repository

### 11.5 변경 이력 (Changelog)
- 버전 1.0 (2025-11-15): 초기 문서 작성

---

## 문서 읽기 가이드

### 역할별 추천 독서 순서

#### 처음 시작하는 사용자
1. **1. 시작하기** → **2. 설치 및 설정** → **4.1 기본 사용법** → **9.3 트러블슈팅**

#### 개발자
1. **1. 시작하기** → **5. 시스템 아키텍처** → **6. 핵심 기능 상세** → **7. API 레퍼런스** → **8. 개발자 가이드**

#### DevOps 엔지니어
1. **2. 설치 및 설정** → **3. 데이터 준비** → **9. 운영 가이드** → **10. 데이터 스키마 레퍼런스**

#### 데이터 관리자
1. **3. 데이터 준비** → **10. 데이터 스키마 레퍼런스** → **4.1 기본 사용법**

---

## 빠른 링크

- [clarify.md](clarify.md) - 문서화 방향성 및 결정사항
- [todo.md](todo.md) - 문서화 작업 계획
- [프로젝트 Repository](https://github.com/planitaicojp/poster-ai-create-psd)

---

**작성일**: 2025-11-15
**문서 버전**: 1.0 (초안)
**관리자**: TBD
**라이선스**: TBD