무엇이 참이어야 하는가

목차

§2의 "이것이 아니다" 열과 §3의 "어기면" 열, 그리고 §4 전체가 이 문서의 값어치다 — 나머지는 다른 문서에도 있다.

1. 한 장 요약 먼저 이것만

정류장마다 "곧 오는 버스"와 그 버스가 그 정류장에 닿을 때의 좌석 분포를 낸다. 만석 확률은 그 분포의 0 지점이다.

프로세스 둘 · 패키지 셋

두 프로세스는 PostgreSQL을 사이에 두고 만난다. 패키지끼리 직접 못 부르고 ArchUnit 세 규칙이 CI에서 막는다. 같은 이유로 관측 한 행을 읽는 형이 패키지마다 따로 있다(VehicleObservation / ObservedVehicle) — 형을 공유하면 그 순간 규칙이 깨진다.

하루가 어떻게 도나

셋째 줄이 이 파이프라인의 심장이다 — 관측 commit과 예보 쓰기를 같은 트랜잭션에 묶지 않는다. 수집의 4단계 차감 사다리에 모델 추론 시간이 섞이면 안 되기 때문이다. 넷째·다섯째 줄은 주기가 안 정해져 있고, 그 둘은 서로 묶여 있다 — 회수가 느리면 온라인 이동 보정이 하루 종일 안 걸린다(B7).

이미 정해진 것과 아직 아닌 것

장부의 두 축은 다른 것이다. "미결 16"은 계약이 스스로 세어 둔 목록이고, "막는 것 19"는 이 문서가 착수를 막느냐로 다시 가른 수다. 둘은 겹치되 같지 않다 — 계약 미결 중 아홉은 4-3에서 "나중"으로 내려갔고, 계약에 없던 자리 열셋이 "막는 것"으로 올라왔다.

2. 용어 사전 뜻이 흔들리는 말

근거가 없는 것은 원천 없음이라고 적었다. 그 줄은 지어내지 말고 §4에서 정해야 한다.

2-1. 시각 · 판 · 지평

경계 포함 규칙이 어디에도 없다. 07~09가 07:00:00 이상 09:00:00 미만인지 이하인지, 20시가 evening인지 other인지 — 원천에 없다. TimeBand.of()도 골격뿐이다.

2-2. 노선 · 정류장 · 판본

2-3. 차량 · 여정 · 좌석

2-4. 셀과 통계

2-5. 예보 · 배포

2-6. 판 축 다섯 — 무엇이 바뀌면 어느 축이 움직이나

3. 구현 포인트 어기면 무슨 일이 나는가

각 줄은 한 문장이다. 길어지는 넷은 표 아래에 따로 뗐다. "어기면" 열에 조용히 가 붙은 줄은 오류로 보이지 않고 정상 응답의 모양으로 화면까지 나간다 — 그 줄들을 먼저 읽어라.

3-1. 수집 collector

3-2. 처리 processor

3-3. API api

Board의 필수 필드가 언제나 채워지는 근거는 이미 제약에 있다 — observedAt은 ck_poll_forecast가, vehiclesInService는 후보 outcome 둘 다 stored_rows를 가진다는 사실이, stops(minItems: 1)는 "판본이 있으면 route_stop 행이 있고, 없는 판본은 애초에 스냅샷을 갖지 못한다"가 받친다. api에서 방어 코드를 다시 두지 마라.

3-4. 경계와 배포 패키지 · 마이그레이션

3-5. 따로 떼는 넷

4. 결정이 필요한 자리 이 문서의 본체

코드보다 앞에 놓이는 것들이다. 여기서 갈리면 아래 절의 검수 기준도 뜻을 잃는다. 각 줄은 선택지와 대가까지 적었다 — "정해야 한다"만 적힌 줄은 두지 않았다.

4-1. 막는 것 20

「누가 정하나」의 뜻 — 모델 특징 계약·번들을 소유하는 쪽 · BE 백엔드 구현자 · 계약 프론트와 합의해야 하는 것 · 운영 팀 판단.

4-2. vehicleTripKey — 규칙이 아예 없는 자리 B6 의 상세

가장 큰 결정거리다. 이것 하나가 학습 자료의 slope·prev_seat, 라벨 회수, 채점 표본을 동시에 정한다. 그런데 있는 것은 키의 모양뿐이고 판정 규칙의 값이 없다.

vehicleId null → 키 null 은 계약 본문에 "(CHECK)"라고 적혀 있지만 V4__a18_seat_forecast.sql 에 그 제약이 없다. 실제 DDL 은 ADD COLUMN vehicle_trip_key varchar(120) 한 줄뿐이다. 제약을 넣을지도 같이 정해야 한다.

순번 되돌림 — 후보 셋

결정 전에 잴 것 — 전수 관측에서 "감소폭 1칸이 났다가 다음 관측에서 되돌아온" 사건이 몇 건인가. 그 수가 0 에 가까우면 T1 이 답이고 T3 는 없어도 되는 복잡도다. 지금 그 수가 어느 원천에도 없다.

관측 공백 — 후보 넷

먼저 못박아야 할 사실 하나 — 회차 대기는 같은 여정 안이다. 회차로 여정을 끊지 않기로 했다. 그러니 공백 문턱은 회차 대기보다 크고 밤 공백보다 작아야 한다. 실측이 그 사이를 이렇게 벌려 놓았다.

나머지 둘

4-3. 나중에 정해도 되는 것 22

기본 동작이 이미 있거나 첫 배포 뒤에 정해도 손해가 없다. 시한 이 붙은 셋은 방치하면 비용이 는다.

4-4. 원천끼리 다르게 말하는 자리 정본을 못박아라

여기 일곱은 둘 다 원천에 적혀 있다. 지어낸 것이 아니라 문서가 갈린 것이다. C1(status)·C2(배포 단위)·C10(Cache-Control)은 코드를 막아서 위 4-1(B8·B9·B18)에 올렸고, 나머지를 여기 둔다.

C11 은 말꼬리가 아니다. 노선 키로 판정하면 개편이 나도 503 이 안 나고(축에 판본이 없으니 개편과 무관하다), 판본으로 판정하면 판본이 새로 생길 때마다 번들을 다시 배포해야 503 이 풀린다. 두 구현의 운영 부담이 다르다.

4-5. 원천에 아예 없는 것 구현하다 반드시 부딪힌다

위 4-1·4-3 의 항목 상당수가 여기서 왔다. 여기 있는 것을 지어내지 마라 — 없다고 적고 결정을 요구하는 것이 이 문서의 일이다. 아직 어느 표에도 안 올라간 나머지를 모아 둔다.

5. 경계 조건 "이때 무엇이 참인가"

응답과 저장을 갈라 적는다. 둘이 다른 자리가 결함이 숨는 자리다 — 응답은 200 인데 저장이 비었거나, 저장은 정상인데 응답에서 사라지는 경우.

내리면 안 되는 것 하나만 다시 — approachingVehicles 가 비었다고 RouteStatus 를 내리면 매일 밤 노선이 PREPARING 으로 떨어졌다가 아침에 돌아온다.

6. 검수 기준 시험 시나리오 63

"이렇게 하면 맞게 만든 것이다"를 시험으로 적는다. DB 가 막는 것 · 응답이 지키는 것 · DB 로 못 막아서 다른 것으로 지키는 것 셋으로 가른다.

6-1. DB 제약이 막아야 하는 것 21

9번이 B12 와 붙어 있다 — 상류가 25:00 을 주면 이 제약이 적재를 막는다. "막는 것이 맞다"고 정할 수도 있고 "접어서 넣는다"로 정할 수도 있는데, 정하기 전에는 이 시험의 기대값을 못 적는다.
17~21 은 DDL 에 제약이 있는데 시험 목록에 없던 다섯이다 — 제약이 있으니 새로 걸 것은 없고 시험만 이어 붙이면 된다.

6-2. 막으면 안 되는 것 3

6-3. 코드 불변식 11

6-4. 응답 계약 15

6-5. DB 제약으로 표현 못 하는 불변식 8

왜 CHECK 가 안 되나 — CHECK 는 한 행 안의 열만 본다. 아래 불변식은 전부 다른 표의 값이거나 여러 행에 걸친 것이다. 트리거로 만들 수 있지만 그러지 않기로 했다 — 쓰기 경로가 processor 한 곳뿐이라는 사실에 기대고 그쪽 테스트와 감시 질의로 막는다. 그러니 이 표의 오른쪽 칸이 곧 검수 항목이다.

-- ① 지평·시각 불변식
SELECT p.vehicle_observation_id, p.target_stop_order
  FROM vehicle_stop_prediction p JOIN vehicle_observation o ON o.id = p.vehicle_observation_id
 WHERE p.horizon_stops <> p.target_stop_order - o.stop_order OR p.generated_at < o.observed_at;

-- ② 경유 정류장에 행이 생겼나 (demand_profile 에도 같은 질의)
SELECT count(*) FROM vehicle_stop_prediction p JOIN route_stop s
    ON s.route_reference_version_id = p.route_reference_version_id AND s.stop_order = p.target_stop_order
 WHERE NOT s.boarding_allowed;

-- ③ 한 판이 한 배포인가   ④ 같은 generatedAt 인가 (count(DISTINCT p.generated_at) 로 바꿔 같은 모양)
SELECT o.poll_id, count(DISTINCT p.model_deployment_id) FROM vehicle_stop_prediction p
  JOIN vehicle_observation o ON o.id = p.vehicle_observation_id
 GROUP BY 1 HAVING count(DISTINCT p.model_deployment_id) > 1;

감시 질의는 "돌린다"가 아니라 "주기와 경보를 붙인다"까지가 검수다. 질의만 문서에 적어 두면 아무도 안 돌린다. 어느 주기로 돌고 0 이 아닐 때 누가 보는지를 같이 정해라.

6-6. 재현·회귀 5

7. 작업 순서 무엇부터 만들어야 다음이 안 막히나

왼쪽이 결정, 오른쪽이 구현이다. 각 결정은 바로 오른쪽 단계를 막는다 — 그 단계에 손대기 전에 정해야 한다.

이 절이 가정하는 것 하나 — 위 순서는 4-1 의 결정 스물이 각 단계 시작 전에 내려진다는 전제 위에 있다. 임시값으로 시작하면 순서는 같지만 ③·④에서 만든 자료를 나중에 버려야 할 수 있다 — 여정 키와 시간대 축이 그 둘이다.

원천 문서

이 문서의 모든 이름과 수치는 아래에서 왔다. 여기 없는 것은 §4에서 "원천 없음"으로 표시했다.