# 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 반영)