# 10. 데이터 스키마 레퍼런스 (Data Schema Reference) > **문서 버전**: 1.0 > **최종 업데이트**: 2025-11-15 --- ## 10.1 poster.csv 스키마 ### 10.1.1 전체 컬럼 목록 | # | 컬럼명 | 데이터 타입 | 필수 | 기본값 | 설명 | |---|--------|------------|------|-------|------| | 1 | `id` | Integer | ✓ | - | 머신 고유 ID (Primary Key) | | 2 | `name` | String | ✓ | - | 머신 이름 (일본어/한국어) | | 3 | `category` | String | ✓ | - | 머신 카테고리 | | 4 | `maker` | String | ✗ | NULL | 제조사 | | 5 | `release_date` | Date | ✗ | NULL | 출시일 (YYYY-MM-DD) | | 6 | `spec` | String | ✗ | NULL | 스펙 정보 | | 7 | `image_path` | String | ✗ | `/data/machine/{id}/` | 이미지 경로 | --- ### 10.1.2 각 필드 상세 설명 #### id (필수) **타입**: Integer **제약사항**: - 양의 정수 (> 0) - 중복 불가 (Unique) - NULL 불가 **예시**: ```csv 1 107 205 312 ``` **용도**: 머신 식별자, 디렉토리 매핑 --- #### name (필수) **타입**: String **제약사항**: - 빈 문자열 불가 - 최대 길이: 100자 - 특수문자 허용 **예시**: ```csv エヴァンゲリオン 沖ドキ! 北斗の拳 天昇 まどか☆マギカ ``` **용도**: 포스터 표시명, 머신 이름 이미지 생성 기준 --- #### category (필수) **타입**: String **제약사항**: - 빈 문자열 불가 **표준값** (권장): - `パチンコ` (파칭코) - `スロット` (슬롯) **예시**: ```csv パチンコ スロット ``` **용도**: 머신 분류, 검색 필터 --- #### maker (선택) **타입**: String **제약사항**: 없음 **예시**: ```csv ビスティ アクロス サミー メーシー ``` **용도**: 제조사 정보, 메타데이터 --- #### release_date (선택) **타입**: Date **형식**: `YYYY-MM-DD` **제약사항**: - ISO 8601 형식 준수 **예시**: ```csv 2024-01-10 2023-11-20 2024-02-15 ``` **용도**: 출시일 정보, 정렬 기준 --- #### spec (선택) **타입**: String **제약사항**: 없음 **예시**: ```csv 確変タイプ A+ART AT MAX2400枚 ``` **용도**: 스펙 정보, 메타데이터 --- #### image_path (선택) **타입**: String **형식**: 디렉토리 경로 **기본값**: `/data/machine/{id}/` **예시**: ```csv /data/machine/1/ /data/machine/107/ /data/machine/205/ ``` **용도**: 머신 이미지 디렉토리 경로 --- ### 10.1.3 샘플 데이터 #### 완전한 예제 ```csv id,name,category,maker,release_date,spec,image_path 1,エヴァンゲリオン,パチンコ,ビスティ,2024-01-10,確変タイプ,/data/machine/1/ 107,沖ドキ!,スロット,アクロス,2023-11-20,A+ART,/data/machine/107/ 205,北斗の拳,パチンコ,サミー,2024-02-15,確変タイプ,/data/machine/205/ 312,まどマギ,スロット,メーシー,2023-12-01,AT,/data/machine/312/ ``` #### 최소 예제 (필수 필드만) ```csv id,name,category 1,エヴァンゲリオン,パチンコ 107,沖ドキ!,スロット 205,北斗の拳,パチンコ ``` --- ## 10.2 템플릿 메타데이터 JSON 스키마 ### 10.2.1 필드 정의 #### JSON 스키마 (JSON Schema Draft-07) ```json { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "machine_name_image": { "type": "string", "description": "머신 이름 텍스트 이미지 파일명", "pattern": "^[a-z]{5}\\.png$", "examples": ["gtwcs.png", "mtwcs.png", "gtwcl.png"] } }, "required": ["machine_name_image"], "additionalProperties": false } ``` --- ### 10.2.2 기본값 JSON 파일이 없을 경우 시스템이 사용하는 기본값: ```json { "machine_name_image": "gtwcs.png" } ``` --- ### 10.2.3 예제 #### 예제 1: Gothic 폰트, 중앙 정렬 ```json { "machine_name_image": "gtwcs.png" } ``` #### 예제 2: Mincho 폰트, 중앙 정렬 ```json { "machine_name_image": "mtwcs.png" } ``` #### 예제 3: Gothic 폰트, 좌측 정렬 ```json { "machine_name_image": "gtwcl.png" } ``` --- ## 10.3 머신 데이터 구조 ### 10.3.1 디렉토리 레이아웃 ``` /data/machine/{machineId}/ ├── main.png # 메인 이미지 (필수) ├── sub1.png # 서브 이미지 1 (선택) ├── sub2.png # 서브 이미지 2 (선택) ├── sub3.png # 서브 이미지 3 (선택) └── machine-text/ # 머신 이름 텍스트 이미지 (필수) ├── gtwcs.png # Gothic, Center ├── mtwcs.png # Mincho, Center (선택) └── gtwcl.png # Gothic, Left (선택) ``` --- ### 10.3.2 파일 명명 규칙 #### 메인/서브 이미지 | 파일명 | 용도 | 필수 | 형식 | |--------|------|------|------| | `main.png` | 메인 머신 이미지 | ✓ | PNG/JPEG | | `sub1.png` | 서브 이미지 1 | ✗ | PNG/JPEG | | `sub2.png` | 서브 이미지 2 | ✗ | PNG/JPEG | | `sub3.png` | 서브 이미지 3 | ✗ | PNG/JPEG | #### 머신 이름 텍스트 이미지 **파일명 규칙**: `{폰트}{t}{w}{정렬}{s}.png` | 파일명 | 폰트 | 배경 | 색상 | 정렬 | 라인 | |--------|------|------|------|------|------| | `gtwcs.png` | Gothic | Transparent | White | Center | Single | | `mtwcs.png` | Mincho | Transparent | White | Center | Single | | `gtwcl.png` | Gothic | Transparent | White | Left | Single | | `mtwcl.png` | Mincho | Transparent | White | Left | Single | **코드 의미**: | 코드 | 의미 | 옵션 | |------|------|------| | 첫 글자 | 폰트 | `g` (Gothic), `m` (Mincho) | | `t` | Transparent (투명 배경) | 고정 | | `w` | White (흰색 텍스트) | 고정 | | 네 번째 | 정렬 | `c` (Center), `l` (Left) | | `s` | Single-line | 고정 | --- ### 10.3.3 메타데이터 머신별 메타데이터는 `poster.csv`에 저장됩니다. 디렉토리 자체에는 별도 메타데이터 파일 없음. --- ## 10.4 작업 디렉토리 구조 ### 각 실행 결과물 ``` /data/working/{timestamp}-{uuid}/ ├── file.psd # 생성된 PSD 파일 ├── create-psd.log # 실행 로그 ├── template.json # 템플릿 메타데이터 (복사 또는 생성) └── machine-text/ # 머신 이름 이미지 (복사) ├── 1/ │ └── gtwcs.png ├── 107/ │ └── gtwcs.png └── 205/ └── gtwcs.png ``` --- ## 10.5 JSON 출력 스키마 ### Success Response ```json { "status": "success", "result": { "psdPath": "string", "workingDirectory": "string", "templateUuid": "string", "machineIds": ["integer"], "startTime": "string (ISO 8601)", "endTime": "string (ISO 8601)", "duration": "number (seconds)", "machine_name_layer_replacements": [ { "machineId": "integer", "layerName": "string", "imagePath": "string", "status": "string", "scaleFactor": "number (optional)" } ], "template_metadata": { "path": "string", "imageFilename": "string", "autoCreated": "boolean" } } } ``` ### Error Response ```json { "status": "error", "error": { "message": "string", "type": "string", "stackTrace": "string", "timestamp": "string (ISO 8601)", "duration": "number (seconds)", "workingDirectory": "string (optional)" } } ``` --- ## 데이터 검증 체크리스트 ### poster.csv - [ ] UTF-8 인코딩 - [ ] 헤더 행 포함 - [ ] 필수 컬럼 존재 (`id`, `name`, `category`) - [ ] ID 중복 없음 - [ ] ID는 양의 정수 - [ ] 빈 이름 없음 ### 템플릿 메타데이터 - [ ] JSON 파일 형식 유효 - [ ] `machine_name_image` 필드 존재 - [ ] 파일명이 표준 규칙 준수 ### 머신 데이터 - [ ] 각 머신 ID별 디렉토리 존재 - [ ] `main.png` 파일 존재 - [ ] `machine-text/` 디렉토리 존재 - [ ] 최소 1개 텍스트 이미지 존재 (gtwcs.png 권장) --- ## 다음 단계 - **[3. 데이터 준비](doc_3_data_preparation.md)**: 데이터 준비 실무 가이드 - **[11. 부록](doc_11_appendix.md)**: 용어집 및 참고 자료 --- **[← 목차로 돌아가기](doc_index.md)**