# SAM 시스템 개요

> **최종 갱신**: 2026-02-27
> **상태**: Phase 1-B 작성

---

## 1. 프로젝트 개요

**SAM** (Smart Automation Management) — 블라인드/스크린 제조업체용 ERP/MES 통합 시스템

| 항목 | 내용 |
|------|------|
| 서비스명 | SAM |
| 회사명 | (주)코드브릿지엑스 |
| 아키텍처 | Multi-tenant (tenant_id 기반 데이터 격리) |
| DB | MySQL 8.0 (단일 DB `samdb`, 통계 `sam_stat`) |
| 레거시 | 5130.co.kr (PHP 7.3) → SAM으로 마이그레이션 중 |

---

## 2. 어플리케이션 구조

```
SAM/
├── api/       Laravel 12 REST API (PHP 8.4)
├── mng/       Laravel 12 관리자 패널 (PHP 8.4, HTMX + DaisyUI)
├── react/     Next.js 15 사용자 프론트엔드 (React 19)
├── design/    디자인 시스템 (Vite, Storybook)
├── 5130/      레거시 시스템 (PHP 7.3)
├── sales/     영업자 사이트 (추후 개발)
├── docs/      기술 문서
├── planning/  기획 문서
└── docker/    Docker 설정
```

### 앱별 역할

| 앱 | 역할 | 기술 스택 | Git 저장소 |
|----|------|----------|-----------|
| **api** | REST API 서버, DB 마이그레이션 관리 | Laravel 12, PHP 8.4, Sanctum, Swagger | 독립 |
| **mng** | 관리자 패널 (admin.sam.kr 포함) | Laravel 12, PHP 8.4, HTMX, DaisyUI, Vite 7 | 독립 |
| **react** | 사용자 프론트엔드 | Next.js 15, React 19, Tailwind v4, Zustand | 독립 |
| **design** | 디자인 시스템/컴포넌트 | Vite | 독립 |

### 앱 간 관계

```
react (dev.sam.kr)  ──API 호출──→  api (api.sam.kr)  ←──DB 공유──→  mng (mng.sam.kr)
                                         │
                                    MySQL (samdb)
                                         │
                                   5130 (chandj DB)
```

- **api**: DB 마이그레이션 유일 관리자. 모든 테이블 정의는 api에서만.
- **mng**: 자체 모델 보유 (185개), DB 마이그레이션 없음. api와 동일 DB 사용.
- **react**: Server Actions로 api 호출. DB 직접 접근 없음.

---

## 3. 기술 스택 상세

### api/ (REST API)

| 항목 | 상세 |
|------|------|
| Framework | Laravel 12 |
| PHP | 8.4+ |
| 인증 | Sanctum (Access 120분, Refresh 7일) |
| 권한 | Spatie Permission (RBAC) |
| API 문서 | L5-Swagger (OpenAPI) |
| 큐 | Database Driver |
| 캐시 | Database Driver |
| 규모 | 모델 205, 서비스 179, 컨트롤러 131, FormRequest 271 |
| 마이그레이션 | 458개 (메인 437 + 통계 21) |
| API 도메인 | 18개 라우트 파일, ~876 엔드포인트 |

### react/ (프론트엔드)

| 항목 | 상세 |
|------|------|
| Framework | Next.js 15 (App Router, Turbopack) |
| React | 19 |
| 스타일 | Tailwind CSS v4 |
| UI | shadcn/ui (Radix 기반) 55개 컴포넌트 |
| 상태관리 | Zustand 5 (13 stores) |
| 폼 | React Hook Form + Zod |
| i18n | next-intl (ko, en, ja) |
| 차트 | Recharts |
| PDF | jspdf + Puppeteer |
| 규모 | 페이지 249, 컴포넌트 612, Server Actions 91 |

### mng/ (관리자 패널)

| 항목 | 상세 |
|------|------|
| Framework | Laravel 12 (Blade + HTMX) |
| PHP | 8.4+ |
| 프론트 | HTMX 2 + DaisyUI 5 + Tailwind 3 |
| 빌드 | Vite 7 |
| PDF | TCPDF + FPDI |
| Excel | PhpSpreadsheet |
| 규모 | 컨트롤러 171, 블레이드 436, 모델 185, 서비스 98 |

---

## 4. 핵심 아키텍처 패턴

### Multi-tenancy
- 모든 테넌트 데이터는 `tenant_id`로 격리
- `BelongsToTenant` 트레이트/스코프 필수
- 글로벌 테이블 (users, plans 등)은 예외

### Service-First
- 비즈니스 로직은 반드시 Service 클래스에
- Controller는 라우팅 + FormRequest 검증만 담당
- `ApiResponse::handle()` 통일 응답 포맷

### API 인증
- 글로벌: API Key (모든 요청)
- 사용자: Sanctum Bearer Token
- 내부: HMAC (mng ↔ api 내부 통신)

### FormRequest
- Controller에서 직접 검증 금지
- 모든 입력 검증은 FormRequest 클래스에서

---

## 5. 환경 구성

| 환경 | 도메인 | 위치 | 비고 |
|------|--------|------|------|
| **로컬** | *.sam.kr | Docker (macOS) | 개발용 |
| **개발** | codebridge-x.com | 114.203.209.83 | react만 |
| **스테이지+운영** | TBD | 211.117.60.189 | api, mng, react |

### 로컬 도메인

| 도메인 | 서비스 | 포트 |
|--------|--------|------|
| `dev.sam.kr` | react (Next.js) | 3000 |
| `api.sam.kr` | api (Laravel) | 9000 (FastCGI) |
| `mng.sam.kr` | mng (Laravel) | 9000 (FastCGI) |
| `admin.sam.kr` | mng (동일) | 9000 (FastCGI) |
| `design.sam.kr` | design (Vite) | 3002 |
| `5130.sam.kr` | 5130 (레거시) | 9000 (FastCGI) |

---

## 관련 문서

- **DB 스키마**: [database/README.md](database/README.md)
- **API 구조**: [api-structure.md](api-structure.md)
- **React 구조**: [react-structure.md](react-structure.md)
- **MNG 구조**: [mng-structure.md](mng-structure.md)
- **Docker 설정**: [docker-setup.md](docker-setup.md)
- **보안 정책**: [security-policy.md](security-policy.md)