superport_v2/doc/approval_flow_frontend_task_plan.md

Approval Flow 프런트엔드 작업 계획

• 기준 문서: doc/ApprovalFlow_System_Integration_and_ChangePlan.md, 백엔드 계획(../superport_api_v2/doc/approval_flow_backend_task_plan.md)
• 범위: 입고/출고/대여 등록 화면 결재 단계 구성 UI, 결재 템플릿/이력 메뉴 전면 개편, 감사 로그/회수/재상신 UX 정비
• 작업 순서: 사전 정비 → 데이터 계층 → UI/상호작용 → 검증/UI/테스트 → 문서/배포

---

0. 킥오프 & 환경 준비

• F0-1 백엔드 스키마/엔드포인트 변경 리뷰 및 DTO 영향 범위 표 정리 (doc/frontend_backend_alignment_report.md 갱신)
• F0-2 기능 토글(feature.approval_flow_v2) 주입 경로 설계 (lib/core/config/feature_flags.dart, Environment.initialize)
• F0-3 QA용 샘플 데이터(결재 단계 1~5단계, 회수/반려 케이스) 확보 후 test/fixtures/approvals/에 JSON 추가

1. 데이터 계층 업데이트

• F1-1 ApprovalRequestDto/ApprovalStepDto/ApprovalAuditDto 추가 및 기존 DTO 개편 (lib/features/approvals/data/dtos/)
• F1-2 ApprovalRepositoryRemote API 시그니처 확장: 제출/승인/반려/회수/재상신/템플릿 CRUD(/approval/*) 연동 (유즈케이스 연결은 F2 단계에서 후속 진행)
• F1-3 StockTransactionDto/StockTransactionInput에 결재 구성 필드 추가 (lib/features/inventory/data/dtos/)
• F1-4 ApiClient 요청 헬퍼에 새 엔드포인트 경로/쿼리 빌더 추가 (lib/core/network/api_client.dart)
• F1-5 lib/injection_container.dart 의존성 갱신: 신규 레포지터리/유즈케이스 바인딩

2. 도메인 & 유즈케이스

• F2-1 ApprovalFlowEntity 정의: 제출자/최종 승인자/단계/이력/상태 요약 포함 (lib/features/approvals/domain/entities/approval_flow.dart)
• F2-2 제출/승인/반려/회수/재상신 유즈케이스 구현 (lib/features/approvals/domain/usecases/submit_approval_use_case.dart 등)
• F2-3 템플릿 CRUD 유즈케이스 분리(SaveApprovalTemplate, ApplyApprovalTemplate)
• F2-4 Inventory 도메인에 결재 설정 전달용 값 객체 추가 (lib/features/inventory/*/domain/entities/create_*_request_input.dart)

3. 상태관리 & 컨트롤러

• F3-1 ApprovalRequestController 재구성: 단계 98개 제한, 중복 승인자 검사, 제출자/최종 승인자 바인딩
• F3-2 ApprovalTemplateController 확장: 템플릿 목록/저장/삭제/적용, 버전 체크
• F3-3 ApprovalHistoryController 개선: recall/resubmit 액션, 감사 로그 탭 분리
• F3-4 Inbound/Outbound/Rental 페이지 컨트롤러에서 결재 구성 상태 저장 및 제출 요청 병합
• F3-5 AuthGuard/Router에 결재 템플릿/이력 메뉴 권한 플래그 연결
• F3-6 임시저장/재개 플로우 구현: 결재 관리 목록에 draft 필터 추가, 세션 종료 후 초안 복구 UX 설계

4. UI 구성 요소

• F4-1 ApprovalStepConfigurator 모달/섹션 구현 (lib/features/approvals/request/presentation/widgets/)
• F4-2 ApprovalStepRow 컴포넌트: 순번, 승인자 검색, 역할, 삭제 버튼, 오류 표시
• F4-3 ApprovalTemplatePicker UI: 템플릿 선택/미리보기/적용/새로 저장 플로우
• F4-4 ApprovalTemplateManagerPage 리디자인: ShadTable 적용, 단계 요약 칼럼, CRUD 모달 연동
• F4-5 ApprovalHistoryPage 리디자인: 상태 타임라인, 감사 로그, 회수/재상신 버튼 상태 표시
• F4-6 입고/출고/대여 등록 폼에 Approval 섹션 삽입(lib/features/inventory/*/presentation/pages/)
• F4-7 SuperportDialog/ShadTable 커스텀 컬럼 추가: 승인자 아바타, 상태 뱃지, 메모 툴팁

5. 검증 & UX 개선

• F5-1 제출 폼 검증: 최종 승인자 필수, 제출자 자기 승인 금지, 중복 승인자 방지
• F5-2 단계 정렬/Drag & Drop 옵션 검토(필수 아님) 및 순서 변경 UX 결정
• F5-3 회수 가능 조건(첫 승인자 미행동) UI 표시 및 비활성화 처리
• F5-4 반려/회수/재상신 토스트/다이얼로그 메시지 표준화 (한국어)
• F5-5 감사 로그 뷰어에 필터(행위자, 액션, 기간) 추가
• F5-6 대시보드 pending approvals 카드가 새 상태/요약을 노출하도록 업데이트
• F5-7 결재 열람 권한/최종대기 노출 제한 UX: 상신자·기결재자만 상세 접근, 최종 승인 대기 전표 기본 목록 비노출 및 대기 섹션 분리

6. 테스트

• F6-1 단위 테스트: DTO 직렬화/역직렬화, 유즈케이스 권한 체크 (test/features/approvals/domain/)
• F6-2 위젯 테스트: 결재 구성 모달, 템플릿 적용, 회수/재상신 흐름 (test/features/approvals/presentation/)
• F6-3 통합(골든) 테스트: 입고 등록 → 결재 제출 → 승인자 전환 UI (integration_test/approvals_flow_test.dart)
• F6-4 모킹 대신 스테이징 API 더블 사용을 위한 HttpOverrides 정비(토글 기반)
  ↳ flutter_test_config.dart에서 USE_APPROVAL_STAGING_DOUBLE 토글 시 허용 호스트 기반 HttpOverrides를 주입하도록 구성
• F6-5 테스트 데이터 정비: 승인자 목록/권한/템플릿 샘플 업데이트
  ↳ test/helpers/fixture_loader.dart 추가, test/fixtures/approvals/*.json 및 ApprovalApproverCatalog를 스테이징 샘플과 동기화
• F6-6 권한/노출 테스트: 초안 복구, 비도달 승인자 403, 최종 승인 전 리스트 비노출 시나리오
  ↳ approval_controller_test.dart, approval_history_controller_test.dart, approval_form_initializer_test.dart 등에서 초안 복구/403 차단/목록 비노출 플로우 검증

7. 문서 & 개발자 경험

• F7-1 doc/IMPLEMENTATION_TASKS.md에 Approval Flow 섹션 추가 및 진행 상태 트래킹
• F7-2 doc/frontend_api_alignment_plan.md에 엔드포인트/계약 변화 반영
• F7-3 doc/frontend_backend_alignment_report.md에 프런트 측 후속 작업 연결
• F7-4 lib/widgets/ 컴포넌트 가이드에 결재 위젯 사용법 추가 (필요 시)
• F7-5 완료 시 notify.py 워크플로 실행 및 알림 (/Users/maximilian.j.sul/.codex/notify.py)

8. 배포 & 롤백

• F8-1 기능 토글 기본 비활성 상태로 머지 → 백엔드 배포/마이그레이션 완료 후 활성화
  ↳ assets/.env.production 기본값을 FEATURE_STOCK_TRANSITIONS_ENABLED=false로 유지하고, 운영 전환 시 토글 변경·검증 절차를 doc/frontend_api_alignment_plan.md에 정리했다.
• F8-2 스테이징 UAT 체크리스트: 제출/승인/반려/회수/재상신/템플릿 CRUD/대시보드 반영
  ↳ doc/qa/approval_flow_uat_checklist.md를 추가해 스테이징에서 검증해야 할 승인 플로우·예외 케이스를 항목화했다.
• F8-3 운영 배포 전 QA 결과 공유 및 위험 항목 점검, 롤백 시 토글 비활성화 절차 문서화
  ↳ 접근 거부 시 토스트/리다이렉트 흐름을 구현하고, 장애 시 플래그를 즉시 비활성화하는 롤백 가이드를 문서화했다.
• F8-4 배포 후 모니터링: 에러 토스트/네트워크 실패 레포트 수집, 사용자 피드백 채널 열람
  ↳ ApprovalController가 403 응답을 감지해 토스트 경고와 대시보드 리다이렉트를 수행하도록 했으며, 모니터링 관점에서 필요한 지표(토스트 발생/네트워크 실패)를 QA 체크리스트에 포함했다.

---

참고 링크

• 백엔드 계획: ../superport_api_v2/doc/approval_flow_backend_task_plan.md
• 스펙 문서: doc/stock_approval_system_spec_v4.md, doc/stock_approval_system_api_v4.md
• QA 체크리스트: doc/qa/approval_flow_uat_checklist.md (작성 대상)