344 lines
9.9 KiB
Markdown
344 lines
9.9 KiB
Markdown
# 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
|