# 부록 B — 12 필수 컬럼 자동 매핑

SPEC-META-ADS-001 §3.4 + 작업명세서 부록 B 직접 인용.

---

## B.1 권장 보고서 추출 방식

보다 정확한 분석을 위해 노출지면 + 연령·성별이 모두 포함된 보고서를 권장합니다.

### 방식 1. 통합 보고서 (권장)

광고 × 노출 위치 × 연령 × 성별을 모두 포함한 보고서 1개 추출.

- 장점: 4차원 교차 분석 완전 지원, 가장 정밀한 진단 가능
- 단점: 메타 광고관리자에서 추출 시 데이터 크기 커질 수 있음

### 방식 2. 분리 보고서

- 보고서 A: 광고 × 노출 위치
- 보고서 B: 광고 × 연령 × 성별

- 장점: 추출 부하 분산, 메타 광고관리자 처리 속도 안정적
- 단점: 4차원 교차 분석은 제한적 (공통 키로 매칭 후 부분 교차만 가능)

### 방식 3. 노출 위치만 (제한적)

기존 추출 방식. 인구통계 분석 모듈 비활성화됨.

---

## B.2 추출 시 포함 권장 차원

메타 광고관리자에서 보고서 추출 시 다음 차원을 포함하는 것을 권장합니다:

- 노출 위치 (Placement)
- 연령 (Age)
- 성별 (Gender)
- 광고 (Ad)

---

## B.3 12 필수 컬럼 자동 인식 (SPEC §3.4 직접 인용)

| 한국어 컬럼명 | 영어 컬럼명 | 용도 |
|-------------|-----------|------|
| 보고 시작 | Reporting starts | 기간 인식 |
| 보고 종료 | Reporting ends | 기간 인식 |
| 광고 이름 | Ad name | 광고 식별 |
| 노출 위치 | Placement | 지면 분석 |
| 연령 | Age | 인구통계 분석 |
| 성별 | Gender | 인구통계 분석 |
| 지출 금액 | Amount spent | 비용 분석 |
| 링크 클릭 | Link clicks | 트래픽 분석 |
| CTR | CTR (link CTR) | 효율 분석 |
| CPC | CPC | 효율 분석 |
| 구매 | Purchases | 전환 분석 |
| 구매 전환값 | Purchase conversion value | 매출 분석 |
| 구매 ROAS | Purchase ROAS | 효율 분석 |

> 12개 컬럼 이외에 추가 컬럼이 있는 경우 자동으로 선택 컬럼으로 분류합니다.

---

## B.4 선택 컬럼 (있으면 분석 강화)

| 한국어 | 영어 | 효과 |
|--------|------|------|
| 플랫폼 | Platform | 플랫폼(FB/IG/AN/Threads) 분석 강화 |
| 기기 플랫폼 | Device platform | 모바일/데스크톱 분석 가능 |
| 노출수 | Impressions | 노출 추정 불필요 (직접 값 사용) |
| 도달수 | Reach | 빈도(Frequency) 분석 가능 |
| 빈도 | Frequency | 광고 피로도 분석 |
| 기여 설정 | Attribution setting | 어트리뷰션 창 명시 |

---

## B.5 컬럼 누락 처리 4룰 (SPEC §3.4 직접 인용)

1. **필수 컬럼 누락** → 명확한 오류 메시지 출력 + 가능한 분석 항목만 진행
2. **연령·성별 컬럼 없음** → 인구통계 분석 모듈(모듈 3 일부 + 모듈 4 일부) 비활성화 + 사용자에게 명시
3. **자동 매핑 실패** (컬럼명 인식 불가) → 사용자에게 컬럼명 확인 요청
4. **노출수 컬럼 없음** → CTR 기반 추정 공식 사용 (`노출 = 클릭 / (CTR / 100)`), CTR=0인 행은 제외

---

## B.6 컬럼 자동 매핑 로직

스킬은 다음 순서로 컬럼 매핑을 시도합니다:

1. **한국어 정확 일치**: 위 B.3 표의 한국어 컬럼명 그대로 검색
2. **영어 정확 일치**: 위 B.3 표의 영어 컬럼명 그대로 검색
3. **부분 일치 (Fuzzy)**: 핵심 키워드 포함 여부로 매핑
   - "spent" 포함 → 지출 금액
   - "ROAS" 포함 → 구매 ROAS
   - "purchase" + "value" 포함 → 구매 전환값
4. **매핑 실패 시**: 사용자에게 해당 컬럼명을 직접 알려달라고 요청

---

## B.7 정합성 자동 검증 항목

컬럼 매핑 완료 후 다음 6개 항목을 자동 검증합니다 (상세: 부록 H.1):

1. 보고 기간 일관성 (파일 내·파일 간)
2. 필수 컬럼 존재 여부
3. 수치 범위 합리성 (음수 ROAS, 0 노출 등 이상값)
4. 결측치 비율 (과도한 결측치 경고)
5. 중복 행 감지
6. 인구통계 컬럼 일관성 (연령·성별 컬럼이 일부 행에만 있는 경우)
