source catalog와 ingestion run

공공데이터 수집에는 출처별 실행 주기, 실패 시 화면 상태, row 수 변화와 마지막 성공 시각을 함께 기록해야 한다.

한강자리는 수집 계획표(source catalog)에 작업과 실행 시점을 정의하고 수집 기록(ingestion run)에 각 실행의 결과를 남긴다. 두 기록을 연결하면 출처별 실패 시점을 확인할 수 있다.

한곳에 모은 수집 대상과 주기

수집 계획표에는 출처 ID, job ID, owner, 역할, interval과 stale 기준 시간을 모아 둔다.

flowchart LR
  Catalog["수집 계획표"] --> Scheduler["워커 스케줄러"]
  Catalog --> Cron["Kubernetes CronJob"]
  Scheduler --> Jobs["주차 / 나들이 / 예측 작업"]
  Cron --> Batch["기준 데이터와 백테스트 작업"]

이 목록에는 다음 성격의 출처가 함께 들어간다.

범주	예
parking master	주차장 기준 데이터 동기화
parking status	실시간 주차 값 polling
outing facility	시설 데이터 수집
outing event	행사 정보 수집
outing notice	공지·통제 정보 수집
realtime context	혼잡도, 날씨, 교통 문맥 수집
forecast	예측 만들기와 backtest

각 작업에는 실행 위치와 함께 화면 값의 근거인지, 최신성에 영향을 주는지와 사용자 화면에 직접 드러나는지를 표시했다.

이 catalog는 외부 출처를 읽어 화면 데이터의 최신성을 바꾸는 작업만 다룬다. 알림 후보 생성과 outbox dispatch는 발송 원장에 속하므로 push worker는 제외했다.

수집 종료 상태의 기록

ingestion run은 수집 작업이 어떻게 끝났는지를 남긴 기록이다.

flowchart LR
  Fetch["출처 가져오기"] --> Write["파싱 · 정규화<br/>도메인 행 upsert"]
  Write --> Observe["수집 실행 기록<br/>상태 · 행 수 · 오류"]
  Observe --> Health["출처 상태<br/>API 최신성"]

한강자리의 outing 수집은 성공하면 다음 값을 남긴다.

출처 ID.
시작 시각과 종료 시각.
성공 여부.
읽은 row 수.
status distribution.
schema hash.
실패 error 요약.

운영자는 이 값으로 parser 실패를 확인한다. API도 출처 확인 결과를 만들어 화면에 “fresh”, “stale”, “unavailable” 상태를 제공한다.

run 기록은 수집 결과 row와 함께 저장해 과거의 출처 실패와 parser 변화를 확인할 수 있게 했다.

”데이터 없음”과 “수집 실패”의 구분

모든 수집 실패를 “없음”으로 표시하면 실제 0건과 장애를 구분할 수 없다.

행사가 0건인 것과 행사 출처가 실패한 것은 다르다. 시설이 없는 것과 facility parser가 빈 row를 만든 것도 다르다. 실시간 문맥이 오래된 것과 출처가 disabled된 것도 다르다.

수집 계획표와 수집 기록은 이 상태 구분을 유지한다.

구분	의미	사용자에게 주는 신호
fresh	최근 성공 데이터가 있음	참고할 수 있음
partial	일부 출처만 사용 가능	제한적 참고
stale	마지막 성공이 오래됨	현장 차이 가능성 표시
unavailable	수집 실패 또는 출처 불가	없음과 구분

row 수와 구조 변화

공공데이터 출처는 사전 공지 없이 바뀔 수 있다. 필드명이나 HTML 구조가 바뀌고 특정 공원 row가 사라질 수 있다.

그래서 수집 결과에는 schema hash와 row count가 필요하다. 이 값이 있어야 “오늘은 행사가 적다”와 “parser가 절반만 읽었다”를 구분할 수 있다.

status distribution도 같은 신호를 준다. 시설 값이 갑자기 전부 unknown이 되거나 혼잡도 분포가 비정상적으로 치우치면 출처나 parser의 문제일 수 있다.

수집 결과를 따르는 화면 안내

출처 확인 결과는 운영 화면과 앱·위젯의 최신성 문구에 함께 쓰인다.

한강자리 API는 출처별 마지막 성공과 stale로 볼 시간을 바탕으로 fresh, stale, unavailable을 나눈다. 이 정보는 화면에서 출처와 갱신 여부를 설명하는 데 쓰이고 위젯에서는 warning text와 unavailable 이유가 된다.

대시보드의 stale 상태는 앱에서 “최신 정보가 아닐 수 있음”이라는 문구와 위젯의 warning text로 이어진다.

erDiagram
  DATA_SOURCES ||--o{ INGESTION_RUNS : 기록
  DATA_SOURCES ||--o{ OUTING_SIGNALS : 발행
  DATA_SOURCES ||--o{ OUTING_FACILITIES : 공급
  INGESTION_RUNS }o--|| SOURCE_HEALTH : 파생

API 상태로 이어지는 수집 기록

source catalog는 실행 주기와 stale 기준을 정의한다. ingestion run은 상태, row count, status distribution과 schema hash를 남긴다. API는 최신 run을 읽어 0건과 수집 실패를 구분하고 같은 상태를 운영 alert, 앱의 최신성 문구와 위젯 warning에 반영한다.