LogiNippon — 기술 요구사항 명세 (TRD)

index.html · LogiNippon · TRD · 초안 2026-06-13 · 신뢰도 라벨 확인 추정 설계

일본 국내 B2B 트럭 화물 운송에 화물 단위 실시간 가시성을 가져오는 LogiNippon(가칭)의 기술 요구사항 명세(Technical Requirements Document). techspec(설계: 무엇을·왜·어떻게)과 Research(시장·구현 근거)를 토대로, 테스트 가능한 요구사항으로 형식화하고 모든 목표치를 구체화하며 계약을 고정해 구현 착수가 가능한 수준으로 기획을 고도화한다.

이 TRD가 techspec에 더하는 것. techspec은 이미 성숙한 설계 문서다. TRD는 그 위에 ① 모든 기능·비기능 요구사항에 고유 ID 부여, ② 모든 목표(추정) 플레이스홀더를 방어 가능한 구체 수치로 확정, ③ API·데이터·WebSocket 계약 고정, ④ 측정 가능한 수용기준·SLO, ⑤ 요구사항→근거→검증 추적성 척추, ⑥ Svelte console vs Flutter 대시보드 모순 해소(ADR-0010)를 더한다.

읽기 전에 — 본 명세의 사실 기반

이 TRD는 추상적 청사진이 아니라 실제 구현 상태를 정독한 결과 위에 쓰였다. 핵심 발견:

server(백엔드)는 자체 techspec보다 앞서 있다. 인증·테넌트 격리(404)·지오펜스 enter/exit/dwell 엔진·荷待ち CSV 리포트가 약 50개 테스트와 함께 DONE. TRD는 각 요구사항을 구현 파일에 역참조하고 모든 스텁을 표시한다.
프론트엔드는 모순 상태다. 동작하는 화주 컨트롤 타워는 console(Astro+Svelte)인데, ADR-0003은 화주 대시보드를 Flutter Web으로 규정한다(현재 미구현 placeholder). → ADR-0010으로 해소.
모든 NFR/SLO 목표가 플레이스홀더였고, 요구사항 ID와 기계가독 API 계약이 어디에도 없었다. TRD가 이 전부를 신설한다.

한눈에 보는 확정 수치 (고도화 결과)

≤200ms

인제스트 p95 (NFR-PERF-001)

≤1.5s

실시간 WS p95 (NFR-PERF-003)

99.9%

월 가용성·버짓 43분 (NFR-AVAIL-001)

≥85%

Tracking Rate MVP 게이트 (KPI-TRACK-001)

≤25%→15%

ETA MAPE 룰→ML (KPI-ETA-001)

45min

추적 손실 임계 (FR-ENG-EXC-003)

120min

荷待ち 법정 임계 (FR-ENG-EXC-002)

5/7년

이벤트/규제 보존 (RET-EVENT/REG)

모든 수치는 운영 데이터가 없는 진입 단계의 초기 확정 목표이며, 운영 베이스라인으로 분기 조정한다(명시적 개정 트리거 보유). 달성치를 날조하지 않는 Research 신뢰도 규약을 계승한다.

00 — 개요·규약

목적·범위·작성 규약 기준
TRD의 목적, techspec/Research/ADR과의 관계, 독자, 요구사항 ID 네임스페이스, RFC2119(반드시/권장/선택), 신뢰도·구현상태 라벨, 추적성 규약
아키텍처 기준선 (as-built + as-specified) 기준
요구사항이 전제하는 아키텍처 — C4 요약, Cloudflare 프리미티브 매핑, 3대 데이터 흐름, ADR 색인·상태, ADR-0010 요약, 환경 토폴로지, server 구현 완성도 맵

01 — 제품·전략 (기획 고도화)

North Star · KPI 트리 고도화
북극성 지표, 단계별 KPI 목표치 구체화, OTD·Dwell·Tracking Rate·MAPE·CO₂ 공식(분자/분모/윈도/제외)
수익모델 · 제휴 GTM 신규
수익 모델·가치지표·패키징·가격 가설, Phase 0 제휴 플레이북, 파트너 자격 루브릭, GTM 시퀀스, 상업 요구사항, 물류×금융 확장 게이트
전략 추적 · 리스크 레지스터 v2 고도화
가설 H1~H4 → 리스크 → 완화 → 요구사항 추적, R1~R5 정량화(가능성×영향·선행지표·트리거·오너)

02 — 요구사항

기능 요구사항 (FR-*) 핵심
인증·수집·인제스트·지오펜스·ETA·예외·전달·웹훅·알림·규제·프로비저닝 — 각 요구사항: 진술·우선순위·단계·근거·수용기준·구현상태
데이터 모델·식별자 계약 (DM-*) 핵심
11테이블 DDL을 규범 요구사항으로, 타임스탬프 +09:00 통일, dedup 해시, 소스 정밀도 매트릭스, canonical 이벤트 enum·파생표, 상태머신, 테넌트 격리, 送り状番号 정규화
API·WebSocket·웹훅 계약 (IR-*) 핵심
단일 버전드 와이어 계약(OpenAPI 3.1 + AsyncAPI), 전 /v1 엔드포인트 표(+누락 배치 tracking 추가), 에러 엔벨로프·커서 페이지네이션, 웹훅 카탈로그·서명·재시도 래더, @loginippon/contract + CI drift 게이트
비기능 요구사항·용량 (NFR-*) 핵심
성능·가용성·신뢰성·보안·확장성·비용·유지보수·관측성을 측정값으로 확정, 용량/부하 모델과 스케일 레버 트리거, 비용 추정·가드레일

03 — 품질·보안·규제

보안·프라이버시·APPI (SR-*) 핵심
위협 모델→완화, scope→endpoint→role 권한 매트릭스, 테넌트 격리 404, APPI 5대 의무(동의 하드게이트·목적제한·보존표·마스킹 함수·삭제권 SLA), 키 로테이션·revocation, 감사 로그
규제 출력 명세 (RR-*) — 킬러 피처 킬러
実運送体制管理簿 필수 컬럼, 荷待ち 집계 차원, 구속시간 필드, CSV 인코딩, 리포트 라이프사이클, provenance FK, 공식 포맷 법무 확인 플래그
SLI/SLO 카탈로그 핵심
S1~S8 SLO를 측정 윈도·데이터소스 쿼리·에러버짓 공식으로 확정 + METRICS 방출 요구(측정 불가능한 SLO는 요구사항이 아니다)
테스트 전략·수용기준·추적성 매트릭스 척추
unit/integration/e2e 전략, 필수 회귀셋, 단계 게이트 수용기준, 모든 FR/NFR→근거→구현상태→검증 마스터 매트릭스

04 — 딜리버리·운영·의사결정

단계 게이트 · 로드맵 계획
Phase 0/1/2 진입·종료 DoD 수치화, 마일스톤·의존성, 비목표 해제 매핑, 제휴 하드 게이트
배포 파이프라인 · 운영 운영
3환경 wrangler, 전진전용 expand-first 마이그레이션, 시딩, feature-flag 거버넌스, CI 게이트, 롤백, cron 락, 인시던트 P1~P4·MTTA/MTTR, 에러버짓 릴리스 게이트, 리소스 확정·리네임 체크리스트
미해결 결정 · RFC 백로그 결정
ADR-0010(대시보드 해소-제안), 가칭→정식명, 토큰 저장 하드닝, CSV 인코딩, 리소스 프로비저닝, 용량 베이스라인, 런타임 config 권위, GS1 흡수

문서 상태

TRD 초안 (2026-06-13) — techspec 13문서·9 ADR과 server/app/web/console 구현, Research 종합을 정독해 작성. 본 명세의 목표는 망라가 아니라 구현 착수가 가능하도록 요구사항·계약·수치를 고정하고 미해결 결정을 드러내는 것이다. 모든 목표 수치는 진입 단계 초기 확정치이며 운영 데이터로 베이스라인을 조정한다.