diff --git a/INDEX.md b/INDEX.md index 2e21a9d..12ea2f2 100644 --- 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` | 계정, 권한, 백업, 리플리케이션 | diff --git a/dev/dev_plans/api-route-improvement-plan.md b/dev/dev_plans/api-route-improvement-plan.md new file mode 100644 index 0000000..37f17d0 --- /dev/null +++ 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