sam-docs/dev/dev_plans/api-route-improvement-plan.md

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

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 — API 개발 규칙
• api-structure.md — API 서버 구조
• migration-status.md — MNG→API+React 이관 현황

---

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