359 lines
8.8 KiB
Markdown
359 lines
8.8 KiB
Markdown
|
# SAM 시스템 아키텍처
|
||
|
|
|
||
|
|
**업데이트**: 2025-11-18
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 전체 아키텍처
|
||
|
|
|
||
|
|
SAM은 다중 애플리케이션 Laravel 기반 시스템으로 구성됩니다:
|
||
|
|
|
||
|
|
```
|
||
|
|
SAM/
|
||
|
|
├── admin/ # Laravel 12 + Filament v4 (관리자 패널, 점차 deprecated)
|
||
|
|
├── api/ # Laravel 12 REST API (백엔드)
|
||
|
|
├── mng/ # Laravel 12 + Plain Blade/Tailwind (운영 관리자 패널)
|
||
|
|
├── react/ # Next.js 15 프론트엔드
|
||
|
|
├── 5130/ # 레거시 PHP 애플리케이션
|
||
|
|
└── docker/ # Docker 설정
|
||
|
|
```
|
||
|
|
|
||
|
|
## 애플리케이션별 상세
|
||
|
|
|
||
|
|
### admin/ - 관리자 패널
|
||
|
|
|
||
|
|
**기술 스택:**
|
||
|
|
- Laravel 12
|
||
|
|
- Filament v4
|
||
|
|
- TailwindCSS + Vite
|
||
|
|
|
||
|
|
**주요 기능:**
|
||
|
|
- 테넌트 관리
|
||
|
|
- 사용자 관리
|
||
|
|
- 권한 관리 (RBAC)
|
||
|
|
- 메뉴 관리
|
||
|
|
- 역할 및 부서 관리
|
||
|
|
|
||
|
|
**개발 명령어:**
|
||
|
|
```bash
|
||
|
|
composer dev # 전체 서비스 실행
|
||
|
|
php artisan serve # Laravel 서버
|
||
|
|
npm run dev # Vite HMR
|
||
|
|
```
|
||
|
|
|
||
|
|
### mng/ - Plain Laravel 관리자 패널
|
||
|
|
|
||
|
|
**기술 스택:**
|
||
|
|
- Laravel 12
|
||
|
|
- PHP 8.4
|
||
|
|
- Pure Blade + Tailwind CSS 3.x
|
||
|
|
- Sanctum (인증)
|
||
|
|
|
||
|
|
**주요 특징:**
|
||
|
|
- AI 없이 수정 가능한 단순 구조
|
||
|
|
- Filament 의존성 제거
|
||
|
|
- admin/ 기능 점진적 이식
|
||
|
|
- 좌측 사이드바 + 상단 헤더 레이아웃
|
||
|
|
|
||
|
|
**개발 명령어:**
|
||
|
|
```bash
|
||
|
|
php artisan serve # Laravel 서버
|
||
|
|
npm run dev # Vite HMR (Tailwind)
|
||
|
|
```
|
||
|
|
|
||
|
|
**현재 진행 상황:**
|
||
|
|
- ✅ Phase 1: 인증 시스템 (로그인/로그아웃)
|
||
|
|
- ✅ Phase 2: 레이아웃 구조 (sidebar + header)
|
||
|
|
- ✅ Phase 3: 테넌트 선택 기능
|
||
|
|
- 🔄 Phase 4: 시스템 관리 메뉴 (admin/ 이식)
|
||
|
|
|
||
|
|
### 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
|
||
|
|
- React 19.2.0
|
||
|
|
- 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. `ApiKeyMiddleware` - API Key 검증
|
||
|
|
3. `CheckSwaggerAuth` - Swagger 인증 체크
|
||
|
|
4. `CorsMiddleware` - CORS 처리
|
||
|
|
5. `CheckPermission` - 권한 검증
|
||
|
|
6. `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']);
|
||
|
|
// ...
|
||
|
|
});
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
## 공유 모델 구조
|
||
|
|
|
||
|
|
`shared/Models/` 디렉토리 구조:
|
||
|
|
- **Members/** - 사용자 및 테넌트 관리
|
||
|
|
- **Products/** - 제품 카탈로그 및 BOM
|
||
|
|
- **Materials/** - 자재 사양 및 재고
|
||
|
|
- **Orders/** - 주문 처리 워크플로우
|
||
|
|
- **Tenants/** - 멀티테넌트 설정
|
||
|
|
- **Commons/** - 공유 유틸리티 및 공통 데이터
|
||
|
|
|
||
|
|
## Docker 설정
|
||
|
|
|
||
|
|
**위치**: `docker/` 디렉토리
|
||
|
|
|
||
|
|
### 서비스 구성
|
||
|
|
|
||
|
|
**docker-compose.yml**에 정의된 5개 서비스:
|
||
|
|
|
||
|
|
1. **nginx** - 리버스 프록시 서버
|
||
|
|
- 포트: 80
|
||
|
|
- 도메인: `api.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. **admin** - Laravel 12 Admin 패널
|
||
|
|
- 이미지: `php:8.4-fpm`
|
||
|
|
- Filament v4 지원
|
||
|
|
- Supervisor로 nginx + php-fpm 동시 실행
|
||
|
|
|
||
|
|
4. **react** - Next.js 15 프론트엔드
|
||
|
|
- 이미지: `node:20-alpine`
|
||
|
|
- 포트: 3000 (내부)
|
||
|
|
- HMR 지원 (WebSocket)
|
||
|
|
|
||
|
|
5. **mysql** - MySQL 8.0 데이터베이스
|
||
|
|
- 포트: 3306
|
||
|
|
- 데이터베이스: `samdb`
|
||
|
|
- 사용자: `samuser` / `sampass`
|
||
|
|
|
||
|
|
### 네트워크 구조
|
||
|
|
|
||
|
|
```
|
||
|
|
samnet (bridge network)
|
||
|
|
├── nginx (리버스 프록시)
|
||
|
|
├── api (Laravel API)
|
||
|
|
├── admin (Laravel Admin)
|
||
|
|
├── react (Next.js)
|
||
|
|
└── mysql (데이터베이스)
|
||
|
|
```
|
||
|
|
|
||
|
|
### 도메인 매핑
|
||
|
|
|
||
|
|
| 도메인 | 대상 서비스 | 포트 | 용도 |
|
||
|
|
|--------|-----------|------|------|
|
||
|
|
| `api.sam.kr` | api (Laravel) | 80 | REST API |
|
||
|
|
| `admin.sam.kr` | admin (Laravel) | 80 | 관리자 패널 |
|
||
|
|
| `dev.sam.kr` | react (Next.js) | 3000 | 프론트엔드 |
|
||
|
|
|
||
|
|
### 주요 설정 파일
|
||
|
|
|
||
|
|
**nginx/nginx.conf**
|
||
|
|
- 리버스 프록시 설정
|
||
|
|
- 보안 규칙 (경로 탐색, User-Agent 필터링)
|
||
|
|
- WebSocket 지원 (Next.js HMR)
|
||
|
|
|
||
|
|
**api/Dockerfile, admin/Dockerfile**
|
||
|
|
- PHP 8.4-fpm 기반
|
||
|
|
- Composer 2 포함
|
||
|
|
- Supervisor 설정
|
||
|
|
|
||
|
|
**react/Dockerfile**
|
||
|
|
- Node.js 20 Alpine
|
||
|
|
- Next.js 15 개발 서버
|
||
|
|
|
||
|
|
**mysql/init.sql**
|
||
|
|
- 초기 데이터베이스 설정
|
||
|
|
|
||
|
|
## 저장소 구조
|
||
|
|
|
||
|
|
이 프로젝트는 **3개의 독립적인 Git 저장소**로 구성됩니다:
|
||
|
|
|
||
|
|
1. **api/** - API 프로젝트 저장소
|
||
|
|
2. **admin/** - 관리자 패널 저장소
|
||
|
|
3. **react/** - Next.js 프론트엔드 저장소
|
||
|
|
|
||
|
|
각 저장소는 독립적으로 운영되며:
|
||
|
|
- 개별 Git 히스토리 및 브랜치
|
||
|
|
- 독립적인 환경 설정 (`.env` 파일)
|
||
|
|
- 독립적인 의존성 및 빌드 프로세스
|
||
|
|
|
||
|
|
## 관련 문서
|
||
|
|
|
||
|
|
- [API 개발 규칙](./api_rules.md)
|
||
|
|
- [데이터베이스 스키마](./database_schema.md)
|
||
|
|
- [보안 가이드](./security.md)
|
||
|
|
- [Git 컨벤션](./git_conventions.md)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
**최종 업데이트**: 2025-11-18 (PHP 8.4, Filament v4, Next.js 15 반영)
|