백엔드 수정 요청서 (2025-10-16 갱신)

1. 배경

Flutter 프런트엔드(superport_v2)와 최신 백엔드(superport_api_v2) 사이 계약을 점검한 결과, 다수의 엔드포인트가 미구현이거나 응답 스키마가 상이해 실사용 플로우를 마무리할 수 없다.
프런트는 Clean Architecture 구조 및 DTO를 백엔드 스펙(v4)에 맞춰 구현한 상태이며, 실연동 전까지 계약 정합성을 확보해야 한다.
본 문서는 백엔드 측 추가 개발/수정을 요청하기 위한 정리 문서이다.

로그인 및 대시보드 핵심 엔드포인트(/api/v1/auth/**, /api/v1/dashboard/summary)가 존재하지 않아 애플리케이션 초기 진입이 불가능하다.
보고서 다운로드 화면이 호출하는 /api/v1/reports/** 엔드포인트가 미구현 상태다.
결재·재고 API 응답 키가 프런트 DTO와 불일치하여 승인 상태, 요청자, 제품/벤더 정보 등이 전부 기본값으로 표시되며, 단계/상태 전환 이후 최신 데이터를 확보할 수 없다.
결재 단계(approval-steps) API가 단계 CRUD/액션 수행 후 적절한 본문을 반환하지 않고, 목록 필터(승인자·상태·검색)도 지원하지 않는다.
그룹-메뉴 권한 API가 라우팅 정보를 제공하지 않고, 삭제 항목 조회 파라미터가 프런트와 불일치해 권한 동기화가 깨진다.

엔드포인트
- POST /api/v1/auth/login: identifier, password, remember_me를 받아 Access/Refresh 토큰, 만료 시각, 사용자 요약(employee)을 반환.
- POST /api/v1/auth/refresh: refresh_token으로 토큰을 갱신.
- GET /api/v1/dashboard/summary: KPI(inbound/outbound/pending_approvals/customer_inquiries), 결재 대기 목록, 기간별 전표 요약, generated_at을 포함한 JSON 반환.
요구 사항
- 응답 포맷은 { "data": { ... } } 컨벤션을 따른다.
- 인증 실패/세션 만료 케이스별 HTTP 코드(401/403)와 메시지 정책을 문서화한다.

엔드포인트
- GET /api/v1/reports/transactions/export
- GET /api/v1/reports/approvals/export
요구 사항
- 공통 쿼리: from, to, format(xlsx|pdf), transaction_status_id, approval_status_id, requested_by_id
- 응답: 파일 스트림 또는 data.download_url, data.filename, data.mime_type, data.expires_at
- 권한/감사 로그 정책을 명확히 할 것.

결재 요약 응답의 필드명을 다음과 같이 정렬:
- approval_status → status
- requested_by → requester
- current_step.step_status → current_step.status
- histories[].approval_action_id 대신 histories[].action { id, name }을 포함
재고 트랜잭션 응답은 헤더/라인/고객 정보를 도메인 모델 구조에 맞게 중첩 객체로 내려준다.
- 헤더: transaction_type { id, name }, transaction_status { id, name }, warehouse { id, warehouse_code, warehouse_name }, created_by { id, employee_no, employee_name }
- 라인: product { id, product_code, product_name, vendor { id, vendor_name }, uom { id, uom_name } }
- 고객: customer { id, customer_code, customer_name }
상태 전환(Submit/Approve/Reject/Cancel/Complete) 응답에 최신 data.transaction 혹은 최소한 data.transaction_status와 data.updated_at을 포함.

GET /api/v1/approval-steps에 다음 필터를 지원:
- approver_id, approval_id, status_id(또는 step_status_id), q(결재번호/승인자 키워드)
단계/액션/일괄 배정 API는 204 대신 갱신된 결재 전체(data.approval) 또는 단계 리스트를 JSON으로 반환.
응답에 단계가 속한 템플릿명(approval.template_name)을 포함.

GET /api/v1/group-menu-permissions 및 단건 응답의 menu 객체에 route_path를 추가.
삭제 항목 조회 시 deleted=true 파라미터 혹은 include_deleted=true 별칭을 허용하고, 응답에 is_deleted를 포함.
include=group 파라미터를 공식 문서화하여 그룹 정보를 함께 반환.

POST /api/v1/approvals/PATCH /api/v1/approvals/{id} 응답에 최신 결재 요약(data.approval)과 단계 리스트(data.approval.steps)를 포함.
approval_status_id가 요청에 없을 경우 기본 대기 상태를 할당하는 규칙을 문서화하고, 결재번호 중복/포맷 검증 로직을 명확히 한다.

상기 엔드포인트 및 스키마 변경이 구현되고, 요청/응답이 문서와 일치해야 한다.
기존 204 응답은 JSON 응답으로 교체되고, 키(data.approval, data.transaction 등)가 프런트 기대와 동일해야 한다.
cargo fmt, cargo check, cargo test 및 CI 파이프라인이 통과한다.