# 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