데이터 모델 · 식별자 계약 (DM-*)

요구. 시스템은 아래 11개 D1 테이블(tenant, carrier, vehicle, driver, geofence, geofence_cell, shipment, stop, event, event_code_map, regulatory_report)을 반드시(MUST) 마이그레이션 0001_init.sql이 정의한 컬럼·CHECK 제약·UNIQUE·인덱스 그대로 유지해야 한다. 적용된 마이그레이션 파일은 불변이며, 변경은 새 번호 마이그레이션으로만 전진(forward-only) 한다.

수용기준

• Given 신규 D1 인스턴스, When 0001→0002→0003을 순서대로 적용, Then 11 코어 테이블 + auth 2테이블(auth_credential·api_key) + geofence_membership이 생성되고 모든 CHECK enum이 본 문서 §5·§6 카탈로그와 일치한다.
• Given 스키마, When 컬럼/제약을 본 문서와 대조, Then 차이가 0이다(이 페이지가 단일 진실원).

요구. 모든 시각 필드(occurred_at, actual_arrival_at, planned_* 등)는 ISO 8601 +09:00 오프셋을 명시해 저장(MUST)한다. 시스템은 오프셋이 없거나 잘못된 형식의 타임스탬프를 반드시 거부해야 한다. 荷待ち 법정 계산(dwell_minutes = actual_departure_at − actual_arrival_at)과 구속시간 산정이 이 정합성에 의존한다.

수용기준

• Given 인제스트/이벤트 페이로드, When 시각이 2026-06-13T09:00:00+09:00 형식, Then 그대로 저장된다.
• Given 오프셋 없는 ...T09:00:00 또는 모호한 로컬 시각, When 인제스트, Then 422로 거부된다.
• Given 같은 순간을 Z와 +09:00로 표현한 두 핑, When dedup, Then 동일 키로 1건만 저장(UTC 정규화 후 분 절단).

요구. 내부 식별은 시스템이 발급한 불변 ID(shipment_id, stop_id, event_id, geofence_id, carrier_id 등)로만 한다(MUST). 외부 식별자(shipper_ref = 送り状番号 / 화주 PO)는 별개 필드로 보관하며 PK로 쓰지 않는다(SHOULD). event_id는 UUID, 모든 ID는 라우팅/API에서 안정적이어야 한다.

수용기준

• Given 동일 화물이 두 번 인입(상이한 shipper_ref), When 복합 키로 매핑, Then 단일 shipment_id로 수렴(§11 정규화 레이어).
• Given 외부 시스템이 shipper_ref 변경, When 갱신, Then shipment_id는 불변 유지.

요구. 이벤트 멱등 삽입을 위해 event.dedup_key는 반드시 다음 정규 공식으로 합성하고 D1 UNIQUE로 강제한다:

dedup_key = sha256( source_type | shipment_id | canonical_code | floor(occurred_at→분) [| stop_id] )

occurred_at은 분 단위 내림(floor) 후 사용한다(혼재 오프셋은 UTC 정규화 후 절단 — DM-TS-001 정합). 삽입은 INSERT ... ON CONFLICT(dedup_key) DO NOTHING으로 처리해 Queues at-least-once 재전달과 지오펜스 OUTSIDE→INSIDE + last_seen_at 단조 가드를 안전하게 만든다.

수용기준

• Given 동일 (source_type, shipment_id, canonical_code, 분)의 핑 2건, When 두 번 삽입, Then 1건만 저장(ON CONFLICT DO NOTHING).
• Given 같은 순간의 Z·+09:00 표현, When dedup, Then 동일 키.
• Given 다른 분의 동일 이벤트, When 삽입, Then 별개 행(정상).

요구. 동일 shipment에 여러 소스가 같은 canonical 이벤트를 보내 충돌할 때, 시스템은 반드시 아래 정밀도 순서로 "정답"을 고른다. 동률(같은 정밀도)은 received_at 최소값(먼저 도착)을 채택한다.

event_code_map.confidence(HIGH/MEDIUM/LOW)는 매핑 신뢰도, 위 매트릭스는 소스 간 충돌 해소로 역할이 다르다. 일반적으로 캐리어 EDI > GPS 지오펜스 퇴출 추정.

수용기준

• Given EDI_X12:DELIVERED와 GEOFENCE:DELIVERED 동시 수신, When 충돌 해소, Then EDI_X12 채택.
• Given 동률 두 소스, When 해소, Then received_at 최소가 우선.

요구. 모든 소스의 raw 코드는 반드시 아래 canonical 11종 집합으로 매핑된다(+ 예외 코드 TRACKING_LOST). geofence-type → canonical 파생표를 동결하며, PORT/BORDER 파생은 PARTIAL(Phase 2, 현재 미파생)이다.

geofence-type → canonical 파생표(동결)

수용기준

• Given WAREHOUSE 지오펜스 ENTER, When 파생, Then ARRIVED_AT_PICKUP.
• Given CUSTOMER 지오펜스 EXIT(dwell>0), When 파생, Then DELIVERED + stop.actual_departure_at 채움.
• Given PORT/BORDER 적중, When 파생, Then 이벤트 미생성(PARTIAL, Phase 2 트래킹).

요구. shipment.current_status는 canonical 코드만 가지며(MUST), 정상 경로를 따라 단조 전진한다. 지오펜스 ENTER/EXIT가 current_status를 advance하고 stop.actual_arrival_at/actual_departure_at/dwell_minutes를 채운다.

CREATED → DISPATCHED → ARRIVED_AT_PICKUP → PICKUP_COMPLETED
        → IN_TRANSIT → ARRIVED_AT_DELIVERY → DELIVERED        (정상 종결)

분기:  (임의 상태) → EXCEPTION      (룰 엔진/X12 X6; exception_flag=1)
      (종결 전)   → CANCELLED      (X12 CA)
      배달 변형: OUT_FOR_DELIVERY → DELIVERY_ATTEMPTED → DELIVERED
      예외코드:  TRACKING_LOST    (45min 무핑, 상태머신 외 예외 표식)

arrival/departure 기록 규칙.

• arrival: 지오펜스 OUTSIDE→INSIDE(ENTER) 확정 시 stop.actual_arrival_at를 first-write-wins(COALESCE)로 기록 — 荷待ち 도착 시계가 뒤로 밀리지 않게 함.
• departure: INSIDE에서 핑 셀이 gridDisk(cover, +1)를 벗어나면(EXIT) actual_departure_at 기록 + dwell_minutes = departure − arrival 계산.
• 순서 가드: geofence_membership.last_seen_at(단조)로 늦게 도착한 pre-exit 핑이 arrival/departure를 뒤집지 못하게 한다(out-of-order drop).
• dwell > geofence.dwell_threshold_min(기본 120, 법정 2시간)이면 EXIT 이벤트에 荷待ち超過 플래그(FR-ENG-EXC-002).

수용기준

• Given WAREHOUSE ENTER 후 EXIT, When 처리, Then ARRIVED_AT_PICKUP→PICKUP_COMPLETED, arrival/departure/dwell_minutes 채워짐.
• Given 같은 stop의 두 번째 ENTER 핑, When 처리, Then actual_arrival_at은 첫 값 유지(COALESCE first-write-wins).
• Given 늦게 도착한 pre-exit 핑(captured_at ≤ last_seen_at), When 처리, Then drop되어 departure가 arrival을 역전하지 않음.

요구. 핑당 O(1) 지오펜스 멤버십 판정을 위해 KV에 역인덱스 cell → geofence_id[]를 둔다(권장). 키는 H3 셀 ID(latLngToCell 결과, 16진), 값은 그 셀을 덮는 지오펜스 ID 배열이다. D1 geofence_cell이 진실, KV는 판정 가속 사본이다.

• 값 형식: geofence_id 문자열 배열(빈 셀은 키 부재 = 매칭 없음).
• 재기록 시점: 지오펜스 생성·수정·삭제 시에만(읽기 多·쓰기 少). 등록/수정 시 polygonToCells로 geofence_cell·KV 역인덱스를 함께 재생성한다.
• 판정: interior 셀 적중 = 확정, boundary 셀 적중 = 그 핑만 point-in-polygon 1회 확인(하이브리드 PIP).

수용기준

• Given 지오펜스 폴리곤 수정, When 저장, Then geofence_cell 재생성 + KV 역인덱스 동일 트랜잭션적 재기록.
• Given 핑 셀 ID, When KV 조회, Then 1회 lookup으로 덮는 geofence_id[] 반환(폴리곤 PIP 미수행).

요구. 모든 shipment/stop/event/geofence(및 regulatory_report) 접근은 반드시 인증 컨텍스트의 tenant_id로 스코프된다. tenant_id는 토큰/API 키 클레임에서만 바인딩하고 클라이언트 입력에서 절대 받지 않는다. 타테넌트 행은 0행 → 404(존재 자체를 숨김; 403 아님).

• DRIVER 역할은 추가로 driver_id 스코프(자기 案件만).
• 모든 DB 접근을 단일 repo 계층으로 라우팅해 tenant_id 미바인딩 쿼리를 구조적으로 불가능하게 한다.

수용기준

• Given 테넌트 A 토큰, When 테넌트 B의 shipment_id GET, Then 404(0행).
• Given DRIVER 토큰, When 타 드라이버 案件 GET, Then 404.
• Given 임의 쿼리 경로, When 코드 검사, Then tenant_id 바인딩이 auth 컨텍스트에서만 옴.

요구. 단일 화물의 무한 폭증으로부터 D1·DO를 보호하기 위해 shipment당 stop·event 상한과 비정상 증가 알람을 둔다(권장). 일본 국내 트럭의 3계층 모델상 stop은 소수(1~2 구간)이므로 비정상 폭증은 데이터 오류·악용 신호다.

• 인제스트 배치는 서버 하드캡 500 samples/req(초과 413); 클라 목표 배치 100(FR-ACQ-API-001) — 이벤트 유입의 1차 가드.
• shipment당 stop/event 상한은 초기 확정 목표(설계)로 두고 운영 베이스라인으로 조정(OD-006 용량 베이스라인 post-launch).
• 비정상 증가(예: 한 shipment에 분당 이벤트 급증)는 비용/한도 근접 대시보드 알람(NFR-COST-001)과 연계.

수용기준

• Given 501 samples 단일 인제스트, When POST, Then 413.
• Given 한 shipment의 이벤트 비정상 폭증, When 모니터, Then 알람 발화(미매핑 급증 >50/시간 알람과 동형).

요구. 외부에서 들어오는 화물을 우리 shipment_id(불변)로 수렴시키는 정규화 레이어를 둔다(SHOULD).

• 복합 키 매핑: (화주 tenant + shipper_ref) 또는 (화주 PO + 운송사 + 날짜) 복합 키로 내부 shipment에 연결.
• 운송사별 파서: 번호 형식 비표준 → 운송사별 파싱·정규화 규칙(설정 관리). 초기엔 대형 운송사(ヤマト·佐川·NX·セイノー) 위주 선구축 — 개발보다 협상·조사 공수가 큰 작업.
• GS1 흡수 여지: GS1 Japan의 SSCC(출하포장 시리얼)·GLN(장소 식별) 보급 시 shipment.shipper_ref/geofence에 GLN을 표준 식별자로 승격할 수 있게 여지를 남긴다 추정(OD-008).

운송사 A 送り状番号: A-2025-0001  ┐
화주 PO: PO-98765                ├─→ [정규화 레이어 · 운송사별 파서]
운송사 B 전표: B/240515/77        ┘        │ 복합 키 매핑
                                          ▼
                          내부 shipment_id: SHP-2025-00456 (불변)

수용기준

• Given 운송사 A 형식 shipper_ref, When 파서 적용, Then 정규 복합 키로 단일 shipment_id 매핑.
• Given 동일 화물 중복 인입(상이 형식), When 매핑, Then 단일 shipment_id로 수렴(신규 행 생성 안 함).
• Given GLN 포함 화주 데이터, When 인입, Then shipper_ref에 GLN 보존(흡수 여지).