North Star 지표 · KPI 트리

01-product/north-star-kpi.html · LogiNippon · TRD · 2026-06-13 · 신뢰도 라벨 확인 추정 설계

이 페이지는 LogiNippon의 성공을 측정 가능하게 고정한다. 하나의 North Star Metric(NSM)을 결정적으로 고르고 그 이유를 밝히며, NSM을 정점으로 입력·결과·사업 지표를 KPI 트리로 묶고, 각 KPI의 정확한 공식(분자/분모/측정윈도/제외/반올림)을 마스터 스펙 §4.2의 정규 수치 그대로 정의한다. 단계별 목표치(Phase 1 MVP exit floor vs 정상상태 지향치)와 각 KPI의 데이터 출처·SLO 연결을 명시한다. 모든 목표치는 운영 데이터 없는 진입 단계의 초기 확정치(설계)이며, 운영 베이스라인으로 분기별 조정한다 — 달성치가 아니다.

1. North Star 지표 (NSM)

NSM은 "제품이 고객에게 전달하는 핵심 가치를 한 숫자로 대리하는 지표"여야 하고, 우리 비전과 정합해야 한다. 비전(vision.md)의 한 문장은 "일본 국내 B2B 트럭 화물 운송에 B2C 택배 수준의 화물 단위 실시간 가시성을 가져온다"이고, 핵심 난이도는 UI가 아니라 多重下請け(元請→下請→孫請)를 관통해 실제 운행 차량의 위치를 조직 경계를 넘어 확보하는 데 있다. 즉 우리가 파는 가치는 "보이게 만드는 것"이고, 그 가치가 실제로 발생했음을 가장 직접적으로 증명하는 부산물이 위치·체류 데이터의 수집 커버리지다.

결정 — NSM = Tracking Rate (추적 커버리지). 활성 화물 중 GPS 이벤트로 실제 가시화된 비율을 NSM으로 확정한다(KPI-NSM-001). 설계

왜 Tracking Rate인가.

고려했으나 보조로 강등한 대안. 더 복합적인 정의 "추적 커버리지로 가시화된 화물 비율 × 荷待ち 단축분"도 검토했으나, 두 단위를 곱한 합성지표는 (a) 해석이 모호하고 (b) 荷待ち 단축은 외생 요인(거점 운영) 의존도가 높아 제품 가치 귀속이 어렵다. 따라서 荷待ち 단축(KPI-DWELL-001)은 NSM이 아니라 1차 결과지표로 둔다 — NSM이 오르면 결과지표가 따라 오른다는 인과 가설을 트리로 표현한다.

KPI-NSM-001 North Star Metric = Tracking Rate P0Phase 1A 분석

요구. 시스템은 활성 화물의 추적 커버리지(Tracking Rate)를 NSM으로 정의하고 반드시 대시보드·리포트에서 staleness와 함께 정직하게 노출해야 한다(MUST). 정의·공식은 KPI-TRACK-001을 단일 진실원으로 따른다.

수용기준

  • Given 28일 롤링 윈도의 활성 화물 집합, When NSM을 산출하면, Then 값은 Σ received_pings / Σ expected_pings로 계산되고 0–100%로 표기된다.
  • Given NSM 표기, When 화면/리포트에 표시하면, Then 100%는 비현실(스마트폰 GPS 한계)임을 명시하고 staleness 분포를 함께 노출한다.
  • Given 추적 손실(FR-ENG-EXC-003) 발생 구간, When NSM을 계산하면, Then 해당 구간의 누락 핑이 분모(expected)에 반영되어 NSM을 낮춘다(은폐 금지).
근거 vision.md(가시성=핵심가치·부산물 수집) · delivery.md(Tracking Rate 정직 노출) · Research H3 · 구현 server/src/lib/reports.ts(집계 기반 존재) — Analytics Engine writeDataPoint TODO로 SLI 미측정 PARTIAL · 검증 분석(NSM 산출 쿼리) · SLO-S4

2. KPI 트리

NSM(Tracking Rate)을 정점에 두고, 가시성이 확보되면 결과가 개선되고 결과가 개선되면 사업이 자란다는 인과 가설을 트리로 표현한다. 각 노드의 타깃은 마스터 스펙 §4.2 인용(초기 확정 목표, 설계)이다. 사업지표 수치는 본 TRD가 정한 보수적 가설로 추정 라벨을 붙인다.

읽는 법. 입력지표는 우리가 엔지니어링으로 직접 끌어올리는 레버(정규화·ETA·추적), 결과지표는 그 결과로 고객 페인이 줄어드는 정도(荷待ち·OTD·예외), 사업지표는 그 가치가 시장에서 돈·잔존으로 환산되는 정도다. NSM↑ → 결과지표↑ → 사업지표↑가 핵심 인과 가설이며, 트리의 모든 화살표는 검증 대상이다.

3. KPI 정의 표

아래 8개 KPI의 공식은 마스터 스펙 §4.2를 그대로 인용한다(임의 변형 금지). 분자/분모/측정윈도/제외/반올림을 고정해 측정 재현성을 보장한다. 모든 목표치는 진입 단계 초기 확정 목표(설계)다.

KPI · ID공식 (분자 / 분모)측정윈도제외 · 반올림확정 목표
Tracking Rate
KPI-TRACK-001 (S4)		 received_pings / expected_pings; expected = active_segment_sec / ping_cadence 28일 롤링 비활성 구간 expected 미산입; 100%는 비현실(스마트폰 GPS 한계)로 정직 노출 MVP exit floor ≥ 85%, 정상상태 지향 ≥ 92%
ETA MAPE
KPI-ETA-001 (S7)		 mean(|actual − predicted| / actual); 배달 12h 전 기준 예측 사용 완료 운행 집계(레인 클래스별) eta_is_estimate=1 표기; 룰 ETA는 하드 SLO 아님 룰 기반 ≤ 25%, ML 후 ≤ 15% (Shippeo 90%@12h는 지향 참조 추정)
정규화 정확도
KPI-NORM-001 (S8)		 canonical 해결 이벤트 / 전체 raw 이벤트 일(日) 집계 미매핑 비율 <1%/일; 정밀도 매트릭스 후 충돌 0 ≥ 99% canonical 해결; 미매핑 급증 알람 >50/시간
OTD 정시 배달률
KPI-OTD-001		 (약속시각 이내 배달 / 전체 배달) ×100 30일 롤링 (JST) 취소 제외; 소수점 1자리 베이스라인 측정 후 분기 목표 설정 설계
OTP 정시 픽업률
KPI-OTP-001		 OTD와 동형(픽업 시각 기준) 30일 롤링 (JST) 취소 제외; 소수점 1자리 OTD와 동형 설계
평균 荷待ち (Dwell)
KPI-DWELL-001		 AVG(actual_departure − actual_arrival); 거점/운송/기간별 거점·운송·기간별 그룹 mean + p90 함께 보고 법정 2시간(=120min, FR-ENG-EXC-002) 초과분 표시 확인
예외율 (Exception Rate)
KPI-EXC-001		 (예외 화물 / 전체 화물) ×100 기간 집계 예외 정의는 FR-ENG-EXC-001..006 베이스라인 후 추이 관리 설계
CO₂ 추정
KPI-CO2-001		 Σ(구간거리km × 차급 배출계수) 화물·기간별 화주 ESG 보고용 제공 자체가 목표(스코어카드 동봉) 설계

아래 카드는 NSM과 1차 입력지표 3종을 정규 요구사항으로 고정한다(나머지 결과/사업 KPI는 위 표를 단일 진실원으로 참조). 추적 손실(FR-ENG-EXC-003)·荷待ち 초과(FR-ENG-EXC-002)·예외 정의(FR-ENG-EXC-*)는 functional.html이 소유하므로 여기서는 링크로 참조한다.

KPI-TRACK-001 Tracking Rate 추적 커버리지 (SLI S4) P0Phase 1A 분석

요구. 시스템은 추적 커버리지를 received_pings / expected_pings(expected = active_segment_sec / ping_cadence)로 산출하고, MVP exit floor ≥ 85%를 단계 종료 게이트로 반드시 충족해야 한다(MUST). 정상상태 지향치는 ≥ 92%다.

수용기준

  • Given 28일 롤링 윈도, When Tracking Rate를 산출하면, Then 분모 expected는 활성 구간 길이를 ping cadence(FR-ACQ-GPS-001 30/60/180s)로 나눠 계산한다.
  • Given Phase 1 MVP exit 평가, When 측정값이 ≥ 85%이면, Then 게이트 통과; 미만이면 차단(GATE-P1).
  • Given 어떤 화물도 100% 커버리지에 도달하지 못함, When 사용자에게 노출하면, Then 100% 천장이 비현실임을 명시하고 staleness 분포를 동반한다.
근거 마스터 §4.2 KPI-TRACK-001 · delivery.md(추적 커버리지 정직 노출) · 구현 GET /v1/shipments/tracking 배치 라이브 스냅샷 존재(console FleetMap 6s 폴링 하드의존, 스펙 미기재 as-built); 28일 롤링 Tracking Rate 집계 SLI는 Analytics Engine writeDataPoint TODO로 미측정 PARTIAL · 검증 SLO-S4
KPI-ETA-001 ETA MAPE 예측 정확도 (SLI S7) P1Phase 1A 분석

요구. 시스템은 ETA 예측 정확도를 MAPE(배달 12h 전 예측 기준)로 측정하고, 룰 기반 단계에서 ≤ 25%를 권장 목표로, ML 전환 후 ≤ 15%를 지향치로 둔다(SHOULD). 룰 기반 MAPE는 하드 SLO가 아니다.

수용기준

  • Given 완료 운행 집합, When MAPE를 레인 클래스별로 산출하면, Then eta_is_estimate=1인 예측만 룰-MAPE에 포함된다.
  • Given 레인-클래스 누적 ≥ 3,000 완료 운행 AND 룰-MAPE > 20%, When 트리거 조건이 충족되면, Then ML 전환을 개시한다(FR-ENG-ETA-002).
근거 마스터 §4.2 KPI-ETA-001 · 구현 handleEtaBatch ack-only(룰 미구현) STUB · 검증 SLO-S7
KPI-NORM-001 이벤트 정규화 정확도 (SLI S8) P0Phase 1A 분석

요구. 시스템은 raw_code의 ≥ 99%를 canonical 이벤트로 해결해야 하며(MUST), 미매핑 비율은 < 1%/일을 유지해야 한다. 미매핑이 > 50/시간으로 급증하면 알람을 발생시킨다.

수용기준

  • Given 일(日) 단위 raw 이벤트 집합, When 정규화하면, Then canonical 해결 비율 ≥ 99%이고 미매핑 < 1%/일이다.
  • Given 정밀도 매트릭스(DM-EVT-PREC-001) 적용 후, When 동일 사건의 다중 소스가 충돌하면, Then 충돌 0(정밀도·received_at 규칙으로 결정).
  • Given 미매핑 발생률, When > 50/시간을 초과하면, Then 운영 알람을 발생시킨다.
근거 마스터 §4.2 KPI-NORM-001 · DM-EVT-ENUM-001(canonical enum) · 구현 정규화·dedup 로직 존재 DONE · 검증 SLO-S8

4. 단계별 목표치 — Phase 1 MVP exit floor vs 정상상태 지향치

진입 단계에는 운영 데이터가 없으므로, KPI를 둘로 나눠 관리한다. Phase 1 MVP exit floor는 단계 종료 게이트(하드 바닥선)이고, 정상상태 지향치는 운영 베이스라인으로 분기 조정하는 도전 목표다. 두 값 모두 초기 확정치(설계)이며, 명시적 개정 트리거를 둔다.

≥85%
Tracking Rate — MVP exit floor (정상상태 ≥92%)
≤25%
ETA MAPE 룰 기반 floor (ML 후 ≤15%)
≥99%
정규화 정확도 — MVP exit floor
120min
荷待ち 법정 2시간 목표 — 초과 표시 임계
KPIPhase 1 MVP exit floor (게이트)정상상태 지향치 (도전)개정 트리거
Tracking Rate (KPI-TRACK-001)≥ 85%≥ 92%2분기 연속 >92% 또는 <85% 시 재설정
ETA MAPE (KPI-ETA-001)룰 기반 ≤ 25%ML 후 ≤ 15%레인 누적 ≥3,000 & 룰-MAPE >20% → ML 전환
정규화 정확도 (KPI-NORM-001)≥ 99% (미매핑 <1%/일)정밀도 매트릭스 후 충돌 0미매핑 >50/시간 알람 누적 시
荷待ち Dwell (KPI-DWELL-001)측정 가동(거점별 mean+p90)법정 2시간(120min) 초과 건 감소물流効率化法 2026.4 목표 갱신 시
OTD/OTP/예외율베이스라인 측정 가동분기별 목표 상향베이스라인 확보 후 첫 분기 검토

구현 현실(as-built) 주의. 위 목표는 측정 인프라가 가동되어야 검증 가능하다. 현재 Analytics Engine METRICS.writeDataPoint가 TODO 상태라 SLI가 미측정이고(slo-catalog OBS-METRICS-001), handleEtaBatch는 ack-only stub이며 룰 ETA가 미구현이다. 따라서 ETA MAPE는 엔진 구현 후에야 베이스라인을 잡을 수 있다. Tracking Rate는 GET /v1/shipments/tracking 배치 라이브 스냅샷(console FleetMap 6s 폴링 의존)으로 라이브 위치 노출은 되나, 28일 롤링 커버리지 집계 SLI 방출은 미가동이다.

5. 측정 출처 — 데이터·SLO 연결과 정직성 원칙

각 KPI가 어느 데이터 소스(D1 / Analytics Engine)에서 산출되고 어느 SLO에 연결되는지 고정한다. 실시간 1건 조회는 D1, 28일/일 롤링 집계는 Analytics Engine·Cron 집계 경로다(delivery.md §분석).

KPI데이터 소스연결 SLO비고
Tracking RateAnalytics Engine(28일 롤링 커버리지) · 라이브 위치는 D1/DOSLO-S4GET /v1/shipments/tracking 배치 스냅샷(as-built); 집계 SLI는 writeDataPoint TODO로 미측정
ETA MAPED1 완료 운행 + Cron 재계산(*/5 * * * *)SLO-S7handleEtaBatch 룰 구현 후 측정 STUB
정규화 정확도D1 event(canonical) + 미매핑 카운터SLO-S8미매핑 >50/시간 알람
荷待ち DwellD1 stop.dwell_minutes(지오펜스 자동 측정)SLO-S2(지오펜스 lag)일/월 Cron 리포트(0 17 * * *=02:00 JST)
OTD / OTP / 예외율D1 집계(JST, 취소 제외)리포트 경로 NFR(nonfunctional)30일 롤링, 소수1
CO₂ 추정D1 구간거리 × 차급 배출계수—화주 ESG 스코어카드

정직성 원칙 (Honesty by design). Tracking Rate와 staleness_seconds(마지막 핑 경과)를 제품 표면에 그대로 노출한다 — 스마트폰 GPS 한계를 숨기지 않는다(vision.md·delivery.md §개인정보 보호 설계, acquisition.md). 구체 규칙: console 플릿 폴링은 핀 >60s = stale 표시, >300s = drop(NFR-PERF-003b). 100% 커버리지는 비현실임을 명시하고, NSM에 거짓 천장을 두지 않는다. 추적 손실(FR-ENG-EXC-003, 마지막 유효 핑 후 45min)은 NSM 분모에 반영되어 지표를 낮춘다 — 누락을 은폐하지 않는다.

법무 확인 플래그(RR-LEGAL). 荷待ち 법정 2시간(120min) 목표와 規制 출력(実運送体制管理簿·荷待ち 기록)이 KPI에 미치는 정의는 物流効率化法·改正物流法의 공식 포맷·산정 규칙에 의존한다. 공식 포맷의 법무 서명 전까지는 추정으로 표기하며, 확정 절차는 RR-LEGAL-001을 따른다.

근거·상호참조