docs: API 라우터 분리 및 버전 폴백 시스템 문서화
- api-rules.md: 라우팅 섹션 전면 개편 - 도메인별 라우트 파일 구조 (13개) - ApiVersionMiddleware 설명 - API 버전 폴백 시스템 상세 설명 - system-overview.md: 라우팅 구조 섹션 확장 - 도메인별 분리 구조 다이어그램 - 미들웨어 스택에 ApiVersionMiddleware 추가 - dev-commands.md: 라우트 관리 명령어 추가 - INDEX.md: 2026-01-28 변경 이력 추가 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
6
INDEX.md
6
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`
|
||||
|
||||
@@ -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 전용 라우트
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## 공유 모델 구조
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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`
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user