diff --git a/INDEX.md b/INDEX.md index d7a3a7d..9504681 100644 --- 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 등) | --- diff --git a/changes/20260318_api_response_extra_fields.md b/changes/20260318_api_response_extra_fields.md new file mode 100644 index 0000000..6d00fe3 --- /dev/null +++ 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