sam-docs/architecture/system-overview.md

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)
• 메뉴 관리
• 역할 및 부서 관리

개발 명령어:

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/ 기능 점진적 이식
• 좌측 사이드바 + 상단 헤더 레이아웃

개발 명령어:

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 - 권한 매핑

라우팅 구조

기본 경로 그룹:

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 개발 규칙
• 데이터베이스 스키마
• 보안 가이드
• Git 컨벤션

---

최종 업데이트: 2025-11-18 (PHP 8.4, Filament v4, Next.js 15 반영)