발행·캐시 provenance
board_publication.publicationSeq
board_publication.publishedAt · etag
board_publication.observedAt · inService
발행 지연과 조건부 조회를 진단한다. 공개 시각은 HTTP Last-Modified로만 나간다.
Board response anatomy
Board는 “지금부터 탈 때까지”를 한 장에 담는다.
현재 차량과 정류장별 미래 예보를 한 시점에 고정한 스냅샷이다.
보드는 kind로 갈린다 — 운행 중(OPERATING)이면 차량·예보·대기열을 담고,
운행 시간 밖(OUT_OF_SERVICE)이면 노선 정보와 마지막 관측 시각만 남는다.
화면에 필요한 값만 JSON에 두고 재현용 계산 정보는 서버 내부에 분리했다.
아래 장면의 요소를 선택하면 클라이언트가 실제로 받는 필드만 풀어서 보여준다.
현재 사실
activeVehicles[]는 지금 관측된 차량 위치와 좌석이다.정류장별 미래
stops[].nextArrival은 그 정류장 도착 시점의 예보다.정류장의 현재 줄
stops[].queueEstimate는 실험적 대기 인원 추정이다. 추정 불가면 0명이 아니라 사유가 온다.낡음은 클라이언트가 판정서버는
observedAt·staleAt만 준다. 지금이 staleAt을 넘으면 낡음 경고를 띄운다.
도촌동 방면 →
실선 장면 현재 관측
점선 연결 차량과 정류장 예보의 참조
주황 강조 현재 선택한 응답 영역
가장 중요한 연결
현재 차량 한 대가 정류장 예보로 이어지는 법
vehicleRef가 같은 값을 가리키므로 “어느 차량이 범계역의 다음 차량인지”를 프론트가 안전하게 연결한다. 예보가 불가한 SEAT_DATA_UNAVAILABLE·INSUFFICIENT_PROFILE에도 vehicleRef는 온다.
현재 차량 배열
activeVehicles[0].refvehicle-1범계역 다음 차량
stops[0].nextArrival.vehicleRefvehicle-1사용자가 보는 결론
expectedSeats · verdict7석 예상 · 여유대기열 추정은 실험 기능이다. 마지막 해소 후 경과 시간에 시간대별 유입률을 곱해 계산하고, 근거가 없으면 0명 대신 UNAVAILABLE 사유가 온다.
SERVER INTERNAL · CLIENT JSON 아님
응답에서 뺀 값은 버린 게 아니라, 재현 가능한 내부 기록으로 옮겼다.
프론트는 아래 값을 몰라도 화면을 완성한다. 백엔드와 데이터 담당자는 발행 번호(publicationSeq)로 발행 메타·예보·대기열 레코드를 연결해 원인을 추적한다.
모델·학습 provenance
board_publication.modelVersion
board_publication.profileTrainedThrough
prediction_log.vehicleHash · fromSeats · horizon
같은 입력과 버전으로 예보를 재현하고 모델별 정확도를 채점한다.
대기열 계산 provenance
board_queue.estimatedPeople · elapsedMinutes
board_queue.boundLow · boundHigh
stop_arrival_rate.rate · sampleSpans
왜 과대·과소 추정됐는지 확인한다. 유입률 λ는 따로 싣지 않고 점추정 ÷ 경과분으로 역산한다. Client에는 결과와 표시 맥락만 남는다.
상태 사전
영어 상태값은 화면에서 이렇게 해석한다.
숫자 0과 정보 없음, 차량 없음과 학습 부족을 각각 다른 상태로 구분한다. 서버가 만들 수 없는 값은 enum에 없다.
kind — 보드 두 형태
- OPERATING
- 운행 중. route·freshness·activeVehicles·stops를 담는다.
- OUT_OF_SERVICE
- 운행 시간 밖. route와 lastObservedAt만 온다. 화면은 운행 종료 안내.
- BOARD_NOT_FOUND
- 보드가 한 번도 없던 노선. kind가 아니라 404 오류 코드다.
activeVehicles[].seat.kind
- EXACT
- 정확한 잔여 좌석 수가 있다. 출발 이후 관측의
remaining: 0만 만석이고, 도착 시점의 0은 하차로 자리가 생길 수 있다. - CROWDEDNESS_ONLY
- 정확한 숫자 없이 여유(FREE)·보통(NORMAL)·혼잡(CROWDED)만 안다.
- UNKNOWN
- 좌석·혼잡도 정보가 없다. 센서 없는 차량(2층버스 포함). 절대 0으로 바꾸지 않는다.
nextArrival.kind
- FORECAST
- 다음 차량과 도착 좌석 예보가 만들어졌다.
- NO_APPROACHING_VEHICLE
- 현재 이 정류장으로 접근하는 차량이 없다.
- SEAT_DATA_UNAVAILABLE
- 차량은 있지만 좌석 원본이 없어 계산 불가. vehicleRef는 온다.
- INSUFFICIENT_PROFILE
- 차량은 있지만 이 시간대 학습 표본이 부족하다. samples가 가용 가중 표본량이다. 승차·하차 인원은 원본에 없어 잔여석 순변화만 관측한다.
verdict
- ROOMY
- 여유. 여기서 기다려도 된다.
- TIGHT
- 탈 수는 있으나 줄 위치에 따라 갈린다. 앞쪽이면 타고 뒤쪽이면 못 탈 수 있다.
- UNLIKELY
- 좌석 부족에 만석 연속. 지금 여기서는 어렵다.
queueEstimate — UNAVAILABLE.reason
- OUTSIDE_SUPPORTED_WINDOW
- 유입률을 계산한 시간대(아침·저녁) 밖.
- UNSUPPORTED_STOP
- 유입률 자료가 없는 정류장.
- NO_CLEARING_EVIDENCE
- 마지막 해소 시각을 잡을 근거가 없다.
- CLEARING_TOO_OLD
- 마지막 해소가 60분을 넘었다.
- INSUFFICIENT_SOURCE_DATA
- 유입률 근거 구간 수가 부족하다.
route.status
- ACTIVE
- 정상 운영.
- LEARNING
- 수집 중. 보드는 발행되나 INSUFFICIENT_PROFILE 위주다. 표본이 쌓이면 예보로 바뀐다.
- PAUSED
- 새 발행이 없다. 마지막 보드가 남고 staleAt이 지나 낡음 경고가 뜬다.
전체 예시
이 장면을 한 번에 보내는 Board JSON
필요한 영역을 위에서 이해한 뒤 전체 응답을 보면 각 덩어리의 역할이 분명해진다. 운행 시간 밖이면 보드는 OUT_OF_SERVICE 한 형태로 줄어든다.
운행 중 보드(OPERATING) 펼쳐 보기
운행 종료 보드(OUT_OF_SERVICE) 펼쳐 보기