# 인천공항 주차 예측 대시보드 — 실행 계획

> 최종 갱신: 2026-10-01 KST · 상태: 0단계 대기 (data.go.kr 서비스키 발급 필요)

## 1. 목표

- 과거 요일×시간 패턴으로 **다가오는 시간대**의 주차 여유를 예측한다.
- 발행 시점에 고정한 예측과 실제를 계속 비교해 정확도·편향·흐름 변화를 추적한다.
- 공개 웹 대시보드로 누구나 미리 참고하고 움직일 수 있게 한다.

### 성공 기준 (초기 가설, 4주 운영 후 재설정)

| 지표 | 목표 |
|---|---|
| 1시간 앞 점유율 예측 평균 오차 | ≤ 3%p |
| 3시간 앞 점유율 예측 평균 오차 | ≤ 5%p |
| 예측 범위(P10–P90) 적중률 | ≈ 80% |
| 만차 경보 재현율 | ≥ 80% |
| 수집 가용성 | ≥ 99% / 월 |

## 2. 데이터 소스 (data.go.kr, 서비스키 1개)

| 용도 | 엔드포인트 | 주기 | 호출/일 |
|---|---|---|---|
| 목표변수: 구역별 주차대수·총면수 | `https://apis.data.go.kr/B551177/StatusOfParking/getTrackingParking` | 5분 | 288 |
| 선행지표: 시간대별 예상 출·입국 승객 (D, D+1) | `https://apis.data.go.kr/B551177/passgrAnncmt/getPassgrAnncmt` | 1시간 | ~48 |
| 공휴일·연휴 | `https://apis.data.go.kr/B090041/openapi/service/SpcdeInfoService/getRestDeInfo` | 월 1회 | ~0 |
| (선택) 날씨 | 기상청 단기예보 (data.go.kr 15084084) | 3시간 | 8 |

- 주차 API 요청: `serviceKey`, `numOfRows=100`, `pageNo=1`, `type=json`
- 주차 API 응답: `floor`(구역명), `parking`(주차대수), `parkingarea`(총면수, 0=미운영), `datetm`(`yyyyMMddHHmmss.fff`, KST)
- 조회 당일 현재값만 제공 → **과거 데이터 소급 불가, 수집을 최대한 빨리 시작**
- 개발계정(1,000회/일)으로 충분. 공개 시 운영계정(활용사례 등록, 자동승인)으로 전환
- 승객예고 데이터를 화면에 노출하면 인천공항공사 관리부서와 안내문구 협의 필요 (모델 입력으로만 쓰면 부담 적음)

### 구역 유형별 특성

- 장기주차장·주차타워: 며칠 단위로 쌓이는 **재고형** → 최근 3일 누적(출국 − 입국 예상 승객)이 핵심 입력
- 단기주차장: 시간 단위 **흐름형** → 시간대별 출국 예상 승객이 핵심 입력
- 예약주차장: 일반 이용자 추천에서 분리

## 3. 아키텍처

```mermaid
flowchart LR
  API["data.go.kr<br/>주차 · 승객예고 · 특일"] --> COL["collect<br/>5분"]
  API --> EXO["exog<br/>1시간"]
  COL --> PRIV[("Blob private<br/>raw · obs · exog<br/>forecasts · accuracy · model")]
  EXO --> PRIV
  PRIV --> FC["forecast<br/>15분"]
  FC --> PRIV
  PRIV --> EV["evaluate 1시간<br/>profile 매일"]
  EV --> PRIV
  COL --> WEB[("Blob $web<br/>대시보드 + data/*.json")]
  FC --> WEB
  EV --> WEB
  WEB --> U["브라우저"]
```

| 구성 | 선택 | 비고 |
|---|---|---|
| 실행 | Azure Functions Flex Consumption, Python 3.12, 인스턴스 2,048MB | TZ 설정 미지원 → CRON은 UTC 기준. 실행당 최소 1초 과금 |
| 저장 | Storage Account (StorageV2, Hot, LRS, Korea Central) | private 컨테이너 + `$web` 정적 웹사이트 |
| 서빙 | Storage 정적 웹사이트 (`$web`) | 대시보드와 데이터가 같은 출처 → CORS 불필요 (정적 웹사이트는 CORS 미지원). `$web`은 익명 접근 차단 설정과 무관하게 항상 공개 |
| 비밀 | Key Vault | data.go.kr 서비스키, Function managed identity로 참조 |
| 모니터링 | Azure Monitor 메트릭 알림 2개 + App Insights 최소 설정 | §10 |
| 비용 통제 | Budget 알림 $5 / $10 | |
| 배포 | GitHub + Actions(OIDC) + Bicep | 구독: MCAP, 지역: Korea Central |
| 이번 범위 제외 | Cosmos DB, Static Web Apps, CDN | §14 결정 기록 |

### 함수와 스케줄

| 함수 | CRON (UTC, 6필드) | KST | 역할 |
|---|---|---|---|
| `collect` | `0 */5 * * * *` | 5분마다 | 주차 API 수집 → raw, obs, `$web/data/latest·today` |
| `exog` | `0 5 * * * *` | 매시 05분 | 승객예고 D/D+1 수집, 매월 1일 특일 갱신 |
| `forecast` | `0 2/15 * * * *` | 02·17·32·47분 | 모델 실행 → forecasts(불변 저장), `$web/data/forecast` |
| `evaluate` | `0 10 * * * *` | 매시 10분 | 대상 시각이 지난 예측 vs 실측 → accuracy, `$web/data/accuracy` |
| `profile` | `0 30 18 * * *` | 매일 03:30 | 최근 8주 요일×슬롯 통계 → `model/profile.json`, `$web/data/pattern·history` |

## 4. 저장소 레이아웃

### private 컨테이너

```
raw/parking/YYYY/MM/DD/HHmm.json         호출별 원본 + {http_status, result_code, latency_ms, error}  (PutBlob)
raw/passenger/YYYY/MM/DD/HH.json         승객예고 원본                                             (PutBlob)
obs/YYYY/MM/DD.jsonl                     정규화 실측, 수집 성공 시에만 append                        (AppendBlock, 유일)
exog/passenger/YYYY/MM/DD.json           승객예고 정규화, 하루 파일 덮어쓰기                          (PutBlob)
exog/calendar/YYYY.json                  공휴일·연휴 블록                                          (PutBlob)
forecasts/YYYY/MM/DD/HHmm.json.gz        발행분 불변 저장, 덮어쓰기 금지                             (PutBlob)
accuracy/YYYY/MM/DD.json                 일별 정확도 집계                                          (PutBlob)
model/profile.json                       요일×15분 슬롯 통계, forecast가 읽음                        (PutBlob)
```

- `AppendBlock`은 `obs/`에서만 사용한다 → 적재 중단 알림의 기준 신호 (§10)
- 규모: 실측 5,472행/일, 예측 발행 96회/일 × 19구역 × 96시점, 1년 누적 약 3GB 이하
- 필요 시 월 1회 obs를 Parquet으로 압축 (선택)

### `$web` 컨테이너 (공개)

| 경로 | 갱신 | Cache-Control | 내용 |
|---|---|---|---|
| `index.html`, `app.js`, `style.css` | 배포 시 | `max-age=300` | 대시보드 |
| `data/latest.json` | 5분 | `public, max-age=60` | 구역별 최신값, 마지막 수집 시각, stale 여부 (~3KB) |
| `data/today.json` | 5분 | `public, max-age=60` | 오늘 5분 단위 실측 (~20KB) |
| `data/forecast.json` | 15분 | `public, max-age=300` | 앞으로 24시간 예측, P10/P50/P90, 만차 확률 (~15KB) |
| `data/accuracy.json` | 1시간 | `public, max-age=3600` | 정확도 지표 |
| `data/pattern.json` | 매일 | `public, max-age=3600` | 요일×시간 통계 |
| `data/history.json` | 매일 | `public, max-age=3600` | 일별 최고·평균 점유율 |

- 모든 데이터 JSON은 gzip으로 저장하고 블롭 속성 `Content-Encoding: gzip`, `Content-Type: application/json` 지정
- 크기는 압축 후 기준
- 브라우저는 5분 경계 + 45초에만 갱신, `pattern`·`accuracy`·`history`는 해당 탭을 열 때만 로드
- 데이터 기본 URL은 설정값 하나로 둔다 → CDN 전환 시 코드 변경 없음

## 5. 데이터 모델

| 엔터티 | 주요 필드 |
|---|---|
| `zones` (repo `config/zones.yaml`) | zone_id, terminal(T1/T2), category(단기/장기/타워/예약), raw_names(별칭), active_from, active_to |
| `observations` | slot_ts_kst(5분 내림), zone_id, parking, capacity, available, occupancy, source_ts(datetm), collected_at_utc, flags |
| `raw_calls` | collected_at_utc, http_status, result_code, latency_ms, error, blob_path |
| `calendar` | date, dow, is_holiday, holiday_name, block_id, day_in_block, days_to_block, days_from_block |
| `exog_passenger` | date, hour, terminal, dep_expected, arr_expected, fetched_at |
| `forecasts` | issued_at, model, model_version(git SHA), zone_id, target_ts, horizon_min, p10, p50, p90, available_p50, full_prob |
| `accuracy` | date, model, zone_id/terminal/category, horizon_bucket, dow, hour, mae_pp, mae_cars, bias, wape, coverage, n |

### 초기 구역 (19개, 1단계 첫 응답으로 확정)

- T1 (10): 단기 지하1층·지하2층·지하3층·지상층, 장기 P1·P2·P3, 장기 P1 주차타워·P2 주차타워, P5 예약주차장
- T2 (9): 단기 지하M층·지상1층·지상2층·지상3층·지상4층, 장기 주차장, P1 장기주차타워·P2 장기주차타워, 예약주차장

## 6. 수집기 (`collect`)

1. 주차 API 호출 (`numOfRows=100`, `type=json`), 타임아웃 10초, 재시도 3회 (2초·5초·10초)
2. 원본 + 호출 메타(상태·결과코드·지연·에러)를 `raw/parking/...` 에 PutBlob (실패해도 저장)
3. 정규화
   - `floor` → zone_id 매핑 (공백 제거, 별칭). 미등록 구역명 → 경고 로그 + `unknown_zone` flag
   - available = max(capacity − parking, 0), occupancy = parking / capacity, capacity=0 → 미운영(null)
4. 품질 플래그: `STALE`(datetm 직전과 동일), `OVER`(parking > capacity), `CAPCHANGE`(총면수 변경), `GAP`(누락 구간)
5. 성공 시에만 `obs/YYYY/MM/DD.jsonl` 에 append (중복은 읽을 때 slot+zone 기준 제거)
6. `$web/data/latest.json`, `today.json` 갱신 (datetm 30분 이상 정체 시 `stale: true`)
7. 시각: slot_ts는 KST 5분 내림, 원본 `datetm`과 UTC 수집 시각 모두 보존

## 7. 예측 모델

- 예측 대상: 구역별 점유율 → 최신 총면수로 가용 대수 환산
- 발행: 15분마다, 15분 해상도, 24시간 앞까지
- 터미널·유형 합계는 면수 가중 합산

| 모델 | 방법 | 사용 가능 시점 |
|---|---|---|
| M0 | 지난주 같은 요일·같은 시각 (벤치마크) | 1주 후 |
| M1 | 최근 4~8주 같은 요일·15분 슬롯 가중 중앙값 + 잔차 기반 P10/P90 | 2주 후 (4주 후 안정) |
| M1b | M1 × (당일 예상 승객 ÷ 같은 요일 평균 예상 승객) | 2주 후, 연휴 대응 |
| M2 | M1 + 현재 편차 Δ를 horizon에 따라 감쇠 (Δ·φ^h, φ는 구역 유형별 학습) | 2주 후, 단기 nowcast 핵심 |
| M3 | LightGBM 분위수 회귀 (슬롯, 요일, 연휴 블록, 승객예고, 래그: 현재·1시간 전·어제·지난주) | 8~12주 후 |

- 챔피언: 최근 14일 WAPE 최저 모델을 구역 유형 × horizon 버킷별로 선택, 나머지는 도전자로 계속 발행
- 파생 출력
  - 가용 대수 예측 (P50, 보수적 P10)
  - 만차 확률: P(가용 < max(50대, 총면수 3%))
  - 도착 시각별 여유 구역 순위 (P10 기준)
- 예측 작업은 `model/profile.json` + 오늘 실측 + 승객예고만 읽는다 (8주 재스캔 금지)

## 8. 정확도 추적

- 모든 예측은 발행 시각·모델 버전과 함께 불변 저장, 재계산으로 덮어쓰지 않음
- `evaluate`가 매시 대상 시각이 지난 예측을 가장 가까운 5분 실측(±5분)과 조인
- 지표: 평균 오차(%p, 대수), 편향, WAPE, P10–P90 적중률, pinball loss, 만차 경보 정밀도·재현율
- 분할: 모델 × 구역/터미널/유형 × horizon 버킷(≤1h, 1–3h, 3–6h, 6–24h) × 요일 × 시간
- 이례일 로그: 오차 상위 사례에 연휴·데이터 누락·면수 변경 자동 주석 + `config/annotations.yaml` 수동 메모
- 드리프트: 7일 편향이 ±5%p를 3일 연속 초과 → 경고 로그 + 재학습 플래그

## 9. 대시보드

| 페이지 | 내용 |
|---|---|
| 앞으로 24시간 (메인) | T1/T2 탭, 유형별 차트: 오늘 실측(실선) + 예측 P50(점선) + P10–P90 밴드 + 현재 시각선, 만차 위험 구간 강조. 도착 시각 선택 → 여유 예상 구역 순위, 만차 확률, 최근 정확도 기반 신뢰도 |
| 요일×시간 패턴 | 최근 8주 7×24 히트맵 (점유율 / 만차 확률 / 가용 대수), 요일별 하루 곡선 비교 |
| 예측 정확도 | 어제·오늘 예측 vs 실제, horizon별 오차 추이, 요일×시간 오차 히트맵, 모델 비교, 이례일 로그 |
| 장기 추이 | 일별 최고 점유율 달력 히트맵, 연휴 D-3~D+3 겹쳐 보기, 주간 평균 추이 |
| 방법·출처 | 출처 "인천국제공항공사, 공공데이터포털", 비공식 서비스·예측값 안내, 수집률, 마지막 수집 시각 |

- 기술: 정적 HTML/JS + Apache ECharts, 빌드 도구 없음, 모바일 우선
- 언어: 한국어 우선 (영어는 5단계)

## 10. 모니터링·알림

| 대상 | 방법 | 조건 | 비용 |
|---|---|---|---|
| 데이터 적재 중단 (앱 중단 + API 실패 모두) | Storage 메트릭 `Transactions`, `ApiName = AppendBlock` | 15분 합계 < 1 → 이메일 | ~$0.1/월 |
| 앱 미실행 | Function 메트릭 `OnDemandFunctionExecutionCount` | 20분 합계 < 3 → 이메일 | ~$0.1/월 |
| 원천 데이터 정지 | `latest.json`의 `stale` + 대시보드 "마지막 수집 N분 전" 배지 | datetm 30분 정체 | $0 |
| 코드 예외 | App Insights 최소 설정: 로그 Warning 이상, 샘플링, 일일 상한 50MB, 대시보드·워크북 없음 | — | $0~1/월 |
| 비용 | Budget 알림 | $5 / $10 | $0 |

## 11. 비용 추정 (Korea Central 정가, 2026-10-01 Retail Prices API)

### 단가

| 항목 | 단가 |
|---|---|
| Blob Hot LRS 저장 | $0.02 / GB·월 |
| Blob 쓰기 | $0.05 / 1만 건 |
| Blob 읽기 | $0.004 / 1만 건 |
| 인터넷 전송 | 월 100GB 무료, 이후 $0.11 / GB |
| Functions Flex 실행 | $0.000037 / GB·s (무료 제공량 있음), 실행 $0.40 / 100만 건 |
| Log Analytics 수집 | $3.11 / GB |
| (참고) Cosmos 서버리스 | $0.271 / 100만 RU, 저장 $0.25 / GB·월 |
| (참고) Front Door Standard | 기본료 $35 / 월, 요청 $1.08 / 100만 건, 전송 $0.115 / GB |

### 월 추정 (1년차)

| 항목 | 월 비용 |
|---|---|
| Functions (약 1.3만 실행, 전부 과금 시 약 7.8만 GB·s) | $0 ~ 3 |
| Blob 쓰기 (약 4만 건) | $0.2 |
| Blob 내부 읽기 | $0.06 |
| Blob 저장 (연말 약 3GB) | $0.06 |
| 방문자 서빙 (하루 1만 방문, gzip) | $0.4 |
| Key Vault, 메트릭 알림 2개 | $0.25 |
| App Insights | $0 ~ 1 |
| **합계** | **약 $1 ~ 5** |

### 방문자 수별 서빙 비용 (방문당 파일 3개, gzip 약 50KB)

| 하루 방문 | Blob 직접 | Front Door Standard |
|---|---|---|
| 1천 | $0.04 | 약 $35 |
| 1만 | $0.4 | 약 $38 |
| 10만 (한 달 지속 가정) | 약 $9 | 약 $62 |
| 10만, 압축 안 함 | 약 $75 | — |

## 12. 단계별 일정

| 단계 | 기간 | 산출물 | 완료 기준 |
|---|---|---|---|
| **0단계** | 10/1 | 서비스키 발급(주차·승객예고·특일), 첫 응답으로 구역 마스터 확정, 리소스 그룹·구독 확정 | 실제 응답 수신 |
| **1단계 (최우선)** | 10/1~10/2 | Bicep 인프라, `collect`, raw/obs 저장, `latest·today.json`, 메트릭 알림 2개, App Insights 최소, 예산 알림 | 24시간 288/288 슬롯 수집. 10/3 연휴 전 가동 |
| 2단계 | 1~2주 | 대시보드 v0 (오늘 실측 + 어제·지난주 겹쳐 보기, 수집 현황), `exog`, M0 발행 시작 | `$web` 공개 URL 접속 가능 |
| 3단계 | 2~4주 | `profile`, M1·M1b·M2, `evaluate`, 정확도 페이지, 요일×시간 히트맵, 운영계정 신청 | horizon별 정확도 매일 갱신 |
| 4단계 | 6~12주 | M3, 만차 확률 보정, 7일 전망 | 챔피언이 M0 대비 WAPE 20% 이상 개선 |
| 5단계 | 3개월~ | 장기 추이·연휴 비교, 전날 밤 "내일 만차 위험" 요약, 영어 | 연휴 3회 이상 평가 |

- 10월 연휴(10/3~5 개천절·대체공휴일, 10/9~11 한글날) 전에 1단계를 가동해야 첫 연휴 샘플을 확보한다.

## 13. 위험과 대응

| 위험 | 대응 |
|---|---|
| API 장애·지연 | 재시도, GAP 플래그, 적재 중단 알림, 대시보드 지연 배지 |
| 구역 구성 변경 (신규 주차장, 공사) | 미등록 구역명 경고, CAPCHANGE 플래그, zones 이력 관리 |
| 연휴 데이터 부족 | M1b 승객예고 스케일링, 1년 후 연휴 전용 모델 |
| 예측을 공식 정보로 오인 | "비공식·예측값" 안내, 승객예고 노출 시 공항공사 협의 |
| 개발계정 한도·만료 | 공개 시점에 운영계정 전환 |
| 트래픽 급증·악용 | gzip, Cache-Control, 예산 알림. 기준 초과 시 CDN 전환 (§14 D4) |
| Flex 제약 | TZ 미지원 → CRON UTC, 앱 초기화 30초 제한 → 무거운 import 지연 로딩 |

## 14. 결정 기록

| # | 날짜 | 결정 | 근거 |
|---|---|---|---|
| D1 | 10/1 | 저장소는 Blob 단독 (JSONL·JSON·gzip) | 시계열 append + 범위 통째 읽기 + 정적 배포 패턴. Blob 월 $0.5 미만 vs Cosmos 잘 설계 $1.5~2.5, 단순 설계 $80~250 |
| D2 | 10/1 | Cosmos 병행 보류 | 같은 데이터 이중 쓰기로 비용 절감 없이 복잡도만 증가. 방문자 API 경로는 Function 최소 1초 과금으로 Blob 대비 수십 배. 사용자 기능(알림 구독·즐겨찾기·피드백) 도입 시 그 부분만 Cosmos 서버리스. 저장소 접근은 인터페이스로 분리 |
| D3 | 10/1 | 서빙은 Storage 정적 웹사이트 `$web` (SWA 제외) | 같은 출처라 CORS 불필요, 익명 접근 차단 정책과 무관, 추가 비용 없음 |
| D4 | 10/1 | CDN 보류, CDN-ready 설계 | Front Door 기본료 $35가 전체 비용보다 큼. 전환 기준: 월 전송 100GB 초과 지속, 악용 트래픽, 커스텀 도메인+HTTPS 필요 → Front Door Standard 또는 Cloudflare 무료. Azure CDN classic은 2025-08-15부터 신규 생성 불가 |
| D5 | 10/1 | App Insights 최소 설정 | 분석·대시보드 불필요. 수집 중단 감지는 메트릭 알림으로 해결, App Insights는 코드 예외 기록용 |
| D6 | 10/1 | 예측 15분 발행, 15분 해상도, 24시간 앞 | 다가오는 시간대 중심, 저장량 부담 적음 |
| D7 | 10/1 | MCAP 구독, Korea Central | 데이터·사용자 모두 국내 |

## 15. 다음 행동

- [ ] (사용자) data.go.kr 활용신청: 인천국제공항공사_주차 정보(15095047), 승객예고-출·입국장별(15095066), 한국천문연구원_특일 정보(15012690)
- [ ] (사용자) 구독·리소스 그룹 이름 확정
- [ ] 첫 응답으로 `config/zones.yaml` 확정
- [ ] 1단계 착수: repo 생성 → Bicep → `collect` → 알림 → 배포 → 24시간 검증

## 16. 저장소 구조 (repo)

```
icn-parking-forecast/
  infra/                 main.bicep, modules/ (storage, function, keyvault, monitor, budget)
  functions/             function_app.py, collect/, exog/, forecast/, evaluate/, profile/, common/storage.py
  web/                   index.html, app.js, style.css, charts/
  config/                zones.yaml, annotations.yaml
  notebooks/             탐색 분석
  tests/
  .github/workflows/     infra.yml, functions.yml, web.yml
```