인천공항 주차장 예측 대시보드 상세 계획

공식 주차 API를 바탕으로 짠 계획입니다. 계획을 세우면서 모델 입력으로 쓸 추가 공공 API 두 개(시간대별 예상 승객 수, 공휴일)도 확인했습니다.

0. 목표와 성공 기준

대시보드가 답할 질문: "내가 ○시에 도착하면 어느 주차장에 자리가 있을까?", 그리고 "그 예측은 실제로 얼마나 맞았나?"

초기 목표치 (4주 운영 후 실제 데이터로 다시 정합니다) → 우선은 모으는 것에 집중합니다. 아래는 임의로 지정한 지표와 목표입니다.

1. 데이터 소스

공공데이터포털 서비스키 하나로 아래 API를 모두 신청할 수 있습니다.

• 합계가 하루 약 350회라서 개발 계정(주차·승객예고 API는 하루 1,000회) 안에 들어옵니다. 공개할 때는 운영 계정으로 올립니다.
• 예상 승객 수가 중요한 이유: 연휴·명절 효과를 주차 데이터만으로 배우려면 1년이 필요합니다. 공항공사가 매일 내는 오늘·내일 예상 승객 수를 넣으면 첫 연휴부터 대응할 수 있습니다.

구역 유형별로 움직이는 방식이 다릅니다.

• 장기주차장·주차타워는 며칠에 걸쳐 차가 쌓입니다. 연휴 전에 차오르고 연휴가 끝나면 빠집니다. 그래서 "지난 3일 출국 승객 − 입국 승객" 같은 누적 값을 입력으로 씁니다.
• 단기주차장은 몇 시간 단위로 들고 납니다. 시간대별 출국 승객 수를 입력으로 씁니다.

2. 아키텍처 (Azure, MCAP 구독)

flowchart LR
  API["data.go.kr<br/>주차 · 승객예고 · 특일"] --> C["collect<br/>5분"]
  API --> X["exog<br/>1시간"]
  C --> RAW[("Blob raw/<br/>원본 JSON")]
  C --> OBS[("Blob obs/<br/>일별 JSONL")]
  X --> EXO[("Blob exog/")]
  OBS --> FC["forecast<br/>15분"]
  EXO --> FC
  FC --> FCS[("Blob forecasts/<br/>발행분 불변 저장")]
  FCS --> EV["evaluate + publish<br/>1시간 · 매일"]
  OBS --> EV
  EV --> PUB[("public/*.json")]
  C --> PUB
  PUB --> WEB["Static Web Apps<br/>ECharts 대시보드"]
  C -.-> AI["App Insights<br/>20분 무수집 알림"]

비용은 합쳐서 월 $1~5 정도로 추정합니다.

이렇게 짠 이유

• 방문자는 미리 계산해 둔 JSON만 읽습니다. 사람이 몰려도 공공 API 호출 한도나 계산 비용에 영향이 없습니다.
• 데이터가 하루 약 5,500행(19개 구역 × 288회)으로 작습니다. 그래서 DB 없이 일별 JSONL 파일을 DuckDB로 바로 읽는 구조로 충분합니다.

검토했지만 뺀 선택지

먼저 확인할 위험: MCAP 구독에 Blob 공개 접근을 막는 정책이 걸려 있을 수 있습니다. 그렇다면 Function의 HTTP 엔드포인트가 managed identity로 Blob을 읽어 JSON을 캐시와 함께 내주는 방식으로 바꿉니다. 0단계에서 확인합니다.

3. 데이터 모델

• 첫 구역 목록은 19개입니다(현재 외부 사이트 기준, 1단계 첫 응답으로 확정).
  • T1 10개: 단기 지하1·2·3층·지상층, 장기 P1·P2·P3, P1·P2 주차타워, P5 예약
  • T2 9개: 단기 지하M층·지상1~4층, 장기, P1·P2 주차타워, 예약
• 예약주차장은 일반 이용자 추천에서 따로 분리합니다.

4. 수집기 (collect, 5분마다)

1. numOfRows=100, type=json으로 호출합니다. 타임아웃은 10초, 실패하면 2초·5초·10초 간격으로 세 번까지 다시 시도합니다.
2. 받은 응답을 그대로 raw/parking/YYYY/MM/DD/HHmm.json에 저장합니다. 나중에 가공을 다시 하거나 점검할 때 씁니다.
3. 정리 과정
   • 구역 이름(floor)을 구역 목록과 맞춥니다. 목록에 없는 이름이 나오면 알림을 보냅니다(신규 주차장이나 이름 변경 감지).
   • 가용 대수와 점유율을 계산합니다. 총 면수가 0이면 미운영으로 처리합니다.
4. 품질 표시
   • STALE: 원본 갱신 시각이 직전과 같음 (원천 데이터가 멈춤)
   • OVER: 주차 대수가 총 면수보다 많음
   • CAPCHANGE: 총 면수가 바뀜 (공사 등)
   • GAP: 수집이 빠진 구간
5. obs/YYYY/MM/DD.jsonl에 이어 붙이고, 중복은 읽을 때 걸러냅니다. public/latest.json도 갱신합니다.
6. 20분 동안 수집 성공이 없거나 원본 갱신 시각이 30분 동안 멈추면 알림을 보냅니다.

5. 예측 모델 (데이터가 쌓이는 만큼 단계적으로)

예측 대상은 구역별 점유율입니다. 총 면수는 공사 등으로 바뀔 수 있어서, 점유율로 예측한 뒤 가용 대수로 바꿉니다. 발행은 15분마다, 15분 간격으로 24시간 뒤까지입니다.

• 운영 모델 선택: 모든 모델이 예측을 계속 내고, 최근 14일 오차율이 가장 낮은 모델을 대시보드에 보여줍니다. 구역 유형 × 예측 거리별로 따로 고릅니다.
• 예측에서 뽑는 결과
  • 가용 대수 예측
  • 만차 확률: 가용 대수가 50대 또는 총 면수의 3% 중 큰 값보다 적을 확률
  • 도착 시각별 여유 구역 순위: 보수적 값(하위 10%) 기준

6. 예측과 실제 비교

• 예측은 발행 당시 값 그대로 보관합니다. 발행 시각과 모델 버전(git 커밋)을 붙여 저장하고, 나중에 다시 계산해서 덮어쓰지 않습니다. 그래야 "그때 뭐라고 예측했나"를 정직하게 잴 수 있습니다.
• 평가는 1시간마다 합니다. 대상 시각이 지난 예측을 가장 가까운 5분 실측값과 짝지어 비교합니다.
• 지표
  • 평균 오차(%p와 대수 두 가지)
  • 편향: 늘 높게 또는 낮게 예측하는지
  • 오차율
  • 예측 범위 적중률
  • 만차 경보가 맞은 비율과 놓친 비율
• 나눠 보는 기준: 모델, 구역·터미널, 예측 거리(1시간 이내 / 13시간 / 36시간 / 6~24시간), 요일 × 시간
• 특이 상황 기록: 오차가 컸던 날에 연휴, 데이터 누락, 면수 변경을 자동으로 표시합니다. 폭설이나 공사 같은 메모는 annotations.yaml에 직접 적습니다.
• 흐름 변화 감지: 최근 7일 편향이 ±5%p를 넘는 날이 3일 이어지면 알림을 보내고 재학습 대상으로 표시합니다.

7. 대시보드 구성

• 화면은 정적 HTML과 Apache ECharts로 만듭니다. 히트맵, 달력, 범위 띠를 그대로 지원합니다. 모바일을 먼저 생각하고, 필요하면 한/영 전환을 넣습니다.
• 대시보드가 읽는 JSON 파일

8. 저장소 구조

icn-parking-forecast/
  infra/        Bicep (main + modules)
  functions/    function_app.py, collect/, exog/, features/, models/, evaluate/, publish/
  web/          index.html, app.js, charts/, i18n/
  config/       zones.yaml, annotations.yaml
  notebooks/    데이터 탐색
  tests/
  .github/workflows/  infra.yml, functions.yml, web.yml

9. 일정

⚠️ 1단계를 서두를 이유: 과거 데이터는 나중에 소급해서 받을 수 없습니다. 이번 주말 개천절 연휴(10/35)나 한글날 연휴(10/911) 전에 수집을 시작해야 첫 연휴 자료를 확보할 수 있습니다.

10. 위험 요소와 대응

11. 결정할 사항 (괄호 안이 제가 권하는 기본값)

1. 공개 범위 (외부 전체 공개)
2. 배포할 구독 (기존 SWA와 같은 MCAP 구독)
3. 예측 간격 (15분)
4. 언어 (한국어 먼저, 영어는 5단계)

계획은 세션의 plan.md에 저장했고, 이 프로젝트 내용은 기억해 두었습니다. 1단계를 서둘러야 하는 만큼 다음 진행 방식을 골라 주세요. API 키는 공공데이터포털에 로그인해서 직접 발급받으셔야 하고, 나머지 코드와 인프라는 제가 준비할 수 있습니다.