superport_v2/doc/approval_flow_alignment_review.md

Approval Flow 정합성 점검 (2025-10-31)

최신 검증 요약

• ✅ 7건의 과거 불일치 항목을 모두 해결했고 프런트/백엔드 구현이 v4 스펙과 일치한다.
• ✅ 프런트 최신 코드 기준 include·필터·토글·초안 저장 로직이 반영되었으며, 대응 단위·위젯·통합 테스트가 성공한다.
• ✅ 백엔드 스펙(doc/stock_approval_system_api_v4.md)과 정합성 문서(doc/frontend_backend_alignment_report.md)를 동기화해 참조 경로를 최신화했다.
• 🔎 검증 커맨드: flutter analyze, flutter test, cargo test (2025-10-31 실행)

검증 범위 및 방법

• 리포지토리: superport_v2(Flutter) + 문서화된 백엔드 리포(superport_api_v2) 기준.
• 참조 문서: doc/stock_approval_system_api_v4.md, doc/ApprovalFlow_System_Integration_and_ChangePlan.md, 백엔드 노출 포인트 문서.
• 코드 확인: 주요 레포지토리/컨트롤러/UI 위젯/테스트 파일을 라인 단위로 점검하여 실제 include·필터·토글 동작을 검증.

세부 항목

1. 결재 상세 조회 시 전표 동기화 정보

상태: ✅ 해결 (2025-10-31)

• 프런트: ApprovalRepositoryRemote.fetchDetail 기본 include가 transaction과 requested_by를 항상 전달한다 (lib/features/approvals/data/repositories/approval_repository_remote.dart:73). 회수/재상신 UI는 재조회 후 transactionUpdatedAt 값이 없으면 사용자에게 재시도를 안내하며 동작을 중단한다 (lib/features/approvals/history/presentation/pages/approval_history_page.dart:1153).
• 백엔드: 상세 응답에 전표 수정 시각이 포함되도록 통합 테스트가 존재하며(backend/tests/api/approvals_flow.rs), 스펙도 동일 요구사항을 명시한다.
• 테스트: 회수/재상신 패널이 최신 전표 타임스탬프를 요구하는 위젯 테스트가 존재한다 (test/features/approvals/history/presentation/widgets/approval_action_panel_test.dart:307).

2. 결재 목록 “전체 상태” include_pending 처리

상태: ✅ 해결 (2025-10-31)

• 프런트: 목록 조회 기본 include에 requested_by, transaction을 포함하고 ApprovalStatusFilter.all일 때 include_pending=true를 쿼리에 전달한다 (lib/features/approvals/data/repositories/approval_repository_remote.dart:38, lib/features/approvals/presentation/controllers/approval_controller.dart:194).
• 테스트: 컨트롤러 단위 테스트가 include_pending 전달 여부와 상태 코드 매핑을 검증한다 (test/features/approvals/presentation/controllers/approval_controller_test.dart:143).
• 문서: 스펙에서 include_pending 규칙을 보강하고 프런트 문서에 반영했다 (doc/stock_approval_system_api_v4.md:1231).

3. 결재 목록 상신자·전표 요약 누락

상태: ✅ 해결 (2025-10-31)

• 프런트: 목록 include 기본값이 requested_by,transaction으로 고정되어 상신자·전표 요약을 항상 수신한다 (lib/features/approvals/data/repositories/approval_repository_remote.dart:38). DTO 파서도 해당 필드를 안전하게 역직렬화한다 (lib/features/approvals/data/dtos/approval_dto.dart:100).
• 테스트: 목록 API 쿼리 검증 테스트가 include 문자열을 점검한다 (test/features/approvals/data/approval_repository_remote_test.dart:42).
• 문서: 정합성 리포트의 Approval Flow 항목이 완료로 업데이트돼 동일 사실을 기록한다 (doc/frontend_backend_alignment_report.md).

4. 서버 임시저장(Approval Draft) 연동

상태: ✅ 해결 (2025-10-31)

• 프런트: /approval-drafts 경로와 DTO/UseCase가 구현되어 초안 저장·복원 흐름을 제공한다 (lib/features/approvals/data/repositories/approval_draft_repository_remote.dart:18, lib/features/approvals/domain/usecases/save_approval_draft_use_case.dart:8). 인벤토리 컨트롤러는 초안을 자동 저장하며 세션 키 기반으로 복원한다 (lib/features/inventory/inbound/presentation/controllers/inbound_controller.dart:256).
• 테스트: 초안 저장소 단위 테스트가 요청 파라미터를 검증한다 (test/features/approvals/data/approval_draft_repository_remote_test.dart:28).
• 문서: 스펙과 통합 계획 문서가 /approval-drafts 흐름을 포함하도록 갱신됐다 (doc/stock_approval_system_api_v4.md:1545).

5. 결재 이력 검색/행위 필터 적용

상태: ✅ 해결 (2025-10-31)

• 프런트: ApprovalHistoryController가 ApprovalAction 카탈로그를 캐싱하고 코드→ID 매핑을 수행해 쿼리를 생성한다 (lib/features/approvals/history/presentation/controllers/approval_history_controller.dart:162). 원격 저장소는 approval_action_id, action_from, action_to를 포함한 쿼리를 전송한다 (lib/features/approvals/history/data/repositories/approval_history_repository_remote.dart:37).
• 테스트: 컨트롤러 테스트가 필터 적용 시 매핑된 ID를 검증한다 (test/features/approvals/history/presentation/controllers/approval_history_controller_test.dart:150).
• 문서: API 스펙에 동일 필터 사용법과 q 미지원 사실을 명시했다 (doc/stock_approval_system_api_v4.md:1545).

6. 결재 이력 목록 include 누락

상태: ✅ 해결 (2025-10-31)

• 프런트: _defaultInclude에 결재·단계·행위·상태 요약을 선언해 항상 함께 요청한다 (lib/features/approvals/history/data/repositories/approval_history_repository_remote.dart:17).
• 백엔드: 기본 include 확장이 반영되었다는 문서 업데이트가 확인된다 (superport_api_v2/backend/src/domain/approval_histories.rs, 문서 기준).
• 테스트: 위젯 테스트가 결재번호와 단계가 렌더링되는지 확인한다 (test/features/approvals/history/presentation/pages/approval_history_page_test.dart:266).

7. Approval Flow V2 기능 토글 키 불일치

상태: ✅ 해결 (2025-10-31)

• 프런트: FeatureFlags.initialize가 FEATURE_APPROVAL_FLOW_V2, FEATURES_APPROVAL_FLOW_V2, feature.approval_flow_v2, features.approval_flow_v2를 모두 인식한다 (lib/core/config/feature_flags.dart:24).
• 백엔드: 설정 로더와 .env.example이 동일 alias를 허용하도록 정리되었다는 문서 기록이 있다 (superport_api_v2/backend/src/config/mod.rs, .env.example).
• 테스트/빌드: flutter analyze, flutter test, cargo test가 통과했다.

후속 관리 제안

• 백엔드 배포 절차(B9-1~B9-4)와 프런트 QA 일정이 남아 있으므로 운영 이전에 순차 진행한다.
• 새 스펙 변경 시 tool/sync_stock_docs.sh --check로 문서 차이를 확인하고 본 문서를 함께 갱신한다.
• Approval Flow 관련 통합 테스트(integration_test/approvals_flow_test.dart)를 주기적으로 실행해 스펙 회귀를 감시한다.
• 기능 토글 변경 시 운영 알림 문서(superport_api_v2/doc/approval_flow_release_notification.md)와 이 문서를 동시에 업데이트한다.