# 10. 모듈 분리 아키텍처

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

---

## 목차

| 번호 | 항목 |
|------|------|
| 10.1 | [개요](#101-개요) |
| 10.2 | [모듈 구조](#102-모듈-구조) |
| 10.3 | [핵심 패턴: moduleAware](#103-핵심-패턴-moduleaware) |
| 10.4 | [라우트 가드](#104-라우트-가드) |
| 10.5 | [크로스 모듈 임포트 규칙](#105-크로스-모듈-임포트-규칙) |
| 10.6 | [적용 영역](#106-적용-영역) |

---

## 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

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

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

---

## 10.3 핵심 패턴: moduleAware

```typescript
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에서 자동 차단:

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

### 명시적 가드

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

```typescript
// /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 호출 차단 |