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

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

---

## 4.1 기본 사용법

### 4.1.1 단일 머신 포스터 생성

가장 기본적인 사용 사례로, 하나의 머신에 대한 포스터를 생성합니다.

```powershell
pwsh -f Create-PSD.ps1 -machineIds "107"
```

**출력**:
```
[INFO] Starting PSD creation...
[INFO] Machine IDs: 107
[INFO] Orientation: vertical (default)
[INFO] Logotype: renewalOpen (default)
[INFO] Template selected
[INFO] Processing machine 107...
[INFO] PSD file created: /data/working/20250115143022-uuid/file.psd
[SUCCESS] Completed in 23.5 seconds
```

---

### 4.1.2 다중 머신 포스터 생성

여러 머신을 하나의 포스터에 배치합니다.

```powershell
pwsh -f Create-PSD.ps1 -machineIds "1,107,205"
```

**주의사항**:
- 쉼표로 구분, 공백 없이 입력
- 템플릿이 지원하는 머신 수 확인 필요 (일반적으로 1~4대)
- 머신 수가 템플릿 용량 초과 시 경고 발생

---

### 4.1.3 방향 설정 (horizontal / vertical)

포스터 방향을 지정합니다.

**세로 방향 (vertical)**:

```powershell
pwsh -f Create-PSD.ps1 -orientation vertical -machineIds "107"
```

**가로 방향 (horizontal)**:

```powershell
pwsh -f Create-PSD.ps1 -orientation horizontal -machineIds "107"
```

---

### 4.1.4 로고타입 설정

포스터의 로고타입(이벤트 종류)을 지정합니다.

#### 지원되는 로고타입

| 로고타입 | 설명 | 사용 예 |
|----------|------|---------|
| `grandOpen` | 그랜드오픈 | 신규 매장 오픈 |
| `renewalOpen` | 리뉴얼오픈 (기본값) | 매장 리뉴얼 |
| `newOpen` | 신규 오픈 | 일반 오픈 |
| `refreshOpen` | 리프레시 오픈 | 재단장 오픈 |
| `newMachineReplacement` | 신기종 교체 | 머신 교체 이벤트 |

#### 예제

```powershell
# 그랜드오픈 포스터
pwsh -f Create-PSD.ps1 -logotype grandOpen -machineIds "1,2,3"

# 신기종 교체 포스터
pwsh -f Create-PSD.ps1 -logotype newMachineReplacement -machineIds "107"
```

---

## 4.2 고급 사용법

### 4.2.1 JSON 출력 모드

API 연동을 위해 구조화된 JSON 응답을 받습니다.

#### `-json` 플래그 사용

```powershell
pwsh -f Create-PSD.ps1 -machineIds "107" -json
```

#### JSON 응답 구조

**성공 시**:

```json
{
  "status": "success",
  "result": {
    "psdPath": "/data/working/20250115143022-a1b2c3d4/file.psd",
    "workingDirectory": "/data/working/20250115143022-a1b2c3d4",
    "templateUuid": "36cc0517-bc80-43b7-9ff6-bd947b2136e7",
    "machineIds": [107],
    "startTime": "2025-01-15 14:30:22",
    "endTime": "2025-01-15 14:30:45",
    "duration": 23.5,
    "machine_name_layer_replacements": [
      {
        "machineId": 107,
        "layerName": "machine-name_g01 #1",
        "imagePath": "/data/working/.../machine-text/107/gtwcs.png",
        "status": "success"
      }
    ],
    "template_metadata": {
      "path": "/data/working/.../template.json",
      "imageFilename": "gtwcs.png",
      "autoCreated": false
    }
  }
}
```

**실패 시**:

```json
{
  "status": "error",
  "error": {
    "message": "Template not found for orientation=vertical, logotype=grandOpen",
    "type": "TemplateNotFoundException",
    "stackTrace": "at line 142 in Create-PSD.ps1...",
    "timestamp": "2025-01-15 14:30:45",
    "duration": 1.2,
    "workingDirectory": "/data/working/20250115143022-a1b2c3d4"
  }
}
```

---

### 4.2.2 FastAPI 연동

Python FastAPI 애플리케이션에서 포스터 생성 기능을 호출하는 예제입니다.

#### Python 코드 예제

```python
import subprocess
import json
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class PosterRequest(BaseModel):
    machine_ids: str  # "1,107,205"
    orientation: str = "vertical"
    logotype: str = "renewalOpen"

@app.post("/create-poster")
async def create_poster(request: PosterRequest):
    """PSD 포스터 생성 API"""

    cmd = [
        "pwsh", "-f", "/app/poster-ai-create-psd/Create-PSD.ps1",
        "-machineIds", request.machine_ids,
        "-orientation", request.orientation,
        "-logotype", request.logotype,
        "-json"
    ]

    try:
        result = subprocess.run(
            cmd,
            capture_output=True,
            text=True,
            timeout=300,  # 5분 타임아웃
            check=False
        )

        # JSON 응답 파싱
        output = json.loads(result.stdout)

        if output["status"] == "success":
            return {
                "success": True,
                "psd_path": output["result"]["psdPath"],
                "duration": output["result"]["duration"],
                "working_directory": output["result"]["workingDirectory"]
            }
        else:
            raise HTTPException(
                status_code=500,
                detail=output["error"]["message"]
            )

    except json.JSONDecodeError as e:
        raise HTTPException(
            status_code=500,
            detail=f"Failed to parse script output: {str(e)}"
        )
    except subprocess.TimeoutExpired:
        raise HTTPException(
            status_code=504,
            detail="Poster creation timeout"
        )
    except Exception as e:
        raise HTTPException(
            status_code=500,
            detail=str(e)
        )

# 사용 예
# POST http://localhost:8000/create-poster
# Body: {"machine_ids": "1,107", "orientation": "vertical", "logotype": "grandOpen"}
```

---

### 4.2.3 커스텀 템플릿 제작

자체 템플릿을 제작하여 사용할 수 있습니다.

#### 템플릿 제작 가이드라인

1. **Photoshop에서 템플릿 PSD 생성**
   - 해상도: 300 DPI 권장
   - 색상 모드: RGB
   - 레이어 구조 명확히 구성

2. **머신 이미지 플레이스홀더 레이어 생성**
   - 스마트 오브젝트로 생성
   - 명명 규칙: `machine_{order}` (예: `machine_1`, `machine_2`)

3. **머신 이름 텍스트 레이어 생성**
   - 명명 규칙: `machine-name_g{order} #1`
   - 예: `machine-name_g01 #1`, `machine-name_g02 #1`

4. **템플릿 메타데이터 JSON 생성**
   ```json
   {
     "machine_name_image": "gtwcs.png"
   }
   ```

5. **템플릿 저장**
   - 디렉토리: `/data/psd_template/{orientation}/{logotype}/machine_{count}/.../{uuid}/`
   - 파일명: `{uuid}.psd`, `{uuid}.json`

---

### 4.2.4 배치 처리

여러 포스터를 자동으로 생성하는 배치 스크립트 예제입니다.

```powershell
# batch-create.ps1

$machines = @(
    @{ ids = "1"; orientation = "vertical"; logotype = "grandOpen" },
    @{ ids = "107"; orientation = "horizontal"; logotype = "renewalOpen" },
    @{ ids = "1,107,205"; orientation = "vertical"; logotype = "newOpen" }
)

foreach ($config in $machines) {
    Write-Host "Creating poster: $($config.ids)"

    pwsh -f Create-PSD.ps1 `
        -machineIds $config.ids `
        -orientation $config.orientation `
        -logotype $config.logotype

    if ($LASTEXITCODE -eq 0) {
        Write-Host "✓ Success" -ForegroundColor Green
    } else {
        Write-Host "✗ Failed" -ForegroundColor Red
    }
}
```

실행:

```powershell
pwsh -f batch-create.ps1
```

---

## 4.3 CLI 파라미터 레퍼런스

### 4.3.1 `-orientation`

**설명**: 포스터 방향 지정

**타입**: String

**허용값**: `vertical`, `horizontal`

**기본값**: `vertical`

**예제**:
```powershell
-orientation vertical
-orientation horizontal
```

---

### 4.3.2 `-logotype`

**설명**: 포스터 로고타입(이벤트 종류) 지정

**타입**: String

**허용값**: `grandOpen`, `renewalOpen`, `newOpen`, `refreshOpen`, `newMachineReplacement`

**기본값**: `renewalOpen`

**예제**:
```powershell
-logotype grandOpen
-logotype newMachineReplacement
```

---

### 4.3.3 `-machineIds`

**설명**: 포스터에 포함할 머신 ID (쉼표 구분)

**타입**: String

**형식**: `"id1,id2,id3"` (공백 없이)

**기본값**: `"1"`

**예제**:
```powershell
-machineIds "107"
-machineIds "1,107,205"
```

---

### 4.3.4 `-datetime`

**설명**: 날짜/시간 설정 (향후 구현 예정)

**타입**: String

**기본값**: `"random"`

**현재 상태**: 미구현

---

### 4.3.5 `-userphrase`

**설명**: 사용자 정의 문구 (향후 구현 예정)

**타입**: String

**기본값**: `"random"`

**현재 상태**: 미구현

---

### 4.3.6 `-json`

**설명**: JSON 출력 모드 활성화

**타입**: Switch (플래그)

**기본값**: `$false`

**효과**:
- 콘솔 로그 억제
- JSON 형식 응답 출력 (stdout)
- API 연동에 적합

**예제**:
```powershell
-json
```

---

## 사용 예제 모음

### 예제 1: 기본 실행

```powershell
pwsh -f Create-PSD.ps1
```

### 예제 2: 모든 파라미터 지정

```powershell
pwsh -f Create-PSD.ps1 `
  -machineIds "1,107,205" `
  -orientation horizontal `
  -logotype grandOpen
```

### 예제 3: JSON 모드

```powershell
pwsh -f Create-PSD.ps1 -machineIds "107" -json
```

### 예제 4: Windows 환경

```powershell
pwsh -File "E:\create-psd\Create-PSD.ps1" `
  -MachineIds "1,107" `
  -Orientation "vertical" `
  -Logotype "grandOpen"
```

### 예제 5: Linux 환경

```bash
pwsh -File /app/poster-ai-create-psd/Create-PSD.ps1 \
  -MachineIds "1,107" \
  -Orientation "vertical" \
  -Logotype "grandOpen"
```

---

## 다음 단계

- **[5. 시스템 아키텍처](doc_5_architecture.md)**: 시스템 구조 이해
- **[6. 핵심 기능 상세](doc_6_core_features.md)**: 기능 동작 원리
- **[9. 운영 가이드](doc_9_operations_guide.md)**: 트러블슈팅

---

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