/board 를 A18 에 맞추면
백엔드는 무엇이 달라지나

한 장 요약 30초

규모부터 적는다. 표와 열의 정본은 파이프라인 계약 v4 에 있다.

정원이 A18 에만 걸리는 이유는 기존 후보 모델의 입력이 노선·정류장 순번·시간대 셋뿐이어서다. A18 은 현재 잔여석 ÷ 정원을 점유율로, 좌석 감소 ÷ 정원을 순수요로 쓰므로 정원이 틀리면 두 값이 함께 어긋난다. v6 말뭉치 60,158행에서 정원은 열 갈래로 관측된다 — 44석 40,612 · 45석 7,448 · 40석 6,055 · 68석 5,757 · 49석 192 · 67석 54 · 42석 16 · 41석 12 · 36석 11 · 43석 1이고 최빈값은 44다. 종전 47 은 어느 근거에도 없던 수였다. 모델이 쓰는 정원은 형식승인 좌석수와 다른 양이라 합치지 않고, DB 열이 아니라 번들의 특징 계약이 소유한다.

0. 하지 않아도 되는 것 범위를 먼저 좁힌다

/board 를 다시 만든다고 8/17 확정본이 뒤집히지 않는다.

그대로 쓰이는 것

실제로 움직이는 것

/board 응답 구조가 이번 안에서 가장 큰 변경이다 — 정류장당 값 하나에서 정류장별 도착 예정 차량 목록으로 바뀌고, 원천이 발행본에서 관측으로 옮겨가며, api 예보 객체 7개의 안이 다시 쓰인다(3절). 표 둘이 신설되고 발행 표 둘이 빠지며, 기존 표에 열 여섯이 붙고 정원 47석 고정이 교정된다(1절).

processor 가 하는 일이 시간대 경계 발행에서 관측 적재마다 도는 추론으로 바뀌고, 예보 저장량이 약 2,000배가 되어 보존과 파티션이 설계 항목으로 올라온다(2절). v8 의 "서버는 통계를 집계하지 않는다"는 문장도 개정된다 — demand_profile 은 채점 대상이 아니라 모델이 읽는 입력이라 성격이 다르지만, 서버가 경험 통계를 집계하는 것은 맞다.

v2 초안이 버렸던 demand_profile 만 모습을 바꿔 돌아온다 — 시간 축을 열에 박지 않고 셀 식별자 하나로 두어 셀 세분화 실험이 마이그레이션을 부르지 않게 했고, 적률 합 대신 1차 적률만 담으며 폴백 지시자는 열이 아니라 그 셀의 행이 있는지로 정해진다. stop_arrival_rate 와 4계층 12테이블은 돌아오지 않는다. v3 가 두 표를 버린 근거는 "읽는 코드가 없다"였고, 바뀐 것은 그 판단이 아니라 전제다 — A18 의 L_cell 이 그 값을 직접 읽는다.

1. 스키마 변경 표와 열

열 정의와 제약의 정본은 파이프라인 계약 v4 다.

기존 8개 표 중 둘이 빠지고, 계약에 남는 여섯 중 열이 느는 것은 셋이며 넷 이상 느는 것은 route_reference_version 하나다. 남는 표에서 열의 삭제·타입 변경·NOT NULL 변경은 0건이다. 나머지 셋(call_ledger · route_stop · model_deployment)은 열 정의가 한 글자도 안 바뀐다.

새 열에 딸린 규칙 셋

• 방향별 첫차·막차는 contentDigest 대상이 아니다. 시간표만 바뀌면 판본을 새로 끊지 않고 같은 행을 UPDATE 해서 판본이 "정류장 목록의 판본"이라는 뜻을 지킨다. 갱신은 노선당 하루 1회와 판본 신설 시점이다. 방향마다 다른 것이 이 열의 존재 이유다 — 1650 은 상행 04:10~22:35 · 하행 05:25~23:55 로 막차가 80분 어긋난다.
• 회차 순번 열은 v3 부터 있다. 실측은 1650 이 44 · 3330 이 43 이고 회차 정류장은 둘 다 안양역이다. 그 station_id(208000069)는 저장하지 않는다 — 순번이면 판정이 되고 그 순번의 station_id 는 route_stop 에 있다. (DB 열은 station_id 이고 응답 필드만 stopId 다.)
• vehiclesInService 는 새 열이 아니다. 스냅샷 poll 의 storedRows 가 그 값이다 — 같은 poll 안 차량 중복을 부분 unique index 가 막으므로 저장 행 수가 곧 distinct 차량 수다.

2. 도메인 변경 모듈 경계와 데이터 흐름

A18 은 지금 파이프라인에 없는 넷을 요구한다 — 회차 키 판정 · 셀 통계 집계 · 차량별 추론 · 정류장 조립이다. 넷은 도는 주기가 서로 달라서 같은 자리에 놓으면 빠른 쪽이 느린 쪽에 끌려간다. 계약이 다섯째를 얹는다 — 방향별 첫차·막차는 A18 이 재료로 쓰지 않는데 응답에는 실린다. 빠지는 자리도 하나다 — processor 의 시간대 경계 발행은 이 설계에 없다.

결정과 근거

stop_prediction 을 늘리지 않고 신설하는 근거와 셀 통계를 번들이 아니라 표에 두는 근거는 스키마 쪽 결정이라 파이프라인 계약 v4 에 적었다. stop_prediction 은 그 계약에서 빠지므로 늘릴 대상 자체가 남지 않는다.

끊어야 할 것은 회차가 아니라 여정이다

회차를 이어서 지난 운행이 1650 94.0% · 3330 72.4% 이고 회차 전후 관측 간격은 중앙 0.3분이다. 차고지에 서지 않고 지나간다는 뜻이라, 회차에서 끊으면 재구성한 운행의 순번 폭 중앙 86/89·81/85 가 절반으로 잘려 상류 좌석 기울기의 재료가 사라진다. 회차 너머 정류장에도 예보를 낸다(approachingVehicles 항목의 10.0%·12.8%).

다만 근거가 바뀐다 — 회차를 넘으면 현재 잔여석이 도착 잔여석을 설명하지 못해 지평 8에서 R² 가 0.178 에서 0.011 로 떨어진다. v6와 같은 5일 표본에서 회차 너머는 지평 8이 5,247건·만석 3건(0.057%), 지평 12가 8,091건·만석 72건(0.890%)이다. 떠받치는 것이 차량 상태보다 정류장 통계에 가까워지므로, 모델은 turnSeq 를 입력으로 받지 않는다.

백엔드에 주는 뜻은 하나다. 회차 횡단 여부를 서버가 저장하지도 계산하지도 않는다. sequence − horizonStops 와 route.turnSequence 를 견주는 순번 비교 하나이고 두 재료가 모두 응답 안에 있다. 서버가 필드를 더 두면 같은 판정이 두 곳에 생기는데, 그 값이 틀려도 확률은 그대로라 아무도 어긋남을 못 잡는다. 채점을 회차 횡단 여부로 가를 때만 같은 식을 쓰고, 저장이 아니라 조회 시 유도다.

예보를 못 내는 자리는 하나뿐이다

잔여석이 결측인 관측이다. 설계행렬이 잔여석을 세 열로 그대로 쓰고 앵커도 거기서 출발하는데, 그 자리에는 상류 기울기·직전 좌석과 달리 결측 지시자가 없다. 확정 계약에 "예보 없는 approachingVehicles 항목"이라는 상태가 없으므로 항목째로 빠지고 그것이 정상 응답이다 — 상태 코드도 사유 코드도 새로 만들지 않는다. 여정 키가 없다고 거르지는 않는다. 라벨 회수만 못 한다.

규모 — 쓰는 쪽은 크고 내보내는 쪽은 작다

05~24시 poll 기준 동시에 관측되는 차량이 중앙 11대·13대, 최대 28·36대다. 지평 12를 곱하면 수집 한 번에 계산할 예보가 중앙 132~156개 · 최대 336~432개다. 하루로 치면 08-18 실측 기준 노선당 차량 관측이 7.4만~8.2만 건이라 예보 행이 89만~98만이 되고, v3 의 stop_prediction 이 노선당 하루 340~445행인 것과 견주면 약 2,000배다. 보존 기간과 파티션 축을 먼저 정하지 않으면 이 표가 파이프라인에서 가장 먼저 문제를 낸다.

응답 쪽은 반대로 작다. 지평 12 창만 걸어도 노선당 항목이 중앙 120·150 이고, 상한 없이 담았을 때의 중앙 462~554 와 견주면 4분의 1 아래다. 정류장당 상한(3)은 그 위에서 꼬리만 자른다 — 한 정류장에 붙는 항목이 중앙 3·4 · 최대 9·12 이기 때문이다. 줄이는 일은 지평 창이 하고 상한은 화면을 위해 건다. (중앙 119·133 은 상한 2 로 재던 값이다.) 한 바퀴 돌아 오는 차량이 실제 다음 도착 차량인 경우는 5.1%·15.6% 뿐이라 랩어라운드도 뺐다.

vehiclesInService 와 운행 시간은 서로 다른 시계에 있다

둘 다 예보가 아니라 예보를 읽는 법에 관한 값인데 나오는 자리가 멀다. vehiclesInService 는 관측 시계에 있고 approachingVehicles 가 빈 이유를 가르려고 둔다 — 0 이면 운행이 끝난 쪽이고 0 보다 크면 이 구간에 지금 차가 없는 쪽이다. 다만 단정은 서버가 하지 않는다. 상류가 빈 응답을 주면 운행 중에도 0 이 되므로(실측 22,010 스냅샷 중 1건, 0.005%) 판별자로 굽지 않고 정수 그대로 내보낸다. 방향별 첫차·막차는 기준정보 시계에 있어 차량위치 poll 과 다른 경로로 들어오고 poll 예산에 얹히지 않는다.

되돌릴 수 없는 변경이다

v3 로 물러설 자리를 남겨 두는 설계가 아니다. 무엇을 안전장치로 둘지는 아직 정하지 않았다.

발행 계층은 남기지 않는다 — 표 둘과 그 경로를 함께 걷어낸다. 봉인 확인과 CAS 승격, 시간대 경계 재발행이 /board 서빙 경로에서 빠지고 그 자리를 관측마다 도는 차량 예보가 대신한다. 앞선 초안은 "표는 남기고 쓰기만 멈춘다"로 적었고 그 서술을 걷어냈다. 물러설 자리로 쓸 수 있는 경로가 아니었기 때문이다 — 그 경로는 한 번도 발행한 적이 없다. 적재할 계수 번들이 없어 processor 가 뜬 적이 없으므로, 한 번도 뜬 적 없는 경로를 안전장치라고 부를 수 없다.

되돌리려 해도 /board 응답 구조가 v3 형태로 함께 돌아간다. 정류장당 값 하나와 정류장별 도착 차량 목록은 같은 필드로 읽히지 않으므로, 프론트가 두 형태를 다 읽지 못하면 되돌림이 곧 중단이다. 무엇을 안전장치로 둘지는 이 문서가 정하지 않았다 — 5절 ② 에 미결로 남겼다.

신규 노선 생애주기

A18 은 노선별로 학습하고 계수를 공유하지 않는다. 그래서 새 노선은 자기 이력이 쌓이기 전까지 예보를 낼 재료가 없다.

품질 낮은 예보를 내는 중간 단계를 두지 않는다. 새 노선에는 셀 통계가 없어 마스킹 폴백만 도는데 그 값은 그 노선의 평균조차 아니고, 차량 상태만으로는 못 버틴다 — 학습에 쓰지 않은 하루에서 재면 차량 상태의 설명력이 지평 1에서 R² 0.958 인데 지평 8에서 0.179, 지평 12에서 0.002 까지 무너지고 정류장 상태는 0.336 에서 0.310 으로 거의 그대로다. 먼 지평일수록 새 노선이 갖지 못한 쪽에 의존한다.

마지막 줄이 실질적으로 가장 센 관문이다 — 학습 자료가 전부 휴일일 때 평일 아침 판별력은 0.518 에 머물고 휴일을 세 배로 늘려도 그대로인데, 평일 반나절이 들어오면 0.958 로 뛴다. 모자란 것은 모델이 아니라 그 노선의 자료다. 다만 위 값들은 A18 이 낸 실측이지 통과 기준이 아니다 — 기준으로 쓰려면 결과를 보기 전에 문턱을 고정해야 한다. 기존 노선의 판본이 개편될 때도 같은 자리에 선다. demand_profile 이 노선 판본에 매여 있어 개편 직후 새 판본에는 셀 행이 없고, 폴백만으로 며칠을 버틸 수 있는지가 위 점선 화살표를 정한다.

아직 갈리는 선택지 둘

① 운행 시간의 요일패턴을 무엇으로 내보내나

상류 마스터에서 공휴일(we*) 값은 사실상 일요일(sun*)의 복제다 — 양쪽 다 값이 있는 1,927개 노선 중 실제로 다른 것은 10개뿐이다.

② 셀 통계 재계산을 누가 도나

3. 백엔드 API 변경 /board 를 만드는 절차

api 가 하는 일이 계산이 아니라 조립인 것은 그대로다. 무엇을 읽어 무엇을 담는지가 바뀐다.

정렬을 지평 오름차순으로 두는 것이 "먼저 도착할 순서"와 어긋나지 않는다. 맨 앞 항목이 실제 첫 도착일 확률이 96.68% 이고 앞의 두 대끼리의 순서는 96.76% 정확하다. 가까울수록 정확해서 1정류장 앞은 96.6% · 10정류장 앞은 88.5% 다. 세 번째 항목은 지평이 멀어 더 흔들린다 — 상한을 3 으로 늘리면서 이 자리의 불확실성이 커졌고, 그래서 확정 계약이 horizonStops 를 화면에서 감추지 말라고 못박는다.

/vehicles 와 /routes 의 서빙은 바뀌지 않는다. 확정본이 손댄 것은 폴링 권고, Observation 주석, RouteStatus 뜻풀이, /routes 예시의 status 값이라 문서 쪽 일이다. api 의 읽기 전용 경계도 유지된다. v8 이 적은 "모델이 무엇으로 바뀌어도 api 는 고칠 일이 없다"는 문장이 시험대에 오르는데, 고치는 이유는 모델이 아니라 응답 계약이고 모델 계약에 대한 의존은 여전히 없다.

4. 작업량 추정

계약 문서만 보고 낸 추정이라 기존 구현의 결합도에 따라 움직인다. 짝 문서는 같은 일을 계약 관점으로 다시 갈라 센다 — 항목 묶음이 다를 뿐 겹치는 일을 두 번 세지 않았다.

여기 들어 있지 않은 것 셋 — 계수 번들 생산(외부 ML 환경 소유. 노선별이라 노선마다 블록이 필요하다), 프론트엔드 작업(v4-fe 가 범위를 적는다), 과거 관측의 여정 소급 계산(여정 키가 NULL 허용이라 백필은 없지만, 이전 관측은 여정이 비어 라벨 대상에서 빠진다). A18 채점은 evaluation-v6 · composite-score-v2 사설 일일 원장에 편입됐다. 지평 1~12 채점행 합은 608,512건이고, 서빙에는 그 12개 지평만 담는다.

5. 먼저 재야 할 것 코드보다 앞선다

작업량 추정보다 앞에 놓이는 확인이 있다. 결과에 따라 4절의 표가 흔들린다.

설계에서 아직 안 정한 것

• 운행 시간의 요일패턴과 demand_profile 재계산 주기·주체. 2절 선택지 ①·②다.
• 좌석이 결측인 관측의 서빙 처리. 전수 22,010 스냅샷에서 차량행 314,688 중 237행(0.075%)이고 판의 1.07% 가 그런 차량을 하나 이상 담으며 한 차량에 연속 18회까지 이어진 사례가 있다. /vehicles 는 같은 차량을 kind: UNKNOWN 으로 계속 보여 주므로 두 화면이 어긋난다.
• 차량 예보 보존 기간과 파티션 축. 채점에 필요한 창과 저장 비용의 절충이 필요하다.
• 노선 판본 개편 시 상태 전이. 폴백만으로 며칠을 버틸 수 있는지에 답이 달렸다.
• 노선 관문의 문턱값. 채택 규칙은 모델 채택용이라, 노선 관문으로 옮기려면 문턱을 결과 보기 전에 고정해야 한다.
• 여정 분할 문턱. 순번이 줄어드는 것을 새 여정의 신호로 쓰는데 상류 지터로 잠깐 되돌아가는 경우와 구별할 값이 없다. 3330 은 회차 순번 언저리(42~43)에서 끝나고 다시 시작하는 여정이 있어 순번만으로는 갈리지 않는다. 밤 공백의 중앙이 1650 487분 · 3330 462분이라 시간 문턱으로 가를 여지는 있는데, 회차 대기 자체가 시간대에 따라 변한다 — 1650 기준 중앙이 07시 106.7분에서 21시 46.0분까지 내려간다(전체 중앙 75.3분). 문턱 하나로 고정하면 아침에는 한 여정을 둘로 쪼개고 밤에는 둘을 하나로 붙인다.

v3 의 미결 셋(계수 번들 부재 · 학습 사건의 노선 판본 부재 · 제품 공개 노선 ID)은 그대로 남아 있다. 스키마 쪽 미결 전량은 파이프라인 계약 v4 끝에 있다.

관련 문서

이 문서는 검토 요청안이다. 확정 계약은 v3 이고, 여기서 제안한 어느 항목도 팀 합의 전에는 적용되지 않는다.