SamProject/sam-docs
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
614e90066f68a0a0990ac1814fbf1ac00fbac1d6
sam-docs/system/overview.md
권혁성 d4e5f62413 docs: [종합정비] Phase 1 시스템 현황 문서 14개 작성 
- 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>
2026-02-27 18:03:13 +09:00

4.9 KiB
Raw Blame History

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)

관련 문서