# API 라우트 구조 개선 계획

> **작성일**: 2026-03-13
> **상태**: 분석 완료, 실행 미정
> **대상**: `sam/api` (Laravel REST API)

---

## 1. 개요

### 1.1 목적

sam/api의 전체 라우트를 분석하여 중복, 비일관성, 비효율적 패턴을 식별하고 개선 방향을 수립한다.

### 1.2 핵심 원칙

- API 수를 단순히 줄이는 것이 목표가 **아니다**
- **일관된 패턴 정리 + 중복 제거 + 네임스페이스 정리**가 목표
- Resource-oriented REST 설계 원칙 준수
- 기존 React/MNG 클라이언트와의 호환성 고려

---

## 2. 현황 분석 (2026-03-13 기준)

### 2.1 전체 현황

| 항목 | 수치 |
|------|------|
| 총 API v1 라우트 | **1,099개** |
| 리소스(컨트롤러) 그룹 | **115개** |
| 비표준 REST 액션 | **625개 (56%)** |
| stats/summary 엔드포인트 | **88개** |
| 단일 엔드포인트 리소스 | **22개** |
| 3단계 이상 URL 네스팅 | **198개** |

### 2.2 리소스별 라우트 수 (상위 20)

| 리소스 | 라우트 수 | 비고 |
|--------|----------|------|
| `item-master` | 50 | 품목기준관리 (페이지/섹션/필드 CRUD) |
| `design` | 40 | 설계 (모델/버전/BOM 템플릿) |
| `quotes` | 33 | 견적 |
| `work-orders` | 33 | 작업지시 |
| `items` | 29 | 품목 |
| `settings` | 28 | 설정 |
| `approvals` | 27 | 결재 |
| `admin` | 26 | 관리자 |
| `categories` | 26 | 카테고리 |
| `equipment` | 26 | 설비 |
| `quality` | 26 | 품질 |
| `construction` | 24 | 시공 |
| `users` | 19 | 사용자 |
| `payrolls` | 18 | 급여 |
| `boards` | 17 | 게시판 |
| `barobill-card-transactions` | 16 | 바로빌 카드 |
| `esign` | 16 | 전자서명 |
| `roles` | 16 | 역할 |
| `leaves` | 15 | 휴가 |
| `pricing` | 15 | 단가 |

---

## 3. 개선 포인트

### 3.1 stats/summary 엔드포인트 난립 (88개)

**현재**: 거의 모든 리소스에 `/stats`, `/summary`, `/dashboard-detail`이 각각 존재한다.

```
GET /api/v1/orders/stats
GET /api/v1/quotes/stats
GET /api/v1/sales/summary
GET /api/v1/purchases/summary
GET /api/v1/dashboard/sales/summary
GET /api/v1/dashboard/purchases/summary
... 총 88개
```

**문제점**:
- Dashboard 로딩 시 6~8개 API를 동시 호출해야 한다
- 각 리소스마다 stats/summary 메서드가 반복 구현된다
- dashboard 전용 summary와 리소스 자체 summary가 중복된다

**개선안 A**: Dashboard 통합 API

```
# Before: 6번 호출
GET /dashboard/sales/summary
GET /dashboard/purchases/summary
GET /dashboard/production/summary
GET /dashboard/attendance/summary
GET /dashboard/construction/summary
GET /dashboard/unshipped/summary

# After: 1번 호출
GET /api/v1/dashboard?sections=sales,purchases,production,attendance
```

**개선안 B**: index에 통계 포함 옵션

```
# 목록 조회 시 통계도 함께
GET /api/v1/orders?with_stats=true
```

---

### 3.2 의미적 중복 리소스

#### 금융/뱅킹 — 9개 리소스, 74개 라우트

```
bank-accounts             (8개)
bank-transactions         (3개)
barobill                  (7개)
barobill-bank-transactions (13개)
barobill-card-transactions (16개)
barobill-settings         (3개)
card-transactions         (10개)
deposits                  (7개)
withdrawals               (7개)
```

**개선안**: 논리적 네임스페이스 그룹핑

```
/api/v1/finance/accounts           ← bank-accounts
/api/v1/finance/transactions       ← deposits + withdrawals + bank-transactions
/api/v1/finance/cards              ← cards
/api/v1/finance/card-transactions  ← card-transactions
/api/v1/integrations/barobill/...  ← barobill* 4개 통합
```

#### 세금/세금계산서 — 관련 리소스 분산

```
tax-invoices      (14개)
hometax-invoices  (13개)
bills             (8개)
vat               (2개)
```

**개선안**:

```
/api/v1/tax/invoices?source=hometax|manual
/api/v1/tax/bills
/api/v1/tax/vat-reports
```

#### HR/인사 — 6개 리소스, 70개 라우트

```
attendance   (1개) ← 단수
attendances  (10개) ← 복수 (중복!)
employees    (9개)
leaves       (15개)
payrolls     (18개)
salaries     (9개)
labor        (10개)
```

**개선안**:
- `attendance`(단수) → `attendances`에 통합 (필수)
- `salaries` → `payrolls`에 통합 검토
- `labor` → `hr/labor` 네임스페이스

---

### 3.3 분개(Journal Entries) 액션 반복 (5+ 리소스)

동일한 CRUD 패턴이 여러 리소스에 반복된다:

```
GET    /deposits/{id}/journal-entries
POST   /deposits/{id}/journal-entries
DELETE /deposits/{id}/journal-entries

GET    /withdrawals/{id}/journal-entries
POST   /withdrawals/{id}/journal-entries

GET    /sales/{id}/journal-entries
POST   /sales/{id}/journal-entries

(purchases, bills 등도 동일 패턴)
```

**개선안**: Polymorphic 분개 API

```
# Before: 리소스마다 3개씩 x 5개 = 15개
# After: 단일 리소스
GET    /api/v1/journal-entries?source_type=deposit&source_id=123
POST   /api/v1/journal-entries  { source_type: "deposit", source_id: 123, ... }
DELETE /api/v1/journal-entries/{id}
```

---

### 3.4 단일 엔드포인트 리소스 22개 (통합 후보)

1~2개 엔드포인트만 가진 리소스는 부모 리소스에 병합할 수 있다:

| 현재 | 통합 대상 | 방법 |
|------|----------|------|
| `attendance/summary` | `attendances` | summary 액션으로 통합 |
| `production/summary` | `dashboard` | dashboard 통합 |
| `unshipped/summary` | `dashboard` 또는 `shipments` | 통합 |
| `entertainment/summary` | `reports` | 회계 리포트에 통합 |
| `welfare/summary` | `reports` | 회계 리포트에 통합 |
| `vat/summary` + `vat/detail` | `tax-invoices` | 세금 리소스에 통합 |
| `status-board/summary` | `dashboard` | 통합 |
| `storage/usage` | `settings` | 설정에 통합 |
| `comprehensive-analysis` | `reports` | 리포트에 통합 |

인증 관련 분산:

| 현재 | 통합 후 |
|------|---------|
| `POST /login` | `POST /auth/login` |
| `POST /logout` | `POST /auth/logout` |
| `POST /register` | `POST /auth/register` |
| `POST /signup` | `POST /auth/signup` (또는 register와 통합) |
| `POST /token-login` | `POST /auth/token-login` |
| `POST /refresh` | `POST /auth/refresh` |

---

### 3.5 bulkUpdateAccountCode 패턴 반복

동일 로직이 4개 리소스에 분산되어 있다:

```
PUT  /card-transactions/bulk-update-account
POST /deposits/bulk-update-account-code
PUT  /sales/bulk-update-account
POST /withdrawals/bulk-update-account-code
```

**개선안**: 통합 Batch API

```json
POST /api/v1/accounting/bulk-assign-codes
{
  "items": [
    { "type": "deposit", "id": 1, "account_code": "401" },
    { "type": "sale", "id": 5, "account_code": "101" }
  ]
}
```

---

### 3.6 비표준 REST 액션 정리 (56%, 625개)

| 커스텀 액션 | 횟수 | 개선 방향 |
|------------|------|----------|
| `stats` | 31 | `?with_stats=true` 또는 dashboard 통합 |
| `summary` | 30 | 동일 |
| `reorder` | 13 | `PATCH /{resource}/order` 패턴 통일 |
| `toggle` | 12 | `PATCH /{id}` body에 `{ is_active: true }` |
| `bulkDestroy` | 12 | `DELETE /{resource}?ids=1,2,3` |
| `cancel` | 8 | 상태 머신 통합: `PATCH /{id}/status` |
| `restore` | 7 | `POST /{id}/restore` 유지 (Laravel 관례) |
| `updateStatus` | 6 | `PATCH /{id}/status { action: "approve" }` |
| `clone` | 6 | `POST /{resource}?clone_from={id}` |
| `approve/reject/confirm/complete` | 17 | 상태 머신: `PATCH /{id}/status` |
| `export` | 5 | `GET /{resource}/export?format=xlsx` 통일 |

---

### 3.7 과도한 URL 네스팅 (198개, 3단계 이상)

```
# 4단계 네스팅 예시
PUT  /design/models/{modelId}/versions/{id}
POST /work-orders/{id}/items/{itemId}/material-inputs
PUT  /settings/options/{gid}/values/{id}
POST /boards/{code}/posts/{postId}/comments
```

**개선안**: 2단계까지만 네스팅, 그 이상은 독립 리소스 또는 쿼리파라미터

```
# Before
GET /work-orders/{id}/items/{itemId}/materials

# After (옵션 1: 독립 리소스)
GET /work-order-items/{itemId}/materials

# After (옵션 2: 쿼리파라미터)
GET /materials?work_order_id={id}&item_id={itemId}
```

---

## 4. 실행 계획 (권장 순서)

| 순서 | 작업 | 영향도 | 난이도 | 예상 감소 |
|------|------|--------|--------|----------|
| 1 | `attendance`/`attendances` 단수/복수 통합 | 낮음 | 쉬움 | -1 |
| 2 | 인증 라우트 `/auth/*` 그룹핑 | 낮음 | 쉬움 | -6 (네임스페이스 정리) |
| 3 | 단일 엔드포인트 22개 → 부모 리소스에 병합 | 중간 | 쉬움 | -15~20 |
| 4 | Journal Entries polymorphic 통합 | 중간 | 중간 | -12~15 |
| 5 | `bulkUpdateAccountCode` 통합 | 낮음 | 중간 | -3 |
| 6 | stats/summary → dashboard 통합 또는 `?with_stats` | 높음 | 중간 | -40~50 |
| 7 | 금융 리소스 네임스페이스 정리 | 높음 | 높음 | (구조 개선) |
| 8 | 상태 변경 액션 → 통일된 status 패턴 | 높음 | 높음 | -20~30 |
| 9 | 비표준 액션 패턴 통일 (reorder, toggle 등) | 중간 | 중간 | (일관성 개선) |

**예상 결과**: 1,099개 → **약 700~800개** (자연스러운 감소)

---

## 5. 주의사항

### 5.1 Breaking Change 관리

- React 프론트엔드가 호출하는 API를 변경할 때는 **React 코드도 동시에 수정**해야 한다
- MNG에서 HTMX로 직접 호출하는 API가 있을 수 있으므로 확인 필요
- 기존 URL을 즉시 제거하지 말고 **deprecated 기간**을 두거나 redirect 처리

### 5.2 단순 통합이 아닌 설계 개선

```
 API 수를 줄이자         → 잘못된 목표
 API 설계를 개선하자     → 올바른 목표
```

파라미터를 많이 담은 God Endpoint를 만드는 것은 안티패턴이다. 각 API가 **명확한 단일 책임**을 가지되, **일관된 패턴**으로 설계되어 있는 것이 핵심이다.

---

## 관련 문서

- [api-rules.md](../standards/api-rules.md) — API 개발 규칙
- [api-structure.md](../../system/api-structure.md) — API 서버 구조
- [migration-status.md](../../system/migration-status.md) — MNG→API+React 이관 현황

---

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