---
name: 2-collect
description: 분석 4단계의 ② 수집. 데이터를 확보하고 분석 가능한 상태로 다듬을 때 사용한다. "전처리해줘", "CSV 다듬어줘", "데이터 정리해줘", "데이터 어디서 구해", "공공데이터 받아줘", "네이버 데이터랩", "엑셀 내보냈는데", 한글이 깨져 보임, 날짜·숫자가 문자로 들어온 컬럼, 결측·중복 확인이 필요한 상황.
---

# ② 수집 — 확보 + 정리

분석 4단계의 두 번째. **확보**(어디서 가져오나)와 **정리**(분석 가능하게 다듬기)를 한 단계로 묶는다. 전처리는 결과를 바꾸므로, 바꾼 내역이 남지 않으면 분석을 재현할 수 없다.

**산출물**: `data/clean/` + `collection_report.md` + `preprocessing_report.html`
**앞 단계**: `datapopcorn-analysis:1-hypothesis` (가설) — `hypothesis.md`가 없으면 먼저 그쪽으로
**다음 단계**: `datapopcorn-analysis:3-suspect` (EDA·함정)

---

## 경로 / 스크립트 (고정)

| 무엇 | 경로 |
|---|---|
| 입력 | `input/` (사용자가 넣은 파일) 또는 `data/raw/` (수집 스크립트 산출물) |
| 출력 | `data/clean/` |
| 보고서 | `collection_report.md`(확보) · `preprocessing_report.html`(정리) |
| 스크립트 | `1_collect.py`(확보) · `2_preprocess.py`(정리) |

`input/`과 `data/raw/` 둘 다 있으면 둘 다 읽고 출력 파일명으로 구분한다. 형식(CSV·Excel·JSON) 무관.

---

## 확보 — 데이터는 보통 어딘가에 있다

없다고 느끼는 건 대개 분석을 안 해봐서다. 세 패턴 중 하나:

| 상태 | 어디에 | 할 일 |
|---|---|---|
| 플랫폼에 갇힘 | 스마트스토어·GA·인스타·인프런·CRM | **내보내기(CSV)** → `input/` |
| 흩어져 있음 | 메일·카톡·메모 | "표로 만들어줘" → 비정형에서 항목 추출 → CSV |
| 엑셀에 지저분 | 구글시트·엑셀 | 그대로 `input/` → 정리에서 처리 |
| 아직 없음 | 외부 소스 | `references/data-sources-korea.md` 참고해 `1_collect.py` |

### 한 소스로는 부족하다

가능하면 세 종류 신호를 엮는다: **관심**(검색·조회·문의) + **실제**(구매·방문·계약) + **동인**(캠페인·정책·이벤트·날씨).
관심만으로 결론 내면 ③의심 단계에서 지표 대리 오류에 걸린다.

### 외부 수집일 때만
소스 카탈로그·API 스크립트 패턴 → **`references/data-sources-korea.md`**
- 키는 `.env` → `os.environ`. **코드 하드코딩 금지**, `.env`는 `.gitignore`에
- 민감정보(실명·연락처)는 빼고 넣는다. 연습이면 가상 데이터로 흐름부터

### collection_report.md — 받는 즉시 기록

```markdown
# 수집 기록
- 소스: CRM 문의 관리표 (수동 내보내기)
- 조회일: 2026-08-11
- 기간: 2025-01 ~ 2026-07
- 행수: 1,284 / 컬럼: 12
- 결측: 견적일 8.2%, 담당자 0%
- 알려진 한계: 취소 건이 삭제돼 있어 유실 사유 추적 불가
```

출처·조회일·기간·한계를 안 적으면 나중에 같은 숫자를 재현할 수 없다.

---

## 정리 규칙

1. **인코딩** — CSV는 `utf-8-sig`로 읽고 저장한다. 실패하면 `cp949` → `utf-8` 순서로 재시도하고, 어느 인코딩으로 읽혔는지 로그에 남긴다.
2. **타입 변환** — 날짜·숫자 컬럼의 타입을 변환한다. 명세와 실제 포맷이 다르면 로그에 남긴다. 숫자에 섞인 쉼표·단위 문자(`1,234`, `12%`, `3건`)는 제거 후 변환하고, 제거한 패턴을 기록한다.
3. **결측** — 컬럼별 결측 비율을 계산해 기록한다. **행을 임의로 버리지 않는다.** 버려야 하면 사유와 건수를 로그에 남긴다.
4. **중복** — 완전중복 행 수를 기록한다. 키가 있으면 키 기준 중복도 함께. 제거 여부는 사유와 함께 기록한다.
5. **파생 컬럼** — 분석 단위에 맞춰 만든다. 일 단위 데이터면 요일·평일/주말·월, 월 단위면 연도·월·분기. 적용 불가하면 사유를 로그에 남긴다.
6. **기초통계는 측정값 컬럼에만** — 평균·표준편차·사분위는 측정값에만. 날짜·연도·월·분기·ID 같은 시간·구분 컬럼은 **범위(min~max)·고유값 수·중복 수**만 기록한다. 날짜의 평균 같은 무의미한 통계 금지.
7. **원본 불변** — `input/`·`data/raw/`의 파일을 덮어쓰지 않는다. 항상 `data/clean/`에 새로 쓴다.

### 이상치는 지우지 않는다

이상치를 조용히 제거하면 함정이 사라진 게 아니라 숨는다.

- 이상치는 **표시만** 한다 (플래그 컬럼 또는 로그).
- 제거는 사용자가 사유를 확인한 뒤에만. 제거하면 건수와 사유를 보고서에 적는다.
- **판단은 다음 단계(③ 의심)의 일이다.**

---

## preprocessing_report.html — 반드시 들어갈 것

```
1. 읽은 파일 목록 + 감지된 인코딩 + 원본 행수·컬럼수
2. 변환 로그 (컬럼별: 무엇을 → 무엇으로, 실패 건수)
3. 결측률 표 (컬럼별 %)
4. 중복 건수 (완전중복 / 키중복)
5. before / after 행수·컬럼수
6. 측정값 컬럼 기초통계 + 시간·구분 컬럼 범위표 (분리해서)
7. 이상치 플래그 요약 (제거했다면 사유·건수)
8. 남은 문제 — 해결 못 한 것. ③의심 단계에서 확인할 목록
```

---

## 강제 규칙

1. **경로·파일명 고정** — 출력 `data/clean/`, 보고서 `collection_report.md`·`preprocessing_report.html`. 이름을 바꾸면 파이프라인 체크포인트가 깨진다.
2. **원본 덮어쓰기 금지**
3. **행 삭제는 로그 필수** — 사유 + 건수
4. **이상치 임의 제거 금지** — 표시만. 판단은 ③
5. **날짜·구분 컬럼에 평균 계산 금지**
6. **출처·조회일 기록** — `collection_report.md` 없이 완료 보고 금지
7. **`.env`로 키 관리** — 하드코딩 금지

---

## 흔한 실패

| 증상 | 원인 | 고치는 법 |
|---|---|---|
| 한글이 `ï¿½`로 보임 | 인코딩 미지정 | `utf-8-sig` → `cp949` 순서로 재시도 |
| 숫자 컬럼이 문자로 남음 | `1,234` 쉼표 | 쉼표·단위 제거 후 변환, 패턴 기록 |
| 나중에 같은 숫자가 안 나옴 | 조회일·기간 미기록 | `collection_report.md` |
| ③에서 이상치가 안 보임 | 정리 단계에서 조용히 삭제 | 플래그만 달고 넘김 |

## 참고 파일

- `references/data-sources-korea.md` — 공공·네이버·트렌드·도메인별 소스 카탈로그 + 수집 스크립트 패턴 (외부 수집할 때만 읽는다)

## 연관 스킬

- 앞 단계: `1-hypothesis` · 다음 단계: `3-suspect`
- 전체를 순서대로 굴리려면: `data-analysis-pipeline`
