# API 테스트 인프라 정비 및 수주 API 테스트 추가

**날짜:** 2026-03-14
**작업자:** R&D 개발실장 + Claude Code

## 변경 개요

API 프로젝트의 테스트 기반을 체계적으로 정비하고, 미커버 핵심 도메인인 수주(Order) API에 대한 Feature 테스트를 신규 작성했다. 기술 부채 분석(D1: 테스트 커버리지 확충)의 첫 번째 실행 단계이다.

---

## 1. 테스트 인프라 정비

### 1.1 TestCase 공통화

기존 11개 테스트 파일이 동일한 setUp 코드(약 40줄)를 매번 복붙하고 있었다. `tests/TestCase.php`에 공통 메서드를 추가하여 중복을 제거했다.

**추가된 공통 메서드:**

| 메서드 | 용도 |
|--------|------|
| `setUpAuthenticatedUser()` | API Key + Tenant + User + 로그인 토큰 일괄 생성 |
| `api($method, $uri, $data)` | 인증된 API 요청 (X-API-KEY + Bearer 자동 포함) |
| `assertApiSuccess($response)` | 표준 응답 구조 검증 (`success`, `message`, `data`) |
| `assertApiPaginated($response)` | 페이지네이션 응답 구조 검증 |

**Before (각 테스트 파일마다 반복):**

```php
private Tenant $tenant;
private User $user;
private string $apiKey;
private string $token;

protected function setUp(): void {
    // 40줄의 동일한 초기화 코드...
}
protected function loginAndGetToken(): void { ... }
protected function authenticatedRequest(...) { ... }
```

**After (한 줄 호출):**

```php
protected function setUp(): void {
    parent::setUp();
    $this->setUpAuthenticatedUser();
}
// api(), assertApiSuccess() 등 TestCase에서 상속
```

### 1.2 기존 테스트 파일 정리

11개 기존 테스트 파일에서 `private` 프로퍼티 선언, `use DatabaseTransactions`, 중복 헬퍼 메서드를 제거하고 TestCase 상속으로 전환했다.

### 1.3 Factory 신규 생성

기존에 `UserFactory` 1개만 존재했다. 핵심 도메인 테스트에 필요한 Factory 3개를 추가했다.

| Factory | 모델 | 주요 필드 |
|---------|------|----------|
| `TenantFactory` | `Tenant` | company_name, code, email, phone, business_num |
| `ClientFactory` | `Client` | name, client_code, contact_person, phone, business_no |
| `OrderFactory` | `Order` | order_no, order_type_code, status_code, quantity, supply_amount |

`OrderFactory`에는 상태별 빌더 메서드도 포함:

```php
OrderFactory::new()->confirmed()     // 확정 상태
OrderFactory::new()->inProduction()  // 생산중 상태
OrderFactory::new()->completed()     // 완료 상태
OrderFactory::new()->cancelled()     // 취소 상태
```

---

## 2. 수주(Order) API 테스트

### 2.1 테스트 목록 (12개)

| 테스트 | 검증 내용 | 결과 |
|--------|----------|:----:|
| `test_수주_목록_조회` | GET `/api/v1/orders` 페이지네이션 응답 | ✅ |
| `test_수주_통계_조회` | GET `/api/v1/orders/stats` 집계 데이터 | ✅ |
| `test_수주_생성_성공` | POST `/api/v1/orders` + items 배열 | ✅ |
| `test_수주_생성_빈_데이터_허용_확인` | 빈 데이터 생성 허용 여부 확인 | ✅ |
| `test_수주_상세_조회` | GET `/api/v1/orders/{id}` 단건 | ✅ |
| `test_존재하지_않는_수주_조회시_404` | 없는 ID 조회 → 404 | ✅ |
| `test_수주_수정_성공` | PUT `/api/v1/orders/{id}` 필드 변경 | ✅ |
| `test_수주_삭제_성공` | DELETE → SoftDelete 확인 | ✅ |
| `test_수주_일괄_삭제` | DELETE `/api/v1/orders/bulk` | ✅ |
| `test_수주_상태_등록에서_확정으로_변경` | PATCH `/{id}/status` DRAFT→CONFIRMED | ✅ |
| `test_수주_상태_취소` | PATCH `/{id}/status` DRAFT→CANCELLED | ✅ |
| `test_미인증_요청시_401` | Bearer 토큰 없이 요청 → 401 | ✅ |

### 2.2 테스트 실행 결과

```
PHPUnit 11.5.27
PHP 8.4.18

전체: 120개 통과, 3개 Skip (기존 라우트 충돌 이슈)
신규: 12개 전부 통과 (46 assertions)
실행 시간: ~8초
```

---

## 3. 발견된 문제

### 3.1 빈 데이터로 수주 생성 허용

```
POST /api/v1/orders (body: {})
→ 200 OK (수주가 생성됨)
```

`StoreOrderRequest`의 검증 규칙이 느슨하여 필수 필드 없이도 수주가 생성된다. FormRequest 검증 강화가 필요하다 (D4 개선 대상).

### 3.2 기존 테스트 실패 (변경 전부터 존재)

| 테스트 | 원인 | 영향 |
|--------|------|------|
| `PrefixResolverTest` | Unit 테스트 로직 불일치 (XX vs CF) | Production 도메인 |
| `BendingLotPipelineTest` (3개) | TENANT_ID=287 고정, 로컬 DB에 해당 데이터 없음 | Production 도메인 |
| `ItemMasterApiTest` (3개) | `section_id` 컬럼 미존재 (마이그레이션 불일치) | ItemMaster 도메인 |

> 이 실패들은 이번 변경과 무관한 기존 문제이다.

---

## 수정된 파일

| 파일 | 변경 내용 |
|------|----------|
| `tests/TestCase.php` | 공통 헬퍼 메서드 4개 추가 (`setUpAuthenticatedUser`, `api`, `assertApiSuccess`, `assertApiPaginated`) |
| `tests/Feature/Account/AccountApiTest.php` | `private` → TestCase 상속, 중복 제거 |
| `tests/Feature/BadDebt/BadDebtApiTest.php` | 동일 |
| `tests/Feature/Category/CategoryApiTest.php` | 동일 |
| `tests/Feature/Company/CompanyApiTest.php` | 동일 |
| `tests/Feature/ItemMaster/ItemMasterApiTest.php` | 동일 |
| `tests/Feature/Payment/PaymentApiTest.php` | 동일 |
| `tests/Feature/Popup/PopupApiTest.php` | 동일 |
| `tests/Feature/Production/BendingLotPipelineTest.php` | `use DatabaseTransactions` 중복 제거 |
| `tests/Feature/Subscription/SubscriptionApiTest.php` | 동일 |
| `tests/Feature/User/NotificationSettingApiTest.php` | 동일 |
| `tests/Feature/User/UserInvitationApiTest.php` | 동일 |
| `database/factories/TenantFactory.php` | **신규** — Tenant 모델 Factory |
| `database/factories/ClientFactory.php` | **신규** — Client 모델 Factory |
| `database/factories/OrderFactory.php` | **신규** — Order 모델 Factory (상태 빌더 포함) |
| `tests/Feature/Orders/OrderApiTest.php` | **신규** — 수주 API 테스트 12개 |

---

## 테스트 체크리스트

- [x] TestCase 공통 헬퍼 작성
- [x] 기존 11개 테스트 파일 중복 제거
- [x] Factory 3개 생성 (Tenant, Client, Order)
- [x] Order API 테스트 12개 작성 및 통과
- [x] 기존 테스트 회귀 없음 확인 (기존 실패는 변경 전부터 존재)
- [ ] StockService 테스트 (다음 단계)
- [ ] ApprovalService 테스트 (다음 단계)
- [ ] WorkOrderService 테스트 (다음 단계)

---

## 다음 단계

기술 부채 D1(테스트 커버리지 확충) 로드맵에 따라 다음 서비스 테스트를 순차 진행한다:

1. **StockService** — 재고 관리 (FIFO, LOT 추적)
2. **ApprovalService** — 전자결재 워크플로우
3. **WorkOrderService** — 작업지시 (가장 큰 서비스, 4,097줄)

---

## 관련 문서

- [API 구조 분석 및 개선 로드맵](../../system/api-analysis-report.md)
- [API 개발 규칙](../standards/api-rules.md)
- [품질 체크리스트](../standards/quality-checklist.md)

---

**최종 업데이트**: 2026-03-14
