74 lines
5.4 KiB
Markdown
74 lines
5.4 KiB
Markdown
# 백엔드 수정 요청서 (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`를 받아 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`, `format(xlsx|pdf)`, `transaction_status_id`, `approval_status_id`, `requested_by_id`
|
|
- 응답: 파일 스트림 또는 `data.download_url`, `data.filename`, `data.mime_type`, `data.expires_at`
|
|
- 권한/감사 로그 정책을 명확히 할 것.
|
|
|
|
### 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.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.5 그룹-메뉴 권한 응답 확장
|
|
- `GET /api/v1/group-menu-permissions` 및 단건 응답의 `menu` 객체에 `route_path`를 추가.
|
|
- 삭제 항목 조회 시 `deleted=true` 파라미터 혹은 `include_deleted=true` 별칭을 허용하고, 응답에 `is_deleted`를 포함.
|
|
- `include=group` 파라미터를 공식 문서화하여 그룹 정보를 함께 반환.
|
|
|
|
### 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.transaction` 등)가 프런트 기대와 동일해야 한다.
|
|
- `cargo fmt`, `cargo check`, `cargo test` 및 CI 파이프라인이 통과한다.
|
|
|
|
## 5. 후속 조치
|
|
- 백엔드 담당자가 개발 일정·우선순위를 산출해 프런트 팀과 공유.
|
|
- 구현 완료 후 샌드박스 환경에서 계약 검증 → 프런트엔드 실연동 검증 착수.
|