# Approval Flow 프런트엔드 작업 계획

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

---

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

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

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

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

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

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

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

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

## 8. 배포 & 롤백
- [x] **F8-1** 기능 토글 기본 비활성 상태로 머지 → 백엔드 배포/마이그레이션 완료 후 활성화  
  ↳ `assets/.env.production` 기본값을 `FEATURE_STOCK_TRANSITIONS_ENABLED=false`로 유지하고, 운영 전환 시 토글 변경·검증 절차를 `doc/frontend_api_alignment_plan.md`에 정리했다.
- [x] **F8-2** 스테이징 UAT 체크리스트: 제출/승인/반려/회수/재상신/템플릿 CRUD/대시보드 반영  
  ↳ `doc/qa/approval_flow_uat_checklist.md`를 추가해 스테이징에서 검증해야 할 승인 플로우·예외 케이스를 항목화했다.
- [x] **F8-3** 운영 배포 전 QA 결과 공유 및 위험 항목 점검, 롤백 시 토글 비활성화 절차 문서화  
  ↳ 접근 거부 시 토스트/리다이렉트 흐름을 구현하고, 장애 시 플래그를 즉시 비활성화하는 롤백 가이드를 문서화했다.
- [x] **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` (작성 대상)