에픽 · 유저스토리

荷主 운영자로서 다단계 하청을 관통한 실시간 화물 위치를 한 지도에서 보고 싶다, 그래야 전화 없이 전체 상태를 한눈에 파악한다.

수용기준

• Given 위치 핑이 인제스트된 운송이 있을 때, When 운영자가 地図를 열면, Then 차량 아이콘이 상태색(IN_TRANSIT/EXCEPTION/DELIVERED 등)으로 표시되고 WebSocket으로 이동을 반드시 갱신한다.
• Given 아직 핑이 0건일 때, When 지도를 열면, Then 화면은 반드시 비어 있지 않다(never-empty) — 운송 경로(stop pin·route)와 位置データを受信していません 상태를 보여준다.
• Given WebSocket이 끊겼을 때, When 재연결 중이면, Then 接続エラー（再試行中）를 표시하고 권장 자동 재시도한다.

荷主 운영자로서 전체 화물을 목록(輸送一覧)으로 보고 특정 건을 골라 지도·상세로 내려가고 싶다, 그래야 "이 PO 지금 어디"를 즉시 확인한다.

수용기준

• Given 자사 화물이 여러 건일 때, When 輸送 탭을 열면, Then 운송ID·화주참조(荷主参照)·상태·배달ETA 열을 가진 목록을 반드시 보여준다.
• Given 목록에서 한 행을 클릭할 때, When 행을 선택하면, Then 해당 화물로 지도 포커스가 이동하고 상태·최신 위치를 반드시 표시한다.
• Given 자사 화물이 없을 때, When 목록을 열면, Then 輸送はありません 빈 상태를 반드시 명시한다(오류 아님).

荷主 운영자로서 화면의 ETA가 추정치인지·마지막 핑이 얼마나 오래됐는지 명확히 보고 싶다, 그래야 데이터를 과신하지 않고 의사결정한다.

수용기준

• Given 룰 기반 ETA가 추정치(eta_is_estimate=true)일 때, When 운송 상세를 보면, Then UI는 （推定） 라벨을 반드시 붙인다(달성치로 위장 금지).
• Given 트래킹 데이터에 staleness/tracking_rate가 있을 때, When 화물을 보면, Then 마지막 핑 경과·추적 커버리지를 권장 정직하게 노출한다.

荷主 운영자로서 元請이 아닌 실제로 운반 중인 孫請(실운송) 차량을 위치로 식별해 보고 싶다, 그래야 계약상의 캐리어가 아니라 진짜 운송 주체를 안다(해자=네트워크).

수용기준

• Given 화물에 元請(carrier)과 실운송(actual_carrier)이 다를 때, When 화물 상세를 보면, Then 실시간 위치로 검증된 실운송 차량의 캐리어 계층을 권장 구분 표시한다.
• Given 캐리어 개인정보(드라이버 실명·番号板)일 때, When 화주 스코프로 조회하면, Then 마스킹 규칙(display_name·plate 부분 마스킹)을 반드시 적용한다.

荷主 운영자로서 지정 기간의 荷待ち(체류) 시간을 집계해 CSV로 내보내고 싶다, 그래야 수기 작성 없이 監督官庁 제출·납품처 개선 협상 근거를 쥔다.

수용기준

• Given 운영자가 規制의 開始日/終了日을 고를 때, When レポート生成을 누르면, Then 거점별·운송별 dwell을 집계하고 법정 2시간 초과 건을 반드시 표시한다.
• Given 리포트가 생성됐을 때, When 결과를 보면, Then 행수({n}件)·리포트ID(report_id)·생성 시각(JST)을 반드시 보여준다.
• Given 운영자가 CSVダウンロード를 누를 때, When 파일을 받으면, Then 監督官庁용으로 UTF-8 BOM CSV를 반드시 내려준다.

荷主 운영자로서 리포트 기간이 항상 올바른 범위(JST 기준·≤92일)로 강제되길 원한다, 그래야 무효한 산출물이나 과도한 D1 스캔을 막는다.

수용기준

• Given 開始日 ≥ 終了日 이거나 92일을 초과할 때, When 생성하려 하면, Then 期間が正しくありません（開始日 < 終了日、92日以内） 오류를 반드시 보여주고 생성을 막는다.
• Given 유효한 기간일 때, When 리포트를 생성하면, Then 모든 타임스탬프를 JST로 반드시 표기한다(監督官庁 일관성).

荷主 운영자로서 납품처별 평균 荷待ち·법정 초과 건을 측정해 비교하고 싶다, 그래야 개선 협상의 측정가능 ROI 근거(예: 3-4h→1-2h 단축)를 손에 쥔다.

수용기준

• Given 집계 기간이 지정될 때, When 리포트를 보면, Then 거점/납품처 단위로 평균 체류·>120분 건수를 반드시 분해해 보여준다.
• Given 협상에 사용할 산출물일 때, When 다운받으면, Then 동일 report_id로 반복 출력이 권장 가능하다(R2 egress 무료).

荷主(元請) 운영자로서 청부 체인(元請→下請→孫請)과 실시간 위치로 검증된 실운송 차량을 결합한 実運送体制管理簿를 자동 생성하고, 운행·체류 타임스탬프를 拘束時間 산정의 보조 데이터로 내보내고 싶다.

수용기준

• Given 화물의 청부 계층(tier·parent_carrier_id)과 검증된 실운송 차량이 있을 때, When 운영자가 実運送体制管理簿를 요청하면, Then 실운송 사업자 명칭·청부 계층 리포트를 반드시 생성한다(목표 동작). STUB — 현재 GET /v1/reports/jitsuunso는 501이다.
• Given 공식 포맷이 미확정일 때, When 산출물을 광고하면, Then RR-LEGAL-001 서명 전까지 "官庁 제출 가능" 표기를 반드시 금지한다.
• Given 운행·체류 타임스탬프가 있을 때, When 拘束時間 보조 export를 요청하면, Then 보조 데이터로만(전용 노무관리 대체 아님) 제공함을 반드시 명시한다.

PLATFORM_ADMIN으로서 운송사업자(運送事業者)·도착지(consignee)·물리 거점(facility)·지오펜스를 管理 탭에서 만들고 싶다, 그래야 신규 파트너를 빠르게 온보딩한다.

수용기준

• Given PLATFORM_ADMIN으로 로그인했을 때, When 運送事業者の管理에서 사업자명을 입력하면, Then 캐리어를 반드시 생성하고 목록에 표시한다.
• Given 도착지를 만든 뒤, When 그 하위에 拠点(facility)를 주소와 함께 추가하면, Then 거점과 지오펜스를 반드시 생성한다.
• Given 비-admin 역할로 접근할 때, When 管理 탭을 시도하면, Then 역할 게이트로 반드시 차단한다.

PLATFORM_ADMIN으로서 캐리어별로 1회용 드라이버 초대코드를 발급하고 싶다, 그래야 셀프가입 없이도 드라이버가 안전하게 자동 등록할 입구를 만든다.

수용기준

• Given 캐리어를 선택했을 때, When コードを発行을 누르면, Then max_uses=1·ttl=30d 초대코드를 반드시 발급한다.
• Given 코드가 발급된 직후, When 화면에 표시될 때, Then 코드는 1회만 표시되고(必ずコピーしてドライバーへ伝達) 재표시되지 않음을 반드시 경고한다.
• Given 발급된 코드가 미사용 상태일 때, When admin이 無効化를 누르면, Then 해당 코드를 반드시 즉시 무효화한다.

PLATFORM_ADMIN으로서 실 트럭·GPS 없이 캐리어·도착지·드라이버·차량·운송을 만들고 위치를 시뮬레이션해 픽업→도착→대시보드 전 흐름을 검증하고 싶다, 그래야 cold-start 데모로 도입 가치를 증명한다.

수용기준

• Given 運送登録(factory) 4스텝에서, When ①사업자·도착지 ②차량·드라이버 ③멀티스톱 운송 ④위치 시뮬을 진행하면, Then 시뮬 위치를 반드시 ingest로 전송한다.
• Given 멀티스톱을 정의할 때, When stop을 추가하면, Then ≥1 PICKUP·≥1 DROPOFF·마지막=DROPOFF 규칙을 반드시 강제한다(milk-run/LTL 지원).
• Given 위치를 시뮬레이트한 뒤, When 지도/Inbound/대시보드를 보면, Then 동일 화물이 전 화면에 반영됨을 반드시 확인할 수 있다.

드라이버로서 발급받은 1회용 코드로 앱에서 셀프등록(비번≥8·APPI 동의)하고 싶다, 그래야 관리자 개입 없이 案件 수신을 시작한다.

수용기준

• Given 유효한 미사용 코드를 입력할 때, When 드라이버가 등록을 완료하면, Then 비번(≥8자)·APPI 동의와 함께 계정을 반드시 생성하고 코드를 소비(use)한다(목표 동작).
• Given 이미 사용/만료/무효화된 코드일 때, When 등록을 시도하면, Then 반드시 거부한다.

PLATFORM_ADMIN으로서 캐리어를 선택하고 그 드라이버(氏名/パスワード/APPI 동의)와 차량(ナンバープレート)을 생성·수정·비번 리셋하고 싶다, 그래야 캐리어 인적·차량 자산을 정확히 유지한다.

수용기준

• Given 캐리어를 선택했을 때, When 신규 드라이버를 추가하면, Then 氏名(선택)·비번(8자 이상)·APPI 동의를 받아 반드시 생성한다.
• Given 비번이 8자 미만일 때, When 저장하려 하면, Then パスワードは8文字以上 오류로 반드시 막는다.
• Given 기존 드라이버를 편집할 때, When 새 비번(선택)을 입력하면, Then 비번을 반드시 리셋하고, 차량은 번호판으로 반드시 생성·수정한다.

PLATFORM_ADMIN으로서 드라이버별 운송 일정(어디서→어디로·시각)을 보고, 정류점을 inline으로 추가·수정·삭제하고 싶다, 그래야 멀티스톱 운송을 정확히 배차·조정한다.

수용기준

• Given 드라이버를 펼쳤을 때, When 運送日程을 열면, Then 出発/到着 시각과 함께 담당 운송 목록을 반드시 보여주고, 없으면 担当運送がありません를 표시한다.
• Given 운송의 정류점을 편집할 때, When 경유지(経由地を追加)·주소를 바꾸면, Then 추가/수정/삭제를 반드시 반영한다(삭제는 확인 후).
• Given 일정 행에서, When 地図で見る를 누르면, Then 해당 운송으로 지도 포커스를 권장 이동한다.

PLATFORM_ADMIN(미래 CARRIER_OPS)으로서 캐리어의 진행 중/완료 운송을 구분해 보고 싶다, 그래야 자사 실적을 증명하고 화주 거래를 유지한다.

수용기준

• Given 캐리어 운송 히스토리를 열 때, When 運送履歴를 보면, Then 進行中과 完了 운송을 반드시 구분 표시한다.
• Given 해당 운송이 없을 때, When 목록을 보면, Then 該当運送がありません 빈 상태를 반드시 명시한다.

受取人 운영자로서 자사 시설로 오는 모든 운송을 여러 운송사 횡단으로 한 라이브 목록에서 보고 싶다, 그래야 도크 인력·접안을 미리 계획한다.

수용기준

• Given 자사 시설로 향하는 운송이 있을 때, When 到着便(ライブ)를 열면, Then 운송ID·事業者(캐리어)·到着拠点·상태·ETA(추정 플래그 포함)를 반드시 횡단 표시한다.
• Given 도착 예정 운송이 없을 때, When 목록을 보면, Then 現在到着予定の運送はありません 빈 상태를 반드시 명시한다.
• Given 한 행을 선택할 때, When 클릭하면, Then 지도로 포커스를 권장 이동한다.

受取人 운영자로서 기간 내 도착 운송을 운송사별로 집계해 件数·평균 荷待ち·定時率·ETA 오차(MAE)로 비교하고 싶다, 그래야 어느 캐리어를 계속 쓸지 객관 근거로 결정한다.

수용기준

• Given 집계 기간이 지정될 때, When 事業者比較(集計)를 열면, Then 운송사별 件数·平均荷待ち·定時率·ETA誤差(MAE)를 반드시 한 표로 비교 표시한다.
• Given 대상 기간에 데이터가 없을 때, When 대시보드를 보면, Then 対象期間にデータがありません를 반드시 표시한다.
• Given 데이터를 새로 받을 때, When 更新을 누르면, Then 집계를 반드시 갱신한다.

荷主 운영자로서 컨사이니가 보는 것과 동등한 캐리어 스코어카드(OTD·dwell·tracking rate·예외율·CO₂)를 화주 관점에서 받고 싶다, 그래야 특정 제1종 荷主의 효율화 의무를 데이터로 증명한다.

수용기준

• Given 화주가 캐리어 성과를 요청할 때, When 스코어카드를 조회하면, Then 캐리어별·레인별 OTD·체류·추적 품질·예외율·CO₂ 추정을 반드시 제공한다(목표 동작).
• Given 컨사이니 Dashboard에 병렬 뷰가 이미 있을 때, When 화주向 뷰를 추가하면, Then 동일 집계를 화주 스코프로 권장 재사용한다.

드라이버로서 배정된 案件을 푸시로 받아 큰 버튼 한 번으로 受託(수락)하고 싶다, 그래야 복잡한 조작 없이 업무를 시작한다(고령·최소 탭).

수용기준

• Given 案件이 배정될 때, When 드라이버에게 푸시(FCM/APNs)가 도착하면, Then 출발지→도착지·시각을 큰 글자로 반드시 보여준다(목표 동작).
• Given 案件을 확인할 때, When 큰 수락 버튼을 누르면, Then 상태를 ACCEPTED(受託)로 반드시 전이한다.

드라이버로서 수락하면 위치 공유가 자동으로 켜지고 완료하면 자동으로 꺼지길 원한다, 그래야 공유 버튼을 누를 필요 없이(자동화), 잡 외에는 추적되지 않는다(프라이버시).

수용기준

• Given 案件을 수락할 때, When 상태가 ACCEPTED가 되면, Then 배경 위치 공유를 반드시 자동 ON 한다(공유 버튼 없음).
• Given 주행 중일 때, When 위치를 수집하면, Then 적응 샘플링으로 배터리 예산을 권장 지키며 ingest로 전송한다.
• Given 완료 보고를 마칠 때, When 案件이 종료되면, Then 공유를 반드시 자동 OFF 한다.

드라이버로서 터널·전파 음영에서도 위치가 버퍼링됐다가 복구 시 올라가고, 도착/이탈은 서버가 자동 도출하길 원한다, 그래야 수기 보고 없이 도착이 증명되고 추적이 유지된다.

수용기준

• Given 오프라인 구간일 때, When 위치를 수집하면, Then 로컬 버퍼에 쌓았다가 복구 시 반드시 순서대로 전송한다(목표 동작).
• Given 위치가 거점 지오펜스에 진입/이탈할 때, When 서버가 핑을 받으면, Then ENTER/EXIT·dwell 이벤트를 반드시 자동 도출한다(드라이버 수기 입력 없음 — 서버측 DONE).

드라이버로서 배달지 도착 후 완료 보고와 증빙 사진을 큰 버튼으로 올리고 싶다, 그래야 배달 사실을 증명하고 案件을 닫는다.

수용기준

• Given 배달지(DROPOFF)에 도착했을 때, When 完了報告 버튼을 누르면, Then 상태를 DELIVERED(配達完了)로 반드시 전이한다(목표 동작).
• Given 증빙 사진을 첨부할 때, When 업로드하면, Then 사진을 반드시 R2에 저장한다(egress 무료).

荷主 운영자로서 다음 stop의 도착 예정 시각을 룰 기반으로 받고, 그것이 추정치임을 명확히 알고 싶다, 그래야 약속 시각(promised) 대비 지연을 판단한다.

수용기준

• Given 운송이 진행 중일 때, When 서버가 위치 배치를 처리하면, Then 룰 기반 다음 stop ETA를 반드시 산출하고 eta_is_estimate=true로 반드시 표시한다(목표 동작).
• Given 룰 ETA MAPE 목표일 때, When 정확도를 측정하면, Then 룰 ≤25%(설계)를 기준으로 하고 달성치로 위장하지 않는다.

荷主·運送会社 운영자로서 지연·荷待ち 초과·추적 손실·이탈·정차·픽업 같은 예외를 자동으로 분류해 받고 싶다, 그래야 "지금 처리할 것"에 집중한다.

수용기준

• Given 거점 체류가 임계(120분)를 초과할 때, When 엔진이 평가하면, Then DWELL_THRESHOLD_EXCEEDED 荷待ち 예외를 반드시 생성한다.
• Given 예측 ETA가 약속을 초과하거나 핑이 끊길 때, When 엔진이 평가하면, Then 지연·추적 손실 등 canonical 예외를 반드시 심각도와 함께 분류한다.
• Given 추적 손실이 일정 시간 지속될 때, When 스윕 cron이 돌면, Then 추적 손실 예외를 반드시 표시한다. STUB — 현재 tracking-loss sweep cron은 비어 있다.

荷主 운영자로서 화물별·전체 추적 커버리지(Tracking Rate)와 마지막 핑 경과(staleness)를 정직하게 보고 싶다, 그래야 스마트폰 GPS 한계를 알고도 신뢰한다.

수용기준

• Given 28일 창에서, When Tracking Rate(received_pings/expected_pings)를 계산하면, Then 100%로 위장하지 않고 실측치를 반드시 노출한다(목표 동작).
• Given SLI를 측정하려 할 때, When 메트릭을 기록하면, Then writeDataPoint(OBS-METRICS-001) 배선이 반드시 선결된다. STUB — 현재 METRICS.writeDataPoint는 TODO다.

運送会社 운영팀으로서 예외(지연·荷待ち 초과 등)를 LINE/LINE Works로 즉시 받고 싶다, 그래야 이메일보다 빠르게 현장 대응한다.

수용기준

• Given 예외 이벤트가 발생할 때, When 알림이 전달되면, Then LINE/LINE Works를 1순위 채널로 반드시 사용한다(이메일·웹훅 병행)(목표 동작).
• Given 예외 큐를 볼 때, When 심각도·시간순으로 정렬하면, Then "지금 처리할 것" vs "모니터링"을 권장 구분한다.

荷主 운영자로서 "지연 30분 초과 시 이메일" 같은 알림 규칙을 직접 정의하고 싶다, 그래야 내 운영 기준에 맞춰 잡음을 줄인다.

수용기준

• Given 운영자가 임계·채널을 설정할 때, When 규칙을 저장하면, Then 조건 충족 시 지정 채널로 반드시 알린다(목표 동작).
• Given 규칙이 없을 때, When 예외가 발생하면, Then 기본 심각도 정책으로 권장 분류한다.

운영자/드라이버로서 관리자가 발급한 ID·비밀번호로 로그인하고 싶다, 그래야 셀프가입 없이도(ADR-0001) 안전하게 접근한다.

수용기준

• Given 발급된 자격(ID（発行された資格）·비번)일 때, When 로그인하면, Then 액세스·리프레시 토큰을 반드시 발급한다(POST /v1/auth/token).
• Given 자격이 틀릴 때, When 로그인하면, Then ログインに失敗しました를 반드시 보여준다.
• Given 셀프가입 경로일 때, When 사용자가 가입을 시도하면, Then 경로는 반드시 존재하지 않는다(관리자 발급만).

모든 역할 사용자로서 내 역할에 맞는 화면만 보고 싶다, 그래야 권한 밖 기능에 접근하지 않는다(admin은 다크 사이드바 콘솔, 비-admin은 self-track 뷰).

수용기준

• Given PLATFORM_ADMIN일 때, When 콘솔을 열면, Then 地図/管理/事業者管理/運送登録/輸送 탭을 반드시 노출한다.
• Given CONSIGNEE_ADMIN/VIEWER 역할일 때, When 콘솔을 열면, Then 地図/到着便/ダッシュボード를, SHIPPER_ADMIN/VIEWER는 地図/輸送/規制/発行을 반드시 노출한다.
• Given 비-admin 역할일 때, When 접근하면, Then CustomerTrack(self-track) 뷰로 반드시 제한한다.

화주/캐리어로서 내 테넌트 리소스만 보이고, 세션이 만료돼도 매끄럽게 갱신되길 원한다, 그래야 데이터가 새지 않고 작업이 끊기지 않는다.

수용기준

• Given 타 테넌트 리소스를 조회할 때, When 요청하면, Then 반드시 404로 응답한다(존재 비노출).
• Given 액세스 토큰이 만료될 때, When 리프레시 토큰이 유효하면, Then 토큰을 반드시 갱신한다. 만료/무효 시 セッション期限切れ — 再ログインしてください를 반드시 보여준다.

3PL/화주 시스템으로서 API Key→토큰 교환 후 화물 목록·상태·트래킹을 REST로 폴링하고 싶다, 그래야 자사 TMS에서 화물을 본다.

수용기준

• Given 유효한 API Key·스코프(shipments:read)일 때, When GET /v1/shipments를 호출하면, Then 테넌트 스코프로 필터된 커서 페이지를 반드시 반환한다(목표 동작).
• Given 테넌트별 한도를 둘 때, When 과도 호출하면, Then RateLimit-* 헤더와 429를 반드시 노출한다. STUB — 현재 rate limit 미구현.

3PL/화주 시스템으로서 이벤트 타입을 골라 웹훅을 구독하고, HMAC 서명된 이벤트를 멱등하게 받고 싶다, 그래야 폴링 없이 푸시로 상태를 반영한다.

수용기준

• Given 구독을 등록할 때, When POST /v1/webhooks를 호출하면, Then 이벤트 타입(SHIPMENT_EXCEPTION·DWELL_THRESHOLD_EXCEEDED 등)을 선택해 반드시 구독한다(목표 동작). STUB — 현재 웹훅 CRUD는 501.
• Given 이벤트가 발생할 때, When 전달되면, Then X-LogiNippon-Signature(HMAC-SHA256)·X-LogiNippon-Event-Id를 붙이고 at-least-once로 반드시 전달한다(수신자는 서명 검증·id 멱등 처리).
• Given 수신자가 5초 내 2xx를 못 줄 때, When 실패하면, Then 지수 백오프(1m→5m→…→최대 24h)로 반드시 재시도한다.

3PL 중개업자로서 위임 범위 내 다 화주/캐리어를 멀티테넌트로 분리해 오케스트레이션하고 정산 근거를 산출하고 싶다, 그래야 ERP를 대체하지 않고 위에 얹는다.

수용기준

• Given 다 화주/캐리어를 위탁받을 때, When 데이터를 조회하면, Then 위탁 범위 내로만 반드시 스코프된다(테넌트 격리).
• Given 캐리어가 공개 범위를 정할 때, When "누구에게·언제·무엇을" 제어하면, Then 그 범위를 권장 준수한다(MVP 단순 스코프 → Phase 2 세분).

法務/컴플라이언스로서 드라이버 위치 수집이 APPI 동의(driver.consent_at) 없이는 절대 인제스트되지 않길 원한다, 그래야 個人情報保護法 노출을 없앤다.

수용기준

• Given 드라이버 동의가 없을 때, When 위치가 ingest로 들어오면, Then consentGate가 반드시 차단한다(목표 동작). STUB — 현재 ingest가 consentGate를 호출하지 않는다(APPI 갭·R9).
• Given 드라이버 생성 시(factory/CarrierManager), When APPI 동의 체크 없이 생성하려 하면, Then 동의를 반드시 받는다(位置情報の収集に同意する（APPI） — 콘솔 단 DONE).

受取人(최종 수령인)으로서 로그인 없이 추적 링크로 배달 ETA만 보고 싶다, 그래야 몇 시에 오는지 알되 차량 실시간 위치(個人情報)는 노출되지 않는다.

수용기준

• Given 受取人 스코프로 트래킹을 조회할 때, When GET /v1/shipments/{id}/tracking을 부르면, Then position은 반드시 생략되고 ETA만 노출된다(個人情報保護法).
• Given 화주/운송사 스코프일 때, When 같은 트래킹을 조회하면, Then position이 반드시 채워진다(스코프별 차등).

法務/캐리어로서 화주 스코프에서 드라이버 실명·番号板이 마스킹되고, 캐리어가 화주에게 공개할 범위를 계약으로 제어하길 원한다, 그래야 가시성이 마진을 무차별 노출하지 않는다(R4).

수용기준

• Given 화주 스코프로 화물을 볼 때, When 드라이버·차량 정보를 조회하면, Then 실명(display_name)·plate를 반드시 부분 마스킹한다.
• Given 캐리어가 데이터 공유 범위를 정할 때, When "누구에게·언제·무엇을" 설정하면, Then 계약 명시 범위를 권장 따른다(MVP 단순 → Phase 2 세분).