# Research Data Schema

> 5개국 × 카테고리별 사업성·수요·규제·물류·경쟁 데이터의 공통 스키마
> 모든 CSV는 이 문서의 규칙을 따른다.

**Last updated**: 2026-04-21
**Owner**: @재근 (협력: @희진, @현상, @CEO)

---

## 원칙

1. **실제 있는 수치만 입력**. 없으면 **공란**으로 둔다. `N/A`, `0`, 추정치 금지.
2. 모든 row에 **source + source_date + confidence** 필수.
3. 원문 통화 유지. 별도 `fx_to_usd` 컬럼으로 환산용 환율 기록.
4. 분기별 갱신 (Q1/Q2/Q3/Q4) — 수치의 `source_date`가 2분기 이상 오래되면 재검증.
5. 공란도 데이터. "해당 조사 우선순위 ↓" 신호로 해석.

---

## 공통 컬럼 정의

### `country`
- 값: `JP`, `US`, `UK`, `AE`, `VN` (UAE = AE는 ISO 3166-1 alpha-2)

### `category`
- **대분류(7)**: `skincare`, `makeup`, `haircare`, `bodycare`, `fragrance`, `innerbeauty`, `tools`
- **소분류(약 20)**: 대분류 + 하위로 `.` 구분

| 대분류 | 소분류 | 전체 코드 |
|---|---|---|
| skincare | cleanser | `skincare.cleanser` |
| skincare | toner | `skincare.toner` |
| skincare | serum | `skincare.serum` |
| skincare | moisturizer | `skincare.moisturizer` |
| skincare | mask_sheet | `skincare.mask_sheet` |
| skincare | sunscreen | `skincare.sunscreen` |
| makeup | base | `makeup.base` |
| makeup | lip | `makeup.lip` |
| makeup | eye | `makeup.eye` |
| makeup | cheek | `makeup.cheek` |
| makeup | nail | `makeup.nail` |
| haircare | shampoo | `haircare.shampoo` |
| haircare | treatment | `haircare.treatment` |
| haircare | styling | `haircare.styling` |
| bodycare | cleanser | `bodycare.cleanser` |
| bodycare | lotion | `bodycare.lotion` |
| bodycare | other | `bodycare.other` |
| fragrance | perfume | `fragrance.perfume` |
| innerbeauty | supplement | `innerbeauty.supplement` |
| tools | device | `tools.device` |

전체 = **20개 소분류**. 대분류 전체 수치를 표기할 때는 `skincare.*`, `makeup.*` 형식 사용.

### `year`, `quarter`
- 연도: 4자리 YYYY
- 분기: `Q1`, `Q2`, `Q3`, `Q4` 또는 `FY`(연간)

### `currency`
- ISO 4217: `JPY`, `USD`, `GBP`, `AED`, `VND`, `KRW`

### `fx_to_usd`
- 해당 row의 `source_date` 기준 1 단위 원통화 → USD 환율
- 예: `JPY`의 `fx_to_usd = 0.00672` → 1 JPY = 0.00672 USD

### `source`
- 출처명. 예: `KOTRA`, `Statista`, `METI`, `Euromonitor`, `Google_Trends`, `Korea_Customs_Service`, `site_check`
- 다중 출처 시 `;` 구분

### `source_url`
- 직접 링크. 없으면 공란. 유료 리포트면 리포트 제목 명시.

### `source_date`
- 출처 자료의 **발행 월**. 형식 `YYYY-MM`.

### `confidence`
- `H`: 공식 통계청·정부 발표·대형 리서치(Euromonitor·Statista Global·NPD·Kantar 등)·관세청
- `M`: 2차 인용·업계 리포트·KOTRA 보고서·일부 기업 연차 보고서
- `L`: 블로그·뉴스 추정치·스니펫·소셜 관찰

### `notes`
- 자유 텍스트. 단위·조건·특이사항 기록.

---

## 빈 셀 처리 규칙

- **공란 유지**. `-`, `N/A`, `0`, `unknown` 모두 금지.
- 엑셀에서 열 때 혼란 없도록 빈 문자열만 허용.

---

## Table별 스키마

개별 CSV 파일의 컬럼 구조는 각 파일 상단 주석 참조:

- `raw_data/market_size.csv` — 국가 × 카테고리 시장 규모
- `raw_data/demographics.csv` — 국가 × 카테고리 × 인구통계
- `raw_data/seasonality.csv` — 국가 × 카테고리 × 월/계절 수요 지수

  **⚠️ 중요 주석 — `demand_index` 컬럼 2가지 의미 혼재**:
  - 타입 A — **진짜 seasonality index** (해당 기간 수요 / 연평균 수요): 예) JP skincare.sunscreen Q2=1.24 (Q2는 연평균의 124%)
  - 타입 B — **YoY 성장률 (1 + growth_rate)**: 예) AE Ramadan 1.20 (전년 동기 대비 +20%, 연평균 비교 아님)
  - row별 `notes` 컬럼에서 어느 타입인지 구분. 분석 리포트 작성 시 **두 타입을 함께 평균 내지 말 것**
  - 향후 데이터 갱신 시 `value_type` 컬럼 추가 검토 (A/B 구분)
- `raw_data/regulations.csv` — 국가 × 카테고리 × 규제
- `raw_data/logistics.csv` — 국가 × 캐리어 × 요율·소요시간
- `raw_data/competitors.csv` — 국가 × 경쟁사 × 지표

---

## 업데이트 프로세스

1. **분기 첫 주**에 모든 CSV의 `source_date`가 2분기 이상 경과한 row 식별
2. 해당 row의 출처 재방문 → 최신 수치 있으면 **새 row 추가** (기존 row 삭제 ❌, 히스토리 유지)
3. `analysis/` 리포트 재생성
4. 변경 로그는 git commit message로

---

## 팀 R&R 기본안

| 영역 | 담당 |
|---|---|
| 시장 규모·인구통계·계절성 (Table 1~3) | @재근 + AI 리서치 |
| 규제 (Table 4) | @희진 (법무 연계 시 @CEO) |
| 물류 (Table 5) | @현상 |
| 경쟁사 (Table 6) | @희진 (MD 관점) + @재근 (IR 관점) |
| 스키마·분석 리포트 | @재근 |