superport_v2/doc/frontend_backend_alignment_report.md

프런트엔드/백엔드 정합성 점검 리포트 (2025-10-21)

개요

• 기준 문서: doc/backup/backend_change_requests.md와 최신 계약 문서(doc/stock_approval_system_api_v4.md)를 토대로 Flutter 프런트(superport_v2)와 Rust 백엔드(superport_api_v2) 구현을 재검증했다.
• 백엔드 팀이 전달한 최신 패치(로그인/트랜잭션, 결재 단계, 대시보드·보고서, 권한)와 cargo test 통과 결과를 반영해 실제 로그인 → 대시보드 → 재고/결재 → 보고서/권한 흐름을 다시 점검했다.

주요 정합성 결과

구분	내용	결과	후속 조치
1	대여/출고 expected_return_date 저장·조회	✅ 해결 (backend/src/domain/stock_transactions.rs:274, backend/src/adapters/repositories/stock_transactions.rs:808)	프런트 DTO·폼이 필드를 유지하는지 위젯 테스트로 확인
2	결재 단계 q·status_id 필터 및 status 응답	✅ 해결 (backend/src/domain/approval_steps.rs:31, backend/src/adapters/repositories/approval_steps.rs:162)	검색/필터 UI와 리스트 표시가 새 계약(status)을 반영하는지 시나리오 테스트 필요
3	결재 단계 요청/응답 내 상태 필드 정규화	✅ 해결 (요청 status_id, 응답 status)	프런트 DTO(lib/features/approvals/step/domain/entities/approval_step_input.dart:30)에서 레거시 step_status_id 제거 여부 확인
4	보고서 PDF 스트리밍·메타데이터 생성	✅ 해결 (backend/src/api/v1/reports.rs:94)	ReportingRepositoryRemote가 스트림·파일명 메타 처리하는지 합동 점검
5	그룹-메뉴 권한 path·is_deleted·include_deleted	✅ 해결 (backend/src/domain/group_menu_permissions.rs:149, backend/src/adapters/repositories/group_menu_permissions.rs:227)	DTO/필터·권한 편집 UI가 추가 필드로 회귀 없는지 테스트
6	대시보드 KPI delta 전일 대비 비율 계산	✅ 해결 (backend/src/adapters/repositories/dashboard.rs:61)	KPI 카드/차트가 백분율·부호 표시를 지원하는지 확인
7	사용자 요약(created_by, requester) 기본 노출 및 회귀 테스트	✅ 해결 (backend/src/domain/approval_templates.rs:34, backend/src/adapters/repositories/approval_templates.rs:100, backend/src/adapters/repositories/approvals.rs:878, backend/src/adapters/repositories/stock_transactions.rs:1173, backend/src/adapters/repositories/reports.rs:256)	프런트 DTO가 사번(employee_id)·이름을 모두 반영하는지, 리스트/리포트 표시가 정상인지 검증

아래 섹션에서 영역별 관찰 내용과 프런트엔드 후속 작업을 정리했다.

로그인 & 세션

• 변경 없음: 로그인/세션 API는 기존 계약과 동일하며(backend/src/api/v1/login.rs), 프런트 AuthSessionDto 매핑도 변동이 없다(lib/features/auth/data/dtos/auth_session_dto.dart:17).
• 체크포인트: 세션 만료 401 처리 시 백엔드 토큰 갱신 로직은 유지되므로, 프런트 재시도/로그아웃 UX를 QA 체크리스트에 유지한다.
• 추가 확인: POST /api/v1/auth/refresh 오류 메시지가 문서 규격(token expired, token revoked, invalid token)으로 일치하는지 스테이징 로그로 검증한다. 메시지 표준화가 미완료인 경우 Failure 매퍼에서 임시 매핑을 추가해야 한다.

대시보드

• KPI delta가 전일 대비 증감률(예: 0.125 → 12.5%)로 채워지며(backend/src/adapters/repositories/dashboard.rs:61), 프런트는 % 포맷과 부호를 고려해 렌더링해야 한다(lib/features/dashboard/presentation/widgets/dashboard_kpi_card.dart).
• step_summary 포맷이 "2단계 / 승인자"에서 "2단계 · 승인자"로 정규화됐다. 문자열을 그대로 노출하는 UI라면 디자인팀과 표시 규칙을 다시 합의한다.
• 추가 활동: 대시보드 테스트에서 delta != null 기준으로 동작하는 메트릭 뱃지/차트 회귀 여부를 확인한다.

재고·대여 트랜잭션

• expected_return_date가 생성/수정/조회 전 흐름에 포함된다(backend/src/domain/stock_transactions.rs:274, backend/src/adapters/repositories/stock_transactions.rs:808). 프런트 StockTransactionInput과 RentalPage는 이미 필드를 전송하므로, 저장 후 상세/목록에서 값이 노출되는지 UI 테스트를 추가하면 된다(lib/features/inventory/rental/presentation/pages/rental_page.dart:1651).
• 마이그레이션 migration/006_add_expected_return_date_to_stock_transactions.sql을 반드시 적용해야 하며, 로컬/스테이징 DB에 컬럼이 없으면 500 에러가 발생한다. DevOps와 일정 합의 후 diesel migration run을 실행하고 .env DB URL을 재확인한다.
• 추가 확인: 고객 정보(customers[].customer), 거래 라인 메모, 템플릿명 등 선택 필드가 null일 때 키가 빠지지 않는지 샘플 데이터를 확보해 양쪽 DTO 직렬화/역직렬화 테스트를 보강한다.

결재 단계

• 목록 API가 q·status_id 필터를 처리하고 응답에 transaction_no를 포함한다(backend/src/adapters/repositories/approval_steps.rs:176). 프런트 검색 바(lib/features/approvals/step/presentation/controllers/approval_step_controller.dart)가 두 파라미터를 전달하는지, 리스트에서 거래번호를 표시하는지 확인한다.
• 도메인이 status 구조체({ id, name, code })를 반환한다(backend/src/domain/approval_steps.rs:84). 프런트 DTO는 status_id 입력과 status 응답을 모두 지원해야 하므로, 레거시 필드 제거와 단위 테스트(test/features/approvals/step/domain/) 성공 여부를 점검한다.
• 컨트롤러/위젯 테스트: 필터링, 상태 변경, 거래번호 표시 흐름을 추가해 회귀를 방지한다.
• 추가 확인: histories[].action에 레거시 데이터가 들어오는 경우(id, name 누락) 프런트가 안전하게 폴백 문자열을 표시하는지, 백엔드는 해당 케이스를 데이터 정제 로직으로 보완할지 정한다.

보고서 (PDF)

• 백엔드가 PDF를 스트리밍으로 내려주고 파일명·Content-Length·ETag를 헤더에 포함한다(backend/src/api/v1/reports.rs:94). 프런트 ReportingRepositoryRemote는 StreamedResponse 처리를 유지하되, 새 메타데이터(report_name, generated_at)로 다운로드 UI를 업데이트한다(lib/features/reporting/presentation/controllers/reporting_controller.dart).
• 단위 테스트(backend/tests/api_reports_pdf.rs)가 계약을 고정하고 있으므로, 프런트에서도 PDF 다운로드 및 실패 경로(404/500 등)를 위젯 테스트에 반영한다.
• 추가 확인: PDF 다운로드 요청이 감사 로그에 기록되는지 스테이징에서 확인하고, 정책상 필요 시 프런트 다운로드 성공/실패 토스트에 감사 로그 연동 여부를 표시한다.

권한/문서

• 그룹-메뉴 권한 API가 include_deleted=true 시 삭제 항목을 함께 반환하고 각 항목에 path, is_deleted가 포함된다(backend/src/domain/group_menu_permissions.rs:149). 프런트 DTO(lib/features/masters/group_permission/data/dtos/group_permission_dto.dart:49)와 편집 UI가 새 필드를 사용하는지 확인한다.
• doc/stock_approval_system_api_v4.md가 갱신됐으므로, 프런트 문서는 tool/sync_stock_docs.sh로 재동기화한다.
• 추가 확인: 그룹-메뉴 배치 업데이트 API가 변경 이력을 남기는지 백엔드 로그로 점검하고, 프런트 편집 시 이력 누락에 대비한 사용자 안내를 준비한다.

공동 액션 아이템

구분	작업 내용	담당	상태	비고
DB	006_add_expected_return_date_to_stock_transactions.sql 적용 확인	백엔드	진행 예정	스테이징 DB 스키마 점검 후 공유
결재	단계 검색(q, status_id)·거래번호 노출 통합 테스트	프런트/백엔드	준비	계약 데이터 샘플 확보 필요
결재	histories.action 레거시 데이터 폴백 처리 협의	프런트/백엔드	준비	데이터 정제 vs UI 폴백 선택
보고서	Approvals/Transactions PDF 스트리밍 합동 점검	프런트/백엔드	준비	대용량 파일·감사 로그 확인
보고서	감사 로그 정책 준수 여부 재확인	백엔드	준비	정책 준수 결과 문서화
QA	flutter analyze, flutter test --coverage 회귀 실행 후 공유	프런트	준비	DTO/테스트 수정 후 notify.py 발송
QA	cargo test + 통합 시나리오 스크립트 재실행	백엔드	준비	보고서/결재 단계 회귀 포함

테스트 & 다음 단계

• 백엔드 cargo test 통과 보고가 공유됐지만, 프런트 QA 관점에서는 다음을 진행한다.
  • 새 마이그레이션(006_add_expected_return_date_to_stock_transactions.sql) 적용 → 스테이징 DB 반영 상태 확인.
  • 결재 단계 검색(q, status_id), 거래번호 노출, 보고서 PDF 다운로드를 프런트/백엔드 합동 점검.
  • flutter analyze, flutter test --coverage로 DTO·테스트 변경 이후 회귀 여부 확인.
• 모든 작업을 마치면 notify.py 워크플로를 통해 완료 알림을 발송한다.