diff --git a/INDEX.md b/INDEX.md index 4b4d585..12c7783 100644 --- a/INDEX.md +++ b/INDEX.md @@ -187,6 +187,12 @@ API Flow Tester에서 생성되는 JSON 파일 저장 경로 ## 🔄 문서 구조 변경 이력 +- **2026-01-28**: API 라우터 분리 및 버전 폴백 시스템 구현 + - `routes/api.php` → 13개 도메인별 파일로 분리 (1,479줄 → 61줄) + - `ApiVersionMiddleware` 추가 (헤더/쿼리 기반 버전 선택, v2→v1 폴백) + - `standards/api-rules.md` 라우팅 섹션 업데이트 + - `architecture/system-overview.md` 라우팅 구조 업데이트 + - **2025-12-09**: 품목 정책 통합 문서 생성 - `rules/item-policy.md` 생성 (4개 문서 통합) - 삭제: `specs/ITEM-MASTER-INDEX.md`, `specs/item-master-field-key-validation.md`, `specs/item-master-field-integration.md`, `plans/items-api-unified-plan.md` diff --git a/architecture/system-overview.md b/architecture/system-overview.md index 3fb1922..35f2d58 100644 --- a/architecture/system-overview.md +++ b/architecture/system-overview.md @@ -1,6 +1,6 @@ # SAM 시스템 아키텍처 -**업데이트**: 2025-12-26 +**업데이트**: 2026-01-28 --- @@ -212,26 +212,70 @@ menu:{menu_id}.{permission_type} **실행 순서:** 1. `ApiRateLimiter` - Rate Limiting -2. `ApiKeyMiddleware` - API Key 검증 -3. `CheckSwaggerAuth` - Swagger 인증 체크 -4. `CorsMiddleware` - CORS 처리 -5. `CheckPermission` - 권한 검증 -6. `PermMapper` - 권한 매핑 +2. `ApiVersionMiddleware` - API 버전 선택 및 폴백 처리 +3. `ApiKeyMiddleware` - API Key 검증 +4. `CheckSwaggerAuth` - Swagger 인증 체크 +5. `CorsMiddleware` - CORS 처리 +6. `CheckPermission` - 권한 검증 +7. `PermMapper` - 권한 매핑 ## 라우팅 구조 -**기본 경로 그룹:** -```php -Route::prefix('v1')->middleware(['auth.apikey'])->group(function () { - // 공개 라우트 - Route::post('/login', [AuthController::class, 'login']); +### 도메인별 라우트 분리 - // 보호된 라우트 - Route::middleware(['auth:sanctum'])->group(function () { - Route::get('/users', [UserController::class, 'index']); - // ... - }); +API 라우트는 도메인별로 분리되어 관리됩니다: + +``` +routes/api/ +├── v1/ # v1 API 라우트 (13개 도메인) +│ ├── auth.php # 인증 (login, logout, signup) +│ ├── admin.php # 관리자 기능 +│ ├── users.php # 사용자 관리 +│ ├── tenants.php # 테넌트 관리 +│ ├── hr.php # HR/인사 관리 +│ ├── finance.php # 재무/회계 +│ ├── sales.php # 영업/판매 +│ ├── inventory.php # 재고/품목 +│ ├── production.php # 생산 관리 +│ ├── design.php # 설계/모델 +│ ├── files.php # 파일 관리 +│ ├── boards.php # 게시판 +│ └── common.php # 공통 기능 +├── v2/ # v2 API (필요시 생성) +└── api.php # 라우트 로더 +``` + +### API 버전 관리 + +**ApiVersionMiddleware**가 버전 선택 및 폴백을 처리합니다: + +**버전 지정 방법:** +- `Accept-Version` 헤더 (권장) +- `X-API-Version` 헤더 +- `api_version` 쿼리 파라미터 +- 미지정 시 기본값: `v1` + +**폴백 동작:** +- v2 요청 시 해당 라우트가 v2에 없으면 v1으로 자동 폴백 +- 응답 헤더 `X-API-Version`에 실제 사용 버전 표시 + +### 기본 경로 그룹 + +```php +// routes/api.php - 라우트 로더 +Route::prefix('v1')->middleware(['auth.apikey'])->group(function () { + require __DIR__.'/api/v1/auth.php'; + require __DIR__.'/api/v1/admin.php'; + require __DIR__.'/api/v1/users.php'; + // ... 13개 도메인 파일 로드 }); + +// v2 라우트 (존재하는 경우) +if (is_dir(__DIR__.'/api/v2')) { + Route::prefix('v2')->middleware(['auth.apikey'])->group(function () { + // v2 전용 라우트 + }); +} ``` ## 공유 모델 구조 diff --git a/quickstart/dev-commands.md b/quickstart/dev-commands.md index 3c604ba..e19c476 100644 --- a/quickstart/dev-commands.md +++ b/quickstart/dev-commands.md @@ -1,6 +1,6 @@ # 개발 명령어 모음 -**업데이트**: 2025-12-26 +**업데이트**: 2026-01-28 --- @@ -59,6 +59,29 @@ php artisan l5-swagger:generate # - JSON Spec: http://api.sam.kr/docs/api-docs.json ``` +### 라우트 관리 +```bash +# 등록된 라우트 목록 확인 +php artisan route:list + +# 특정 이름 패턴으로 필터 +php artisan route:list --name=v1.users + +# 특정 경로 패턴으로 필터 +php artisan route:list --path=api/v1/users + +# 라우트 캐시 (Production) +php artisan route:cache + +# 라우트 캐시 클리어 +php artisan route:clear + +# API 버전 테스트 +# - 기본 (v1): curl https://api.sam.kr/api/v1/users +# - v2 헤더: curl -H "Accept-Version: v2" https://api.sam.kr/api/v1/users +# - 쿼리: curl "https://api.sam.kr/api/v1/users?api_version=v2" +``` + ### 개발 도구 ```bash # IDE Helper diff --git a/standards/api-rules.md b/standards/api-rules.md index 2a775e5..b06fe11 100644 --- a/standards/api-rules.md +++ b/standards/api-rules.md @@ -1,6 +1,6 @@ # SAM API 개발 규칙 -**업데이트**: 2025-11-10 +**업데이트**: 2026-01-28 --- @@ -80,14 +80,68 @@ class YourModel extends Model ## 3. Middleware Stack - ApiKeyMiddleware, CheckSwaggerAuth, CorsMiddleware, CheckPermission, PermMapper +- **ApiVersionMiddleware** - API 버전 선택 및 폴백 처리 (v2 없으면 v1 사용) - Default route group: auth.apikey (some with auth:sanctum) --- -## 4. Routing (v1) +## 4. Routing -- Auth, Common codes, Files, Tenants, Users (me/tenants/switch), Menus+Permissions, Roles/Permissions, Departments, Field settings, Options, Categories, Classifications, Products, BOM -- REST conventions: index/show/store/update/destroy + extensions (toggle, bulkUpsert, reorder) +### 4.1 라우트 파일 구조 + +API 라우트는 도메인별로 분리되어 있습니다: + +``` +routes/api/ +├── v1/ # v1 API 라우트 +│ ├── auth.php # 인증 (login, logout, signup, token) +│ ├── admin.php # 관리자 (users, global-menus, FCM) +│ ├── users.php # 사용자 (me, profiles, invitations, roles) +│ ├── tenants.php # 테넌트 (CRUD, settings, stat-fields) +│ ├── hr.php # HR (departments, positions, employees, attendances) +│ ├── finance.php # 재무 (cards, deposits, withdrawals, payrolls) +│ ├── sales.php # 영업 (clients, quotes, orders, pricing) +│ ├── inventory.php # 재고 (items, BOM, stocks, shipments) +│ ├── production.php # 생산 (processes, work-orders, inspections) +│ ├── design.php # 설계 (models, versions, BOM templates) +│ ├── files.php # 파일 (upload, download, folders) +│ ├── boards.php # 게시판 (boards, posts, comments) +│ └── common.php # 공통 (menus, roles, permissions, settings) +├── v2/ # v2 API 라우트 (필요시 생성) +└── api.php # 라우트 로더 +``` + +### 4.2 API 버전 폴백 시스템 + +**버전 선택 방법 (우선순위 순):** +1. `Accept-Version` 헤더: `Accept-Version: v2` +2. `X-API-Version` 헤더: `X-API-Version: v2` +3. `api_version` 쿼리 파라미터: `?api_version=v2` +4. 기본값: `v1` + +**폴백 동작:** +- v2 요청 시 해당 라우트가 v2에 없으면 자동으로 v1 라우트 사용 +- 응답 헤더 `X-API-Version`에 실제 사용된 버전 표시 + +**사용 예시:** +```bash +# v1 명시적 요청 +curl -H "Accept-Version: v1" https://api.sam.kr/api/v1/users + +# v2 요청 (v2 없으면 v1으로 폴백) +curl -H "Accept-Version: v2" https://api.sam.kr/api/v1/users + +# 쿼리 파라미터로 버전 지정 +curl "https://api.sam.kr/api/v1/users?api_version=v2" + +# 버전 미지정 (기본 v1) +curl https://api.sam.kr/api/v1/users +``` + +### 4.3 REST 컨벤션 + +- 기본 CRUD: `index`, `show`, `store`, `update`, `destroy` +- 확장 메서드: `toggle`, `bulkUpsert`, `reorder`, `stats`, `options` ---