백엔드 계약 문서 동기화하고 DTO 파서 정합성 확장

doc/backup/backend_change_requests.md

@@ -1,62 +1,73 @@
 # 백엔드 수정 요청서 (2025-10-16 갱신)
 
 ## 1. 배경
-- Flutter 프론트엔드(`superport_v2`)가 최신 백엔드(`superport_api_v2`)와 실연동을 준비하면서, 일부 엔드포인트가 미구현이거나 응답 스키마가 불완전해 화면 기능을 마무리하기 어렵다.
-- 프론트는 Clean Architecture 기반으로 이미 도메인/레포지토리 계층을 구성했으며, UI 스펙에 맞춰 API 계약을 준수해야 한다.
-- 본 문서는 백엔드 측 변경·추가 개발이 필요한 항목을 정리해 담당자에게 전달하기 위한 요청서이다.
+- Flutter 프런트엔드(`superport_v2`)와 최신 백엔드(`superport_api_v2`) 사이 계약을 점검한 결과, 다수의 엔드포인트가 미구현이거나 응답 스키마가 상이해 실사용 플로우를 마무리할 수 없다.
+- 프런트는 Clean Architecture 구조 및 DTO를 백엔드 스펙(v4)에 맞춰 구현한 상태이며, 실연동 전까지 계약 정합성을 확보해야 한다.
+- 본 문서는 백엔드 측 추가 개발/수정을 요청하기 위한 정리 문서이다.
 
 ## 2. 주요 이슈 요약
-- 보고서 다운로드 화면이 호출하는 `/api/v1/reports/**` 엔드포인트가 존재하지 않는다.
-- 결재 단계(`approval-steps`) 관련 API가 단계 CRUD 조회/생성 응답을 돌려주지 않아 프론트 단계 관리 화면을 구현할 수 없다.
-- 결재 단계 액션(`POST /approval-steps/{id}/actions`)과 승인 단계 일괄 등록/수정(`POST/PATCH /approvals/{id}/steps`)이 204만 반환해 프론트가 최신 결재 정보를 다시 받지 못한다.
-- 그룹-메뉴 권한 목록이 메뉴 `route_path` 정보를 제공하지 않아 권한 매니저가 라우트별 권한을 구성할 수 없다.
+- 로그인 및 대시보드 핵심 엔드포인트(`/api/v1/auth/**`, `/api/v1/dashboard/summary`)가 존재하지 않아 애플리케이션 초기 진입이 불가능하다.
+- 보고서 다운로드 화면이 호출하는 `/api/v1/reports/**` 엔드포인트가 미구현 상태다.
+- 결재·재고 API 응답 키가 프런트 DTO와 불일치하여 승인 상태, 요청자, 제품/벤더 정보 등이 전부 기본값으로 표시되며, 단계/상태 전환 이후 최신 데이터를 확보할 수 없다.
+- 결재 단계(`approval-steps`) API가 단계 CRUD/액션 수행 후 적절한 본문을 반환하지 않고, 목록 필터(승인자·상태·검색)도 지원하지 않는다.
+- 그룹-메뉴 권한 API가 라우팅 정보를 제공하지 않고, 삭제 항목 조회 파라미터가 프런트와 불일치해 권한 동기화가 깨진다.
 
 ## 3. 상세 요청
 
-### 3.1 보고서 Export API 구현
-- 엔드포인트:
+### 3.1 로그인/세션 및 대시보드 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)와 메시지 정책을 문서화한다.
+
+### 3.2 보고서 Export API 구현
+- 엔드포인트
   - `GET /api/v1/reports/transactions/export`
   - `GET /api/v1/reports/approvals/export`
-- 요구 사항:
-  - 쿼리 파라미터: 
-    - 트랜잭션: `from`, `to`(yyyy-MM-dd), `format`(xlsx|pdf), `transaction_status_id`, `approval_status_id`, `requested_by_id`
-    - 결재: `from`, `to`(ISO 8601), `format`(xlsx|pdf), `transaction_status_id`, `approval_status_id`, `requested_by_id`
-  - 응답:
-    - 파일 다운로드(바이트 스트림) 또는 `data.download_url`, `data.filename`, `data.mime_type`, `data.expires_at`을 포함한 JSON.
-  - 인증/권한 정책 확정 후 문서화.
+- 요구 사항
+  - 공통 쿼리: `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`
+  - 권한/감사 로그 정책을 명확히 할 것.
 
-### 3.2 결재 단계/행위 API 정합성 보강
-- `GET /api/v1/approval-steps` 및 단건/생성/수정/삭제/복구 API 구현이 필요하다. (프론트 `ApprovalStepRepository`가 CRUD 전체를 호출)
-- `POST /api/v1/approval-steps/{id}/actions`는 204 대신 갱신된 결재 본문 혹은 최소한 단계와 상태 변화를 반환해야 한다.
-- `POST|PATCH /api/v1/approvals/{id}/steps` 역시 204가 아닌
-  - 변경된 `approval` 요약, 혹은
-  - 새로 구성된 단계 리스트
-  를 포함한 JSON 응답을 제공해 프론트가 재조회 없이 상태를 갱신할 수 있도록 해 달라.
-- 액션/단계 요청 본문은 `stock_approval_system_api_v4.md` 스펙과 동일하게 유지.
+### 3.3 결재/재고 응답 스키마 정합성
+- 결재 요약 응답의 필드명을 다음과 같이 정렬:
+  - `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`을 포함.
 
-### 3.3 그룹-메뉴 권한 응답 확장
-- `GET /api/v1/group-menu-permissions` 및 단건 응답의 `menu` 객체에 다음 필드를 추가:
-  - `route_path` (launched 메뉴일 경우 실제 라우트 경로)
-  - 필요 시 `menu_code` 그대로 유지.
-- 선택적으로 `include=group` 파라미터를 지원해 그룹 요약을 함께 반환하면 Front 권한 동기화 시 재조회가 줄어든다.
+### 3.4 결재 단계/행위 API 정합성
+- `GET /api/v1/approval-steps`에 다음 필터를 지원:
+  - `approver_id`, `approval_id`, `status_id`(또는 `step_status_id`), `q`(결재번호/승인자 키워드)
+- 단계/액션/일괄 배정 API는 204 대신 갱신된 결재 전체(`data.approval`) 또는 단계 리스트를 JSON으로 반환.
+- 응답에 단계가 속한 템플릿명(`approval.template_name`)을 포함.
 
-### 3.4 응답/에러 문서화
-- 위 변경 사항이 반영되면 `stock_approval_system_api_v4.md`를 업데이트하고, 각 엔드포인트 예제 응답을 최신 상태로 반영한다.
-- 회귀 테스트(`cargo test` + 통합 시나리오 스크립트)가 변경된 계약을 검증하도록 보강한다.
+### 3.5 그룹-메뉴 권한 응답 확장
+- `GET /api/v1/group-menu-permissions` 및 단건 응답의 `menu` 객체에 `route_path`를 추가.
+- 삭제 항목 조회 시 `deleted=true` 파라미터 혹은 `include_deleted=true` 별칭을 허용하고, 응답에 `is_deleted`를 포함.
+- `include=group` 파라미터를 공식 문서화하여 그룹 정보를 함께 반환.
 
-### 3.5 결재 생성/수정 API 정합성
-- `POST /api/v1/approvals`가 다음 요청 바디를 수용하도록 구현 필요:
-  - 필수: `transaction_id`, `approval_no`, `approval_status_id`, `requested_by_id`
-  - 선택: `note`
-  - 응답에는 갱신된 결재 요약(`data.approval`)과 현재 단계/상태 정보가 포함돼야 프론트가 즉시 리스트를 재사용할 수 있다.
-- `PATCH /api/v1/approvals/{id}`는 본문에 `id`를 요구하고 `approval_status_id`, `note` 변경을 허용해야 한다. 응답은 최신 결재 정보를 반환해 상세 패널을 재조회 없이 갱신할 수 있도록 한다.
-- 결재번호(`approval_no`) 중복/포맷 검증과 기본 상태(예: 대기) 자동 할당 규칙을 API 스펙에 명시해 달라.
+### 3.6 결재 생성/수정 응답 보강
+- `POST /api/v1/approvals`/`PATCH /api/v1/approvals/{id}` 응답에 최신 결재 요약(`data.approval`)과 단계 리스트(`data.approval.steps`)를 포함.
+- `approval_status_id`가 요청에 없을 경우 기본 대기 상태를 할당하는 규칙을 문서화하고, 결재번호 중복/포맷 검증 로직을 명확히 한다.
+
+### 3.7 응답/에러 문서화 및 테스트
+- `stock_approval_system_api_v4.md`에 변경된 요청/응답 예시를 반영.
+- 회귀 테스트(`cargo test`, 통합 시나리오 스크립트)에 신규 계약을 검증하는 케이스를 추가.
 
 ## 4. 수용 기준
-- 상기 엔드포인트가 모두 구현되고, 요청/응답이 문서와 일치해야 한다.
-- 레거시 응답(204)에서 JSON 반환으로 변경될 경우, 클라이언트가 기대하는 키(`data.approval`, `data.steps` 등)를 포함해야 한다.
-- `cargo fmt`, `cargo check`, `cargo test` 및 기존 CI 파이프라인이 통과한다.
+- 상기 엔드포인트 및 스키마 변경이 구현되고, 요청/응답이 문서와 일치해야 한다.
+- 기존 204 응답은 JSON 응답으로 교체되고, 키(`data.approval`, `data.transaction` 등)가 프런트 기대와 동일해야 한다.
+- `cargo fmt`, `cargo check`, `cargo test` 및 CI 파이프라인이 통과한다.
 
 ## 5. 후속 조치
-- 백엔드 담당자가 일정/우선순위를 산출해 프론트 팀과 공유.
-- 구현 완료 후 샌드박스 환경에서 API 계약 검증 → 프론트엔드 실연동 착수.
+- 백엔드 담당자가 개발 일정·우선순위를 산출해 프런트 팀과 공유.
+- 구현 완료 후 샌드박스 환경에서 계약 검증 → 프런트엔드 실연동 검증 착수.