# 1. 시작하기 (Getting Started)

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

---

## 1.1 프로젝트 개요

### 1.1.1 프로젝트 소개

**poster-ai-create-psd**는 PowerShell 기반의 PSD 포스터 자동 생성 시스템입니다. 템플릿 PSD 파일과 머신(기계) 데이터를 결합하여 맞춤형 포스터를 자동으로 생성하는 작업을 자동화합니다.

#### 프로젝트 목적

이 프로젝트는 수작업으로 진행하던 반복적인 포스터 제작 작업을 스크립트화하여 다음을 실현합니다:

- **생산성 향상**: 포스터 1개당 작업 시간을 10분에서 1분으로 단축 (90% 감소)
- **일관성 보장**: 템플릿 시스템을 통해 브랜드 가이드라인에 맞는 일관된 디자인 유지
- **확장성**: 여러 머신 데이터와 다양한 포스터 유형을 유연하게 처리
- **시스템 통합**: JSON API 모드를 통해 웹 서비스나 자동화 워크플로우와 쉽게 통합

#### 주요 사용 사례

- 마케팅 담당자가 특정 머신에 대한 프로모션 포스터를 빠르게 생성
- 신규 매장 오픈 시 여러 대의 머신을 한 장의 포스터에 배치
- 웹 애플리케이션에서 포스터 생성 기능을 프로그래밍 방식으로 호출

---

## 1.1.2 주요 기능

### 템플릿 기반 PSD 자동 생성

- **다양한 템플릿 지원**: 방향(가로/세로)과 로고타입(그랜드오픈, 리뉴얼오픈 등)에 맞는 템플릿 자동 선택
- **스마트 오브젝트 처리**: Aspose.PSD를 활용하여 링크된 스마트 오브젝트를 임베디드 형식으로 변환
- **다중 머신 지원**: 단일 또는 여러 머신 데이터를 하나의 포스터에 통합

### 머신 이름 레이어 자동 교체

- **자동 레이어 감지**: 템플릿 내 머신 이름 텍스트 레이어를 패턴 기반으로 자동 탐색
- **사전 렌더링 이미지 사용**: 폰트 설치 이슈 없이 사전 렌더링된 PNG 이미지로 교체
- **스케일링 최적화**: Fit-to-bounds 알고리즘으로 이미지 크기를 자동 조정
- **다양한 스타일 지원**: Gothic/Mincho 폰트, Center/Left 정렬 등 다양한 스타일

### JSON 출력 모드 및 API 연동

- **구조화된 응답**: 성공/오류 상태, 생성된 파일 경로, 메타데이터를 JSON 형식으로 출력
- **FastAPI 연동**: Python 웹 애플리케이션에서 손쉽게 통합
- **에러 처리**: 상세한 오류 정보와 스택 트레이스 제공

### 포괄적인 로깅 시스템

- **상세 로그**: 모든 파일 I/O, 라이브러리 호출, 오류를 타임스탬프와 함께 기록
- **디버그 모드**: 문제 추적을 위한 상세 트레이싱
- **작업 디렉토리**: 각 실행마다 고유한 작업 디렉토리에 결과와 로그 보관

---

## 1.1.3 시스템 요구사항

### 필수 요구사항

| 항목 | 사양 | 비고 |
|------|------|------|
| PowerShell | PowerShell Core 7.0 이상 | Windows/Linux 모두 지원 |
| .NET Runtime | .NET Core 6.0 이상 | Aspose.PSD 실행 환경 |
| Aspose.PSD | Aspose.PSD for .NET 23.x 이상 | 유효한 라이선스 필요 |
| 디스크 공간 | PSD 파일 크기의 3배 이상 | 작업 디렉토리 공간 |

### 의존성 라이브러리

- Aspose.Drawing.dll
- System.Text.Encoding.CodePages.dll
- Newtonsoft.Json.dll
- System.Drawing.Common.dll

### 지원 플랫폼

- **Windows 10/11**: 개발 환경 (권장)
- **Linux**: 운영 환경 (Ubuntu 20.04 이상, CentOS 8 이상)

---

## 1.1.4 대상 사용자

### 개발자

- 시스템 유지보수 및 기능 확장
- 커스텀 템플릿 개발
- API 연동 구현

### DevOps 엔지니어

- 프로덕션 환경 배포 및 운영
- 모니터링 및 성능 최적화
- 보안 설정 및 라이선스 관리

### 데이터 관리자

- poster.csv 데이터 관리
- 머신 데이터 및 이미지 준비
- 템플릿 메타데이터 설정

---

## 1.2 빠른 시작 (Quick Start)

### 1.2.1 5분 안에 첫 포스터 생성하기

#### 전제 조건

다음 항목이 사전에 준비되어 있다고 가정합니다:

- PowerShell Core 7.0+ 설치 완료
- Aspose.PSD 라이선스 파일 배치 완료
- 템플릿 PSD 파일 준비 (`/data/psd_template/`)
- 머신 데이터 준비 (`/data/machine/`, `poster.csv`)

#### Step 1: Repository Clone

```powershell
# Windows
git clone https://github.com/planitaicojp/poster-ai-create-psd.git
cd poster-ai-create-psd

# Linux
git clone https://github.com/planitaicojp/poster-ai-create-psd.git
cd poster-ai-create-psd
```

#### Step 2: 기본 파라미터로 실행

```powershell
# 가장 간단한 실행 (기본값 사용)
pwsh -f Create-PSD.ps1
```

기본값:
- 방향: `vertical`
- 로고타입: `renewalOpen`
- 머신 ID: `1`

#### Step 3: 결과 확인

실행이 완료되면 작업 디렉토리가 생성됩니다:

```
/data/working/20250115143022-uuid/
├── file.psd              # 생성된 PSD 파일
└── create-psd.log        # 실행 로그
```

---

### 1.2.2 기본 명령어 예제

#### 예제 1: 단일 머신 포스터 생성

```powershell
# 머신 ID 107, 세로 방향, 그랜드오픈 포스터
pwsh -f Create-PSD.ps1 -machineIds "107" -orientation vertical -logotype grandOpen
```

#### 예제 2: 다중 머신 포스터 생성

```powershell
# 머신 ID 1, 2, 3을 하나의 포스터에
pwsh -f Create-PSD.ps1 -machineIds "1,2,3" -orientation horizontal -logotype renewalOpen
```

#### 예제 3: JSON 출력 모드

```powershell
# JSON 형식으로 결과 받기 (API 연동용)
pwsh -f Create-PSD.ps1 -machineIds "107" -json
```

JSON 응답 예시:

```json
{
  "status": "success",
  "result": {
    "psdPath": "/data/working/20250115143022-uuid/file.psd",
    "workingDirectory": "/data/working/20250115143022-uuid",
    "templateUuid": "35ccae63-f06d-4ddf-b7ef-e4fd8b49cca9",
    "machineIds": [107],
    "startTime": "2025-01-15 14:30:22",
    "endTime": "2025-01-15 14:30:45",
    "duration": 23.5
  }
}
```

#### 예제 4: Windows 환경

```powershell
# Windows 경로 사용 (설정 파일에서 경로 지정)
pwsh -f Create-PSD.ps1 -machineIds "1,107" -orientation vertical -logotype grandOpen
```

#### 예제 5: Linux 환경

```bash
# Linux 경로 사용
pwsh -f Create-PSD.ps1 -machineIds "1,107" -orientation vertical -logotype grandOpen
```

---

### 1.2.3 출력 결과 확인

#### 생성된 파일 구조

```
/data/working/20250115143022-a1b2c3d4/
├── file.psd                          # 생성된 PSD 파일
├── create-psd.log                    # 상세 실행 로그
└── machine-text/                     # 머신 이름 이미지 (복사됨)
    ├── 1/
    │   └── gtwcs.png
    └── 107/
        └── gtwcs.png
```

#### 로그 파일 확인

```powershell
# 로그 파일 열기
cat /data/working/20250115143022-a1b2c3d4/create-psd.log
```

로그 예시:

```
[2025-01-15 14:30:22] INFO: Starting PSD creation...
[2025-01-15 14:30:23] INFO: Template selected: /data/psd_template/vertical/grandOpen/...
[2025-01-15 14:30:24] INFO: Loading Aspose.PSD library...
[2025-01-15 14:30:25] INFO: Processing machine ID: 107
[2025-01-15 14:30:30] INFO: Machine name layer replaced successfully
[2025-01-15 14:30:45] INFO: PSD file saved: /data/working/.../file.psd
```

#### PSD 파일 열기

생성된 PSD 파일은 다음에서 열 수 있습니다:

- Adobe Photoshop CC 2019 이상
- GIMP (PSD 플러그인 필요)
- 기타 PSD 호환 이미지 편집 도구

---

## 다음 단계

빠른 시작을 완료했다면 다음 문서로 진행하세요:

- **[2. 설치 및 설정](doc_2_installation.md)**: 상세한 설치 가이드 및 환경 설정
- **[3. 데이터 준비](doc_3_data_preparation.md)**: poster.csv 및 머신 데이터 준비
- **[4. 사용 가이드](doc_4_user_guide.md)**: 고급 사용법 및 CLI 파라미터

---

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