sam-docs/architecture/system-overview.md

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 없이 수정 가능한 단순 구조
• 좌측 사이드바 + 상단 헤더 레이아웃

개발 명령어:

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에 실제 사용 버전 표시

기본 경로 그룹

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

---

최종 업데이트: 2025-12-26 (admin→mng 전환, Next.js 15.5.7, React 19.2.1 반영)