권혁성
d4e5f62413
- system/overview.md: 전체 아키텍처 개요 - system/api-structure.md: API 구조 (220 모델, 1027 엔드포인트, 18 라우트 도메인) - system/react-structure.md: React 구조 (249 페이지, 612 컴포넌트) - system/mng-structure.md: MNG 구조 (171 컨트롤러, 436 Blade 뷰) - system/docker-setup.md: Docker 7 컨테이너 구성 - system/database/README.md + 9개 도메인 스키마 (270+ 테이블) - core, hr, sales, production, finance, boards, files, system, erp-analysis Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
159 lines
4.9 KiB
Markdown
159 lines
4.9 KiB
Markdown
# 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) |