TRD 목적 · 범위 · 작성 규약
이 TRD(Technical Requirements Document)는 techspec(설계: 무엇을·왜·어떻게)의 상위 형식화 계층이다. 이 페이지는 그 형식화의 기준선을 고정한다 — TRD가 무엇을 추가하는가(테스트 가능한 ID·확정 수치·계약·수용기준·추적성), 누가 읽는가, 무엇을 다루고 무엇을 techspec에 위임하는가, 그리고 모든 후속 페이지가 따르는 정규 규약(요구사항 ID 네임스페이스, RFC 2119 키워드, 신뢰도·구현상태 라벨, 요구사항 카드 6요소, 추적성 규칙)이다.
전제 맥락. LogiNippon(가칭)은 일본 국내 B2B 트럭 화물 운송에 화물 단위 실시간 가시성을 가져오는 화주(荷主)向 SaaS다. 핵심 통찰: 해자는 소프트웨어가 아니라 多重下請け(元請→下請→孫請)를 관통한 위치 네트워크(Research H3). 진입 쐐기는 규제를 킬러앱으로 — 実運送体制管理簿(改正物流法 2025년 4월 의무화 확인)·荷待ち 기록(物流効率化法 2026년 4월 전면 시행, 법정 2시간 목표 확인)·구속시간(2024년 문제, 시간외 960h 상한 확인)을 자동 생성한다. 아키텍처는 전면 Cloudflare 엣지, 운영 서버 0대. 본 페이지의 모든 수치 표기는 정규 수치표에서 인용된 진입 단계 초기 확정 목표(설계)이며 운영 베이스라인으로 분기별 조정됨을 전제한다 — 달성치가 아니다.
1. 이 문서의 목적 — Research · techspec · TRD 역할 분담
세 산출물은 같은 프로젝트를 다른 추상 수준에서 고정한다. Research는 시장에 무엇이 있는가, techspec은 그래서 우리가 무엇을 어떻게 만드는가, TRD는 그것을 어떻게 테스트·계약·검증 가능한 형태로 못박는가를 담당한다. TRD는 새 설계를 발명하지 않는다 — techspec의 설계를 형식화한다.
| 레이어 | 질문 | 산출물 | 대표 형식 | 권위 |
|---|---|---|---|---|
| Research | 시장에 무엇이 있고 그들은 어떻게 구현했는가? | LogiNippon/Research(1차 패스 2026-05-15 완료) | 시장 사실(확인/추정), 가설 H1~H4, 비교 매트릭스 | 시장 근거의 단일 진실원 |
| techspec | 그래서 우리는 무엇을·왜·어떻게 만드는가? | LogiNippon/techspec(docs-as-code, Pre-Phase 0) | 설계 서술, Mermaid 다이어그램, DDL, ADR(MADR) | 설계 결정의 단일 진실원 |
| TRD(이 레포) | 그 설계를 어떻게 테스트·계약·검증하는가? | 이 HTML 레포 | FR/NFR 요구사항 카드, 확정 수치, API/WS/데이터 계약, SLO, 추적성 매트릭스 | 요구사항·수치·계약·검증의 단일 진실원 |
TRD가 techspec 위에 추가하는 여섯 가지:
- ① 고유 ID. 테스트 가능한 모든 기능/비기능 요구사항에 고유 식별자를 부여한다(아래 §4 네임스페이스).
- ② 수치 확정. techspec의 모든
목표(추정)플레이스홀더를 방어 가능한 구체 수치로 확정한다(예: observability-slo.md의 SLI/SLO가목표(추정)로 비어 있던 것을 SLO 카탈로그에서 측정 윈도·쿼리까지 고정). - ③ 계약 고정. API·데이터·WebSocket 와이어 계약을 단일 버전드 소스로 동결한다(IR-API-001).
- ④ 수용기준·SLO. 측정 가능한 Given/When/Then 수용기준과 에러버짓을 갖춘 SLO를 부여한다.
- ⑤ 추적성 척추. 요구사항→근거→구현상태→검증을 잇는 마스터 매트릭스를 둔다(acceptance-traceability).
- ⑥ 모순 해소. console(Svelte) vs Flutter Web 대시보드 모순을 ADR-0010으로 해소한다.
2. 독자
| 독자 | 이 TRD에서 주로 보는 것 | 진입 페이지 |
|---|---|---|
| 엔지니어 | FR/NFR 카드의 수용기준, API/WS/데이터 계약, 구현상태 갭(as-built) | 기능 요구사항 · 계약 |
| PM | 범위·비범위, 단계 게이트 DoD, North Star/KPI, 리스크 | 단계 게이트 · KPI |
| 제휴 파트너(화주·운송사) | 공개 API/웹훅 계약, SLO 약속, 규제 산출물(킬러 피처) | SLO · 규제 출력 |
| 법무 | APPI(個人情報保護法) 의무, 보존 기간, 공식 규제 포맷의 법무 서명 플래그 | 보안·APPI · 규제 |
3. 범위 · 비범위
TRD는 요구사항·계약·수치·검증을 다룬다. 상세 알고리즘 서술과 설계 근거는 techspec에 위임한다 — 같은 사실을 두 곳에 중복시키지 않는다.
| TRD가 다루는 것(범위) | techspec에 위임하는 것(비범위) |
|---|---|
| 테스트 가능한 FR(기능)·NFR(비기능) — 고유 ID·우선순위·단계·수용기준 | 설계 서술·트레이드오프 산문, ADR 의사결정 기록 |
| API/WebSocket/웹훅/데이터 계약 고정(OpenAPI 3.1 + AsyncAPI + @loginippon/contract) | 아키텍처 다이어그램의 상세(Mermaid C4·시퀀스) — TRD는 요약·링크만 |
| 측정 가능한 SLO(측정 윈도·데이터소스 쿼리·에러버짓 공식) | 알고리즘의 단계별 의사코드(예: H3 링 히스테리시스 내부 절차) — TRD는 임계·수용기준만 |
| 요구사항→근거→구현상태→검증 추적성 매트릭스 | 비즈니스 전략 서술(페인 우선 진입의 논거 등) — Research/strategy 권위 |
| 규제 산출물의 필드·집계·법무 플래그(공식 포맷 확정 전 표시) | 규제 배경·법 해석 — Research/japan-market |
techspec의 비목표(goals-nongoals.md)는 TRD에서도 그대로 비범위다: 자체 IoT 하드웨어, 국제 물류 visibility, B2C 라스트마일, WMS 자체, 운임 결제·정산, 求荷求車 마켓플레이스, 초기 ML ETA, 복합운송 다중 Leg, 온프레미스 배포. 비목표의 단계별 해제 매핑은 단계 게이트가 소유한다.
4. 요구사항 ID 네임스페이스 레지스트리
각 접두사는 한 페이지만 소유(정의)한다. 다른 페이지는 상대 링크로 참조하며 재정의하지 않는다. 이는 ID 충돌과 정의 중복을 방지하는 거버넌스 규칙이다. 이 페이지(00-overview/purpose-scope.html)는 규약만 정의하며 FR/NFR/DM 등 도메인 요구사항 ID를 소유하지 않는다 — 모든 예시는 소유 페이지로 링크한다.
| 접두사 | 의미 | 소유 페이지 | 예시 ID(소유처 링크) |
|---|---|---|---|
| FR-* | 기능 요구사항 | 02-requirements/functional.html | FR-ENG-EXC-003, FR-AUTH-001 |
| NFR-* | 비기능 요구사항(성능·가용성·신뢰성·보안·확장·비용) | 02-requirements/nonfunctional.html | NFR-PERF-001, NFR-AVAIL-001 |
| DM-* | 데이터 모델·식별자 계약 | 02-requirements/data-model.html | DM-TS-001, DM-DEDUP-001 |
| IR-* | 인터페이스 요구사항(REST/WS/웹훅/EDI 계약) | 02-requirements/api-contracts.html | IR-API-001, IR-WS-001 |
| SR-* | 보안·프라이버시 요구사항(위협·권한·APPI) | 03-quality/security-privacy.html | SR-AUTHZ-001, SR-PII-001 |
| RR-* | 규제 요구사항(規制 산출물 필드·집계·법무) | 03-quality/regulatory.html | RR-JITSUUNSO-001, RR-LEGAL-001 |
| SLO-* | 서비스 수준 목표 카탈로그(S1~S8) | 03-quality/slo-catalog.html | SLO-S1 … SLO-S8 |
| KPI-* | 성공 지표(North Star·트리·공식) | 01-product/north-star-kpi.html | KPI-TRACK-001, KPI-ETA-001 |
| RET-* | 데이터 보존 정책(법정 최소 포함) | 03-quality/security-privacy.html(SR-APPI-RETENTION-001 표) | RET-EVENT-001, RET-REG-001 |
| GATE-* | 단계 게이트(진입·종료 DoD) | 04-delivery/phase-gates-roadmap.html | GATE-P0, GATE-P1 |
| OD-* | 미해결 결정·RFC 백로그 | 04-delivery/open-decisions-rfc.html | OD-001(ADR-0010), OD-002(가칭→정식명) |
보조 네임스페이스. OPS-*(운영, pipeline-ops 소유), OBS-*(관측, slo-catalog 소유), BIZ-*(경량 상업 ID, monetization-gtm 소유)도 동일 규칙을 따른다.
5. 정규 키워드 (RFC 2119 매핑)
요구사항 진술의 강제력은 RFC 2119에 매핑된 한국어 키워드로 표기한다. 모든 요구사항 카드는 이 키워드를 명시한다.
| 한국어 | RFC 2119 | 의미 |
|---|---|---|
| 반드시 | MUST / SHALL | 절대 요구. 위반 시 비준수. 보통 P0·Must 요구사항. |
| 권장 | SHOULD | 강한 권고. 정당한 사유가 있으면 예외 가능. 보통 P1·Should. |
| 선택 | MAY | 허용·재량. 구현 여부가 준수에 영향 없음. 보통 P2·Could. |
6. 신뢰도 라벨 · 구현상태 라벨 (범례)
신뢰도 라벨은 진술의 출처 성격을 표시한다. 시장·외부·법령 사실에는 신뢰도 라벨이 필수이며, 우리가 정한 설계 결정·목표 수치에는 설계를 붙이거나 "초기 확정치, 운영 베이스라인으로 조정"을 명시한다. 달성치를 날조하지 않는다 — 모든 SLO/KPI 수치는 운영 데이터가 없는 진입 단계의 초기 확정 목표다.
확인 출처로 검증된 사실 추정 공개정보 기반 추론(사실처럼 쓰지 않음) 설계 우리의 결정·목표 수치(초기 확정, 베이스라인 조정)
구현상태 라벨은 as-built 추적을 위해 코드 실측 상태를 표시한다. server 레포는 자체 docs보다 앞서 있으므로, 요구사항이 코드와 일치하는지를 이 4개 라벨로 정직하게 노출한다.
DONE 구현 + 테스트 통과 PARTIAL 부분 구현 STUB 껍데기(501/ack-only) ABSENT 미존재
법무 서명 플래그. 규제 사실 중 미확정인 것(예: 実運送体制管理簿·荷待ち 기록 CSV의 공식 제출 포맷)은 추정으로 표기하고 RR-LEGAL-001 법무 확인 플래그를 단다. 시행일 자체(2025년 4월·2026년 4월)는 확인이지만, 산출물 레이아웃의 공식성은 법무 서명 전까지 단언하지 않는다. 보존 기간(RET-*)도 전부 법무 서명 전까지 추정 플래그를 유지한다.
7. 요구사항 카드 읽는 법 (6요소)
모든 규범적 요구사항은 ① ID · ② 우선순위 · ③ 단계 · ④ 근거 · ⑤ 수용기준(Given/When/Then) · ⑥ 구현상태 6요소를 가진 카드로 표현한다. 매트릭스·카탈로그는 표로, 헤드라인 수치는 메트릭 그리드로 표현한다. 아래는 읽는 법을 보이기 위한 예시 카드다 — 이 ID는 functional.html이 소유하며, 본 페이지는 정의하지 않는다(여기서는 ID에 앵커를 부여하지 않는다).
① ID = 접두사+도메인+일련. ② 우선순위 = P0/P1/P2(Must/Should/Could). ③ 단계 = 인도 단계(Phase 0/1/2). ⑥ 검증 배지 = T 테스트·D 데모·A 분석·I 검사.
요구. 시스템은 마지막 유효 핑 후 45min 동안 위치 갱신이 없으면 해당 화물을 TRACKING_LOST로 반드시 표시해야 한다(MUST). 오경보율 <5%. 설계(초기 확정치, 운영 베이스라인으로 조정).
⑤ 수용기준
- Given 활성 화물의 last_valid_ping_at가 현재로부터 46분 전이고, When Cron 5min sweep(
*/5 * * * *)이 실행되면, Then 상태가TRACKING_LOST예외로 전이되고 이벤트가 INSERT된다. - Given 핑이 44분 전이면, When sweep이 실행되어도, Then 손실로 표시되지 않는다(45min 임계 미만).
위 카드는 형식 예시다. 실제 임계·구현상태·테스트의 권위 정의는 FR-ENG-EXC-003(functional.html)에 있다.
8. 추적성 규약
측정·검증 불가능한 요구사항은 요구사항이 아니다. 따라서 모든 FR과 NFR은 마스터 추적성 매트릭스에 정확히 한 행을 가진다. 각 행은 요구사항을 그 근거(techspec/Research/ADR)·구현상태(DONE/PARTIAL/STUB/ABSENT)·검증 방법(T/D/A/I)으로 연결한다. 매트릭스는 새 ID를 정의하지 않고 참조·집계만 한다.
| 요구사항 ID | 근거 | 구현상태 | 검증 |
|---|---|---|---|
| FR-AUTH-001 | techspec 07-security | DONE server/src/lib/auth.ts | T (auth.test.ts) |
| FR-ENG-EXC-003 | techspec 04-tracking-engine | STUB cron sweepActive 빈 구현 | T (회귀셋) |
| NFR-PERF-001 | techspec 08-operations | ABSENT METRICS writeDataPoint TODO → SLI 미측정 | A (Analytics Engine, 28일 롤링) |
이 세 행은 추적성이 어떻게 채워지는지 보이는 발췌일 뿐이다. 전체 매트릭스·단계 게이트 수용기준·필수 회귀셋은 acceptance-traceability.html가 소유한다. 모든 요구사항 ID는 거기서 정확히 한 번 추적된다.
근거·상호참조
- techspec(설계, 단일 진실원): README.md · CONTRIBUTING.md(언어·신뢰도 라벨·ADR 규약) · 00-overview/goals-nongoals.md(목표·비목표·MVP 범위)
- techspec 위임 영역: 08-operations/observability-slo.md(
목표(추정)SLI/SLO) · 04-tracking-engine/engine.md · adr/ - Research(시장 근거): LogiNippon/Research — 가설 H1~H4, japan-market(2024년 문제·改正物流法·物流効率化法), implications-for-us
- 구현 실측(as-built): LogiNippon/server(
routes/,lib/auth.ts, cronsweepActive, METRICSwriteDataPointTODO) · console · app - TRD 내부: 기능 요구사항 · 비기능 요구사항 · 데이터 모델 · 계약 · SLO · 추적성 · ADR-0010 · 아키텍처 기준선