결재 API 계약 보완 및 테스트 정리

doc/backup/backend_change_requests.md

@@ -1,4 +1,4 @@
-# 백엔드 수정 요청서 (2024-08-XX 갱신)
+# 백엔드 수정 요청서 (2025-10-16 갱신)
 
 ## 1. 배경
 - Flutter 프론트엔드(`superport_v2`)가 최신 백엔드(`superport_api_v2`)와 실연동을 준비하면서, 일부 엔드포인트가 미구현이거나 응답 스키마가 불완전해 화면 기능을 마무리하기 어렵다.
@@ -18,7 +18,9 @@
   - `GET /api/v1/reports/transactions/export`
   - `GET /api/v1/reports/approvals/export`
 - 요구 사항:
-  - 쿼리 파라미터: `from`, `to`(ISO 8601), `format`(xlsx|pdf), `type_id`, `status_id`, `warehouse_id` 등 프론트에서 사용하는 필터 수용.
+  - 쿼리 파라미터: 
+    - 트랜잭션: `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.
   - 인증/권한 정책 확정 후 문서화.
@@ -42,6 +44,14 @@
 - 위 변경 사항이 반영되면 `stock_approval_system_api_v4.md`를 업데이트하고, 각 엔드포인트 예제 응답을 최신 상태로 반영한다.
 - 회귀 테스트(`cargo test` + 통합 시나리오 스크립트)가 변경된 계약을 검증하도록 보강한다.
 
+### 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 스펙에 명시해 달라.
+
 ## 4. 수용 기준
 - 상기 엔드포인트가 모두 구현되고, 요청/응답이 문서와 일치해야 한다.
 - 레거시 응답(204)에서 JSON 반환으로 변경될 경우, 클라이언트가 기대하는 키(`data.approval`, `data.steps` 등)를 포함해야 한다.