superport_v2/doc/frontend_api_alignment_plan.md

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 연동 계획 (현황)

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

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

5-2. Failure 파서 고도화

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

5-3. 실패 메시지 통합

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

5-4. 실 API 플로우 검증

• .env.staging.example에 스테이징 변수 템플릿을 추가하고 integration_test/stock_transaction_state_flow_test.dart가 환경 변수 부족 시 필요한 항목을 안내하도록 보강했다. 실제 값은 배포 계정 확보 후 .env.staging에 기록한다.
• flutter test -d macos integration_test/stock_transaction_state_flow_test.dart 실행 결과를 log/API_TEST_RESULT_20251014_173850.txt로 보관한다.
• 실행 로그와 발견 이슈를 본 문서와 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 스펙 반영 체크리스트
• 재고 상태 전이 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 인터페이스와 원격 구현·단위 테스트를 갱신했다.
• 그룹-메뉴 권한 복구 API(POST /group-menu-permissions/{id}/restore) 시나리오를 복구해 삭제/복구 UI가 include_deleted=true 응답을 사용하는지 검증한다.
  • 삭제 포함 토글이 활성화된 상태에서 복구 후 재조회 시 include_deleted=true가 유지되는지를 컨트롤러 단위 테스트로 심사하고, 복구 직후 목록이 최신 상태로 동기화되도록 확인했다.
• 백엔드 배포 확인 후 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 문서에도 신규 체크리스트를 반영한다.