53 lines
3.7 KiB
Markdown
53 lines
3.7 KiB
Markdown
# 백엔드 수정 요청서 (2024-08-XX 갱신)
|
|
|
|
## 1. 배경
|
|
- Flutter 프론트엔드(`superport_v2`)가 최신 백엔드(`superport_api_v2`)와 실연동을 준비하면서, 일부 엔드포인트가 미구현이거나 응답 스키마가 불완전해 화면 기능을 마무리하기 어렵다.
|
|
- 프론트는 Clean Architecture 기반으로 이미 도메인/레포지토리 계층을 구성했으며, UI 스펙에 맞춰 API 계약을 준수해야 한다.
|
|
- 본 문서는 백엔드 측 변경·추가 개발이 필요한 항목을 정리해 담당자에게 전달하기 위한 요청서이다.
|
|
|
|
## 2. 주요 이슈 요약
|
|
- 보고서 다운로드 화면이 호출하는 `/api/v1/reports/**` 엔드포인트가 존재하지 않는다.
|
|
- 결재 단계(`approval-steps`) 관련 API가 단계 CRUD 조회/생성 응답을 돌려주지 않아 프론트 단계 관리 화면을 구현할 수 없다.
|
|
- 결재 단계 액션(`POST /approval-steps/{id}/actions`)과 승인 단계 일괄 등록/수정(`POST/PATCH /approvals/{id}/steps`)이 204만 반환해 프론트가 최신 결재 정보를 다시 받지 못한다.
|
|
- 그룹-메뉴 권한 목록이 메뉴 `route_path` 정보를 제공하지 않아 권한 매니저가 라우트별 권한을 구성할 수 없다.
|
|
|
|
## 3. 상세 요청
|
|
|
|
### 3.1 보고서 Export API 구현
|
|
- 엔드포인트:
|
|
- `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` 등 프론트에서 사용하는 필터 수용.
|
|
- 응답:
|
|
- 파일 다운로드(바이트 스트림) 또는 `data.download_url`, `data.filename`, `data.mime_type`, `data.expires_at`을 포함한 JSON.
|
|
- 인증/권한 정책 확정 후 문서화.
|
|
|
|
### 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 그룹-메뉴 권한 응답 확장
|
|
- `GET /api/v1/group-menu-permissions` 및 단건 응답의 `menu` 객체에 다음 필드를 추가:
|
|
- `route_path` (launched 메뉴일 경우 실제 라우트 경로)
|
|
- 필요 시 `menu_code` 그대로 유지.
|
|
- 선택적으로 `include=group` 파라미터를 지원해 그룹 요약을 함께 반환하면 Front 권한 동기화 시 재조회가 줄어든다.
|
|
|
|
### 3.4 응답/에러 문서화
|
|
- 위 변경 사항이 반영되면 `stock_approval_system_api_v4.md`를 업데이트하고, 각 엔드포인트 예제 응답을 최신 상태로 반영한다.
|
|
- 회귀 테스트(`cargo test` + 통합 시나리오 스크립트)가 변경된 계약을 검증하도록 보강한다.
|
|
|
|
## 4. 수용 기준
|
|
- 상기 엔드포인트가 모두 구현되고, 요청/응답이 문서와 일치해야 한다.
|
|
- 레거시 응답(204)에서 JSON 반환으로 변경될 경우, 클라이언트가 기대하는 키(`data.approval`, `data.steps` 등)를 포함해야 한다.
|
|
- `cargo fmt`, `cargo check`, `cargo test` 및 기존 CI 파이프라인이 통과한다.
|
|
|
|
## 5. 후속 조치
|
|
- 백엔드 담당자가 일정/우선순위를 산출해 프론트 팀과 공유.
|
|
- 구현 완료 후 샌드박스 환경에서 API 계약 검증 → 프론트엔드 실연동 착수.
|