# Phase 1-4: 에러 메시지 포맷 통합 (`formatApiError` 제거)

> 난이도: 저 | 영향도: 🟡 API 레이어 정리 | 예상 변경: 1파일 삭제

---

## 현황 요약

에러 메시지 포맷팅 함수가 2곳에 중복:

| 파일 | 함수 | 외부 사용처 |
|------|------|------------|
| `src/lib/api/error-handler.ts:122` | `getErrorMessage()` | **5+ 파일** (활발히 사용) |
| `src/lib/api/toast-utils.ts:106` | `formatApiError()` | **0건** (dead code) |

또한 `SHOW_ERROR_CODE` 상수도 양쪽에 중복 정의됨.

---

## 핵심 발견: toast-utils.ts 전체가 dead code

`from '@/lib/api/toast-utils'` 를 import하는 파일이 **0건**.

```
toast-utils.ts 내보내는 함수 전부 미사용:
- toastApiError()    → 0 import
- toastSuccess()     → 0 import
- toastWarning()     → 0 import
- toastInfo()        → 0 import
- formatApiError()   → 0 import
```

현재 프로젝트에서 에러 토스트 표시는 직접 `toast.error(getErrorMessage(err))` 패턴으로 처리 중.

---

## 작업 내역

### Step 1: `src/lib/api/toast-utils.ts` 삭제

파일 전체가 dead code이므로 삭제.

### Step 2: (선택) 유용한 헬퍼를 error-handler.ts로 이동

`toastApiError()` 함수는 validation 에러의 첫 번째 필드를 표시하는 로직이 있어,
향후 유용할 수 있으면 error-handler.ts 하단에 통합 가능.

```typescript
// src/lib/api/error-handler.ts 하단에 추가 (선택)
import { toast } from 'sonner';

export function toastApiError(error: unknown, fallbackMessage = '오류가 발생했습니다.'): void {
  if (error instanceof ApiError && error.errors && SHOW_ERROR_CODE) {
    const firstField = Object.keys(error.errors)[0];
    if (firstField) {
      toast.error(`${getErrorMessage(error)}\n${firstField}: ${error.errors[firstField][0]}`);
      return;
    }
  }
  toast.error(getErrorMessage(error) || fallbackMessage);
}
```

이 step은 **선택**. 현재 사용처가 없으므로 당장은 삭제만으로 충분.

### Step 3: 검증

```bash
npx tsc --noEmit
```

toast-utils.ts를 삭제해도 외부 import가 없으므로 타입 에러 없음.

---

## 관련 파일 참조

### 활발히 사용 중인 함수 (변경 없음)

`getErrorMessage()` 사용처 (error-handler.ts에서 export):
- `src/contexts/ItemMasterContext.tsx` (line 7, 589, 682)
- `src/components/items/ItemMasterDataManagement/hooks/usePageManagement.ts` (line 7, 122, 159, 198, 219)
- `src/components/items/ItemMasterDataManagement/hooks/useImportManagement.ts` (line 5, 58, 80, 92)
- `src/components/items/ItemMasterDataManagement/hooks/useInitialDataLoading.ts` (line 7, 130)
- `src/app/[locale]/(protected)/sales/client-management-sales-admin/page.tsx` (line 40, 301, 347)

### 삭제 대상

- `src/lib/api/toast-utils.ts` (전체 116줄)

---

## 중복 구조 비교

```
error-handler.ts                    toast-utils.ts (삭제 대상)
─────────────────                   ──────────────────────────
const SHOW_ERROR_CODE = true;       const SHOW_ERROR_CODE = true;  ← 중복

getErrorMessage(error):             formatApiError(error):
  DuplicateCodeError → [status]       ApiError → [status] msg
  ApiError → [status] msg             else → getErrorMessage()   ← 결국 위임
  Error → .message
  unknown → 기본 메시지
                                    toastApiError(error):
                                      DuplicateCodeError → toast  ← getErrorMessage와 동일 로직
                                      ApiError → toast
                                      Error → toast
                                      unknown → toast
```

`formatApiError`는 결국 `getErrorMessage`를 호출하는 래퍼에 불과. 삭제해도 기능 손실 없음.
