백엔드 계약 문서 동기화하고 DTO 파서 정합성 확장
This commit is contained in:
JiWoong Sul
@@ -9,7 +9,7 @@
|
||||
## 0. 구현 현황 요약 (2025-09-18 기준)
|
||||
- 마스터 데이터: `/vendors`, `/uoms`, `/transaction-types`, `/transaction-statuses`, `/approval-statuses`, `/approval-actions`, `/warehouses`, `/customers`, `/products`, `/employees`, `/groups`, `/menus`, `/group-menu-permissions`, `/zipcodes`
|
||||
- 각 자원은 `/api/v1/<resource>` 패턴을 따르며, 목록 필터·페이지네이션·`include` 확장을 지원한다.
|
||||
- 그룹 권한은 `/api/v1/group-menu-permissions`와 `/api/v1/groups/{id}/permissions` 일괄 갱신 엔드포인트로 관리한다. `group-menu-permissions` 응답의 `menu` 객체에는 `route_path`가 포함되며, FE는 이 값을 사용해 라우트별 권한 매핑을 완성해야 한다. `include=group` 쿼리를 추가하면 그룹 요약이 함께 반환돼 권한 매트릭스를 단일 호출로 구축할 수 있다.
|
||||
- 그룹 권한은 `/api/v1/group-menu-permissions`와 `/api/v1/groups/{id}/permissions` 일괄 갱신 엔드포인트로 관리한다. `group-menu-permissions` 응답의 `menu` 객체에는 `route_path`가 포함되며, `include=group` 쿼리로 그룹 요약을 함께 받을 수 있다.
|
||||
- 우편번호 검색 `/api/v1/zipcodes`는 부분 일치 검색(`q`, `zipcode`, `road_name`)과 단건 조회를 제공한다.
|
||||
|
||||
---
|
||||
@@ -442,7 +442,9 @@
|
||||
블록은 결재 생성에 필요한 정보를 담으며 생략할 수 없다.
|
||||
|
||||
### 4.2 목록 조회
|
||||
`GET /stock-transactions?include=lines,customers,approval`
|
||||
`GET /stock-transactions?customer_id=301&include=lines,customers,approval`
|
||||
|
||||
- `customer_id` (optional, number): 지정한 고객이 연결된 트랜잭션만 반환한다. 다른 검색 파라미터와 조합 가능하며, `include=customers` 사용 시 선택 고객 정보가 응답에 유지된다.
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
@@ -801,7 +803,38 @@
|
||||
"note": "입고 결재"
|
||||
}
|
||||
```
|
||||
응답에는 `id`와 현재 단계 정보가 포함된다.
|
||||
응답:
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"approval": {
|
||||
"id": 5001,
|
||||
"approval_no": "APP-2025-0001",
|
||||
"approval_status": {
|
||||
"id": 1,
|
||||
"status_name": "대기",
|
||||
"is_blocking_next": true,
|
||||
"is_terminal": false
|
||||
},
|
||||
"current_step": null,
|
||||
"requested_by": {
|
||||
"id": 7,
|
||||
"employee_no": "E2025001",
|
||||
"employee_name": "김승인"
|
||||
},
|
||||
"requested_at": "2025-09-18T06:00:00Z",
|
||||
"decided_at": null,
|
||||
"note": "입고 결재",
|
||||
"is_active": true,
|
||||
"created_at": "2025-09-18T06:00:00Z",
|
||||
"updated_at": "2025-09-18T06:00:00Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
- `approval_no`는 활성 결재 기준으로 중복 불가하며(409 Conflict), 길이는 1~30자다.
|
||||
- 최초 생성 시 `approval_status_id`에는 `대기` 상태 ID를 전달하고, 서버는 동일 상태로 저장한다.
|
||||
- 단계나 이력이 존재하면 `data.approval.steps`, `data.approval.histories`가 함께 반환된다.
|
||||
|
||||
### 5.2 목록 조회
|
||||
`GET /approvals?include=steps,histories`
|
||||
@@ -1185,7 +1218,6 @@
|
||||
}
|
||||
```
|
||||
응답에는 전후 상태(`from_status`, `to_status`), 차기 단계 정보가 포함되며, `approval_histories`에 기록된다.
|
||||
프론트엔드는 204 응답이 아닌 위의 `{ "data": { ... } }` 본문을 소비해 화면 상태를 즉시 갱신해야 한다.
|
||||
|
||||
### 5.7 결재 상태 확인
|
||||
`GET /approvals/5001/can-proceed`
|
||||
@@ -1207,6 +1239,36 @@
|
||||
"approval_status_id": 2,
|
||||
"note": "보류 처리"
|
||||
}
|
||||
```
|
||||
응답은 `data.approval` 구조로 최신 요약을 반환한다.
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"approval": {
|
||||
"id": 5001,
|
||||
"approval_no": "APP-2025-0001",
|
||||
"approval_status": {
|
||||
"id": 2,
|
||||
"status_name": "진행중",
|
||||
"is_blocking_next": true,
|
||||
"is_terminal": false
|
||||
},
|
||||
"current_step": {
|
||||
"id": 7002,
|
||||
"step_order": 2
|
||||
},
|
||||
"requested_by": {
|
||||
"id": 7,
|
||||
"employee_no": "E2025001",
|
||||
"employee_name": "김승인"
|
||||
},
|
||||
"requested_at": "2025-09-18T06:00:00Z",
|
||||
"decided_at": null,
|
||||
"note": "보류 처리",
|
||||
"updated_at": "2025-09-18T08:10:00Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
- `DELETE /approvals/5001`
|
||||
- `POST /approvals/5001/restore`
|
||||
@@ -1269,19 +1331,19 @@
|
||||
```
|
||||
|
||||
### 5.10 단계 개별 CRUD
|
||||
- `GET /approval-steps?approval_id=5001&include=approval,approver,step_status` → `{ items: [], page, page_size, total }` 형태로 반환하며, 각 항목은 요청한 `include` 토큰에 따라 관련 결재/결재자/상태 요약을 포함한다.
|
||||
- `GET /approval-steps?approval_id=5001&include=approver,step_status` → `{ items: [], page, page_size, total }` 형태로 반환하며, 각 항목은 `approval`, `approver`, `step_status` 서브 오브젝트를 선택적으로 포함한다.
|
||||
- `GET /approval-steps/7001?include=approval,approver,step_status` → `{ data: { ... } }`.
|
||||
- `POST /approval-steps` → 단일 단계를 생성하고 `{ data: { step, approval } }` 형태로 생성된 요약과 결재 상태를 반환한다. `step_status_id`를 생략하면 자동으로 `대기` 상태가 지정된다.
|
||||
- `POST /approval-steps/batch` → 여러 단계를 한 번에 생성·재정렬하며, 응답은 `{ data: { approval, steps, histories } }` 구조로 최신 결재 상태와 정렬된 단계 목록, 신규 이력 요약을 포함한다.
|
||||
- `PATCH /approval-steps/batch` → 다건 단계 수정/비활성화를 처리하고 `{ data: { approval, steps, histories } }` 본문으로 변경 결과를 반환한다.
|
||||
- `PATCH /approval-steps/{id}` → 갱신된 단계 요약과 함께 `{ data: { step, approval } }`를 반환한다.
|
||||
- `POST /approval-steps` → 단일 단계를 생성하고 `{ data: { ... } }` 형태로 생성된 요약을 반환한다. `step_status_id`를 생략하면 자동으로 `대기` 상태가 지정된다.
|
||||
- `PATCH /approval-steps/{id}` → 갱신된 단계 요약을 반환한다.
|
||||
- `DELETE /approval-steps/{id}` → `{ data: { id, deleted_at } }`.
|
||||
- `POST /approval-steps/{id}/restore` → `{ data: { id, restored_at } }`.
|
||||
|
||||
주요 필터 및 확장 파라미터(approval-steps):
|
||||
주요 필터 및 확장 파라미터:
|
||||
|
||||
- `approval_id`, `approver_id`, `step_status_id`
|
||||
- `include=approval,approver,step_status`
|
||||
- `approval_id`, `approval_step_id`, `approver_id`, `approval_action_id`
|
||||
- `action_from`, `action_to` (ISO8601)
|
||||
- `sort=action_at|created_at|updated_at`, `order=asc|desc`
|
||||
- `include` 기본값은 `approver,approval_action,from_status,to_status`; `approval`, `step` 토큰으로 확장
|
||||
|
||||
`GET /approval-histories/91001?include=approval,step`
|
||||
```json
|
||||
@@ -1329,8 +1391,6 @@
|
||||
}
|
||||
```
|
||||
|
||||
`approval-histories` 엔드포인트는 `approval_id`, `approval_step_id`, `approver_id`, `approval_action_id`, `action_from`, `action_to`, `sort=action_at|created_at|updated_at`, `order=asc|desc` 파라미터와 `include=approval,step,approver,from_status,to_status` 확장을 지원한다.
|
||||
|
||||
---
|
||||
|
||||
## 6. 결재 템플릿 API
|
||||
@@ -1452,19 +1512,32 @@
|
||||
---
|
||||
|
||||
## 7. 보고서 Export
|
||||
- `format=xlsx|pdf` 파라미터를 지원한다. 현재는 `format=xlsx`만 성공하며, `format=pdf`를 지정하면 400 Bad Request가 반환된다.
|
||||
- 응답은 즉시 다운로드 스트림으로 전달되며 `Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`와 `Content-Disposition: attachment` 헤더가 포함된다. 프론트엔드는 받은 바이트 스트림을 그대로 파일로 저장해야 한다.
|
||||
- `format=xlsx|pdf` 파라미터를 지원한다. 현재 구현은 XLSX 다운로드만 제공하며, `format=pdf` 요청 시 400 Bad Request를 반환한다.
|
||||
- `delivery=stream|metadata`(기본값 `stream`) 파라미터를 지원한다.
|
||||
- `delivery=metadata` 요청 시 다운로드 메타데이터를 반환한다.
|
||||
`GET /reports/transactions/export?from=2025-09-01&to=2025-09-30&transaction_status_id=2&delivery=metadata`
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"download_url": "/api/v1/reports/transactions/export?from=2025-09-01&to=2025-09-30&transaction_status_id=2&delivery=stream&exported_at=2025-09-30T12:00:00Z",
|
||||
"filename": "transactions_export_20250930120000.xlsx",
|
||||
"mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
|
||||
"expires_at": "2025-09-30T12:15:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
`download_url`에는 `delivery=stream`과 `exported_at` 값이 포함되며, 해당 URL을 그대로 호출하면 동일한 파일명을 유지한 스트리밍 응답을 받을 수 있다.
|
||||
- `delivery=stream` 요청(기본값)은 `Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `Content-Disposition: attachment` 헤더를 포함한 바이트 스트림을 반환한다.
|
||||
|
||||
### 7.1 트랜잭션 Export
|
||||
`GET /api/v1/reports/transactions/export?from=2025-09-01&to=2025-09-30&transaction_status_id=2&approval_status_id=3&requested_by_id=7&format=xlsx`
|
||||
- 지원 쿼리: `from`, `to`, `transaction_status_id`, `approval_status_id`, `requested_by_id`, `format`.
|
||||
- 열 구성: `Transaction No`, `Transaction Date`, `Transaction Type`, `Status`, `Warehouse`, `Created By`, `Approval No`, `Approval Status`.
|
||||
`GET /reports/transactions/export?from=2025-09-01&to=2025-09-30&transaction_status_id=2&warehouse_id=1&requested_by_id=7&format=xlsx`
|
||||
- 열 구성: `Transaction No`, `Transaction Date`, `Transaction Type`, `Status`, `Warehouse`, `Created By`, `Approval No`, `Approval Status`
|
||||
- `approval_status_id`, `requested_by_id` 파라미터로 결재 상태·요청자 기준 필터링이 가능하다.
|
||||
|
||||
### 7.2 결재 Export
|
||||
`GET /api/v1/reports/approvals/export?from=2025-09-01T00:00:00Z&to=2025-09-30T23:59:59Z&transaction_status_id=1&approval_status_id=1&requested_by_id=7&format=xlsx`
|
||||
- 지원 쿼리: `from`, `to`, `transaction_status_id`, `approval_status_id`, `requested_by_id`, `format`.
|
||||
- 열 구성: `Approval No`, `Approval Status`, `Transaction No`, `Requested By`, `Requested At`, `Decided At`, `Current Step Order`, `Current Step Approver`.
|
||||
- `from`, `to` 파라미터는 `requested_at` 기준 UTC 타임스탬프 범위 필터다.
|
||||
`GET /reports/approvals/export?approval_status_id=1&requested_by_id=7&from=2025-09-01T00:00:00Z&to=2025-09-30T23:59:59Z&format=xlsx`
|
||||
- 열 구성: `Approval No`, `Approval Status`, `Transaction No`, `Requested By`, `Requested At`, `Decided At`, `Current Step Order`, `Current Step Approver`
|
||||
- `from`, `to` 파라미터는 `requested_at` 기준 UTC 타임스탬프 필터로 동작한다.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user