# task-1026.1 완료 보고서: UTM 파라미터 표준화 + URL 빌더 도구

## SCQA

**S**: TOP사업단 리쿠르팅 캠페인 Phase 0에서 7개 채널(Meta, Google, 네이버SA, 네이버GFA, 카카오, 당근, 사람인/잡코리아)의 광고를 운영해야 한다.

**C**: 채널별 UTM 파라미터가 표준화되지 않으면 캠페인 성과 추적이 불일관하고, 수동 URL 생성 시 오타/규칙 위반이 발생한다.

**Q**: UTM 규칙을 표준화하고 URL 생성을 자동화하여 추적 일관성을 확보할 수 있는가?

**A**: UTM 규칙 문서와 CLI URL 빌더 스크립트를 생성하여 해결. 8개 source, 4개 medium, 6개 campaign 값의 검증 규칙을 표준화하고, 잘못된 입력 시 경고 + 올바른 값 목록을 표시하는 Python CLI 도구를 구현. pytest 33건 전체 통과, pyright 에러 0건.

---

## 생성 파일 목록

- `/home/jay/workspace/memory/specs/campaign-utm-standard.md` — UTM 규칙 문서 (7개 채널별 기본 UTM 조합 테이블 포함)
- `/home/jay/workspace/scripts/utm_builder.py` — URL 빌더 CLI 스크립트 (316줄)
- `/home/jay/workspace/scripts/test_utm_builder.py` — 테스트 파일 (557줄, 33개 테스트)

---

## 테스트 결과

- **pytest**: 33/33 passed (0.28s)
  - TestBuildUtmUrl: 6건 (정상 URL 생성, 선택 파라미터, 기존 쿼리스트링 보존)
  - TestValidateSource: 3건 (잘못된/올바른 source 검증)
  - TestValidateMedium: 3건 (잘못된/올바른 medium 검증)
  - TestValidateCampaign: 3건 (잘못된/올바른 campaign 검증)
  - TestValidateBaseUrl: 4건 (도메인 검증, 잘못된 URL 포맷)
  - TestOptionalParams: 4건 (content/term None/빈문자열 처리)
  - TestBatchMode: 3건 (정상 배치, URL 파라미터 확인, 빈 배치)
  - TestBatchModePartialErrors: 2건 (부분 실패, 전체 실패)
  - TestCLI: 5건 (정상/비정상 인자, 배치 모드 subprocess 통합)
- **pyright**: 0 errors, 0 warnings, 0 informations
- **CLI 직접 테스트**: 정상 입력 → exit 0 + URL 출력, 비정상 입력 → exit 1 + 에러 메시지

---

## 주요 구현 상세

- **검증 로직**: source, medium, campaign, base URL(도메인) 4가지 동시 검증. 모든 에러를 수집하여 한 번에 출력.
- **배치 모드**: `--batch` JSON 파일 입력 → 실패 항목은 에러 표시 + 나머지 정상 처리
- **클립보드**: pyperclip 선택적 사용 (없으면 skip)
- **허용 랜딩페이지**: incar-top.tistory.com (상시), incar-top1.tistory.com (긴급)
- **TDD 준수**: 테스트 먼저 작성 → RED 확인 → 구현 → GREEN 확인

---

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **네이밍 규칙 문서에 campaign 값이 대소문자 혼합** — 의도적 유지 (AB_A_snu 등은 브랜드 약어 포함 컨벤션이므로 utm_campaign만 예외 허용)
2. **base URL에 기존 쿼리스트링 존재 시 덮어쓰기 위험** — `parse_qs`로 기존 파라미터 보존 후 UTM 파라미터 병합 구현
3. **배치 모드 부분 실패 시 exit code 불명확** — 에러 항목 1건이라도 있으면 exit 1, 정상 항목은 stdout으로 출력 분리

### 범위 외 미해결 (0건)
없음.

---

## QC 자동 검증

- **overall**: PASS (file_check의 .done 미존재는 finish-task.sh 실행 전이므로 정상)
- **spec_compliance**: PASS — 3/3 완료 조건 충족
  - UTM 규칙 문서 생성 ✓
  - utm_builder.py 동작 확인 (CLI 테스트) ✓
  - 잘못된 값 입력 시 검증 동작 확인 ✓
- **pyright_check**: PASS (0 errors, 0 warnings)
- **style_check**: PASS (black OK, isort OK)
- **critical_gap**: PASS
- **duplicate_check**: PASS (최대 유사도 12.7%)
- **data_integrity**: PASS