변경 이력

2026-08-31Client API v4-1을 확정했다

실코드 2822dcf와 게시 명세를 전 항목 대조했다. 오류 응답은 retryable을 뺀 세 필드가 됐고 오류 코드는 5종에서 9종으로 늘었다. 보드 응답에는 required staleAt(observedAt + 5분)이 추가됐다. SUCCESS_ROWS인데 읽어낸 차량이 0행인 경우는 UNKNOWN으로 명시했다. 공개 경로는 팀 레포 계약대로 routes·board·vehicles 세 개로 고정했다.

horizonStops 스키마는 1~12로 유지한다. 바뀐 것은 산문이다 — sequence - horizonStops는 현재 순번이 아니라 지나온 정류장 수이며, 현재 위치와 회차 전후는 /vehicles.currentStopSequence로 판단한다. 저장 계층은 V4~V9가 들어왔지만 그 변화는 Client 응답 모양에 새 필드를 더하지 않는다.

2026-08-23실제 LIVE 차량번호와 8/22 완료일 성적표를 반영했다

Watch의 차량번호 계약을 vehicle-plate-live-v1로 확정했다. GBIS 번호는 durable commit 뒤 process memory에서만 응답 시점에 결합하며, SQLite·serving S3·모델·평가 artifact·로그에는 저장하지 않는다. 공개 상태이면 화면에는 마지막 네 자리만 보이고, 결손·충돌은 추측값 없이 fail-closed한다. API 문서는 과거 재생 데모를 제거하고 실제 FastAPI 실행 계약에서 다시 생성했다. 이 항목은 당시 별도 runtime의 이력이며 현재 팀 레포 Client 계약에는 포함되지 않는다.

8/21 원천 이상 레코드 4건을 전체 레코드 단위로 격리한 뒤 8/22까지 다시 채점했다. 말뭉치는 통과 사건 104,447건·만석 1,387건이고, 종합 점수는 지평 1 92.0 · 지평 8 75.6 · 지평 12 69.9다. 평가일은 8일이라 여전히 잠정이며 지평마다 표본이 달라 점수 차이를 순위로 읽지 않는다.

2026-08-19v4 개정안에 팀 검토 넷을 반영했다 — 이름 셋 · 상한 하나

팀 검토에서 넷이 확정됐고 전부 반영했다. 아래 v3 → v4 절은 이 개정 이전에 쓴 판이라 옛 이름과 옛 상한이 남아 있던 곳을 이 개정에 맞춰 고쳤다. 확정 계약은 여전히 v3다 — 바뀐 것은 검토 요청 중인 개정안이다.

mobileNo 없음으로 판정하면 틀린다. 경유 지점은 mobileNo 가 없지만, 1650 의 서울 중앙차로 정류장 19곳(석촌역(중) 등)도 mobileNo 가 없으면서 진짜 승차 정류장이다 — 그쪽은 centerYn: Y 로 구분된다. 실측 뒷받침으로 경유 지점의 좌석변화율 중앙은 0.000(31곳), 일반 정류장은 0.053(138곳)이다. 미정차 정류장에는 예보를 만들지 않는다 — 계약이 이미 그렇게 규정한다.

2026-08-19경유 지점을 08번의 예측 대상에서 뺐다

08번(A18)의 학습·평가 말뭉치가 경유(미정차) 지점을 예측 대상으로 쓰고 있었다. boardingAllowed = !stationId.startsWith("277") 로 걸러 105,058행(18.4%)을 빼고 지평 1~12를 전부 재적합·재채점했다. 뺀 것은 예측 대상이고, 차량이 경유를 지나며 남긴 관측은 특징으로 남는다. 계약 문구가 바뀐 곳은 없다.

숫자. 만석 라벨 9,777 → 4,851, 기저율 1.7168% → 1.0445%, 대상 정류장 174곳 → 143곳. 지평 12에서 만석 구분 0.4194 → 0.3729, 채점 만석 표본 686 → 355, 종합 71.6 → 70.3, 운행시간대 커버율 90.8% → 89.9%. 지평 상한은 그대로 12다. 사이트의 08번 성적·코호트·커버율·기저율은 전부 새 값이다.

2026-08-191차 운영 모델을 08번으로 교체했다

팀 검토로 08번 「오고 있는 버스 보기」(차량 상태 조건부 좌석 분포)를 1차 운영 모델로 정했다. 2026-08-17 부터 02번 「재료 다 넣기」가 갖고 있던 자리다. 1차 운영 선택은 운영 적용을 위한 팀 선택이고 성능 입증이 아니다 — 평가는 여전히 잠정이고 일일 채점도 계속된다.

02번은 폐기가 아니다. 평가 파이프라인에 대조군으로 남고 서빙 계약에서는 빠진다. 일일 채점은 계속 받지만 /board가 읽는 자리에는 들어가지 않는다. 두 모델은 재료가 달라 채점 표본도 다르므로 같은 표에서 순위를 매기지 않는다.

이 선택이 계약을 움직인다. 08번은 예측 시점 그 차량의 잔여석을 쓰므로 /board가 시간대 평균 하나를 주던 구조로는 담을 수 없다. 아래 v3 → v4 개정안이 그래서 나왔다. 그 계약은 아직 검토 요청 상태다 — 모델은 골랐고 계약은 팀 검토를 기다린다.

2026-08-19v4 개정안을 뒤집었다 — /board 재구성

처음 낸 v4 안은 v3 위에 선택 필드만 더하는 개정이었다. 08번 모델을 /vehicles에 붙이고 /board는 손대지 않는 것이 그 안의 안전장치였다. 그 전제를 뒤집었다 — 지금 /board가 주는 시간대 평균은 새 모델이 이미 재료로 쓰는 값이라, 따로 내보내면 재료를 덜 가공해서 내보내는 셈이 된다. 그래서 /board는 정류장마다 도착 예정인 버스별 탑승 확률을 주는 모양으로 바뀌고, 개정안은 파괴적 변경(v4-fe 2.0.0 · v4-be 4.0.0)이 된다. 프론트엔드 수정이 함께 필요하다. 무엇이 그대로이고 무엇이 왜 바뀌는지는 아래 명세 v3 → v4 절에 다시 썼다 — 안 바뀌는 것(0절)부터 시작해 FE는 1~5절, BE는 6절, 미결은 7절이다. 확정 계약은 여전히 v3다.

2026-08-19지평 12 확정 — 평가기 등록과 LIVE 별도 구획

08번의 서빙 지평을 12정류장으로 확정하고 평가 규약의 지평 모델 목록에 seat_distribution_j12를 등록했다. 고른 기준은 점수가 아니다 — 지평마다 채점 표본이 달라 점수를 서로 뺄 수 없기 때문이다. 기준은 예보를 낼 수 있는 도착 비율과 만석 구분의 맞바꿈이고, 8→12는 79.2%를 86.3%로 늘리며 기저 대비 향상을 31배에서 24배로 내준다. 12→16은 87.4%로 1.1%p를 더 얻자고 17배까지 내주므로 기각했다.

지평은 시간이 아니라 정류장 수다. 12정류장의 중앙 소요는 25.0분이지만 같은 8정류장이 10%분위 9.1분에서 90%분위 23.0분까지 2.5배로 흩어진다. 걸린 시간은 도착한 뒤에야 알 수 있어서 예측에 쓰면 누출이다.

2026-08-19새 후보 모델과 v4 검토 요청안

후보에 08번 오고 있는 버스 보기를 더했다 — 지금 오고 있는 그 버스가 목표 정류장에 도착할 때 좌석이 몇 석 남을지를 분포로 낸다. 이 모델을 담으려면 /board 응답이 바뀌어야 해서 개정안을 v4-fe·v4-be 두 묶음으로 올렸다. 확정 계약은 여전히 v3다. 무엇이 그대로이고 무엇이 왜 바뀌는지는 아래 명세 v3 → v4 절에 있다.

2026-08-19사이트 전반 서술 갱신 — 08번이 바꾼 개념 다섯

08번 후보가 들어오면서 사이트 여러 곳의 전제가 바뀌었다. 설계는 그대로 두고 내용만 고쳤다. 지운 것은 없고 전부 덧댄 것이며, 정정은 정원 하나다. 어디가 왜 바뀌었는지는 아래 표에 있다.

함께 고친 것 — 「후보 모델 7개」를 8개로(포털·도메인·데이터 스택), 그리고 재료 문서의 오해 소지 하나. 「로지스틱+상호작용」의 서빙 재료 표는 연구 변형 기준인데 확정된 운영 v1(입력 세 개, 실시간 좌석 안 봄)과 헷갈릴 수 있어 주석을 달았다.

2026-08-17평가 규약 cohort-v2 — 공휴일 달력 도입

공휴일·대체공휴일·선거일을 주말 국면으로 분류한다(2026년 22일). 오늘(광복절 대체공휴일)이 평일 코호트를 오염시키는 문제의 교정이며, 내일 일일 평가부터 적용된다. 구간 정의는 평가 규약에 있다.

2026-08-17확정 명세 2판 — 실시간 차량 엔드포인트 추가

GET /api/v1/routes/{routeId}/vehicles를 신설했다 — 차량 위치·잔여석·vehicleId 원문, 60초 폴링. 갱신 주기가 예보와 24배 달라 문을 나눴다: 보드는 순수 예보가 되고(관측 블록은 /vehicles로 이동), 한쪽이 503이어도 다른 쪽은 산다. 응답의 schemaVersion 필드는 제거됐다. 명세에서 보기 · 세부 대비는 아래 표.

2026-08-17확정 API 계약 공개

확정 계약을 v3 문서 묶음으로 공개했다 — Client(노선 예보 조회, 명세 1.0.0)·Data Pipeline(DB 표 8개)·GBIS Upstream·Operations 네 문서. 옛 문서 주소 /api/v1은 /v3/client로 넘어간다(서버 경로 /api/v1은 그대로다). 1차 운영 모델 선택(상호작용 로지스틱 회귀)을 모델 현황판에 반영했다. 확정 전 명세 초안 v2·v1은 그대로 보존한다. 무엇이 왜 바뀌었는지는 아래 명세 v2 → v3 절에 있다.

2026-08-17상황판 개편

홈에 수집·평가 상태 스트립을 달았다. 모델 현황판은 일일 평가와 연동돼 매일 갱신된다. 관문·코호트·지표·분할 정의는 평가 규약 한 곳으로 모았다. 확정 도메인 설계를 /domain에 공개했고, 보드 가이드는 API 초안 v2 어휘로 갱신했다.

2026-08-16일일 모델 평가 시작

매일 00:15 KST에 전 후보를 자동 평가하고 결과를 LIVE에 공개한다. 구형 도메인 문서는 로컬에 보존하고 공개 목록에서 내렸다.

2026-08-15모델 문서 공개

후보 7개의 상세 문서와 재료 문서를 열었다. 현재 평가와 M3 연구 이력은 분리해 실었다.

분야별로 나눠 본 것은 여기다. 이 절은 FE와 BE가 한자리에 섞여 있다. 화면 쪽만 볼 사람과 서버 쪽만 볼 사람을 위해 같은 개정을 분야별로 갈라 놓은 문서를 따로 뒀다. 이 절은 둘을 함께 놓고 보는 판이다.

0안 바뀌는 것부터 — 골격은 그대로다

GET /api/v1/routes           그대로
GET …/routes/{id}/vehicles   그대로
GET …/routes/{id}/board      경로만 그대로

route 8필드                  그대로
  id · displayName
  startStopName · endStopName
  status · turnSequence
  referenceVersionId · directions

stops[] 5필드                자리 그대로
  sequence · stopId · name
  direction · boardingAllowed
// 다섯 중 ID 이름 하나만 바뀐다
//   stationId → stopId (2026-08-19 개정)

// directions 항목에만 필드 둘이 는다
//   originStopName · terminalStopName
//   firstDepartureTime · lastDepartureTime
// 오류 envelope · 코드 5종 그대로
//   (사유 이름 하나만 바뀐다 — 2절)

call_ledger                  그대로
route_reference_version      그대로
route_stop                   그대로
location_poll                그대로
model_deployment             그대로

STAGED → ACTIVE 원자 승격    그대로
노선 판본 유효기간 관리      그대로
상류 API 1종 · 수집 필드     그대로

// 기존 열의 삭제·타입 변경 0건
// 학습·평가·선정은 여전히 외부 ML 환경이
//   소유한다 — v3의 경계 그대로

파괴적 변경이라는 말에 화면을 통째로 다시 그릴 필요는 없다. 노선 화면의 골격 — 정류장 목록·이름·방면, 회차 판정, 개편 감지(referenceVersionId) — 은 v3 그대로다. /routes와 /vehicles는 응답 스키마가 한 필드도 바뀌지 않는다 (설명만 두 곳 고쳤다 — /vehicles의 폴링 권고와 Observation의 주석). /board의 route도 여덟 필드 그대로인데 directions 항목 안에만 originStopName·terminalStopName·firstDepartureTime·lastDepartureTime 넷이 필수로 는다 — 운행 종료를 vehiclesInService 하나로 단정하지 말라는 3절과 짝이다. 상류 API도 늘지 않는다 — A18이 쓰는 재료는 이미 받고 있는 차량 위치 하나뿐이고 새 필드를 요구하지 않는다. 바뀌는 것은 /board 응답 안에서 예보를 담는 부분 하나다.

할 일 — FE가 고칠 곳은 정류장 하나를 그리는 컴포넌트와 그 위의 응답 타입이다. BE가 기존 표에서 만질 것은 vehicle_observation에 열 하나를 더하는 것뿐이고 나머지는 신설이다(6절).

1예보의 단위가 정류장에서 차량으로 옮겨간다

"stops": [ {
  "sequence": 9, "name": "범계역",
  "seatForecast": {
    "kind": "ESTIMATED",
    "seatAvailableProbability": 0.832 } } ]

// 정류장당 값 1개
// 입력 셋 — 노선 · 정류장 순번 · 시간대
// 답: 08~09시에 여기 지나는 버스라면

"stops": [ {
  "sequence": 55, "name": "롯데백화점.범계역",
  "approachingVehicles": [
    { "vehicleId": "SYNTH-VEH-001",
      "horizonStops": 3,
      "seatAvailableProbability": 0.871,
      "expectedSeats": 28.2 },
    { "vehicleId": "SYNTH-VEH-008",
      "horizonStops": 12,
      "seatAvailableProbability": 0.946, … } ] } ]

// 정류장당 값 = 도착 예정 차량 수
// 입력에 그 차량의 현재 잔여석이 더해진다
// 답: 지금 오는 저 버스가 도착할 때

v3이 답하던 질문은 "이 시간대에 이 정류장을 지나는 버스라면"이었다. 사용자가 실제로 묻는 것은 "지금 오는 저 버스에 앉을 수 있나"다. 새 모델은 그 차량의 현재 잔여석을 조건으로 받으므로 버스를 특정해야 답이 나온다.

두 낱말을 먼저 정한다. 지평은 시간이 아니라 노선 순번 차이다 — 대상 정류장까지 남은 칸 수(horizonStops)이고, 경유 지점도 한 칸으로 센다. 모델은 지평마다 따로 적합되며 상한은 12다. seatAvailableProbability는 이 버스가 이 정류장에 도착할 때 빈자리가 한 자리 이상 남을 모델 확률이다 — 0~1 실수를 그대로 주고 서버는 반올림하지 않는다. 뜻은 v3과 같고 차량이 특정된다는 점만 다르다. 정류장에 몇 명이 서 있는지는 모르므로 개인 한 명의 승차 성공 확률은 아니다.

시간대 평균을 폴백으로도 남기지 않은 이유는 둘이다. 새 모델이 그 값을 이미 재료로 쓴다 — (노선, 정류장, 시간대)별 평균 점유율과 순수요를 기억하고 거기에 현재 잔여석을 더해 답을 낸다. 따로 내보내면 재료를 덜 가공해서 내보내는 셈이다. 그리고 차량이 없는 경우는 셋뿐인데(운행 자체가 없다 · 다음 버스가 지평 밖이다 · 추적 이력이 모자라다) 셋 다 시간대 평균이 답이 아니다.

FE 할 일 — stop.seatForecast 하나를 읽던 자리를 stop.approachingVehicles[] 반복으로 바꾼다. 정렬은 서버가 horizonStops 오름차순으로 고정한다. sequence − horizonStops가 그 차량의 현재 순번이라 노선 위에 버스를 찍을 수 있고, route.turnSequence와 견주면 회차를 지나야 오는 차량인지도 알 수 있다 (실측 approachingVehicles 항목의 10.0%(1650)·12.8%(3330)가 여기 해당한다). vehicleId는 필수 필드지만 공급자가 값을 빠뜨리는 드문 경우가 있어 null이 올 수 있다 — 타입은 string | null로 잡는다. 확률만 띄우고 horizonStops를 감추지 마라 — 만석 버스를 골라내는 능력(PR-AUC)이 1~4정류장 0.73~0.84에서 9~12정류장 0.42~0.54로 떨어진다. 무작위 대비로는 43~50배에서 24~31배이니 먼 쪽도 쓸모는 있지만, 같은 확률이라도 난이도가 다르다.

2발행본 개념이 사라진다 — 시간대 경계 굽기에서 관측마다로

"forecast": {
  "publicationId": "pub-01J9X2",
  "targetAt":     "…08:00:00+09:00",
  "publishedAt":  "…08:00:02+09:00",
  "validUntil":   "…09:00:00+09:00",
  "model": { "releaseId": …, … } }

// 07 · 09 · 17 · 20 KST 경계마다 한 판
// 수집이 끊겨도 예보는 유효했다

"observedAt": "2026-08-18T08:29:47+09:00",
"model": {
  "releaseId": "seat-distribution-3330-…",
  "trainedThrough": "…" },
"vehiclesInService": 14

// 값이 바뀌는 횟수 하루 4번 → 관측마다
//   08-18 실측 노선당 4,097회
// 503 사유 이름이 바뀐다
//   NO_CURRENT_PUBLICATION
//     → NO_RECENT_OBSERVATION

v3의 발행은 시간대 경계마다 한 판을 구워 봉인하는 구조였고, 모델 입력이 그 시간대 안에서 변하지 않으니 맞는 설계였다. 새 예보는 관측마다 바뀌므로 그 틀에 담기지 않는다. ForecastMeta 넷을 observedAt 하나로 대체한다. 그 값은 우리 수집기가 상류 응답을 받은 시각이다 — 상류가 주는 queryTime은 실측 1,294건 전부에서 우리 수신 시각보다 2.2~20.5초 뒤라 시계가 어긋나 있어 쓸 수 없다.

대신 v3에 없던 결합이 하나 생긴다. v3은 수집이 끊겨도 예보가 유효했지만 v4의 /board는 관측을 읽으므로 최근 관측이 없으면 NO_RECENT_OBSERVATION 503이다. 같은 이유로 RouteStatus.FORECAST_READY의 뜻도 옮겨간다 — "지금 시각에 유효한 봉인 발행본이 있다"에서 "활성 계수 묶음이 있고 관측이 들어오면 예보를 낸다"로, 즉 "답을 갖고 있다"에서 "답을 낼 수 있다"로. 값은 그대로 2종이다. /vehicles와 서로 죽지 않는 성질은 유지된다.

FE 할 일 — validUntil로 다음 요청 시각을 잡던 코드를 지운다. /board의 Cache-Control이 60초에서 15초로 짧아지고, 자료의 나이는 지금 − observedAt으로 잰다(수집은 적응형이라 15 / 20 / 60 / 600초 간격이다). 503 사유 코드 문자열도 교체한다. BE 할 일 — 발행 계층을 제거한다(6절).

3빈 approachingVehicles의 뜻 — 갈래가 넷이다

"stops": [ {
  "boardingAllowed": true,
  "seatForecast": {
    "kind": "ESTIMATED",
    "seatAvailableProbability": 0.977 } } ]

// 승차 가능 정류장은 늘 값을 가졌다
// 하나라도 점수화에 실패하면
//   발행 전체를 503으로 되돌렸다

"vehiclesInService": 0,
"stops": [ { …, "approachingVehicles": [] } ]
// → "운행이 끝났습니다" (기다려도 안 온다)

"vehiclesInService": 11,
"stops": [ { …, "approachingVehicles": [] } ]
// → "곧 오는 버스 없음" (기다리면 온다)

// 응답 모양은 같고 뜻이 다르다
// 둘 다 정상 200이다 — 503이 아니다
// 이 둘로 끝이 아니다 — 아래 표의 넷

빈 배열은 드문 예외가 아니라 자주 나오는 상태다. 셀 191만 개(스냅샷 11,005개 × 정류장 174개) 기준으로 커버율 86.3%이고, 비는 나머지는 노선 앞머리라 뒤에 볼 구간이 짧은 경우 7.9% · 지평(12정류장) 밖 3.4% · 운행 0대 2.2%다. 운행 시간대(06~23시)만 보면 커버율이 90.4%(1650)·91.1%(3330)이고 심야는 30%로 완전히 다르다. 이만큼 흔한 상태를 오류로 다루면 화면이 자주 깨진다.

셋째 줄이 함정이다. 순번 12 이하 정류장은 뒤로 볼 수 있는 칸이 sequence − 1개뿐이라 커버율이 37~44%로 떨어진다(그 밖의 정류장은 98.7~98.9%다). 그런데 실측하면 실제 다음 버스는 중앙 8.3~12.0분 뒤에 온다 — 그 차가 차고지에서 대기 중이라 차량위치 API에 아직 안 나타날 뿐이다(96.2~96.8%가 그렇다). 해당 정류장은 노선의 13.8%다. 배차 간격(첨두 5~6분·비첨두 15분)을 함께 보여주는 편이 정직하다.

정류장마다 사유를 붙이지 않고 최상위에 값 하나만 둔 이유는 운행 여부가 노선 전체의 사실이기 때문이다. 항목마다 상태 열거형을 두려던 안은 뺐다 — 이유는 4절에 있다. 드물게 상류가 빈 응답을 주면 운행 중에도 0이 된다(실측 22,010 스냅샷 중 1건, 0.005%). observedAt의 나이로 거른다.

FE 할 일 — approachingVehicles: []에 스피너나 오류를 띄우지 마라. 문구는 위 표의 네 갈래로 고른다. vehiclesInService 하나로는 갈라지지 않으므로 sequence와 boardingAllowed를 함께 읽는다. vehiclesInService: 0도 관측일 뿐 단정이 아니다 — "운행이 끝났습니다"는 route.directions[].lastDepartureTime과 견주고 나서 쓴다. 방향마다 다르다: 1650은 상행 막차가 22:35인데 하행은 23:55로 80분 차이가 나서, 노선 하나를 통째로 종료라고 하면 그 사이 시간에 틀린다.

4넣었다가 뺀 것들 — "왜 이건 없나"의 답

"arrivals": [ {
  "vehicleId": "SYNTH-VEH-001",
  "horizonStops": 3,
  "confidence": "HIGH",
  "viaTurnaround": false,
  "seatForecast": {
    "state": "READY",
    "seatAvailableProbability": 0.871,
    "expectedSeats": 28.2,
    "seatQuantiles": {
      "p10": 3, "p50": 12, "p90": 24 } } } ]

"approachingVehicles": [ {
  "vehicleId": "SYNTH-VEH-001",           필수
  "horizonStops": 3,                  필수
  "seatAvailableProbability": 0.871,  필수
  "expectedSeats": 28.2 } ]           선택

// 뺀 자리에 최상위 값 하나만 뒀다
//   — vehiclesInService (3절)

뺀 기준은 하나다 — 다른 필드에서 유도되거나, 자료에 없는 상태이거나, 층만 늘리는 것은 계약에 넣지 않는다. 계약에 들어간 값은 FE가 화면을 만들고 BE가 열을 파야 하는 약속이라, 늘리는 쪽이 아니라 줄이는 쪽에 근거를 뒀다.

할 일 — 위 이름들은 검토 과정에만 있었고 확정본에는 없다. 중간 초안을 보고 작업을 시작했다면 필드 넷으로 맞춘다.

5v3 예시의 오류 넷 — 계약 변경이 아니라 교정이다

"routes": [ {
  "id": "234000016",
  "displayName": "3330",
  "startStopName": "구리수택차고지", … } ]

"route": { …
  "turnSequence": 31 }

1650 status: "PREPARING"

"routes": [ {
  "id": "204000057",
  "displayName": "3330",
  "startStopName": "도촌동9단지앞", … } ]

"route": { …
  "turnSequence": 43 }   1650은 44

1650 status: "FORECAST_READY"

// 회차 정류장은 둘 다 안양역(208000069)
// 정류장 수 1650=89 · 3330=85

셋은 3330 자리에 다른 값이 들어가 있던 것이다 — 구리수택차고지는 1650의 기점이고, 234000016과 31은 확인된 두 노선 어느 쪽의 값도 아니다. 상류 getBusRouteStationListv2·getBusRouteInfoItemv2를 직접 조회해 확정했다. 계약의 모양은 그대로이고 예시 값만 고쳤다. 앞의 셋은 같은 날 v3 문서에도 반영했다(위 「지평 12 확정」 항목의 표).

넷째는 성격이 조금 다르다. v3 예시는 1650을 PREPARING으로 뒀는데, A18은 노선별로 적합하고 계수 묶음이 노선마다 나오므로(블록 2노선 × 지평 12 = 24) 한 노선만 준비되는 그림이 아니다. v4 예시는 둘 다 FORECAST_READY로 뒀다.

할 일 — v3 예시를 그대로 베낀 목업·픽스처·테스트 상수가 있으면 고친다. 204000057이 3330, 234000050이 1650이다.

6백엔드 — 발행본을 굽는 대신, 관측 시점에 계산해 저장한다

forecast_publication  발행 메타
stop_prediction       정류장별 예보
  단위: (발행본, 정류장)
  봉인 확인 5종 · CAS 승격
  노선당 하루 4~5판 · 340~445행

// 라벨 만들기는 연구 export의 일이었다

vehicle_stop_prediction   신설 · 열 14
  단위: (관측, 대상 정류장)
demand_profile            신설 · 열 11
  단위: (판본, 정류장, 시간대)
vehicle_observation
  + vehicleTripKey          열 1
인덱스 3건

forecast_publication  제거
stop_prediction       제거

// 남는 표에서 열 삭제·타입 변경 0건
// 기존 8개 중 둘을 지우고,
//   남는 여섯에서 열이 바뀌는 표는 하나뿐

왜 요청 시점에 계산하지 않고 저장하나. 결정적 근거는 모델 안에 있다 — A18의 L_p0shift 층은 그날 이미 도착이 관측된 사건의 (예보 원값, 실제 라벨) 쌍을 되읽어 절편을 옮긴다. 낸 예보를 저장하지 않으면 그 층이 성립하지 않는다. 채점 편의가 아니라 모델 입력이다. 덧붙는 근거 둘 — /board 캐시가 15초이고 수집이 15~60초라 화면 하나만 열려 있어도 요청 수가 poll 수를 넘고, 요청 시점 계산은 채점 표본이 사람이 본 시간대에만 남아 심야가 0이 된다. 한 판의 계산량은 두 방식이 같다 — 한 차량은 자기 앞 12개 정류장에만 나타나므로 예보 수는 정류장 수와 곱해지지 않고 차량 수에 선형이다.

무엇을 잃는지도 적는다. 발행 계층을 제거하면 봉인 확인이 지키던 불변식 "승차 가능 정류장은 전부 답을 갖는다"가 사라진다. 대체물은 없고 그것이 의도다 — 예보가 정류장이 아니라 차량에 붙으므로 정류장 단위 전수 보장이 성립하지 않는다.

쓰기만 멈추는 것이 아니라 지우는 이유는 그 경로가 한 번도 가동된 적이 없기 때문이다 — 적재할 계수 번들이 없어 발행 processor 가 뜬 적이 없다. 한 번도 뜬 적 없는 경로를 안전장치라고 부를 수는 없고, 남겨 두면 계약이 두 갈래로 읽힌다. 되돌리기도 이 경로로는 안 된다 — 발행 계층을 되살리면 /board 응답 구조가 v3 형태로 함께 돌아간다. 그건 조용한 폴백이 아니라 계약 되돌림이다.

지우는 것은 서빙 계약 쪽 발행 계층뿐이고 모델 평가 파이프라인은 그대로다. 후보 7종은 후보 모델 현황판과 일일 평가에 남아 같은 규약으로 계속 채점된다. 지우는 범위도 층마다 다르다 — 계약에서는 두 표를 적지 않고, 코드에서는 봉인·승격 프로시저와 두 표를 읽는 자리를 걷어내며, 물리 표를 언제 DROP 할지는 아직 정하지 않았다(7절).

더하는 열 하나가 vehicle_observation.vehicleTripKey다. 순번 되돌림으로 나눈 한 번의 운행을 가리키는 키다 — A18이 쓰는 slope(상류 좌석 기울기)가 같은 여정 안에서만 뜻이 있어서, 나누지 않으면 이번 여정의 40번 정류장이 지난 여정의 40번과 짝지어진다. v3에서도 같은 판정을 했지만 그건 연구 export가 하고 저장하지 않았다. 적재 때 한 번 정해 저장한다. 나누는 문턱은 아직 미정이다(7절).

BE 할 일 — 표 둘을 만들고 열 하나·인덱스 셋을 더하며, 발행 표 둘과 그 경로를 지운다. 작업량 추정과 항목별 내역은 짝 문서인 v4-be 파이프라인 계약에 있다. 가장 불확실한 항목은 라벨 회수 배치다 — v3에서 연구 export가 하던 일을 제품이 넘겨받는다. 그 다음이 A18 추론기, /board 재조립 순이다. 응답 구조가 통째로 바뀌므로 기존 /board 계약 시험은 대부분 다시 써야 한다. FE와 맞물리는 곳은 2절(observedAt·503 사유)과 3절(vehiclesInService)이다.

7아직 정해지지 않은 것 — 배포를 막는 것은 없다

v3의 미결 셋(계수 번들 부재 · 학습 사건의 노선 판본 부재 · 제품 공개 노선 ID)은 그대로 남아 있다. A18의 성적은 여전히 오프라인 산출값이다 — 사이트 평가 규약·같은 지표로 지평 12에서 종합 71.6 · 브라이어 0.01242 · PR-AUC 0.419 · 커버율 86.3%(운행 시간대 06~23시 90.4~91.1%)가 나왔고, 일일 평가 원장에는 아직 들어 있지 않다. 이 절도 성능이 입증됐다고 적지 않는다.

1차량 참조 제거 — 예보는 차량을 고르지 않는다

"activeVehicles": [
  { "ref": "vehicle-3", … } ],
"stops": [ {
  "nextArrival": {
    "kind": "FORECAST",
    "vehicleRef": "vehicle-3", … } } ]

"stops": [ {
  "sequence": 9, "name": "범계역",
  "seatForecast": {
    "kind": "ESTIMATED",
    "seatAvailableProbability": 0.832 } } ]

모델 입력은 노선·정류장 순번·KST 시간대 셋뿐이다. vehicleRef를 붙이면 "이 차 기준"이라는 거짓 의미가 되고, activeVehicles도 같은 이유로 예보 응답에서 뺐다 — 실시간 차량은 별도 /vehicles 엔드포인트가 맡는다(2판).

2응답 값 축소 — 확률 하나만

"nextArrival": {
  "expectedSeats": 7,
  "seatAvailableProbability": 0.83,
  "verdict": "UNLIKELY",
  "lowConfidence": false,
  "fullStreak": { "kind": "KNOWN", "count": 0 } }

"seatForecast": {
  "seatAvailableProbability": 0.832 }

// 0~1 실수 그대로. 서버는 반올림하지 않는다
// 표시 자릿수는 화면이 정한다

판정·예상 좌석·연속 만석은 이 모델의 출력이 아니다. 0.996을 두 자리로 자르면 1.00이 되어 "반드시 자리가 있다"로 읽힌다.

3수집 신선도와 모델 신선도를 분리

"freshness": {
  "observedAt": "…22:30:12Z",
  "staleAt":    "…22:33:12Z" }
// 수집 신선도가 보드 신선도를 겸함

/board → "forecast": {
  "publishedAt": …, "validUntil": … }
// 모델 신선도
/vehicles → "observation": {
  "state": "VEHICLES_PRESENT",
  "observedAt": …, "staleAt": … }
// 수집 신선도 — 별도 엔드포인트(2판)

수집이 잠깐 끊겨도 예보는 유효하다 — 수집 신선도를 예보 신선도로 표시하면 오해가 생긴다.

4운행 종료 단정 제거

{ "kind": "OUT_OF_SERVICE",
  "route": …,
  "lastObservedAt": "…13:01:44Z" }
// stops 없음 — 예보도 없음

/vehicles → "observation": {
  "state": "NO_VEHICLES_OBSERVED" },
"vehicles": []
/board → "stops": [ { "seatForecast": {
    "seatAvailableProbability": 0.977 } } ]
// 예보는 그대로 나간다

GBIS resultCode=4는 "호출은 정상인데 그 순간 차량이 없다"일 뿐 운행 종료의 증거가 아니다. 실측에서는 심야에 이 응답이 반복된 뒤 다음 수집에서 차량이 다시 나타났다. 운행 종료 표시는 운행 시간표 같은 권위 근거가 생긴 뒤에만 쓴다.

5발행 주기 — 매 수집 직후에서 시간대 경계로

발행 = 수집 성공 직후, 한 트랜잭션
예보 행(prediction_log)이 쌓임
— 하루 52,000행(v8 산정)

시간대 경계 07:00 · 09:00 · 17:00 · 20:00 KST
모델 승격 · 노선 판본 변경

// validUntil이 지나면 옛 값을 200으로
// 주지 않는다 → 503 + Retry-After

모델 입력이 같은 시간대 안에서 변하지 않으므로 값도 변하지 않는다. targetAt은 도착 예정 시각이 아니라 "그 시간대에 출발한다고 가정했을 때"의 기준 시각이다. 노선당 하루 4~5판이면 충분하다.

6정류장 사유를 좁히고, 실패는 발행 전체 실패로

"nextArrival": { "kind": "FORECAST |
  NO_APPROACHING_VEHICLE |
  SEAT_DATA_UNAVAILABLE |
  INSUFFICIENT_PROFILE" }

"seatForecast": {
  "kind": "ESTIMATED | NOT_APPLICABLE" }
// NOT_APPLICABLE 사유는
//   BOARDING_NOT_ALLOWED 하나
// 승차 가능 정류장의 모델 실패
//   = 발행 전체 실패 → 503

절반만 맞는 보드를 200으로 주는 것보다 503이 낫다. 503 코드는 MODEL_OUT_OF_SCOPE·NO_CURRENT_PUBLICATION·SERVICE_UNAVAILABLE 셋으로 확정했다.

7내부 계약 재편 — 테이블 12개에서 8개로

route · route_feature · route_stop
snapshot · vehicle_observation
demand_profile · stop_arrival_rate
board_publication · board_vehicle
prediction_log · board_queue · board_gap

call_ledger
route_reference_version · route_stop
location_poll · vehicle_observation
model_deployment  배포 영수증
forecast_publication · stop_prediction

학습·평가·선정은 외부 ML 환경이 소유한다 — 학습 파생 테이블을 제품 DB에서 뺐다. 발행은 STAGED → ACTIVE 원자 승격(전용 프로시저만), 노선 판본은 유효기간으로 관리한다(겹침 금지).

1보드를 운행 중 / 운행 종료로 나눔

{
  "route": { … },
  "freshness": { "state": "OUT_OF_SERVICE", … },
  "vehicles": [],
  "stops": [ /* 전부 '차량 없음'으로 채움 */ ]
}

{ "kind": "OPERATING",
  "route": …, "freshness": …,
  "activeVehicles": […], "stops": […] }

{ "kind": "OUT_OF_SERVICE",
  "route": …,
  "lastObservedAt": "2026-08-10T13:01:44Z" }

운행 종료 보드의 정류장 상태는 전부 같은 채움값 — 정보가 없음. 상태가 다른 게 아니라 응답의 종류가 다른 것이라 타입으로 분리.

2freshness 상태 enum 제거

"freshness": {
  "state": "FRESH | STALE | OUT_OF_SERVICE | UNKNOWN",
  "observedAt": "… | null",
  "staleAt":    "… | null"
}

"freshness": {
  "observedAt": "2026-08-10T22:30:12Z",
  "staleAt":    "2026-08-10T22:33:12Z"
}
// 낡음 = 지금 > staleAt
// 지금 = Date 헤더 + 경과 (+ Age 보정)

신선도와 운행 여부는 독립 정보인데 한 enum에 묶여 있었음. 본문의 STALE은 ETag가 같으면 304만 오가서 본문이 갱신되지 않는, 지켜질 수 없는 값. UNKNOWN은 생산 조건 없음 — 보드가 없으면 404.

3features 2개로 축소

"features": [
  "SEAT_FORECAST",
  "BOARDING_VERDICT",
  "QUEUE_ESTIMATE",
  "UPSTREAM_RECOMMENDATION"
]

"features": [
  "SEAT_FORECAST",   // 판정 포함
  "QUEUE_ESTIMATE"
]

판정은 예보와 한 계산 — 따로 켜고 끌 수 없음. v1 예시(1650, 예보만 켜짐)는 스키마로 표현 불가한 조합. UPSTREAM_RECOMMENDATION은 v1 범위 밖.

4방면 이름 교정

{ "id": "UP",   "name": "도촌동 방면" }
{ "id": "DOWN", "name": "안양역 방면" }

{ "id": "UP",   "name": "안양역 방면" }
{ "id": "DOWN", "name": "도촌동 방면" }

그대로 구현하면 사용자에게 반대 방면 표시. Direction enum에 의미 서술 추가.

5필드명 변경

"vehicles": [ … ]

"queueEstimate": {
  "estimatedPeople": 13.7, … }

"activeVehicles": [ … ]

"queueEstimate": {
  "pointEstimate": 13.7, … }

vehicles는 '운행 중인 차량만 담긴다'는 범위가 이름에 없음. estimatedPeople은 점추정(보조값)임이 드러나지 않아 주 표시로 오용될 여지 — 주 표시는 display.

6발행을 행 저장으로 전환 (내부 계약)

published_boards
  └ payload  "{ …보드 전체… }"

board_publication   발행 메타
board_vehicle       차량
prediction_log      예보·판정 = 채점 로그
board_queue         대기열
board_gap           없는 자리의 사유

화면에 나간 값 = 채점 기록(같은 행). 확정된 DB 설계(v3) 반영.