# Frontend API Integration Task Plan

## 진행 현황 스냅샷 (2025-10-31 기준)
- 단계 1~2: 공통 네트워크 인프라와 마스터 도메인 원격 저장소/테스트가 모두 구축돼 실 API 계약 기준 코드가 자리잡았다.
- 단계 3: 결재 레이어는 저장소·컨트롤러·위젯 테스트까지 마쳤으며 `canProceed` API, `include_pending` 필터, 전표 타임스탬프 동기화 및 `FEATURE_APPROVAL_FLOW_V2` 토글 alias 대응이 반영됐다.
- 단계 4: 재고 트랜잭션 컨트롤러가 submit/approve/reject/cancel/complete 전 구간을 API 호출로 전환했고, Approval Draft 서버 저장/복원 사용자 흐름을 재고/결재 화면에 통합했다. 보고서 기능은 `ReportingRepositoryRemote`가 바이너리/링크 응답을 모두 처리한다.
- 단계 5: 공통 테이블 사양과 Failure 매퍼 보강을 완료했고, 남은 작업은 배포 체크리스트(F8)와 스펙 회귀 테스트 확장이다.
- (2025-10-29) Approval Flow v2 대응을 위해 `ApprovalSubmissionInput` 등 도메인 입력 모델과 `/approval/submit|approve|reject|recall|resubmit|history` 호출을 Data 레이어에 도입했다. 기존 `create/update` 경로는 레거시 화면이 교체될 때까지 병행 유지한다.
- (2025-11-01) `ApprovalHistoryController`가 감사 로그·카탈로그 기반 코드→ID 캐싱(`_auditActions`→`_actionIdsByCode`)과 `ApiClient.buildQuery` `filters` 매개변수를 적용해 `approval_action_id`/`action_from`/`action_to`를 전송하며, 위젯 테스트(`approval_history_page_test.dart`)로 회귀를 감시한다.

## 문서 동기화 규칙
1. `superport_api_v2` 리포지터리의 `stock_approval_system_*.md` 문서를 단일 소스로 간주하고, 수정은 반드시 백엔드 리포지터리에서 먼저 수행한다.
2. 백엔드 문서 변경 후 프론트 리포지터리 루트에서 `tool/sync_stock_docs.sh`를 실행해 `doc/` 경로를 갱신한다. CI 또는 로컬 검증 시에는 `tool/sync_stock_docs.sh --check`로 차이를 확인한다.
3. 문서 차이가 감지되면 동기화 커밋을 생성하고 PR 본문에 백엔드 커밋 링크를 포함해 리뷰어가 출처를 추적할 수 있도록 한다.

## Approval Flow v2 연동 계획 (현황)
- [x] 백엔드 세부 작업 계획(`../superport_api_v2/doc/approval_flow_backend_task_plan.md`)과 프런트 작업 계획(`doc/approval_flow_frontend_task_plan.md`)을 동기화했다.
- [x] 입고/출고/대여 등록 화면에 결재 단계 구성 섹션을 추가하고 제출 요청에 Approval payload를 병합했다 (`lib/features/inventory/*/presentation/pages/*_page.dart`).
- [x] 결재 템플릿/이력 메뉴를 `ShadTable` 기반으로 재구성하고 recall/resubmit, 감사 로그 UI를 확장했다 (`lib/features/approvals/request/presentation/widgets/`, `lib/features/approvals/history/presentation/pages/approval_history_page.dart`).
- [x] Approval 관련 DTO/레포지토리/유즈케이스를 전면 재정비하여 신규 엔드포인트(`/approval/submit|approve|reject|recall|resubmit`, `/approval/templates`)와 계약을 맞췄다 (`lib/features/approvals/data/repositories/approval_repository_remote.dart`, `lib/features/approvals/domain/usecases/*`).
- [x] 테스트 체계에 결재 단계 추가/삭제/회수/재상신 위젯·통합 시나리오를 추가했고 `integration_test/approvals_flow_test.dart`로 회귀를 검증한다.

## 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` 엔드포인트까지 연동해 컨트롤러에서 액션 실행 전 검증하도록 구성했다.
   - (2025-10-29) `submit`/`approve`/`reject`/`recall`/`resubmit`/`listHistory` 메서드와 대응 DTO(`ApprovalSubmitRequestDto`, `ApprovalResubmitRequestDto`, `ApprovalDecisionRequestDto`, `ApprovalRecallRequestDto`, `ApprovalAuditListDto`)를 추가했다. 컨트롤러·유즈케이스 연결은 F2 단계에서 마이그레이션한다.
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 시나리오를 커버하는 위젯 테스트를 유지하고 있다.
6. [ ] 결재 열람 제한 연동
   - 상신자/기결재자만 목록·상세 API를 조회할 수 있도록 `ApprovalRepositoryRemote`에 403 (`APPROVAL_ACCESS_DENIED`) 처리 분기를 추가하고, UI에서 권한 토스트/리다이렉트를 구현한다.

## 4. 재고 트랜잭션 (입고/출고/대여) 실데이터 전환 준비
1. [완료] Repository 작성
   - `StockTransactionRepositoryRemote`, `TransactionLineRepositoryRemote`, `TransactionCustomerRepositoryRemote`를 `/api/v1/stock-transactions` 계열 엔드포인트에 맞춰 구현한다.
   - `include=lines,customers,approval` 파라미터를 지원해 상세 응답을 완성한다.
   - ApiClient 모킹 기반 단위 테스트로 쿼리/경로/페이로드 구성을 검증한다.
   - 신규 `status`/`include_pending` 파라미터를 지원해 초안·상신 전표는 기본 목록에서 제외하고, 대기 전용 화면에서만 렌더링한다.
2. [진행중] Controller 연동
   - (완료) `InboundPage`, `OutboundPage`, `RentalPage`에서 `_mockRecords`를 제거하고 `StockTransactionRepository` 기반 실데이터를 로드하도록 전환했다.
   - (완료) 데이터 페칭 로직을 전용 컨트롤러로 분리하고 페이지가 컨트롤러 상태를 구독하도록 리팩터링했다.
   - (진행) 상태 전이 액션(Submit/Approve/Reject/Cancel/Complete)을 `doc/stock_approval_system_api_v4.md` 4.7절 규격에 맞춰 API 호출 기반으로 정비한다 — submit/approve/reject/cancel/complete 모두 컨트롤러·위젯에 연결되도록 리팩터링하고, 생성·수정 다이얼로그의 `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`를 `stock_approval_system_api_v4.md` (2025-09-18) 스펙 반영 버전으로 재실행해 상태 전이·권한 복구 시나리오가 모두 통과하는지 확인하고, 결과 로그(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` 호출 및 릴리스 노트/환경 파일 확정 프로세스는 배포 승인 시점에 수행하도록 안내를 남긴다.

- 백엔드 v4 스펙 반영 체크리스트
- [x] 재고 상태 전이 API 회귀 테스트를 `doc/stock_approval_system_api_v4.md` 4.7절 기준으로 재작성하고 submit/approve/reject/cancel/complete 호출 성공 여부를 통합 테스트에 반영한다.
  - (2025-11-05) `integration_test/stock_transaction_state_flow_test.dart`에서 가상/실제 환경 모두 `submit → approve → complete`, `submit → cancel`, `submit → reject` 흐름을 검증하도록 리팩터링했다.
  - 상태 전이 요청 본문에 `note` 필드를 전달하도록 `StockTransactionRepository` 인터페이스와 원격 구현·단위 테스트를 갱신했다.
- [x] 그룹-메뉴 권한 복구 API(`POST /group-menu-permissions/{id}/restore`) 시나리오를 복구해 삭제/복구 UI가 `include_deleted=true` 응답을 사용하는지 검증한다.
  - 삭제 포함 토글이 활성화된 상태에서 복구 후 재조회 시 `include_deleted=true`가 유지되는지를 컨트롤러 단위 테스트로 심사하고, 복구 직후 목록이 최신 상태로 동기화되도록 확인했다.
- [x] 백엔드 배포 확인 후 `FEATURE_STOCK_TRANSITIONS_ENABLED` 플래그 해제 시나리오와 운영 전환 체크리스트를 정리한다.
  - 운영 배포 전 점검: (1) 스테이징에서 통합 테스트 승인을 완료하고, (2) 백엔드 릴리스 노트의 마이그레이션 완료 여부를 확인한다.
  - 배포 직후 절차: `assets/.env.production`의 `FEATURE_STOCK_TRANSITIONS_ENABLED` 값을 `true`로 전환하고 운영 배포 파이프라인에서 해당 파일을 사용해 웹 번들을 재생성한다. 배포 이후 재고 화면의 상신/승인 버튼 노출과 토스트 메시지를 QA 체크리스트에 따라 검증한다.
  - 롤백 가이드: 장애 발생 시 동일 순서로 토글을 `false`로 되돌리고, 통합 테스트의 `STAGING_RUN_TRANSACTION_FLOW`를 `false`로 설정해 회귀 시나리오를 비활성화한다.

## 8. 재고 생성 결재 정보 수집 계획 (2024-08-XX 업데이트)
> 현황: `StockTransactionApprovalInput`과 인벤토리 컨트롤러 초안 저장 로직이 반영되어 UI/테스트 레벨에서 요구사항을 충족한다 (`lib/features/inventory/*/presentation/controllers/*_controller.dart`, `test/features/inventory/*/presentation/controllers/*_controller_test.dart`).
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 문서에도 신규 체크리스트를 반영한다.
