클라이언트 계약은 확정됐다
백엔드는 그것을 무엇으로 조립하나

SELECT id, response_received_at, stored_rows
  FROM location_poll
 WHERE route_reference_version_id = :refVersionId
   AND outcome IN ('SUCCESS_ROWS', 'SUCCESS_EMPTY')
   AND forecast_completed_at IS NOT NULL
 ORDER BY response_received_at DESC
 LIMIT 1;

WITH ranked AS (
    SELECT p.target_stop_order,
           o.vehicle_id,
           p.horizon_stops,
           p.p_full,
           p.expected_seats,
           row_number() OVER (
               PARTITION BY p.target_stop_order
               ORDER BY p.horizon_stops, o.vehicle_id, o.source_row_no) AS rn
      FROM vehicle_observation o
      JOIN vehicle_stop_prediction p
        ON  p.vehicle_observation_id     = o.id
        AND p.route_reference_version_id = o.route_reference_version_id
      JOIN route_stop s
        ON  s.route_reference_version_id = p.route_reference_version_id
        AND s.stop_order                 = p.target_stop_order
     WHERE o.poll_id = :pollId
       AND s.boarding_allowed
)
SELECT target_stop_order, vehicle_id, horizon_stops, p_full, expected_seats
  FROM ranked
 WHERE rn <= 3
 ORDER BY target_stop_order, horizon_stops;

SELECT stop_order, station_id, name, direction, boarding_allowed
  FROM route_stop
 WHERE route_reference_version_id = :refVersionId
 ORDER BY stop_order;

-- 활성 노선 판본
SELECT id, reference_version_id, source_route_id, display_name,
       start_stop_name, end_stop_name, turn_sequence,
       up_first_departure_time,   up_last_departure_time,
       down_first_departure_time, down_last_departure_time
  FROM route_reference_version
 WHERE source_route_id = :sourceRouteId
   AND valid_to IS NULL;

-- 그 판의 예보를 낸 배포. 예보 행이 없으면 0행이 나오고, 그때만 ACTIVE 를 읽는다
SELECT d.release_id, d.trained_through
  FROM model_deployment d
 WHERE d.id = (SELECT min(p.model_deployment_id)
                 FROM vehicle_stop_prediction p
                 JOIN vehicle_observation o ON o.id = p.vehicle_observation_id
                WHERE o.poll_id = :pollId);

{
  "route": {
    "id": "204000057",              // route_reference_version.source_route_id
    "displayName": "3330",          // display_name
    "startStopName": "도촌동9단지앞",
    "endStopName": "안양역",
    "status": "FORECAST_READY",     // ACTIVE 배포가 이 판본을 지원한다
    "turnSequence": 43,             // turn_sequence
    "referenceVersionId": "3330-v5",
    "directions": [
      { "id": "UP",   "name": "안양역 방면",
        "originStopName": "도촌동9단지앞",   // route_stop, stop_order = 1
        "terminalStopName": "안양역",        // route_stop, stop_order = 43
        "firstDepartureTime": "04:50", "lastDepartureTime": "23:30" },
      { "id": "DOWN", "name": "도촌동9단지앞 방면",
        "originStopName": "안양역",          // 회차 정류장. 44 가 아니다
        "terminalStopName": "도촌동9단지앞", // route_stop, 마지막 stop_order = 85
        "firstDepartureTime": "05:00", "lastDepartureTime": "23:30" }
    ]
  },
  "observedAt": "2026-08-18T08:29:47+09:00",   // location_poll.response_received_at
  "model": {
    "releaseId": "seat-distribution-3330-20260819-001",
    "trainedThrough": "2026-08-18T23:59:59+09:00"
  },
  "vehiclesInService": 14,                     // location_poll.stored_rows
  "stops": [
    {
      "sequence": 55,                          // route_stop.stop_order
      "stopId": "209000135",
      "name": "롯데백화점.범계역",
      "direction": "DOWN",
      "boardingAllowed": true,
      "approachingVehicles": [
        { "vehicleId": "SYNTH-VEH-001", "horizonStops": 3,
          "seatAvailableProbability": 0.871,   // 1 - p_full
          "expectedSeats": 28.2 },
        { "vehicleId": "SYNTH-VEH-008", "horizonStops": 8,
          "seatAvailableProbability": 0.912,
          "expectedSeats": 30.7 },
        { "vehicleId": "SYNTH-VEH-009", "horizonStops": 12,
          "seatAvailableProbability": 0.946,
          "expectedSeats": 33.1 }
      ]
    },
    {
      "sequence": 62,                          // 학의JC(경유)
      "stopId": "277103156",                   // 접두 277 = 경유 지점 대역
      "name": "학의JC(경유)",
      "direction": "DOWN",
      "boardingAllowed": false,                // route_stop.boarding_allowed
      "approachingVehicles": []                // ② 가 s.boarding_allowed 로 걸러서 늘 빈 배열이다
    }
  ]
}

// BoardQueryService — 이 메서드가 유일한 뒤집기 지점이다
static double seatAvailableProbability(double pFull) {
    return 1.0d - pFull;
}

// 노선 골격 + 스냅샷 + 모델 표시. 한 요청에 한 개.
public record BoardRow(
        long           referenceVersionId,          // 아래 질의들의 키
        String         referenceVersionKey,         // reference_version_id — 응답에 나가는 값
        String         sourceRouteId,
        String         displayName,
        String         startStopName,
        String         endStopName,
        Integer        turnSequence,                // null = 단방향
        String         upFirstDepartureTime,
        String         upLastDepartureTime,
        String         downFirstDepartureTime,
        String         downLastDepartureTime,
        long           pollId,
        OffsetDateTime observedAt,                  // location_poll.response_received_at
        int            vehiclesInService) {         // location_poll.stored_rows
}

// route_stop 한 행. 예보가 붙지 않는다.
public record StopRow(
        int       stopOrder,
        String    stationId,                          // route_stop.station_id 그대로. 응답에서는 stopId 로 나간다
        String    name,
        Direction direction,
        boolean   boardingAllowed) {
}

// vehicle_stop_prediction 한 행 + 그 관측의 차량. p_full 은 아직 뒤집지 않았다.
public record PredictionRow(
        int    targetStopOrder,                     // StopRow.stopOrder 와 짝짓는 키
        String vehicleId,                           // 공급자가 빠뜨리면 null
        int    horizonStops,
        double pFull,
        Double expectedSeats) {                     // null 이면 응답에서 키째 뺀다
}

// SQL 만 안다. 계산하지 않고 뒤집지 않는다.
public interface BoardQuery {

    /** 활성 판본 + 예보까지 끝난 마지막 poll. 어느 하나가 없으면 비어 돌아온다. */
    Optional<BoardRow> findCurrentBoard(String sourceRouteId);

    /** 그 판본의 모든 정류장. 승차 불가 정류장도 담는다. */
    List<StopRow> findStops(long referenceVersionId);

    /** 그 poll 의 예보. 정류장마다 지평 오름차순 앞의 둘만. */
    List<PredictionRow> findPredictions(long pollId);

    /** 그 poll 의 예보를 낸 배포. 예보 행이 없으면 비어 돌아온다. */
    Optional<ModelView> findModel(long pollId);

    /** ACTIVE 배포. 위가 비었을 때만 부른다. */
    Optional<ModelView> findActiveModel();
}

@Service
public class BoardQueryService {

    private final BoardQuery query;

    public BoardQueryService(BoardQuery query) {
        this.query = query;
    }

    @Transactional(readOnly = true)
    public BoardView findCurrentBoard(String sourceRouteId) {
        BoardRow board = query.findCurrentBoard(sourceRouteId)
                .orElseThrow(() -> new ForecastUnavailableException(NO_RECENT_OBSERVATION));

        ModelView model = query.findModel(board.pollId())
                .or(query::findActiveModel)
                .orElseThrow(() -> new ForecastUnavailableException(MODEL_OUT_OF_SCOPE));

        List<StopRow> stops = query.findStops(board.referenceVersionId());
        Map<Integer, List<PredictionRow>> byStop = query.findPredictions(board.pollId()).stream()
                .collect(groupingBy(PredictionRow::targetStopOrder, LinkedHashMap::new, toList()));

        return new BoardView(
                RouteView.of(board, stops),
                board.observedAt(),
                model,
                board.vehiclesInService(),
                stops.stream().map(s -> toStopView(s, byStop)).toList());
    }

    private static StopView toStopView(StopRow s, Map<Integer, List<PredictionRow>> byStop) {
        List<ApproachingVehicleView> approachingVehicles = byStop.getOrDefault(s.stopOrder(), List.of()).stream()
                .map(BoardQueryService::toApproachingVehicleView)
                .toList();
        return new StopView(s.stopOrder(), s.stationId(), s.name(),
                            s.direction(), s.boardingAllowed(), approachingVehicles);
    }

    private static ApproachingVehicleView toApproachingVehicleView(PredictionRow a) {
        return new ApproachingVehicleView(a.vehicleId(), a.horizonStops(),
                               seatAvailableProbability(a.pFull()),
                               a.expectedSeats());
    }

    /** 만석 확률을 빈자리 확률로. 뒤집기는 여기 한 곳뿐이고 반올림하지 않는다. */
    static double seatAvailableProbability(double pFull) {
        return 1.0d - pFull;
    }
}

public record BoardView(
        RouteView      route,
        OffsetDateTime observedAt,
        ModelView      model,
        int            vehiclesInService,
        List<StopView> stops) {
}

public record RouteView(
        String              id,
        String              displayName,
        String              startStopName,
        String              endStopName,
        RouteStatus         status,
        Integer             turnSequence,       // null 이어도 키를 뺄 수 없다. 필수 필드다
        List<DirectionView> directions,
        String              referenceVersionId) {
}

public record StopView(
        int               sequence,
        String            stopId,       // ← 여기가 유일한 개명 지점: StopRow.stationId → StopView.stopId
        String            name,
        Direction         direction,
        boolean           boardingAllowed,
        List<ApproachingVehicleView> approachingVehicles) {           // 오는 차가 없으면 빈 배열. null 이 아니다
}

public record ApproachingVehicleView(
        String vehicleId,                       // 필수 · null 허용
        int    horizonStops,
        double seatAvailableProbability,
        @JsonInclude(JsonInclude.Include.NON_NULL)
        Double expectedSeats) {                 // 선택 · 없으면 키째 빠진다
}

HTTP/1.1 503 Service Unavailable
Cache-Control: no-store
Retry-After: 300

{
  "code": "NO_RECENT_OBSERVATION",
  "message": "no vehicle observation recent enough to anchor a forecast",
  "requestId": "req-01J9X2ABCF",
  "retryable": true
}