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

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

---

## 5.1 전체 시스템 개요

### 5.1.1 시스템 아키텍처 다이어그램

```
┌─────────────────────────────────────────────────────────┐
│                     사용자 / API                          │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ├─ CLI 파라미터
                  │  (-machineIds, -orientation, -logotype, -json)
                  ▼
┌─────────────────────────────────────────────────────────┐
│              Create-PSD.ps1 (메인 오케스트레이터)         │
│  - 파라미터 검증                                          │
│  - 설정 파일 로드                                         │
│  - 작업 디렉토리 생성                                     │
│  - 로깅 초기화                                            │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ├─ 설정 로드 ──────┐
                  │                   ▼
                  │         ┌──────────────────────┐
                  │         │ Create-PSD-config.ps1│
                  │         │  - 경로 설정          │
                  │         │  - 옵션 설정          │
                  │         └──────────────────────┘
                  │
                  ├─ 라이브러리 로드 ┐
                  │                   ▼
                  │         ┌──────────────────────┐
                  │         │ Load-AsposePSD.ps1   │
                  │         │  - DLL 로드           │
                  │         │  - 라이선스 적용      │
                  │         └──────────────────────┘
                  │
                  ├─ 핵심 처리 ──────┐
                  │                   ▼
                  │         ┌──────────────────────┐
                  │         │ PSD-Functions.ps1    │
                  │         │  - 템플릿 선택        │
                  │         │  - 이미지 배치        │
                  │         │  - 레이어 교체        │
                  │         │  - PSD 저장           │
                  │         └──────────────────────┘
                  │
                  ├─ 유틸리티 ───────┐
                  │                   ▼
                  │         ┌──────────────────────┐
                  │         │ PSD-Utilities.ps1    │
                  │         │  - 로깅               │
                  │         │  - 파일 처리          │
                  │         │  - 헬퍼 함수          │
                  │         └──────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│                  데이터 계층                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ 템플릿 PSD    │  │ 머신 데이터   │  │ poster.csv    │  │
│  │ /data/        │  │ /data/        │  │              │  │
│  │ psd_template/ │  │ machine/      │  │              │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│                  출력 계층                                │
│  ┌──────────────┐  ┌──────────────┐                     │
│  │ PSD 파일      │  │ 로그 파일     │                     │
│  │ /data/        │  │ create-psd.  │                     │
│  │ working/      │  │ log           │                     │
│  └──────────────┘  └──────────────┘                     │
└─────────────────────────────────────────────────────────┘
```

---

### 5.1.2 컴포넌트 구성

#### 1. 사용자 인터페이스 계층

- **CLI**: PowerShell 명령줄 인터페이스
- **API 연동**: FastAPI 등 외부 시스템과의 JSON 통신

#### 2. 오케스트레이션 계층

- **Create-PSD.ps1**: 전체 프로세스 조율

#### 3. 비즈니스 로직 계층

- **PSD-Functions.ps1**: 핵심 PSD 처리 로직
- **Load-AsposePSD.ps1**: 라이브러리 관리

#### 4. 유틸리티 계층

- **PSD-Utilities.ps1**: 공통 헬퍼 함수

#### 5. 설정 계층

- **Create-PSD-config.ps1**: 환경 설정

#### 6. 데이터 계층

- 템플릿 PSD 파일
- 머신 이미지 데이터
- CSV 메타데이터

---

### 5.1.3 데이터 흐름

```
1. 사용자 입력
   └─> CLI 파라미터 (-machineIds "107")

2. 설정 로드
   └─> Create-PSD-config.ps1
       └─> 경로, 옵션 설정

3. 라이브러리 초기화
   └─> Load-AsposePSD.ps1
       └─> Aspose.PSD 로드 및 라이선스 적용

4. 템플릿 선택
   └─> PSD-Functions.ps1::Select-Template()
       └─> /data/psd_template/{orientation}/{logotype}/...

5. CSV 데이터 로드
   └─> Import-Csv poster.csv
       └─> 머신 ID 107 정보 추출

6. 작업 디렉토리 생성
   └─> /data/working/{timestamp}-{uuid}/

7. 템플릿 PSD 복사
   └─> 작업 디렉토리로 템플릿 복사

8. 머신 이미지 배치
   └─> PSD-Functions.ps1::Place-MachineImage()
       └─> /data/machine/107/main.png → PSD 레이어

9. 머신 이름 레이어 교체
   └─> PSD-Functions.ps1::Replace-LayerWithImage()
       └─> /data/machine/107/machine-text/gtwcs.png → 텍스트 레이어 대체

10. PSD 저장
    └─> /data/working/{timestamp}-{uuid}/file.psd

11. 결과 출력
    └─> JSON 또는 콘솔 로그
```

---

## 5.2 디렉토리 구조

### 5.2.1 프로젝트 디렉토리 구조

```
poster-ai-create-psd/
├── Create-PSD.ps1                    # 메인 오케스트레이터 스크립트
├── Create-PSD-config.ps1             # 설정 파일
├── Create-PSD-config-win.ps1         # Windows 전용 설정
├── PSD-Functions.ps1                 # 핵심 PSD 처리 함수
├── PSD-Utilities.ps1                 # 유틸리티 함수
├── Load-AsposePSD.ps1                # Aspose.PSD 로더
├── poster.csv                        # 머신 데이터 CSV
├── Aspose.PSD.NET.lic                # 라이선스 파일
│
├── aspose-packages/                  # DLL 파일
│   ├── Aspose.PSD.dll
│   ├── Aspose.Drawing.dll
│   ├── Newtonsoft.Json.dll
│   ├── System.Text.Encoding.CodePages.dll
│   └── System.Drawing.Common.dll
│
├── Tests/                            # 테스트 스크립트
│   ├── PSD-Functions.Tests.ps1
│   ├── PSD-Utilities.Tests.ps1
│   └── TestHelpers.psm1
│
├── specs/                            # Feature Spec 문서
│   ├── 001-psd-poster-automation/
│   ├── 002-update-task-status/
│   └── 003-machine-name-layer-replacement/
│
├── test-*.ps1                        # 개별 테스트 스크립트
├── README.md
├── CLAUDE.md
├── prompts.md
└── .gitignore
```

---

### 5.2.2 데이터 디렉토리 구조

```
/data/
├── psd_template/                     # 템플릿 PSD 파일
│   ├── vertical/                     # 세로 방향
│   │   ├── grandOpen/
│   │   │   ├── machine_1/
│   │   │   ├── machine_2/
│   │   │   └── machine_3/
│   │   ├── renewalOpen/
│   │   ├── newOpen/
│   │   ├── refreshOpen/
│   │   └── newMachineReplacement/
│   └── horizontal/                   # 가로 방향
│       └── ...
│
├── machine/                          # 머신 데이터
│   ├── 1/
│   │   ├── main.png
│   │   ├── sub1.png
│   │   └── machine-text/
│   │       ├── gtwcs.png
│   │       ├── mtwcs.png
│   │       └── gtwcl.png
│   ├── 107/
│   │   └── ...
│   └── 205/
│       └── ...
│
└── working/                          # 작업 디렉토리 (출력)
    ├── 20250115143022-a1b2c3d4/
    │   ├── file.psd
    │   ├── create-psd.log
    │   └── machine-text/
    └── 20250115150330-e5f6g7h8/
        └── ...
```

---

### 5.2.3 작업 디렉토리 (working directory)

각 실행마다 고유한 작업 디렉토리가 생성됩니다.

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

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

**내용**:
```
20250115143022-a1b2c3d4/
├── file.psd                          # 생성된 PSD 파일
├── create-psd.log                    # 실행 로그
├── template.json                     # 템플릿 메타데이터 (복사 또는 생성)
└── machine-text/                     # 머신 이름 이미지 (복사)
    ├── 1/
    │   └── gtwcs.png
    └── 107/
        └── gtwcs.png
```

---

## 5.3 기술 스택

### 5.3.1 PowerShell Core 7.0+

**역할**: 스크립트 실행 환경

**주요 기능**:
- 크로스 플랫폼 지원 (Windows, Linux)
- .NET Core 통합
- 강력한 파일 I/O 및 텍스트 처리

**버전 요구사항**: 7.0 이상

---

### 5.3.2 Aspose.PSD for .NET

**역할**: PSD 파일 처리 라이브러리

**주요 기능**:
- PSD 파일 읽기/쓰기
- 레이어 조작
- 스마트 오브젝트 처리
- 이미지 변환 및 내보내기

**버전**: 23.x 이상

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

---

### 5.3.3 의존성 라이브러리

| 라이브러리 | 용도 |
|-----------|------|
| Aspose.Drawing.dll | 그래픽 처리 |
| Newtonsoft.Json.dll | JSON 직렬화/역직렬화 |
| System.Text.Encoding.CodePages.dll | 문자 인코딩 지원 |
| System.Drawing.Common.dll | 이미지 처리 |

---

### 5.3.4 크로스 플랫폼 호환성

#### Windows 지원

- PowerShell Core 7.0+
- .NET 6.0 Runtime
- 경로: `E:\`, `D:\` 드라이브 문자

#### Linux 지원

- PowerShell Core 7.0+ (Ubuntu, CentOS)
- .NET 6.0 Runtime
- 경로: `/data/` 절대 경로
- ImageMagick (PNG 처리 보조, 선택)

---

## 5.4 주요 스크립트

### 5.4.1 Create-PSD.ps1 (메인 오케스트레이터)

**역할**: 전체 프로세스 조율

**주요 책임**:
- CLI 파라미터 파싱
- 설정 파일 로드
- 작업 디렉토리 생성
- 로깅 초기화
- 템플릿 선택
- 머신 데이터 처리
- 결과 출력 (JSON/콘솔)

**주요 함수**:
- `Main()`: 진입점
- `Initialize-Environment()`
- `Process-Machines()`
- `Finalize-Output()`

---

### 5.4.2 PSD-Functions.ps1 (핵심 처리 함수)

**역할**: PSD 파일 처리 로직

**주요 함수**:

| 함수명 | 설명 |
|--------|------|
| `Select-Template()` | 템플릿 PSD 선택 |
| `Load-PsdFile()` | PSD 파일 로드 |
| `Place-MachineImage()` | 머신 이미지 배치 |
| `Find-MachineNameLayer()` | 텍스트 레이어 탐색 |
| `Replace-LayerWithImage()` | 레이어 이미지 교체 |
| `Get-ScaledImageDimensions()` | 이미지 스케일 계산 |
| `Save-PsdFile()` | PSD 파일 저장 |

---

### 5.4.3 PSD-Utilities.ps1 (유틸리티 함수)

**역할**: 공통 헬퍼 함수

**주요 함수**:

| 함수명 | 설명 |
|--------|------|
| `Write-Log()` | 로그 출력 |
| `New-WorkingDirectory()` | 작업 디렉토리 생성 |
| `Copy-FileWithValidation()` | 파일 복사 및 검증 |
| `Get-UniqueIdentifier()` | UUID 생성 |
| `Validate-FilePath()` | 파일 경로 검증 |

---

### 5.4.4 Load-AsposePSD.ps1 (라이브러리 로더)

**역할**: Aspose.PSD 라이브러리 로드 및 초기화

**주요 책임**:
- DLL 파일 로드
- 라이선스 파일 적용
- 의존성 검증

**주요 함수**:
- `Load-AsposeDll()`
- `Apply-License()`
- `Validate-Dependencies()`

---

### 5.4.5 Create-PSD-config.ps1 (설정 파일)

**역할**: 환경별 설정 관리

**설정 항목**:
- 경로 설정 (템플릿, 머신, 작업 디렉토리)
- Aspose.PSD 설정
- 로깅 옵션
- 디버그 모드

---

## 다음 단계

- **[6. 핵심 기능 상세](doc_6_core_features.md)**: 주요 기능 동작 원리
- **[7. API 레퍼런스](doc_7_api_reference.md)**: 함수 레퍼런스

---

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