10. 모듈 분리 아키텍처

대상: 프론트엔드 개발자 최종 업데이트: 2026-03-20

번호	항목
10.1	개요
10.2	모듈 구조
10.3	핵심 패턴: moduleAware
10.4	라우트 가드
10.5	크로스 모듈 임포트 규칙
10.6	적용 영역

10.1 개요

SAM ERP는 멀티테넌트 시스템으로, 테넌트별 업종(tenant.options.industry)에 따라 필요한 모듈만 활성화합니다.

핵심 원칙: industry 미설정 시 모든 모듈 활성화 (기존 동작 100% 유지)

테넌트	industry	활성 모듈
경동	`manufacturing`	production, quality
주일	`construction`	construction
미설정	-	전체 (기존 호환)

10.2 모듈 구조

파일 구조

src/modules/
  types.ts          # ModuleId, TenantIndustry, MODULE_REGISTRY
  tenant-config.ts  # INDUSTRY_MODULE_MAP (업종별 활성 모듈 매핑)
  index.ts          # getModuleForRoute, getEnabledDashboardSections

src/hooks/useModules.ts  # React Hook

ModuleId 목록

ModuleId	설명	라우트 접두사
`common`	공통 ERP	-
`production`	생산관리	`/production`
`quality`	품질관리	`/quality`
`construction`	시공관리	`/business/construction`
`vehicle-management`	차량관리	`/vehicle-management`

useModules Hook

const { isEnabled, tenantIndustry, enabledModules } = useModules();

// 특정 모듈 활성화 여부 확인
if (isEnabled('production')) {
  // 생산관리 관련 UI 표시
}

10.3 핵심 패턴: moduleAware

const { isEnabled, tenantIndustry } = useModules();
const moduleAware = !!tenantIndustry; // industry 미설정 -> false -> 전부 허용

if (!moduleAware) return allData; // 기존과 동일
return filteredData; // 모듈 기반 필터링

moduleAware = false -> 필터링 없음, 모든 기능 노출
moduleAware = true -> 테넌트 업종에 맞는 모듈만 노출

10.4 라우트 가드

라우트 기반 가드 (ModuleGuard)

/production/*, /quality/* 등 전용 라우트는 layout.tsx에서 자동 차단:

// src/app/[locale]/(protected)/production/layout.tsx
<ModuleGuard moduleId="production">
  {children}
</ModuleGuard>

명시적 가드

공통 라우트 내 모듈 의존 페이지는 직접 체크:

// /sales/*/production-orders 같은 공통 라우트 내 모듈 의존 페이지
if (tenantIndustry && !isEnabled('production')) {
  return <div>생산관리 모듈이 활성화되어 있지 않습니다.</div>;
}

10.5 크로스 모듈 임포트 규칙

방향	허용	비고
Common -> Tenant	직접 import 금지	`// MODULE_SEPARATION_OK` 주석 + 공유 래퍼만 허용
Tenant -> Common	자유	-
Tenant -> Tenant	금지	dynamic import만 허용

검증 스크립트: scripts/verify-module-separation.sh

MODULE.md 경계 마커

각 테넌트 모듈 디렉토리에 MODULE.md 파일로 모듈 경계 문서화:

src/components/production/MODULE.md
src/components/quality/MODULE.md
src/components/business/construction/MODULE.md
src/components/vehicle-management/MODULE.md

10.6 적용 영역

영역	적용 방식
CEO 대시보드	`moduleAware` 패턴으로 섹션 필터링
사이드바 메뉴	`isEnabled()` 체크로 메뉴 숨김
라우트 접근	ModuleGuard 또는 명시적 가드
API 호출	비활성 모듈 관련 API 호출 차단

3.8 KiB Raw Blame History