# SAM ERP 멀티테넌트 모듈 분리 아키텍처

> 작성일: 2026-03-18
> 상태: 프론트엔드 Phase 0~3 완료 / 백엔드 작업 필요

---

## 0. 왜 산업군별 모듈 분리가 필요한가 (협의 필요)

### 현재 상황: 하나의 ERP, 다른 업종의 고객사

SAM ERP는 **하나의 코드베이스**로 여러 회사(테넌트)에 서비스를 제공합니다.
그런데 고객사마다 업종이 다릅니다:

```
경동 → 셔터 제조업 (MES) → 생산관리, 품질관리, 차량관리가 필요
주일 → 건설업           → 시공관리, 차량관리가 필요
A사  → 유통/서비스업     → 공통 ERP(회계/인사/영업)만 필요
```

현재는 **모든 테넌트에게 모든 메뉴가 보입니다.**
경동 직원에게 시공관리 메뉴가 보이고, 주일 직원에게 생산관리 메뉴가 보입니다.
→ 사용하지 않는 메뉴가 노출되어 혼란을 주고, 대시보드에도 불필요한 섹션이 나타남.

### 제안: 업종(industry) 기반 모듈 ON/OFF

```
┌─────────────────────────────────────────────────┐
│                SAM ERP (공통)                     │
│  회계 · 인사 · 영업 · 결재 · 게시판 · 설정        │
├──────────┬──────────┬───────────┬───────────────┤
│ 생산관리  │ 품질관리  │ 시공관리   │ 차량관리       │
│ (MES)    │          │ (건설)    │ (선택)        │
├──────────┴──────────┼───────────┤               │
│   셔터 MES 업종      │  건설 업종  │               │
│   (경동)            │  (주일)    │               │
└─────────────────────┴───────────┴───────────────┘
```

- **공통 모듈**: 모든 테넌트가 사용 (회계, 인사, 영업 등)
- **업종 모듈**: 테넌트의 업종에 따라 자동으로 켜짐/꺼짐
- **선택 모듈**: 업종과 관계없이 개별 선택 가능 (차량관리 등)

### 협의가 필요한 부분

이 구조로 가려면 다음 사항의 합의가 필요합니다:

#### 1) 업종 분류 체계
현재 프론트엔드에 하드코딩된 매핑:

| 업종 코드 | 의미 | 활성 모듈 |
|-----------|------|-----------|
| `shutter_mes` | 셔터 제조 (MES) | 생산관리 + 품질관리 + 차량관리 |
| `construction` | 건설업 | 시공관리 + 차량관리 |

**Q. 이 분류가 맞는지? 추가할 업종이 있는지?**
예: 일반 제조업, 도소매업, 서비스업 등

#### 2) 모듈 경계
현재 정의된 모듈 단위:

| 모듈 | 포함 기능 | 비고 |
|------|----------|------|
| 공통 ERP | 대시보드, 회계, 인사, 영업, 결재, 게시판, 설정 등 | 항상 ON |
| 생산관리 | 생산지시, 작업지시, 작업일보 | 경동 전용 |
| 품질관리 | 설비점검, 수리요청, 검사 | 경동 전용 |
| 시공관리 | 프로젝트, 계약, 기성, 시공일보 | 주일 전용 |
| 차량관리 | 차량등록, 운행일지, 지게차 | 선택적 |

**Q. 모듈 단위 범위가 적절한지? 분리/통합이 필요한 모듈이 있는지?**

#### 3) 활성화 방식
| 방식 | 장점 | 단점 |
|------|------|------|
| **A. 업종 자동** (현재) | 간단, 실수 방지 | 유연성 낮음 |
| **B. 모듈 개별 선택** (향후) | 유연함 | 관리 복잡 |
| **C. 업종 기본값 + 개별 재정의** | 균형 | 구현 복잡도 중간 |

**Q. 어떤 방식을 채택할 것인지?**
현재 프론트엔드는 A 방식으로 구현, B/C로 확장 가능하도록 설계됨.

#### 4) 적용 시점과 범위
- 백엔드에서 `tenant.options.industry` 값만 세팅하면 즉시 동작
- 값을 안 넣으면 기존과 100% 동일 (부작용 제로)
- **Q. 언제부터, 어떤 테넌트부터 적용할 것인지?**

---

## 1. 개요

### 목표
하나의 SAM ERP 코드베이스에서 **테넌트(회사)별로 필요한 모듈만 활성화**하여,
불필요한 메뉴·페이지·대시보드 섹션을 숨기는 구조.

### 현재 테넌트별 모듈 구성
| 업종 코드 | 테넌트 예시 | 활성 모듈 |
|-----------|------------|-----------|
| `shutter_mes` | 경동 | 생산관리, 품질관리, 차량관리 |
| `construction` | 주일 | 시공관리, 차량관리 |
| (미설정) | 기타 모든 테넌트 | **전체 모듈 활성화 (기존과 동일)** |

### 안전 원칙
```
tenant.options.industry가 설정되지 않은 테넌트 → 모든 기능 그대로 사용 가능
= 기존 동작 100% 유지, 부작용 제로
```

---

## 2. 프론트엔드 구조 (완료)

### 파일 구조
```
src/modules/
├── types.ts           # ModuleId 타입 정의
├── tenant-config.ts   # 업종→모듈 매핑 (resolveEnabledModules)
└── index.ts           # 모듈 레지스트리 (라우트 매핑, 대시보드 섹션)

src/hooks/
└── useModules.ts      # React 훅: isEnabled(), isRouteAllowed(), tenantIndustry
```

### 모듈 ID 목록
| ModuleId | 이름 | 소유 라우트 | 대시보드 섹션 |
|----------|------|------------|--------------|
| `common` | 공통 ERP | /dashboard, /accounting, /sales, /hr, /approval, /settings 등 | 전부 |
| `production` | 생산관리 | /production | dailyProduction, unshipped |
| `quality` | 품질관리 | /quality | - |
| `construction` | 시공관리 | /construction | construction |
| `vehicle-management` | 차량관리 | /vehicle-management, /vehicle | - |

### 프론트엔드 동작 흐름
```
1. 로그인 → authStore에 tenant 정보 저장
2. useModules() 훅이 tenant.options.industry 읽음
3. industry 값으로 INDUSTRY_MODULE_MAP 조회 → 활성 모듈 목록 결정
4. 각 컴포넌트에서 isEnabled('production') 등으로 분기
```

### 적용된 영역

#### A. CEO 대시보드
- **섹션 필터링**: 비활성 모듈의 대시보드 섹션 자동 제외
- **API 호출 차단**: 비활성 모듈의 API는 호출하지 않음 (null endpoint)
- **설정 팝업**: 비활성 모듈 섹션은 설정에서도 안 보임
- **캘린더**: 비활성 모듈의 일정 유형 필터 숨김
- **요약 네비**: 비활성 섹션 자동 제외

#### B. 라우트 접근 제어
- `/production/*`, `/quality/*`, `/construction/*` 등 전용 라우트는 모듈 비활성 시 접근 차단
- `/sales/*/production-orders` 같은 공통 라우트 내 모듈 의존 페이지는 명시적 가드 적용

#### C. 사이드바 메뉴
- 비활성 모듈의 메뉴 항목 숨김 (isRouteAllowed 기반)

---

## 3. 백엔드 필요 작업

### 3.1 tenants 테이블 options 필드에 industry 추가
**우선순위: 🔴 필수**

현재 프론트엔드는 `tenant.options.industry` 값을 읽어서 모듈을 결정합니다.
이 값이 백엔드에서 내려와야 실제로 동작합니다.

```php
// tenants 테이블의 options JSON 컬럼에 industry 추가
// 예시 데이터:
{
    "industry": "shutter_mes"    // 경동: 셔터 MES
}
{
    "industry": "construction"   // 주일: 건설
}
// 다른 테넌트: industry 키 없음 → 프론트에서 전체 모듈 활성화
```

**작업 내용:**
1. `tenants` 테이블의 `options` JSON 컬럼에 `industry` 키 추가 (마이그레이션 불필요, JSON이므로)
2. 경동 테넌트: `options->industry = 'shutter_mes'`
3. 주일 테넌트: `options->industry = 'construction'`
4. 테넌트 정보 API 응답에 `options.industry` 포함 확인

**확인 포인트:**
- 프론트엔드에서 `authStore.currentUser.tenant.options.industry`로 접근
- 현재 로그인 API(`/api/v1/auth/me` 또는 유사)의 응답에서 tenant.options가 포함되는지 확인
- 포함 안 되면 응답에 추가 필요

### 3.2 (선택) 테넌트 관리 화면에서 industry 설정 UI
**우선순위: 🟡 선택**

관리자가 테넌트별 업종을 설정할 수 있는 UI. 급하지 않음 — DB 직접 수정으로 충분.

### 3.3 (Phase 2 예정) 명시적 모듈 목록 API
**우선순위: 🟢 향후**

현재는 `industry` → 프론트엔드 하드코딩 매핑으로 모듈 결정.
향후 백엔드에서 직접 모듈 목록을 내려주면 더 유연해짐.

```php
// tenant.options 예시 (Phase 2)
{
    "industry": "shutter_mes",
    "modules": ["production", "quality", "vehicle-management"]  // 명시적 목록
}
```

프론트엔드는 이미 이 구조를 지원하도록 준비되어 있음:
```typescript
// src/modules/tenant-config.ts
export function resolveEnabledModules(options) {
  // Phase 2: 백엔드가 명시적 모듈 목록 제공 → 우선 사용
  if (explicitModules && explicitModules.length > 0) {
    return explicitModules;
  }
  // Phase 1: industry 기반 기본값 (현재)
  if (industry) {
    return INDUSTRY_MODULE_MAP[industry] ?? [];
  }
  return [];
}
```

---

## 4. 업종별 모듈 매핑 (프론트엔드 하드코딩)

```typescript
// src/modules/tenant-config.ts
const INDUSTRY_MODULE_MAP: Record<string, ModuleId[]> = {
  shutter_mes: ['production', 'quality', 'vehicle-management'],
  construction: ['construction', 'vehicle-management'],
};
```

새로운 업종 추가 시:
1. 여기에 매핑 추가
2. 필요하면 `ModuleId` 타입에 새 모듈 ID 추가
3. `MODULE_REGISTRY` (src/modules/index.ts)에 라우트/대시보드 섹션 등록

---

## 5. 핵심 코드 패턴

### 기본 사용법
```typescript
import { useModules } from '@/hooks/useModules';

function MyComponent() {
  const { isEnabled, tenantIndustry } = useModules();

  // 안전 장치: industry 미설정이면 모든 기능 활성
  const moduleAware = !!tenantIndustry;

  if (moduleAware && !isEnabled('production')) {
    return <div>생산관리 모듈이 비활성화되어 있습니다.</div>;
  }

  // 생산관리 기능 렌더링...
}
```

### 크로스 모듈 임포트 규칙
```
✅ Common → Common              (자유)
✅ Tenant → Common              (자유)
✅ Common → Tenant (래퍼 경유)   (src/lib/api/에서 MODULE_SEPARATION_OK 주석과 함께)
❌ Common → Tenant (직접)       (scripts/verify-module-separation.sh가 검출)
❌ Tenant → Tenant              (금지, dynamic import만 허용)
```

---

## 6. 구현 이력

| Phase | 내용 | 커밋 | 상태 |
|-------|------|------|------|
| Phase 0 | 크로스 모듈 의존성 해소 | `a99c3b39` | ✅ 완료 |
| Phase 1 | 모듈 레지스트리 + 라우트 가드 | `0a65609e` | ✅ 완료 |
| Phase 2 | CEO 대시보드 모듈 디커플링 | `46501214` | ✅ 완료 |
| Phase 3 | 물리적 분리 (경계 마커, 검증, 가드, 문서) | `4b8ca09e` | ✅ 완료 |

---

## 7. 테스트 시나리오

### 테스트 방법
백엔드에서 `tenant.options.industry`를 설정한 후:

| 시나리오 | 예상 결과 |
|----------|----------|
| industry 미설정 테넌트 로그인 | 기존과 완전 동일 (모든 메뉴/기능 표시) |
| `shutter_mes` 테넌트 로그인 | 시공관리 메뉴 숨김, 대시보드 시공 섹션 안 보임 |
| `construction` 테넌트 로그인 | 생산/품질 메뉴 숨김, 대시보드 생산 섹션 안 보임 |
| `shutter_mes`에서 `/construction` 직접 접근 | 접근 차단 메시지 표시 |
| `construction`에서 `/production` 직접 접근 | 접근 차단 메시지 표시 |

### 롤백 방법
문제 발생 시 DB에서 `tenant.options.industry` 값만 제거하면 즉시 원복.
프론트엔드 코드 변경 불필요.

---

## 8. 향후 로드맵

```
현재 (Phase 1)                     향후 (Phase 2)                    최종 (Phase 3)
┌─────────────────┐          ┌──────────────────────┐          ┌─────────────────────┐
│ industry 하드코딩 │    →    │ 백엔드 modules 목록    │    →    │ JSON 스키마 기반      │
│ 매핑으로 모듈 결정 │          │ API에서 직접 수신       │          │ 동적 페이지 조립       │
└─────────────────┘          └──────────────────────┘          └─────────────────────┘
```

- **Phase 2**: `tenant.options.modules = ["production", "quality"]` 형태로 백엔드에서 명시적 모듈 목록 전달 → 업종 매핑 테이블 불필요
- **Phase 3**: 각 모듈의 페이지 구성을 JSON 스키마로 정의 → 코드 변경 없이 테넌트별 화면 커스터마이징