superport_v2/doc/frontend_api_alignment_plan.md

# Frontend API Integration Task Plan

## 진행 현황 스냅샷 (2025-10-19 기준)
- 단계 1~2: 공통 네트워크 인프라와 마스터 도메인 원격 저장소/테스트가 모두 반영되어 실 API 계약 기준 코드가 자리잡았다.
- 단계 3: 결재 레이어는 저장소·컨트롤러·위젯 테스트까지 구축 완료됐으며, `canProceed` API 연동·UI 차단 로직과 환경별 `FEATURE_APPROVALS_ENABLED=true` 기본값 조정까지 마쳤다.
- 단계 4: 재고 트랜잭션 컨트롤러와 submit/complete 플로우가 API 호출로 전환됐고, 고객 필터/위젯에서 사용하던 정적 카탈로그를 제거하여 전 구간이 실데이터를 사용한다. 보고서 기능은 `ReportingRepositoryRemote` 기반으로 API에 연결돼 다운로드 링크/바이너리 응답을 모두 처리하며, UI는 진행 상태·에러·다운로드 액션(열기/URL 복사)을 제공한다.
- 단계 5: 테이블 spec 분리는 완료됐고, 권한 경로 통일·Failure 파서 고도화·실패 메시지 통합·실제 API 플로우 검증이 잔여 과제로 남아 있다.

## 0. 사전 준비 및 브랜치 전략
1. 현재 백엔드 서버는 아직 기동되지 않았지만, 모든 기능은 실제 API 계약(`stock_approval_system_api_v4.md`)을 기준으로 구현한다.
2. 프론트엔드 작업용 브랜치를 `feature/api-integration` 형태로 생성하고, 단계별 작업이 끝난 뒤 스쿼시 머지한다.
3. `.env.development`/`.env.production`에 `API_BASE_URL`을 최신 서버 URL(가용 시)을 기입하고, 베이스 URL에는 버전 prefix(`/api/v1`)가 포함되지 않는다고 주석으로 명시한다.

## 1. 공통 네트워크 인프라 정비
1. [완료] `lib/core/network/api_routes.dart`(또는 동일 역할 파일)에 `static const apiV1 = '/api/v1';`를 추가하고, `ApiClient` 계층이 prefix를 중복으로 붙이지 않도록 확인한다.
2. [완료] 모든 Remote Repository의 `_basePath`를 `${ApiRoutes.apiV1}/<resource>` 형태로 교정한다(범위: `lib/features/*/data/repositories/**/*.dart`).
3. [완료] `Environment.initialize()` 이후 `lib/injection_container.dart`에서 Customers, Products, Employees, Groups, Menus, GroupMenuPermissions, ApprovalTemplates, Approvals, StockTransactions 등 신규 리포지토리를 전부 등록한다.
4. [완료] 네트워크 예외 처리(`ApiClient` → `Failure`)와 401 재인증 흐름을 단위 테스트로 검증해 실제 API 연결 시 동작 보장을 확보한다.

## 2. 마스터 도메인 API 연동 준비
1. [완료] Customers
   - DTO를 백엔드 응답 스키마(`customer_code`, `zipcode` 객체 등)에 맞춰 업데이트한다.
   - `CustomerRepositoryRemote`에 목록/상세/생성/수정/삭제/복구 메서드를 구현하고, 컨트롤러·페이지에서 검색/활성 상태/페이지네이션 파라미터를 전달한다.
   - 테스트: Repository 인터페이스와 위젯 테스트로 필터·복구 시나리오를 검증한다.
2. [완료] Products / Vendors / UOMs
   - `_basePath`를 `/api/v1/...`로 통일하고 `include=vendor,uom` 파라미터를 지원한다.
   - 빈 응답 시 UI 안내가 노출되는지 위젯 테스트를 추가한다.
3. [완료] Employees / Groups / Menus / Group-Menu Permissions
   - 각 Remote Repository를 구현하고 권한 편집 화면을 서버 스키마에 맞춘다.
   - `PermissionManager`가 서버 권한 데이터를 사용하도록 업데이트하고 단위 테스트로 검증한다.
4. [완료] Warehouses / Transaction Types / Transaction Statuses / Approval Statuses / Approval Actions
   - `InventoryLookupRepositoryRemote` 단위 테스트를 통해 상태/타입/결재 상태 API를 통합했고, 입출고/대여 필터는 모두 실데이터 기반 위젯으로 교체했다. 정적 고객/제품 카탈로그를 제거해 컨트롤러와 페이지가 동일한 실데이터 경로만 사용하며, 승인·반려·취소 버튼은 컨트롤러/상세 카드/모바일 리스트에서 API 기반 상태 전이를 수행한다.
5. [완료] Zipcodes
   - `/api/v1/zipcodes` 규격(`q`, `page`, `page_size`)에 맞춰 `PostalSearchRepositoryRemote`를 조정하고 자동완성 위젯 테스트를 강화한다.

## 3. 결재(Approvals) 도메인 실연동 준비
1. [완료] Feature Flag를 `true` 기본값으로 전환하되, 서버가 준비되기 전에는 UI에서 불필요한 호출이 반복되지 않도록 로딩/에러 처리를 정교화한다 — 개발/운영 환경 모두 `FEATURE_APPROVALS_ENABLED=true`를 기본으로 두고, 운영 배포 전이라도 백엔드 미준비 시에는 `.env.*`에서 수동으로 비활성화하도록 가이드를 명시했다.
2. [완료] `ApprovalRepositoryRemote`에 목록/상세 `include=steps,histories,template` 옵션과 생성/수정/삭제/복구/`canProceed` 호출을 구현한다 — `can-proceed` 엔드포인트까지 연동해 컨트롤러에서 액션 실행 전 검증하도록 구성했다.
3. [완료] `ApprovalStepController.performStepAction`이 `/api/v1/approval-steps/{id}/actions`로 요청을 보낸 뒤 응답으로 상태를 갱신하도록 구성한다.
4. [완료] Approval Templates
   - 템플릿 CRUD/restore 및 스텝 편집 API 연동을 구현하고, 템플릿 적용 시 `/approvals/{id}/steps` 호출과 연계되도록 리팩터링한다.
5. [완료] 테스트
   - `ApprovalController`와 `ApprovalPage` 권한 테스트에 `canProceed` true/false 흐름을 추가했고, 기능 플래그 on/off 시나리오를 커버하는 위젯 테스트를 유지하고 있다.

## 4. 재고 트랜잭션 (입고/출고/대여) 실데이터 전환 준비
1. [완료] Repository 작성
   - `StockTransactionRepositoryRemote`, `TransactionLineRepositoryRemote`, `TransactionCustomerRepositoryRemote`를 `/api/v1/stock-transactions` 계열 엔드포인트에 맞춰 구현한다.
   - `include=lines,customers,approval` 파라미터를 지원해 상세 응답을 완성한다.
   - ApiClient 모킹 기반 단위 테스트로 쿼리/경로/페이로드 구성을 검증한다.
2. [진행중] Controller 연동
   - (완료) `InboundPage`, `OutboundPage`, `RentalPage`에서 `_mockRecords`를 제거하고 `StockTransactionRepository` 기반 실데이터를 로드하도록 전환했다.
   - (완료) 데이터 페칭 로직을 전용 컨트롤러로 분리하고 페이지가 컨트롤러 상태를 구독하도록 리팩터링했다.
   - (진행) 상태 전이 액션(Submit/Approve/Reject/Cancel/Complete)을 API 호출 기반으로 대체한다 — submit/complete는 컨트롤러와 위젯에 연결되어 있으나 approve/reject/cancel 버튼/토스트 연결, 생성·수정 다이얼로그에서 `StockTransaction*Input` 매핑, 신규 공통 위젯을 활용한 필드 교체가 남아있다.
3. 상세 모달 UI
   - 서버 응답 스키마에 맞춘 DTO→Domain 변환기를 작성하고, 편집/삭제 후 상태 동기화를 서버 응답으로 수행한다.
4. 테스트
   - 각 컨트롤러 단위 테스트에서 상태 전이 및 라인/고객 관리 로직을 검증하고, 위젯 테스트로 목록 로딩/빈 상태/승인 버튼 시나리오를 확인한다.
5. 레거시 제거
   - `Inventory*Catalog`, `_mockRecords`, `Fake*Repository` 파일을 삭제하고, `pubspec.yaml`에서 불필요한 참조를 정리한다.

## 5. 권한/실패 처리 고도화

### 5-1. 권한 경로 정규화
- [x] `PermissionResources._aliases`를 서버 표준 경로(`/stock-transactions`, `/approvals/...`)와 비교해 누락/중복을 정리한다. (2025-10-19) 절대 URL·쿼리 문자열 정리를 포함한 `_sanitize` 보강과 `/reports/*` 별칭 추가를 완료했다.
- [x] `PermissionManager`가 반환하는 권한 키와 페이지 컨트롤러에서 사용하는 의존성을 점검해 동일한 정규화 로직을 적용한다. (2025-10-19) `PermissionManager` 테스트에 경로 별칭 시나리오를 추가해 정규화 동작을 검증했다.
- [x] `test/core/permissions/permission_resources_test.dart`를 추가해 경로 정규화 케이스(슬래시, 대소문자, 하위 경로)를 검증한다.

### 5-2. Failure 파서 고도화
- [x] Stage 7 실패 로그(`log/API_TEST_RESULT_20251014_155128.txt`)와 `ApiErrorMapper`를 비교해 상태 전이/권한 오류 메시지 누락을 보완한다. (2025-10-19) 403/409/422 응답이 `details/context/reasons`를 그대로 보존하도록 매퍼 분기를 확장했다.
- [x] 409/422 응답의 `details`를 도메인 계층에서 소비할 수 있도록 DTO 매핑 헬퍼를 확장한다. (2025-10-19) `FailureParser`가 `context` 노드를 흡수하고 `Failure.describe()`가 필드 오류를 병합하도록 보강했다.
- [x] 신규 분기별 단위 테스트를 추가해 UI 레이어가 일관된 메시지를 받을 수 있도록 한다. (`test/core/network/api_error_test.dart`, `test/core/network/failure_parser_test.dart`)

### 5-3. 실패 메시지 통합
- [x] 입·출·대여/결재/보고서 페이지의 토스트/다이얼로그 오류 메시지를 `ApiException` 기반으로 통합한다.
- [x] UX 팀과 합의된 메시지 톤을 정리하고 `doc/error_message_guide.md`에 반영한다. (2025-10-19) 오류 메시지 톤/노출 위치/테스트 체크리스트를 정리했다.
- [x] 주요 위젯 테스트를 업데이트해 메시지 노출 시나리오를 자동 검증한다. (2025-10-19) `reporting_page_test.dart` 재시도 흐름과 컨트롤러·파서 단위 테스트로 메시지 일관성을 검증한다.

### 5-4. 실 API 플로우 검증
- [x] `.env.staging.example`에 스테이징 변수 템플릿을 추가하고 `integration_test/stock_transaction_state_flow_test.dart`가 환경 변수 부족 시 필요한 항목을 안내하도록 보강했다. 실제 값은 배포 계정 확보 후 `.env.staging`에 기록한다.
- [x] `flutter test -d macos integration_test/stock_transaction_state_flow_test.dart` 실행 결과를 `log/API_TEST_RESULT_20251014_173850.txt`로 보관한다.
- [x] 실행 로그와 발견 이슈를 본 문서와 `doc/IMPLEMENTATION_TASKS.md` DoD 섹션에 반영한다.

## 6. 문서 및 운영 가이드 정리
1. 본 문서를 체크리스트로 활용하며 진행 상황을 주기적으로 업데이트한다.
   - (2025-10-14) 입·출·대여 승인/반려/취소 액션을 컨트롤러와 UI에서 API 호출로 연결하고 진행률을 90%로 상향했다.
   - (2025-10-15) 입·출·대여 생성/수정 모달을 `StockTransaction*Input` 기반으로 실 API와 연계하고 작성자·고객 선택 위젯을 실데이터 기준으로 교체했다.
   - (2025-10-16) 라인/고객 편집 동기화 서비스와 컨트롤러/위젯 테스트를 추가해 단계 4 진행률을 100%로 마무리했다.
   - (2025-10-18) 보고서 내보내기 화면을 실 API와 연결하고 다운로드/에러 UX를 정비했으며, 스테이징 환경 검증용 통합 테스트 스켈레톤과 QA 시나리오 문서를 추가했다.
2. [완료] `README.md` "API 연동" 섹션에 신규 자원 목록과 필수 환경 변수 설명을 추가한다.
   - (2025-10-20) `/api/v1` 경로와 연동된 리소스 목록, 필수 환경 변수(`ENV`, `API_BASE_URL`, `FEATURE_*`, `PERMISSION__*`) 안내를 README에 정리했다.
3. [완료] `CHANGELOG.md`에 사용자 영향도가 높은 변경사항(승인/재고 실시간 연동)을 기록한다.
   - (2025-10-20) Failure 기반 오류 메시지 통합과 재고/결재 API 연동 내역을 담은 변경 기록을 추가했다.
4. [완료] QA 시나리오 문서(`doc/qa/...`)가 있다면 실제 API 기준으로 갱신하고, 테스트 데이터 구성 방식을 명시한다.
   - (2025-10-20) 스테이징 QA 문서에 `/api/v1` 마스터 조회 절차와 데이터 생성/정리 플로우를 명시해 테스트 데이터 재현 방법을 고정했다.

## 7. 실제 서버 연동 및 배포 절차 (최종 단계)
1. [완료] 백엔드 서버 기동 및 점검
   - Homebrew로 PostgreSQL 16을 설치해 로컬 DB를 준비한 뒤, `migration/001_initial_schema.sql`과 `script/load_sample_data.sh --with-demo-data`로 스키마·샘플 데이터를 적재했다.
   - `cargo run -p backend`를 `nohup`으로 기동하고 `curl http://127.0.0.1:8080/health`로 헬스 체크를 확인했다.
   - `script/run_api_tests.sh --base-url http://127.0.0.1:8080` 실행 결과 110개 시나리오 중 98건 통과, 12건(재고 전이 흐름 및 그룹-메뉴 권한 복구)이 실패함을 확인했다. 실패 케이스는 미구현 엔드포인트 목록과 함께 log/API_TEST_RESULT_YYYYMMDD_HHMMSS.txt에 기록해 백엔드 공유 예정.
   - (2025-10-19) 프론트 통합 테스트(`integration_test/stock_transaction_state_flow_test.dart`)의 환경 변수 안내 및 `.env.staging.example` 템플릿을 추가했다. 백엔드에서 재고 상태 전이/권한 복구 엔드포인트를 배포하면 스테이징 토큰·ID를 확보한 뒤 재실행한다.
2. [완료] 정적 분석 및 테스트
   - `flutter analyze` → No issues found.
   - `flutter test --coverage` → 모든 230개 테스트 통과, `coverage/lcov.info` 생성.
   - `flutter build web --release` → `build/web` 산출(Wasmtime dry-run 경고는 `flutter_secure_storage_web` 의존으로 인한 JS interop 제한).
3. [완료] 수동 점검
   - 로컬 백엔드 + 스텁 데이터를 이용해 위젯/통합 테스트로 승인·입출고·대여 핵심 플로우를 재검증했다(`group_permission_page_test`, `inbound_page_test` 등). 추가 수동 검증은 스테이징 환경 재가동 시 실행 예정이나, 필수 경로는 자동화 테스트/스크립트로 커버했다.
4. [완료] 배포 준비
   - `assets/.env.production` 기준 값과 README의 환경 변수 설명을 재확인했으며, `flutter build web --release` 산출물을 통해 배포 아티팩트 생성을 검증했다.
   - 최종 머지 전 `notify.py` 호출 및 릴리스 노트/환경 파일 확정 프로세스는 배포 승인 시점에 수행하도록 안내를 남긴다.

- 백엔드 미구현 항목 대응 전략
- [x] 재고 상태 전이 실패(Stage 7 미구현 8건) 관련 API 스펙을 백엔드 팀과 재검토하고, `PATCH /stock-transactions/{id}/status` 확장 일정과 테스트 데이터 세트를 공유한다. (2025-10-19) `doc/backup/backend_change_requests.md` 2.4절에 상태 전이 API 요구사항과 테스트 데이터 항목을 업데이트했다.
- [x] 그룹-메뉴 권한 복구 미구현(4건)은 `/group-menu-permissions/{id}/restore` 엔드포인트 공개 후 프론트 통합 테스트에 포함시킨다. (2025-10-19) 동일 문서 2.2절에 복구 API 요구사항을 명시하고 테스트 시나리오를 정리했다.
  - [x] 프론트단에서는 `ApiErrorMapper`와 `Failure` 파서를 보강해 403/409/422 응답 메시지를 토스트·다이얼로그에 그대로 노출하고, 재시도 시 가이드 문구를 제공한다.
- [x] 백엔드 수정 전까지 승인/취소 버튼에는 기능 플래그를 적용해 운영 환경에서 잘못된 전이 요청이 발생하지 않도록 보호한다. (2025-10-19) `FEATURE_STOCK_TRANSITIONS_ENABLED` 플래그를 추가하고 입·출·대여 화면에서 버튼을 비활성화하며 안내 배지를 노출하도록 조정했다.

## 8. 재고 생성 결재 정보 수집 계획 (2024-08-XX 업데이트)
1. **신규 입력 필드 구성**
   - 입고/출고/대여 등록 모달에 “결재 정보” 섹션을 추가하고 `거래번호`, `결재번호`, `결재 메모`, `결재 요청자` 필드를 배치한다.
   - 거래번호는 수동 입력 + “번호 자동 생성” 버튼을 제공하고, 후자는 시퀀스 API(백엔드 지원 필요)와 연동한다.
   - 결재 요청자는 기존 작성자 자동완성 컴포넌트를 재사용해 `requested_by_id`로 매핑한다.
2. **컨트롤러/검증 로직**
   - `StockTransactionCreateInput`에 `StockTransactionApprovalInput`을 추가해 `approval_no`, `approval_status_id`, `requested_by_id`, `note`를 묶어서 전송한다.
   - 검증 단계에서 거래번호/결재번호 누락 여부를 체크하고, 승인 상태는 Lookup(`fetchApprovalStatuses`)에서 “대기” ID를 로딩해 기본값으로 사용한다.
3. **사용자 경험 보완**
   - 결재 템플릿 선택 시 템플릿에서 결재번호 규칙·승인자를 추천하고, 수동 변경 시 경고 메시지를 노출한다.
   - 저장 직전 `/approvals` 간단 조회 또는 별도 중복 체크 API로 결재번호·거래번호 중복을 사전 확인한다.
4. **후속 일정**
   - 1차 목표는 필수 필드 수집과 API 호출 연계이며, 템플릿 적용/번호 시퀀스 API는 백엔드 명세 확정 이후 2차 작업으로 분리한다.
   - 컨트롤러 단위 테스트·위젯 테스트에 승인 정보 입력 시나리오를 추가하고 QA 문서에도 신규 체크리스트를 반영한다.