docs: [api] API 라우트 구조 개선 계획 문서 추가

- 1,099개 라우트 전수 분석 결과 - 7개 개선 포인트 식별 (stats 난립, 중복 리소스, 분개 반복 등) - 실행 우선순위 및 예상 효과 포함
2026-03-13 20:36:42 +09:00
parent c822a2317d
commit dda539f7f5
2 changed files with 345 additions and 1 deletions
--- a/INDEX.md
+++ b/INDEX.md
@@ -1,7 +1,7 @@
 # SAM 문서 인덱스 (Claude Code용)

 > 작업 유형에 맞는 문서를 먼저 읽고 시작하세요.
-> 최종 갱신: 2026-03-12 (이관 현황 문서 추가)
+> 최종 갱신: 2026-03-13 (API 라우트 개선 계획 추가)

 ---

@@ -25,6 +25,7 @@
 | 급여관리 API | `frontend/api-specs/payroll-api.md` | 급여관리 API 전체 명세 (18개 엔드포인트) |
 | 바로빌 회계 API | `frontend/api-specs/barobill-api.md` | 카드/은행/홈택스 REST API (42개 엔드포인트) |
 | 결재관리 | `dev/dev_plans/approval-system-unification-plan.md` | MNG→API 결재 통합 계획 |
+| API 개선 | `dev/dev_plans/api-route-improvement-plan.md` | API 라우트 구조 개선 계획 (1,099개 분석) |
 | 운영 배포 | `dev/dev_plans/production-deployment-plan.md` | 배포 계획 |
 | 서버 운영 | `dev/deploys/ops-manual/README.md` | 서버 운영 매뉴얼 |
 | 서버 접근/백업 | `system/server-access-management.md` | 계정, 권한, 백업, 리플리케이션 |
--- a/dev/dev_plans/api-route-improvement-plan.md
+++ b/dev/dev_plans/api-route-improvement-plan.md
@@ -0,0 +1,343 @@
+# 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