docs: ApiResponse 에러 신호 배열 추가 필드 전달 변경이력

2026-03-18 20:57:42 +09:00
parent 69f48e9a20
commit 3ddbede4c9
2 changed files with 117 additions and 0 deletions
--- a/INDEX.md
+++ b/INDEX.md
@@ -265,6 +265,7 @@ DB 도메인별:
 | [20260318_receiving_inspection_attachment_bug.md](changes/20260318_receiving_inspection_attachment_bug.md) | 입고상세 수입검사 첨부파일 삭제 후 미갱신 버그 (React 수정 필요) |
 | [20260318_bending_lot_codemap_update.md](changes/20260318_bending_lot_codemap_update.md) | 절곡품 LOT 코드맵 최신화 + 품목 222건 등록 + 일련번호 제거 |
 | [20260318_stock_production_auto_confirm.md](changes/20260318_stock_production_auto_confirm.md) | 재고생산 자동 확정+생산지시 (3단계→1단계, 확정 버튼 제거) |
+| [20260318_api_response_extra_fields.md](changes/20260318_api_response_extra_fields.md) | ApiResponse 에러 신호 배열 추가 필드 전달 (expected_code 등) |

 ---

--- a/changes/20260318_api_response_extra_fields.md
+++ b/changes/20260318_api_response_extra_fields.md
@@ -0,0 +1,116 @@
+# ApiResponse 에러 신호 배열 추가 필드 전달
+
+**날짜:** 2026-03-18
+**작업자:** Claude Code
+
+---
+
+## 변경 개요
+
+`ApiResponse::handle()`에서 에러 신호 배열을 감지할 때 `error`, `code`, `message`, `details` 외 추가 필드(예: `expected_code`)가 응답에서 누락되는 문제를 수정했다.
+
+### 배경
+
+`BendingController::resolveItem()`에서 에러 시 `expected_code`를 포함하여 반환하지만, `ApiResponse::handle()` 229행에서 에러 신호를 감지하면 `self::error()`로 변환하면서 `expected_code` 필드를 버리고 있었다.
+
+```
+컨트롤러 반환값:
+['error' => 'NOT_MAPPED', 'code' => 404, 'message' => '...', 'expected_code' => 'BD-ABCD-1234']
+                                                              ↑ 이 필드가 누락됨
+```
+
+---
+
+## 수정된 파일
+
+| 파일 | 변경 내용 |
+|------|----------|
+| `api/app/Helpers/ApiResponse.php` | `handle()`: 에러 신호 배열의 추가 필드를 `$errorData`에 머지하여 전달 |
+| `api/app/Helpers/ApiResponse.php` | `error()`: `$error` 배열의 `details` 외 추가 필드를 `error` 객체에 포함 |
+
+---
+
+## 상세 변경 사항
+
+### 1. `ApiResponse::handle()` — 에러 신호 배열 처리
+
+**변경 전**: `error`, `code`, `message`, `details`만 추출하고 나머지 필드 버림
+
+**변경 후**: reserved 키 외 나머지를 `$extra`로 분리하여 `$errorData`에 머지
+
+```php
+// 에러 신호 배열의 추가 필드(expected_code 등)를 응답에 포함
+$reserved = ['error', 'code', 'message', 'details'];
+$extra = array_diff_key($result, array_flip($reserved));
+$errorData = ['details' => $details];
+if ($extra) {
+    $errorData = array_merge($errorData, $extra);
+}
+```
+
+### 2. `ApiResponse::error()` — 에러 응답 생성
+
+**변경 전**: `$error['details']`만 추출하여 고정 구조 반환
+
+**변경 후**: `details` 외 추가 필드를 `$errorBody`에 머지
+
+```php
+$errorBody = [
+    'code' => $code,
+    'details' => $error['details'] ?? null,
+];
+
+$reserved = ['details'];
+$extra = array_diff_key($error, array_flip($reserved));
+if ($extra) {
+    $errorBody = array_merge($errorBody, $extra);
+}
+```
+
+### 3. 변경 후 에러 응답 예시
+
+```json
+{
+  "success": false,
+  "message": "[404] 해당 조합에 매핑된 품목이 없습니다.",
+  "error": {
+    "code": 404,
+    "details": null,
+    "expected_code": "BD-ABCD-1234"
+  }
+}
+```
+
+---
+
+## 영향 범위
+
+- `ApiResponse::error()`를 사용하는 모든 에러 응답에 영향
+- 기존 코드 호환성: 추가 필드가 없으면 기존과 동일하게 동작 (breaking change 없음)
+- 현재 활용처: `BendingController::resolveItem()`의 `expected_code`
+
+---
+
+## 프론트엔드 연동 안내
+
+MNG에서 절곡품 품목 조회 API(`/api/v1/bending-items/resolve-item`) 호출 시:
+- 성공 응답: `data.expected_code`에서 조회
+- 에러 응답(404): `error.expected_code`에서 조회
+
+---
+
+## 테스트 체크리스트
+
+- [x] 에러 신호 배열에 추가 필드 포함 시 응답에 전달되는지 확인
+- [x] 추가 필드 없는 기존 에러 응답이 동일하게 동작하는지 확인
+- [x] Pint 포맷팅 적용
+
+---
+
+## 관련 문서
+
+- [20260318_bending_lot_codemap_update.md](20260318_bending_lot_codemap_update.md) — 절곡품 LOT 코드맵 최신화
+
+---
+
+**최종 업데이트**: 2026-03-18