모델·공공 API 기준 설계 검토
동료의 설계안을 현재 7개 모델 역할, GBIS·경기데이터드림 계약, 수집부터 평가까지의 생성 이력(계보)과 대조했다. 지금의 사실과 앞으로의 변경을 정확히 담는지로 판단했다.
수집·처리·조회 프로세스 분리, 테이블별 단일 쓰기 주체, 추정값과 미추정의 구분은 유지한다. 그러나 전체 도메인 모델에는 모델·라벨·발행 계보가 빠져 있다. 도입 전에 보완하고 다시 검토한다.
검토 범위: 이 페이지는 도메인만 검토한다. 전면 재검토 중인 기존 Client API와 스키마는 판단 근거에서 제외한다. 새 스키마와 새 API는 다음 단계에서 설계한다.
estimate(stopOrder, timeBand, CellRisk) 하나로는 7개 역할을 정확히 표현할 수 없다. 원문 설계의 모델 입력과 발행 계보도 서로 이어지지 않는다.63 → 29는 34개 감소인데 제거 목록의 합은 44개다. 추가·병합·개명한 10개가 설명되지 않았다.SnapshotSource와 ChanceModel 두 개다. 다만 이를 Java 인터페이스 전체 수라고 쓰면 sealed ChanceState와 Spring Data 저장소·조회 인터페이스가 빠진다. 의도한 확장점 수와 실제 인터페이스 선언 수를 나눠 써야 한다.@ConditionalOnProperty는 기본적으로 애플리케이션 시작 시 설정을 고르는 기능이지 빌드 시점 선택이 아니다.RouteForecast 메타데이터를 읽으면 JPQL은 실행된다. 이 경우에도 classpath·persistence unit 결합은 남으므로 “import 0”과 “결합 0”을 같은 뜻으로 쓰면 안 된다.이 항목은 아키텍처 취향과 무관한 원문 내부 정합성 문제다. 정확한 타입 목록·선택 시점·조회 구현을 다시 적기 전에는 확인 불가로 둔다.
간결한 구조는 장점이지만, 객체 수만으로 채택할 수는 없다. 현재 모델 규격과 공공 API 명세를 기준으로 유지·수정·보류를 나눴다.
판정 기준은 현재 코드·평가 규격·공공 API가 요구하는 의미를 보존하는지다.
SnapshotSource, 처리·API 분리, Estimated | NotEstimated는 변화 방향과 실패 상태를 드러낸다.공공 API 응답을 곧바로 모델 입력으로 쓰지 않는다. 보존이 허용된 수신 증거, 관측 사실, 통과 근거, 라벨, 특징, 학습·평가 산출물을 순서대로 구분해야 같은 결과를 다시 설명할 수 있다.
현재 공개 평가는 수집·라벨·모델 비교를 수행하지만, 운영에 올릴 모델 파일과 활성 발행본을 아직 고정하지 않는다.
확인한 사실: 현재 정답은 “목표 정류장을 출발한 뒤 잔여석이 0”인 사건이다. 점 근거는 같은 수집 전략·노선의 인접 성공 응답에서 같은 차량·회차·KST 날짜가 이어지고, 경과가 0초 초과 90초 이하이며, 파생 last_passed가 정확히 1 늘고 현재 좌석이 유효한 출발 뒤 상태일 때 생긴다. 목표 정류장을 S라 하면 유효한 (stateCd, stationSeq)는 (2,S), (0,S), (1,S+1)이고, 도착 상태인 (1,S)는 라벨이 아니다. 순번을 건너뛰었거나 90초를 넘긴 관측쌍도 후보 last_passed가 1~6개이면 별도 구간 근거로 남긴다.
검토 판단: BusObservation(vehicleId, stationSeq, remainingSeats, crowded)에는 출발 상태인 stateCd와 각 응답의 성공·무차량·실패 경계가 없다. 공식 무차량 응답이나 실패를 지운 뒤 성공 행끼리 연결하면 실제로 없던 통과 라벨을 만들 수 있다.
권장안: 관측과 라벨 사이에 JourneyKey, PassageEvidence(POINT | INTERVAL), LabelPolicy를 둔다. 정상 차량 있음, 정상 차량 없음, 수집 실패를 서로 다른 CollectionOutcome으로 남긴다.
공급자 응답 키와 오류 코드를 핵심 도메인에 바로 넣지 않는다. 원문을 보존할지, 어떤 필드를 얼마 동안 남길지는 공급자·필드별 정책으로 정한다. 보존하도록 승인한 증거만 비공개 계층에 두고, 공급자별 변환기가 장기간 유지할 표준 관측과 기준정보로 바꾼다.
원문·필드의 보존 여부와 기간은 공급자마다 따로 정한다. 보존하는 증거는 공개하지 않고 접근권한과 보존기간을 좁힌 비공개 계층에 둔다.
| 계약 | 확인한 의미 | 도메인에 남길 것 | 막아야 할 손실 |
|---|---|---|---|
| GBIS | 노선별 실시간 위치 호출. HTTP 성공과 업무 결과 코드를 따로 판정한다. | 호출 결과, 수신 시각, stateCd, 좌석의 정확값·결측 이유, 정책이 허용한 증거 참조 | 공식 무차량 결과를 실패로 세거나, 실패를 빈 차량 목록으로 바꾸는 일 |
| 경기데이터드림 | 기준정보는 여러 페이지를 모두 수집해 만든다. | 데이터셋·페이지 범위·전체 건수·API 버전·취득 시각·완전성 | 한 페이지를 전체 기준정보로 보거나 현재값으로 과거를 덮는 일 |
SUCCESS_ROWSSUCCESS_EMPTYNO_RESULTBUSINESS_ERRORMALFORMED_PAYLOADTRANSPORT_ERROR | HTTP_ERROR이 상태를 모두 Snapshot(buses=[])로 바꾸면 수집 장애를 “그 시각에 운행 차량이 없었다”는 사실로 오인한다. 호출 기록에는 receivedAt, queryTimeRaw, 원문 해시, 공급자·변환기 버전도 남긴다.
0, -1, 필드 없음, null, 잘못된 타입·음수를 구분한다. 0은 만석이고 -1은 정보 없음이다.RawBus는 원문이 아니라 이미 필드를 고른 전달 객체다. 원문 본문과 필드 존재 여부를 별도 증거로 유지한다.page_drift(페이지 일관성 확인 필요) 상태로 남긴다.INFO-000은 성공, INFO-200은 결과 없음, INFO-300과 ERROR-*는 업무 오류다. 성공의 head/row와 최상위 RESULT 모양, 페이지별 수신 시각, api_version, list_total_count, 수집 범위를 그대로 남긴다. HTTP 200만으로 성공 처리하지 않는다.PLATE_NO·AUTOMB_NO는 저장·노출 금지 대상이다. 필요한 목적별 연결값은 정규화 전에 HMAC으로 만들고 원본 번호판은 즉시 버린다. AUTOMB_ID·VEH_ID도 공급자 이름공간 안의 비공개 식별자로만 다룬다.도입 전 해결할 충돌: 현재 GBIS 수집 계열은 원문과 정규화 행을 대조하지만, 프로젝트 GBIS 호환성 명세는 plateNo·vehId를 정규화 전에 HMAC 처리하고 원문을 저장하지 않는다고 적는다. 두 정책을 동시에 지킬 수는 없다. 목표 도메인을 승인하기 전에 보존 정책 하나를 정하고 수집기·명세·기존 저장 자료를 같은 기준으로 맞춰야 한다.
SnapshotSource.collect(routeId, now) 하나는 GBIS 위치 수집 경계로는 쓸 수 있지만, 모든 공급자의 기준정보 수집을 대표하는 공통 인터페이스로 쓰기에는 좁다. 고정 costPerCall도 계정·환경별 호출 정책과 분리해야 한다.CollectionAttempt를 두고, 실시간 관측 소스와 기준정보 소스를 나눈다. 모든 외부 식별자는 SourceKey(source, namespace, rawValue)로 한정한다.다섯 운영 후보는 같은 만석 사건을 예측하지만 입력과 학습 상태가 다르다. 보정층은 기본 모델의 확률을 다시 조정하고, 비운영 참조는 운영 선택 대상이 아니다.
등록된 모델과 실제 운영 중인 모델은 다른 상태다. 2026-08-15 기준 평가 산출물은 일곱 역할 모두 잠정이며, 채택된 운영 모델은 없다.
설계 v3의 TimeBand는 출근과 그 외만 구분해 현재의 퇴근 구간을 잃는다. CellRisk는 여러 수준의 집계, 연속 시각, 평일·주말, 구간 근거, 기본 모델 예측 가운데 어느 것도 공통으로 대신할 수 없다.
route_time → route → global 순서를 적었지만 코드는 global → route → route_time·route_stop → route_stop_time 고정 계층을 쓴다. 둘 중 하나로 맞추고 자동 일치 검사를 둬야 한다.CellRisk는 입력이 아니다.route_stop_time → route_stop → route_time → route → global 순서를 적었지만 코드는 이를 읽지 않는다. 실제 코드는 전역 → 노선 → 노선×시간·노선×정류장 평균 → 세부 셀의 고정 계층으로 계산한다. 선언과 구현을 하나의 검증 가능한 계약으로 맞춰야 한다.logistic_interactions가 낸 보정 전 p_full을 입력으로 Platt 보정을 학습·적용한다. 권장 계약에서는 그 기본 모델 산출물 참조도 함께 묶어야 한다.Beta(0.5, 0.5) 평활 상수확률을 쓴다. 현재 노선 특징은 3330과 그 외 둘로만 나뉘므로 새 노선도 1650과 같은 값이 되며, 정류장 축은 GAM과 같은 임시 범위·0~1 절단 규칙을 쓴다. 이 참조 모델을 운영 후보로 바꾸려면 이 대체 규칙들부터 다시 설계해야 한다.ChanceModel 서명은 7개 전부의 전체 계약을 표현하지 못한다. 특히 GAM, 비운영 참조, 보정층은 입력 모양부터 맞지 않는다.FullnessProbability로 좁히고, 입력은 모델별 특징 스냅샷을 참조하게 한다. 보정은 별도 ProbabilityCalibrator로 조합한다.현재 평가 모델이 계산하는 값은 목표 정류장 출발 뒤 만석확률 p_full이다. 도메인 안에서는 0과 1 사이의 확률값과 미추정 사유를 보존하고, 화면용 이름·퍼센트·상태는 별도 표현 경계에서 정한다.
0 ≤ p_full ≤ 1 · 모델 발행본 · 특징 스냅샷 · 판단 시각1 − p_full은 같은 사건의 비만석확률이다. 실제 탑승확률이라고 단정하지 않는다.설계 v3의 percent(화면 표시 비율)가 만석과 비만석 중 무엇을 뜻하는지 먼저 고정한다. 표시 요구가 모델의 기본 출력을 바꾸게 하지 않는다.
확인한 사실: 설계 v3는 ChanceState를 percent(표시 비율) 또는 reason(미추정 사유)으로 발행한다. 그러나 응답만 보고 어떤 사건을 예측했는지, 어떤 자료·특징·모델 파일을 썼는지 거슬러 확인할 수 없다.
검토 판단: 모델 결과를 하나의 정규화된 만석 위험 예보로 먼저 발행하는 방향은 타당하다. 단, 이 결과를 어떤 사용자 표현으로 바꿀지는 이번 도메인 검토의 근거가 아니다.
권장안: FullRiskForecast에 예측 대상인 노선 버전·정류장·기준 시각, p_full | UnavailableReason, 실제 ActiveModelRelease, 특징·자료 참조를 둔다.
조회 패키지 안에 영속 JPA 엔티티를 선언하지 않는 선택은 가능하다. 설계 원문의 JPQL from RouteForecast를 쓰려면 persistence unit이 다른 패키지의 관리 엔티티 메타데이터를 읽어야 하므로 classpath와 persistence unit 결합이 생긴다.
그 결합을 허용하고 읽기 권한만 제한할지, JDBC·jOOQ·SQL 직접 조회 같은 방식으로 분리할지를 명시한다. 조회 행을 서비스 응답으로 바꾸는 규칙도 별도 계약과 테스트로 정한다.
바뀌는 이유, 쓰기 책임, 보존 규칙이 다를 때만 객체를 분리한다.
CollectionAttempt · ExternalDatasetSnapshot · 비공개 원문 · 표준 관측 · RouteVersion · VehicleSpec · 비공개 VehicleIdentityLink. 공급자 결과와 시간·식별 경계를 소유한다.PassageEvidence · 라벨 정책 · 특징·데이터 고정본 · 5+1+1 정의 · 학습·평가 산출물과 운영 승인 기록을 소유한다.ActiveModelRelease · FullRiskForecast · UnavailableReason. 승인된 만석 위험 완성본만 한 번에 공개한다.처음부터 각 경계를 별도 서비스로 나눌 필요는 없다. 코드 경계와 저장 소유권을 먼저 고정하고, 실제 독립 배포 필요가 생길 때 분리한다.
PLATE_NO·AUTOMB_NO는 HMAC 입력 뒤 즉시 버린다. AUTOMB_ID·VEH_ID는 별도 이름공간에서 검증된 대응표로만 잇는다.번호판 원본은 정규화·학습 계층으로 넘기지 않는다. GBIS 보존 정책의 충돌은 도입 전에 해소하고, 경기데이터드림 번호판은 현재 호환성 명세대로 폐기한다. 해시는 익명화 보증이 아니며, 반복 관측을 잇는 가명값에는 목적·키 수명·접근권한·보존기간이 필요하다.
공개 확률 하나를 재현하려면 모델 이름만으로 부족하다. 어떤 원자료 범위와 라벨·특징 규격으로 학습했고, 어떤 평가와 선택을 거쳐 어느 채널에서 활성화됐는지 이어져야 한다.
LabelPolicy · FeatureSpec · 예측 시점 정보 상한p_full 또는 미추정확인한 사실: 현재 평가 결과는 데이터·평가 규격·구간·모델 버전을 기록하지만, 학습된 계수·트리·보정기 파일과 운영 활성 상태는 아직 없다.
검토 판단: 한 번에 활성 모델 하나만 쓰는 운영 방침은 가능하다. 그러나 빌드 설정 한 칸만으로는 과거 결과 재현, 선택 근거, 되돌릴 대상을 설명할 수 없다.
권장안: 불변 ModelArtifact와 불변 ModelRelease, 현재 발행본을 가리키는 작은 포인터를 둔다. 이것은 실행 중 임의 모델 교체를 뜻하지 않는다. 프로세스가 시작할 때 승인된 하나의 발행본만 읽도록 해도 된다.
변경은 해당 소유 경계 안에서 끝나야 하며, 과거 결과의 의미도 유지돼야 한다.
RouteVersion을 발효한다. 과거 관측을 현재 순번으로 다시 연결하지 않는다.모델을 추가해도 기존 모델은 바꾸지 않는다. 공급자가 바뀌어도 모델은 유지하고, 화면 요구가 바뀌어도 원문 관측은 고치지 않는다.
| 변경 | 설계 v3 그대로 | 권장 경계 적용 뒤 | 과거 재현 조건 |
|---|---|---|---|
| GAM 입력에 새 시간 특징 | ChanceModel, 호출부, 예보 생성부를 함께 수정 | 새 FeatureSpec과 GAM 산출물만 추가 | 이전 특징 스냅샷 보존 |
| 보정 방식 교체 | 독립 모델인지 장식자인지 불명확 | 기본 산출물 + 보정 산출물의 새 조합 | 적용·미적용 상태와 두 해시 보존 |
| GBIS 응답 키·코드 변경 | Snapshot.from과 후속 처리의 의미가 함께 흔들림 | 해당 변환기와 계약 검증용 고정 예제만 수정 | 원문·변환기 버전 보존 |
| 세 번째 노선·새 도시 | 상수·시간 규칙·마스터가 코드로 퍼질 수 있음 | 도시 정책·노선 버전·공급자 매핑을 데이터로 등록 | 유효기간 있는 기준정보 |
| 같은 모델 여러 버전 | 빌드별 단일 문자열로만 구분 | 산출물은 불변, 범위별 활성 포인터만 변경 | 예측마다 실제 발행본 참조 |
현재의 원문 무결성 검사, 순방향 평가, 고정 평가 구간, 완성된 정적 사이트만 한 번에 교체하는 발행 방식은 유지한다. 새 계약을 옆에 추가하고 같은 자료에서 결과를 대조한 뒤 읽기 경로를 바꾼다.
예측 대상을 출발 뒤 만석 사건으로 고정한다. 차량이 있는 정상 응답이 아니면 관측 연결을 끊고, stateCd·인접 응답·회차·KST 날짜·90초 초과 규칙과 p_full 의미를 테스트로 맞춘다.
CollectionOutcome, RouteVersion, FeatureSpec, DatasetSnapshot, ModelArtifact를 기존 경로 옆에 추가한다.
기존 수집 행과 새 표준 관측·라벨·특징을 함께 만들고 행·사건·결과를 전건 대조한다. 과거 행을 덮어쓰지 않는다.
7개 역할을 새 계약으로 평가하고, 승인된 발행본만 FullRiskForecast 생성 경로에 연결한다.
발행 자료 조회 전용 권한, 원문 보존 기간, 가명 키 회전, 감사 로그와 되돌릴 수 있는 기간을 검증한 뒤 중복 경로를 제거한다.
관측이 없던 과거 구간을 복원된 것처럼 채우거나, 과거 관측을 최신 노선 순번에 다시 연결하지 않는다. 원문이 없는 범위는 복구했다고 표시하지 않는다.
p_full, 미추정 사유가 문서와 계약 테스트에서 일치한다.stateCd, 인접 응답, 회차, KST 날짜와 90초 초과 규칙을 보존한다. 차량이 있는 정상 응답이 아니면 관측 연결을 끊는다.