# sample

## 목적 / 책임

YAML 작성 요청 시 코드 분석 없이 빠르게 참조할 수 있는 샘플 파일 모음을 담당한다.
샘플만 읽으면 파라미터 이름·태그 문법·파이프라인 패턴을 바로 파악할 수 있어 토큰을 절약한다.
AI가 파이프라인 YAML을 작성하거나 검토할 때 가장 먼저 읽는 도메인이다.

## 포함 경로

- `assets/yaml/sample/` — 카테고리별 샘플 YAML 파일

## 제거된 레거시 경로

- `assets/yaml/example/` — 기존 실험용 파일. 새 예제 재작성 전 혼선을 줄이기 위해 제거됨
- `assets/templates/` — 알림 테스트 템플릿. 새 예제 재작성 전 혼선을 줄이기 위해 제거됨
- 루트/`assets/` 하위의 구형 테스트 YAML/XML (`build_*.yaml`, `slack_test.yaml`, `pipeline-test*.yaml`, `scheduler*.yaml`, `assets/config.xml`, `assets/example.yaml`)은 현재 형상과 맞지 않아 제거됨

## 제외 경로

- `lib/oto/data/` — 실제 파라미터 모델은 command 도메인

## 주요 구성 요소

| 파일 | 다루는 커맨드 / 패턴 |
|------|-------------------|
| `01_basic.yaml` | property, SetValue, Print — 기본 구조 |
| `02_pipeline_if.yaml` | if (string/int/version 타입 조건 분기) |
| `03_pipeline_foreach.yaml` | foreach (List·Map 순회, 중첩) |
| `04_pipeline_exe_handle.yaml` | exe-handle (on-success / on-fail) |
| `05_pipeline_while_switch.yaml` | while, switch, wait-until |
| `06_git.yaml` | Git, GitCommit, GitPush, GitRev, GitCount, GitBranch |
| `07_file.yaml` | Copy, Delete, FileRead, FileWrite, Zip, FileInfo |
| `08_notification.yaml` | Slack, SlackBuild, Mattermost, MattermostBuild |
| `09_network.yaml` | WebRequest, WebFile, Upload(FTP), Download(FTP) |
| `10_build_ios.yaml` | BuildiOS, ArchiveiOS, ExportiOS, TestflightUpload, TestflightDistribute |
| `11_build_flutter.yaml` | BuildFlutter (멀티플랫폼) |
| `12_scheduler.yaml` | scheduler 섹션 (cron / interval) |
| `13_string_json.yaml` | StringSub, StringReplace, JsonReader, JsonReaderFile, JsonWriterFile |
| `14_shell_process.yaml` | Shell, ShellFile, ProcessRun, ProcessKill, ProcessPortUse |

## YAML 작성 요청 시 참조 가이드

요청 내용에 따라 아래 샘플만 읽으면 충분하다. 코드를 읽지 않는다.

| 요청 키워드 | 읽을 샘플 |
|------------|---------|
| iOS 빌드, Archive, TestFlight | `10_build_ios.yaml` |
| Flutter 빌드 | `11_build_flutter.yaml` |
| Git, 커밋, 푸시, 브랜치 | `06_git.yaml` |
| 파일 복사, 압축, 삭제 | `07_file.yaml` |
| Slack, Mattermost 알림 | `08_notification.yaml` |
| HTTP, FTP, 네트워크 | `09_network.yaml` |
| if 분기 | `02_pipeline_if.yaml` |
| foreach, 반복 | `03_pipeline_foreach.yaml` |
| 성공/실패 분기 | `04_pipeline_exe_handle.yaml` |
| while, switch | `05_pipeline_while_switch.yaml` |
| 스케줄러 | `12_scheduler.yaml` |
| 문자열, JSON | `13_string_json.yaml` |
| 셸, 프로세스 | `14_shell_process.yaml` |
| 처음 만드는 파이프라인, 기본 구조 | `01_basic.yaml` |

## 유지할 패턴

- 파일명은 `NN_카테고리.yaml` 형식 (번호 + 언더스코어 + 카테고리)
- 각 파일 상단에 `# [샘플] 제목` 주석으로 목적 명시
- 실제 작동 가능한 파라미터 구조를 유지한다 (추측 값 사용 금지)
- 새 커맨드가 추가되면 관련 샘플 파일도 함께 갱신한다
- 샘플은 placeholder 값을 사용하고 실제 토큰·비밀번호·API 키를 넣지 않는다
- YAML 작성 요청에서는 먼저 이 rule의 키워드 표로 읽을 샘플을 고르고, 필요한 샘플만 읽는다
- 샘플 변경 후 `dart analyze` 영향은 보통 없지만, 가능하면 해당 YAML이 `Application.getMapFromYamlA()`와 `DataBuild.fromJson()`으로 파싱 가능한지 확인한다

## 다른 도메인과의 경계

- **command**: 커맨드 파라미터가 변경되면 샘플도 동기화 필요. 샘플은 command 도메인을 참조하지 않는다
- **core**: 태그 문법(`<!...>` / `<@...>`)이 변경되면 모든 샘플 파일 업데이트 필요
- **pipeline**: workflow 문법이 변경되면 pipeline 샘플(`02`~`05`)을 함께 갱신한다
- **scheduler**: scheduler YAML 구조는 `12_scheduler.yaml`에서 관리한다

## 금지 사항

- 실제 코드(Dart 파일)를 읽어 파라미터를 추론하지 않는다 — 샘플에서 직접 읽는다
- 샘플에 실제 토큰·비밀번호·API 키를 기재하지 않는다 (placeholder 사용)
- 존재하지 않는 커맨드나 파라미터를 샘플에 넣지 않는다