권혁성
3b6e97dadc
- 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>
392 lines
10 KiB
Markdown
392 lines
10 KiB
Markdown
# SAM 시스템 아키텍처
|
|
|
|
**업데이트**: 2026-01-28
|
|
|
|
---
|
|
|
|
## 전체 아키텍처
|
|
|
|
SAM은 다중 애플리케이션 Laravel 기반 시스템으로 구성됩니다:
|
|
|
|
```
|
|
SAM/
|
|
├── api/ # Laravel 12 REST API (백엔드)
|
|
├── mng/ # Laravel 12 + Plain Blade/Tailwind (관리자 패널)
|
|
├── react/ # Next.js 15.5.7 프론트엔드
|
|
├── docs/ # 기술 문서
|
|
├── design/ # 디자인 시스템 (Storybook)
|
|
├── planning/ # 기획 문서
|
|
├── sales/ # 영업자 사이트 (추후 개발)
|
|
├── 5130/ # 레거시 PHP 애플리케이션
|
|
└── docker/ # Docker 설정
|
|
```
|
|
|
|
## 애플리케이션별 상세
|
|
|
|
### mng/ - 관리자 패널
|
|
|
|
**기술 스택:**
|
|
- Laravel 12
|
|
- PHP 8.4
|
|
- Pure Blade + Tailwind CSS 3.x
|
|
- Sanctum (인증)
|
|
|
|
**주요 기능:**
|
|
- 테넌트 관리
|
|
- 사용자 관리
|
|
- 권한 관리 (RBAC)
|
|
- 메뉴 관리
|
|
- 역할 및 부서 관리
|
|
|
|
**주요 특징:**
|
|
- AI 없이 수정 가능한 단순 구조
|
|
- 좌측 사이드바 + 상단 헤더 레이아웃
|
|
|
|
**개발 명령어:**
|
|
```bash
|
|
php artisan serve # Laravel 서버
|
|
npm run dev # Vite HMR (Tailwind)
|
|
```
|
|
|
|
### api/ - REST API
|
|
|
|
**기술 스택:**
|
|
- Laravel 12
|
|
- PHP 8.4
|
|
- Sanctum (인증)
|
|
- l5-swagger 9.0 (API 문서화)
|
|
|
|
**주요 기능:**
|
|
- RESTful API 엔드포인트
|
|
- Swagger 문서화
|
|
- Multi-tenant 지원
|
|
- 권한 기반 접근 제어
|
|
|
|
**API 구조:**
|
|
- **인증**: `/v1/login`, `/v1/logout`, `/v1/signup`
|
|
- **사용자**: `/v1/users/*`
|
|
- **테넌트**: `/v1/tenants/*`
|
|
- **제품**: `/v1/products/*`
|
|
- **자재**: `/v1/materials/*`
|
|
- **카테고리**: `/v1/categories/*`
|
|
- **파일**: `/v1/file/*`
|
|
- **디자인**: `/v1/design/*`
|
|
|
|
**API 문서:**
|
|
- Swagger UI: `http://api.sam.kr/api-docs/index.html`
|
|
- JSON Spec: `http://api.sam.kr/docs/api-docs.json`
|
|
|
|
### react/ - Next.js 프론트엔드
|
|
|
|
**기술 스택:**
|
|
- Next.js 15.5.7
|
|
- React 19.2.1
|
|
- TypeScript 5.x
|
|
- Tailwind CSS v4
|
|
- Zustand (상태 관리)
|
|
- React Hook Form
|
|
- shadcn/ui
|
|
- next-intl (i18n)
|
|
|
|
**주요 기능:**
|
|
- 모던 UI/UX
|
|
- Server Components 및 App Router
|
|
- 실시간 데이터 동기화
|
|
- 역할 전환 기능
|
|
- 대시보드
|
|
- 다국어 지원 (i18n)
|
|
|
|
## Multi-tenant 아키텍처
|
|
|
|
### 데이터 격리
|
|
|
|
- **방식**: `tenant_id` 컬럼 기반 격리
|
|
- **스코프**: BelongsToTenant global scope 자동 적용
|
|
- **모델**: `shared/Models/` 디렉토리의 공통 모델 사용
|
|
|
|
### 테넌트 구조
|
|
|
|
```
|
|
Tenant (회사/조직)
|
|
├── Users (사용자)
|
|
├── Departments (부서)
|
|
├── Roles (역할)
|
|
├── Permissions (권한)
|
|
└── Data (비즈니스 데이터)
|
|
```
|
|
|
|
### 테넌트 전환
|
|
|
|
- 사용자는 여러 테넌트에 속할 수 있음 (`user_tenants` 테이블)
|
|
- 기본 테넌트 설정 가능
|
|
- API: `POST /v1/users/me/tenants/switch`
|
|
|
|
## 인증 및 권한
|
|
|
|
### 인증 흐름
|
|
|
|
1. **API Key 인증** (모든 요청)
|
|
- 헤더: `X-API-KEY`
|
|
- 미들웨어: `auth.apikey`
|
|
|
|
2. **사용자 인증** (보호된 라우트)
|
|
- 엔드포인트: `POST /v1/login`
|
|
- 토큰: Sanctum Bearer Token
|
|
- 미들웨어: `auth:sanctum`
|
|
|
|
### 권한 시스템
|
|
|
|
**3단계 권한 구조:**
|
|
1. **사용자 역할 권한**: User → Role → Permissions
|
|
2. **사용자 직접 권한**: User → Permissions
|
|
3. **부서 역할 권한**: User → Department → Role → Permissions
|
|
|
|
**권한 명명 규칙:**
|
|
```
|
|
menu:{menu_id}.{permission_type}
|
|
```
|
|
|
|
**권한 타입:**
|
|
- `view` - 조회
|
|
- `create` - 생성
|
|
- `update` - 수정
|
|
- `delete` - 삭제
|
|
- `approve` - 승인
|
|
- `export` - 내보내기
|
|
- `manage` - 관리
|
|
|
|
## 데이터베이스 구조
|
|
|
|
### 핵심 테이블
|
|
|
|
**인증 및 권한:**
|
|
- `api_keys` - API 키 관리
|
|
- `users` - 사용자 계정
|
|
- `user_tenants` - 사용자-테넌트 관계
|
|
- `permissions` - 권한 정의
|
|
- `roles` - 역할 정의
|
|
- `model_has_permissions/roles` - 권한 할당
|
|
|
|
**멀티테넌트:**
|
|
- `tenants` - 테넌트 마스터
|
|
- `tenant_user_profiles` - 테넌트별 사용자 프로필
|
|
- `departments` - 부서 구조
|
|
- `department_user` - 사용자-부서 관계
|
|
|
|
**제품 관리:**
|
|
- `categories` - 카테고리 계층
|
|
- `category_fields` - 동적 필드 정의
|
|
- `products` - 제품 카탈로그
|
|
- `product_components` - BOM 관계
|
|
- `materials` - 자재 마스터
|
|
|
|
**디자인 및 제조:**
|
|
- `models` - 디자인 모델
|
|
- `model_versions` - 모델 버전
|
|
- `bom_templates` - BOM 템플릿
|
|
- `bom_template_items` - BOM 항목
|
|
|
|
**주문 및 운영:**
|
|
- `orders` - 주문/견적 마스터
|
|
- `order_items` - 주문 항목
|
|
- `order_item_components` - 주문 항목 구성
|
|
- `clients` - 고객/벤더 마스터
|
|
|
|
**시스템:**
|
|
- `audit_logs` - 감사 로그 (13개월 보관)
|
|
- `files` - 다형성 파일 첨부
|
|
- `common_codes` - 공통 코드
|
|
|
|
### 공통 컬럼 패턴
|
|
|
|
모든 테이블에 공통으로 포함:
|
|
- `id` - 기본 키
|
|
- `tenant_id` - 테넌트 ID (필수)
|
|
- `created_by` - 생성자 ID
|
|
- `updated_by` - 수정자 ID
|
|
- `deleted_by` - 삭제자 ID
|
|
- `created_at`, `updated_at` - 타임스탬프
|
|
- `deleted_at` - Soft Delete
|
|
|
|
## 미들웨어 스택
|
|
|
|
**실행 순서:**
|
|
1. `ApiRateLimiter` - Rate Limiting
|
|
2. `ApiVersionMiddleware` - API 버전 선택 및 폴백 처리
|
|
3. `ApiKeyMiddleware` - API Key 검증
|
|
4. `CheckSwaggerAuth` - Swagger 인증 체크
|
|
5. `CorsMiddleware` - CORS 처리
|
|
6. `CheckPermission` - 권한 검증
|
|
7. `PermMapper` - 권한 매핑
|
|
|
|
## 라우팅 구조
|
|
|
|
### 도메인별 라우트 분리
|
|
|
|
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 전용 라우트
|
|
});
|
|
}
|
|
```
|
|
|
|
## 공유 모델 구조
|
|
|
|
`shared/Models/` 디렉토리 구조:
|
|
- **Members/** - 사용자 및 테넌트 관리
|
|
- **Products/** - 제품 카탈로그 및 BOM
|
|
- **Materials/** - 자재 사양 및 재고
|
|
- **Orders/** - 주문 처리 워크플로우
|
|
- **Tenants/** - 멀티테넌트 설정
|
|
- **Commons/** - 공유 유틸리티 및 공통 데이터
|
|
|
|
## Docker 설정
|
|
|
|
**위치**: `docker/` 디렉토리
|
|
|
|
### 서비스 구성
|
|
|
|
**docker-compose.yml**에 정의된 주요 서비스:
|
|
|
|
1. **nginx** - 리버스 프록시 서버
|
|
- 포트: 80
|
|
- 도메인: `api.sam.kr`, `mng.sam.kr`, `admin.sam.kr`, `dev.sam.kr`
|
|
- 보안 규칙 적용 (경로 탐색 공격 차단, User-Agent 필터링)
|
|
|
|
2. **api** - Laravel 12 API 서버
|
|
- 이미지: `php:8.4-fpm`
|
|
- PHP 확장: zip, mysqli, pdo, pdo_mysql, intl
|
|
- Supervisor로 nginx + php-fpm 동시 실행
|
|
|
|
3. **mng** - Laravel 12 관리자 패널
|
|
- 이미지: `php:8.4-fpm`
|
|
- Pure Blade + Tailwind CSS
|
|
- Supervisor로 nginx + php-fpm 동시 실행
|
|
|
|
4. **react** - Next.js 15.5.7 프론트엔드
|
|
- 이미지: `node:20-alpine`
|
|
- 포트: 3000 (내부)
|
|
- HMR 지원 (WebSocket)
|
|
|
|
5. **mysql** - MySQL 8.0 데이터베이스
|
|
- 포트: 3306
|
|
- 데이터베이스: `samdb`
|
|
- 사용자: `samuser` / `sampass`
|
|
|
|
6. **design** - 디자인 시스템 (Storybook)
|
|
- 포트: 6006
|
|
|
|
### 네트워크 구조
|
|
|
|
```
|
|
samnet (bridge network)
|
|
├── nginx (리버스 프록시)
|
|
├── api (Laravel API)
|
|
├── mng (Laravel 관리자)
|
|
├── react (Next.js)
|
|
├── design (Storybook)
|
|
└── mysql (데이터베이스)
|
|
```
|
|
|
|
### 도메인 매핑
|
|
|
|
| 도메인 | 대상 서비스 | 포트 | 용도 |
|
|
|--------|-----------|------|------|
|
|
| `api.sam.kr` | api (Laravel) | 80 | REST API |
|
|
| `mng.sam.kr` | mng (Laravel) | 80 | 관리자 패널 |
|
|
| `admin.sam.kr` | mng (Laravel) | 80 | 관리자 패널 (별칭) |
|
|
| `dev.sam.kr` | react (Next.js) | 3000 | 프론트엔드 |
|
|
|
|
### 주요 설정 파일
|
|
|
|
**nginx/nginx.conf**
|
|
- 리버스 프록시 설정
|
|
- 보안 규칙 (경로 탐색, User-Agent 필터링)
|
|
- WebSocket 지원 (Next.js HMR)
|
|
|
|
**api/Dockerfile, mng/Dockerfile**
|
|
- PHP 8.4-fpm 기반
|
|
- Composer 2 포함
|
|
- Supervisor 설정
|
|
|
|
**react/Dockerfile**
|
|
- Node.js 20 Alpine
|
|
- Next.js 15 개발 서버
|
|
|
|
**mysql/init.sql**
|
|
- 초기 데이터베이스 설정
|
|
|
|
## 저장소 구조
|
|
|
|
이 프로젝트는 **독립적인 Git 저장소들**로 구성됩니다:
|
|
|
|
1. **api/** - REST API 저장소
|
|
2. **mng/** - 관리자 패널 저장소
|
|
3. **react/** - Next.js 프론트엔드 저장소
|
|
4. **docs/** - 기술 문서 저장소
|
|
5. **design/** - 디자인 시스템 저장소
|
|
6. **planning/** - 기획 문서 저장소
|
|
|
|
각 저장소는 독립적으로 운영되며:
|
|
- 개별 Git 히스토리 및 브랜치
|
|
- 독립적인 환경 설정 (`.env` 파일)
|
|
- 독립적인 의존성 및 빌드 프로세스
|
|
|
|
## 관련 문서
|
|
|
|
- [API 개발 규칙](./api_rules.md)
|
|
- [데이터베이스 스키마](./database_schema.md)
|
|
- [보안 가이드](./security.md)
|
|
- [Git 컨벤션](./git_conventions.md)
|
|
|
|
---
|
|
|
|
**최종 업데이트**: 2025-12-26 (admin→mng 전환, Next.js 15.5.7, React 19.2.1 반영) |