Frontend API Alignment Plan

1. 현황 요약

Environment API_BASE_URL 기본값은 http://localhost:8080이며 버전 prefix(/api/v1)는 포함되어 있지 않다.
Master/Approval/Inventory 모듈 대부분이 _basePath = '/<resource>'로 정의되어 있어 실제 백엔드(/api/v1/...)와 경로가 불일치한다.
입고/출고/대여 화면은 _mockRecords, Inventory*Catalog 등 정적 데이터를 사용하고 있으며, 서버 응답 모델과 연결되어 있지 않다.
승인 도메인(approvals/steps/histories/templates)은 Repository/DTO가 준비되어 있으나 백엔드 미구현 상태라 기능 플래그로 비활성화되어 있다.

공통 경로 상수화
- lib/core/network/api_client.dart 또는 별도 헬퍼에 const apiV1 = '/api/v1'; 정의.
- 모든 Remote Repository의 _basePath 앞에 ${ApiRoutes.apiV1} prefix 적용.
- WarehouseRepositoryRemote, VendorRepositoryRemote, UomRepositoryRemote, TransactionTypeRepositoryRemote, TransactionStatusRepositoryRemote, ApprovalStatus/Action 등 전체 점검.
DI/환경 값 점검
- .env.* 예시 파일에 API_BASE_URL 주석으로 "버전 prefix 없음" 명시.
- 필요 시 Environment.baseUrl에 /api/v1를 포함한 값을 직접 지정해도 되지만, 기존 백엔드 관례에 맞춰 prefix 상수 사용 권장.
기 구현 백엔드 연동
- 벤더/단위/거래유형/거래상태/결재상태/결재행위/창고 화면에서 Feature_* 플래그를 통해 API 호출 활성화.
- 응답 파싱 결과가 UI에 반영되는지 확인하고, 로딩/에러 핸들러 추가.
테스트/검증
- flutter analyze, flutter test 실행.
- 가짜 데이터 비활성화 후 빈 응답 대비 UI(Empty state) 정상 동작 확인.

고객/제품/직원/권한 등 마스터 확장
- 백엔드 /api/v1/customers, /products, /employees, /groups, /menus, /group-menu-permissions 구현 후 Remote Repository 활성화.
- DTO 매핑 검증 및 리스트/폼 화면에 실데이터 연동.
승인(Approvals) 플로우
- /approvals, /approval-steps, /approval-histories, /approval-templates 엔드포인트 제공 시 기능 플래그 해제.
- Step assign/action API 응답 구조가 ApprovalDto 기대 필드(steps, actions, histories)를 포함하는지 확인.
재고 트랜잭션 (입고/출고/대여)
- /stock-transactions 및 관련 라인/승인 API가 준비되면 _mockRecords, Inventory*Catalog 제거.
- 목록 필터/페이지네이션을 API Query와 동기화하고, 상세 모달 입력/수정 흐름을 서버 모델로 전환.
우편번호 검색
- /zipcodes(검색) API 구현 시 PostalSearchRepositoryRemote 경로와 파라미터를 확인하고 UI를 연동.

기능별 Feature Flag를 단계적으로 해제하면서 QA 진행.
각 단계에서 script/run_api_tests.sh로 백엔드 검증 → 프론트 flutter test → 수동 시연 순으로 검증 체계 유지.
API 변경 사항은 CHANGELOG 및 doc/backend_change_requests.md와 동기화해 추후 회고/인수에 활용.