superport_v2/doc/backup/backend_change_requests.md

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

1. 배경

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

2. 주요 이슈 요약

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

3. 상세 요청

3.1 로그인/세션 및 대시보드 API 구현

• 엔드포인트
  • POST /api/v1/auth/login: identifier, password, remember_me(bool) 입력을 받아 { "data": { "access_token", "refresh_token", "expires_at", "user", "permissions" } } 구조를 반환해야 한다. user 객체는 { id, name, employee_no, email, primary_group { id, name } } 필드를 포함하고, permissions는 resource와 actions[](소문자 문자열)로 구성된다.
  • POST /api/v1/auth/refresh: refresh_token으로 세션을 갱신하며 응답 스키마는 로그인과 동일하다.
  • GET /api/v1/dashboard/summary: { "data": { "generated_at", "kpis": [], "recent_transactions": [], "pending_approvals": [] } } 형태로 내려 KPI 카드, 최근 전표, 결재 대기 목록을 채울 수 있어야 한다.
• 요구 사항
  • kpis[] 항목은 { key, label, value, trend_label, delta } 필드를 제공해 프런트 차트 증감률을 계산할 수 있도록 한다.
  • recent_transactions[]는 { transaction_no, transaction_date, transaction_type, status_name, created_by } 문자열 필드로 구성한다.
  • pending_approvals[]는 { approval_no, title, step_summary, requested_at }을 포함하며 requested_at은 ISO8601 UTC 문자열로 반환한다.
  • 로그인 실패 시 invalid credentials, 비활성 계정 접근 시 account is inactive, 갱신 토큰 만료는 token expired, 재사용·서명 오류는 invalid token 메시지를 반환해 프런트 알림 문구와 동일하게 맞춘다.
  • 인증 실패(401), 세션 만료·권한 거부(403) 시 { "error": { "code": <http-status>, "message": "...", "details": [...] } } 규격을 사용하고, 만료/재사용 토큰별 메시지를 문서화한다.

3.2 보고서 Export API 구현

• 엔드포인트
  • 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.
  • 트랜잭션 보고서 from·to 값은 yyyy-MM-dd 형식, 결재 보고서는 ISO8601 UTC 타임스탬프를 지원한다.
  • 응답은 기본적으로 파일 스트림(Content-Type은 선택한 포맷의 MIME, Content-Disposition: attachment; filename="<name>")이며, 스토리지 연계 시 { "data": { "download_url", "filename", "mime_type", "expires_at" } } 메타데이터로 대체할 수 있다.
  • format=pdf 요청도 정상 처리하고, 지원 불가 시 명확한 4xx 코드·메시지를 반환하도록 문서화한다.
  • 모든 다운로드 요청에 대해 접근 권한·감사 로그 정책을 명시한다.

3.3 결재/재고 응답 스키마 정합성

• 결재 목록·단건 응답은 프런트 도메인 모델과 동일한 키를 사용한다.
  • 단건 응답은 { "data": { ... } } 혹은 { "data": { "approval": { ... } } } 구조를 유지하고, approval_no, transaction_no, status { id, name, color }, requester { id, employee_no, name }, current_step { id, step_order, status { id, name, is_blocking_next, is_terminal }, approver { id, employee_no, name }, assigned_at, decided_at, note }, steps[], histories[], created_at, updated_at을 포함한다.
  • 모든 단계·이력 항목은 status 키로 정규화하고(step_status 금지), histories[]에는 action { id, name }, from_status, to_status, approver, action_at, note를 내려준다.
  • approval 객체에는 필요 시 transaction { id, transaction_no }, template_name 등을 함께 포함해 단계 목록에서도 동일 데이터를 재사용할 수 있도록 한다.
• 재고 트랜잭션 응답은 중첩 객체 구조를 보장한다.
  • 헤더: transaction_type { id, name }, transaction_status { id, name }, warehouse { id, warehouse_code, warehouse_name, zipcode { ... } }, created_by { id, employee_no, employee_name }, expected_return_date.
  • 라인: lines[].product { id, product_code, product_name, vendor { id, vendor_name }, uom { id, uom_name } }, quantity, unit_price, note.
  • 고객: customers[].customer { id, customer_code, customer_name }, note.
  • 결재 요약: approval { id, approval_no, status { id, name, is_blocking_next } }.
  • quantity, unit_price는 BigDecimal 직렬화 그대로 전달하되 null은 키를 생략하지 말 것(프런트 DTO가 숫자·문자열 모두를 파싱한다).
  • warehouse.zipcode는 최소 zipcode, road_name을 포함하고 추가 주소 필드가 있으면 그대로 노출한다.
• 상태 전환(Submit/Approve/Reject/Cancel/Complete) 응답은 최신 data.transaction 전체 또는 최소한 data.transaction_status, data.updated_at, data.approval을 포함해 UI가 즉시 갱신되도록 한다.

3.4 결재 단계/행위 API 정합성

• GET /api/v1/approval-steps는 approver_id, approval_id, status_id(또는 step_status_id), q(결재번호·승인자 키워드)를 지원하고, 항상 include=approval,approver,status 형태의 확장을 처리한다. 응답 항목에는 approval { id, approval_no, transaction_no, template_name }이 포함되어야 한다.
• 단계 생성·수정·복구 응답은 { "data": { ... } } 형태로 단계 요약을 반환하고, 단계 행위·일괄 배정 응답은 최신 결재 데이터를 data.approval 또는 data.approval.steps/data.histories에 담아 돌려준다.
• 모든 단계·행위 응답에서 단계 상태 키는 status로 통일하고, step_status_id는 요청/응답에서 보조 필드로만 유지한다.

3.5 그룹-메뉴 권한 응답 확장

• GET /api/v1/group-menu-permissions 및 단건 응답의 menu 객체에 route_path(가능하면 path 보조 필드 포함)를 항상 채운다.
• deleted=true(또는 include_deleted=true) 파라미터를 허용해 소프트 삭제 항목을 조회할 수 있게 하고, 응답 항목에 is_deleted를 노출한다.
• include=group,menu 확장을 공식화해 그룹/메뉴 요약을 한 번에 받을 수 있도록 한다.

3.6 결재 생성/수정 응답 보강

• POST /api/v1/approvals/PATCH /api/v1/approvals/{id} 응답은 { "data": { "approval": { ... } } } 형태로 최신 결재 요약과 steps[], 필요 시 histories[]를 포함해야 한다.
• approval_status_id가 생략되면 자동으로 기본 대기 상태를 설정하는 규칙을 명시하고, approval_no 포맷·중복 검증 실패 시 상세 에러 메시지를 반환한다.

3.7 응답/에러 문서화 및 테스트

• stock_approval_system_api_v4.md에 변경된 요청/응답 예시를 모두 반영하고, 인증/대시보드/결재 단계/보고서 섹션을 최신 상태로 유지한다.
• 회귀 테스트(cargo test, 통합 시나리오 스크립트)에 신규 계약을 검증하는 케이스를 추가한다.

4. 수용 기준

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

5. 후속 조치

• 백엔드 담당자가 개발 일정·우선순위를 산출해 프런트 팀과 공유.
• 구현 완료 후 샌드박스 환경에서 계약 검증 → 프런트엔드 실연동 검증 착수.