superport_v2/doc/inventory_management_feature_plan.md

재고관리(Inventory) 기능 단계별 개발 계획

개요

• 재고 변동 이력을 기준으로 최신 재고를 노출하는 API/화면을 Clean Architecture 구조에 맞춰 단계적으로 구축한다.
• 공식 명세는 stock_approval_system_spec_v4.md §§3.243.25(재고 이벤트/집계 뷰)와 stock_approval_system_api_v4.md §4.84.9(Inventory Summary API)에 정의되어 있으며, 모든 구현·테스트는 해당 계약을 1차 근거로 삼는다.
• 읽기 전용 권한 스코프 inventory.view가 추가되었고, /api/v1/inventory/** 경로는 해당 스코프와 메뉴 권한(menu_code=inventory, route_path=/inventory/summary)을 모두 충족해야 접근할 수 있다.

최근 진행 현황 (2025-11-08)

• Inventory Summary UI를 정식 릴리스하며 자동 새로고침, 창고 필터, 상세 시트(그래프/타임라인)를 모두 연결 완료했다.
• Golden 테스트(inventory_summary_page_golden_test.dart)와 위젯 테스트를 확장해 정렬/필터/빈 상태/권한 오류까지 회귀 시나리오를 커버한다.
• 릴리스 노트(CHANGELOG.md)와 PR 템플릿(.github/PULL_REQUEST_TEMPLATE.md)에 사용자 영향 및 필수 검증 커맨드를 명시했다.
• 상세 다이얼로그 통합 계획서에 재고 현황 사례와 골든 스냅샷 경로를 기록해 문서 일관성을 확보했다.

전체 타임라인 개요

1. 요구 정합성 확보 (Backend & Product) — 데이터 출처, 뷰 리프레시 주기, RBAC 확정.
2. 백엔드 개발 — 마테뷰·API·권한 시드·테스트·문서 동기화.
3. 프론트엔드 개발 — Flutter 사이드 메뉴/리스트/상세/상태 관리 구현 및 테스트.
4. 통합 검증 — 계약 검증, 샘플 데이터, E2E 시나리오, 배포 산출 정리.

---

백엔드 단계별 Tasks (선행) — ✅ 완료

기준: ../superport_api_v2

1. 요구/계약 정리

   • doc/frontend_backend_alignment_report.md 업데이트로 이벤트 뷰→스냅샷 흐름 문서화 (2025-10-24)
   • 정렬/페이징/오류 코드 스펙 동기화 (stock_approval_system_api_v4.md §§4.8~4.9)
   • 감사 로그/Slack 알림 범위 정의 (doc/inventory_summary_audit_plan.md)

2. 데이터 모델링 & 마이그레이션

   • migration/110_inventory_balance_events_view.sql
   • migration/115_inventory_balance_snapshots_mv.sql + 인덱스/리프레시 정책
   • script/refresh_inventory_mv.sh, doc/qa/inventory_data_replay.md

3. API/서비스 설계

   • backend/src/domain/inventory.rs (쿼리/DTO 규칙)
   • backend/src/api/v1/inventory.rs (/inventory/summary, /inventory/summary/{product_id})
   • stock_approval_system_api_v4.md, doc/API_CLIENT_SPEC.md에 직렬화/빈 결과 규칙 명시

4. 권한·인증·감사

   • migration/105_add_inventory_scope.sql로 inventory.view 스코프 시드
   • backend/src/api/security.rs에 InventoryAuthContext 및 스코프 검사 추가
   • 감사 이벤트 inventory.summary.viewed (backend/src/app/services/inventory.rs)

5. 구현

   • backend/src/adapters/repositories/inventory.rs (뷰 조회)
   • backend/src/app/services/inventory.rs 2초 TTL 캐시
   • 오류 코드 통일 (INVENTORY_SNAPSHOT_NOT_READY, INVENTORY_SCOPE_REQUIRED)

6. 샘플/테스트 데이터

   • migration/120_seed_inventory_summary.sql
   • doc/qa/inventory_data_replay.md

7. 검증 & 문서

   • backend/tests/inventory_summary.rs
   • script/run_backend_checks.sh (fmt/check/clippy/tests::inventory_summary)
   • Postman/Thunder & doc/API_CLIENT_SPEC.md 업데이트 (백엔드 기준)

---

프론트엔드 단계별 Tasks (백엔드 완료 후 착수)

1. 계약 동기화 & 환경 준비

   • superport_v2에서 API DTO/JSON 직렬화를 build_runner로 재생성(InventorySummaryResponse, InventoryDetailResponse).
   • ApiClient에 /api/v1/inventory/summary 경로를 추가하고, 서비스 등록은 기존 의존성 주입 컨테이너(injection_container.dart)에 InventoryRepository/InventoryService로 분리.
   • QA 계정은 로그인 응답(permissions, permission_codes)에 scope:inventory.view가 포함되도록 백엔드와 권한 시드를 맞추고, README에서 해당 흐름을 안내.

2. 내비게이션 & 라우팅

   • Flutter 사이드 메뉴에 재고현황을 대시보드와 입출고 사이에 배치하고, 앱 라우터(GoRouter/AutoRoute)에서 /inventory/summary 라우트를 추가.
   • 라우트 가드: 세션의 permissions 배열에 scope:inventory.view가 없으면 메뉴 자체를 숨기고, 직접 URL 접근 시 권한 부족 안내/감사 로그 전송.

3. 상태 관리 & 데이터 요청

   • 기존 상태관리 패턴(예: Riverpod AsyncNotifier / Bloc)을 따른 InventorySummaryController를 작성하고 페이징, 정렬, 필터 상태를 보존.
   • 상세 패널은 InventoryDetailController를 분리해 제품 ID별 캐시, 동일 요청 중복 방지, event_limit 조절(기본 20) 로직을 포함.
   • HTTP 오류(403, 404, 409)와 빈 데이터 응답 시 UI 상태를 명시적으로 노출하고, 최근 이벤트가 비어있을 때 대체 메시지를 제공.

4. UI 컴포넌트

   • Flutter PaginatedDataTable 또는 기존 공용 테이블 위젯으로 리스트를 구성: 컬럼 = 순번, 제품명/코드, 벤더, 총계, 창고별 요약, 최근 변동(타입/수량/시간/거래처).
   • 상세 뷰(모달 또는 DraggableScrollableSheet)에 warehouse_balances 그래프/Tag, recent_events 타임라인(입·출고/대여/반납 구분 아이콘) 표현.
   • View-only 배지, Skeleton/empty/error state 컴포넌트를 기존 디자인 시스템(superport_v2/lib/widgets/state/)과 재사용.

5. UX 보완

   • 최신 변동 기준 정렬 라벨(최근 이벤트: 2025-10-24 12:12)과 자동 새로고침 토글(뷰 리프레시 시각 기준)을 안내.
   • 창고별 잔량은 Tag/Pill 또는 미니 차트로 시각화하고, 총 보유 수량을 강조(Warning 색상은 음수 재고만).
   • 키보드 포커스 이동, 스크린리더 라벨(recent_event.event_label) 등 접근성 체크.

6. 테스트 & 품질

   • Widget 테스트: 리스트 렌더링, 최근 이벤트 표시, 권한 없는 경우 Alert 노출.
   • 통합/Golden 테스트: 정렬/필터 조합, 빈 데이터 상태, 상세 패널 타임라인.
   • flutter analyze, flutter test --coverage, 필요 시 flutter test --coverage --machine 결과를 CI에 업로드.

7. 문서 & 배포 준비

   • doc/detail_dialog_unification_plan.md 또는 신규 문서에 UI 플로우와 스냅샷을 추가.
   • 릴리스 노트/PR 템플릿에 사용자 영향(읽기 전용 화면 추가)과 검증 커맨드(cargo test -- tests::inventory_summary, flutter test --coverage)를 명시.
   • QA와 함께 재고/입출고/대여 연계 시나리오를 포함한 E2E 테스트 목록을 doc/qa/inventory/ 하위에 정리.

---

통합 체크리스트

• inventory.view 스코프 및 메뉴 권한 시드 적용 (백엔드 105번 마이그레이션)
• inventory_balance_events_view / inventory_balance_snapshots 리프레시 + 모니터링 스크립트
• /api/v1/inventory/summary/{product_id} 스펙 검증 & cargo test -- tests::inventory_summary 통과
• 감사 로그(inventory.summary.viewed) 경보 플로우 스테이징 검증
• 문서/QA/배포 안내 최신화 (doc/API_CLIENT_SPEC.md, doc/qa/inventory_data_replay.md, script/DEPLOY_REMOTE.md)