sam-react-prod/claudedocs/architecture/module-separation-guide.md

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

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

---

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 값을 읽어서 모듈을 결정합니다. 이 값이 백엔드에서 내려와야 실제로 동작합니다.

// 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 → 프론트엔드 하드코딩 매핑으로 모듈 결정. 향후 백엔드에서 직접 모듈 목록을 내려주면 더 유연해짐.

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

프론트엔드는 이미 이 구조를 지원하도록 준비되어 있음:

// 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. 업종별 모듈 매핑 (프론트엔드 하드코딩)

// 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. 핵심 코드 패턴

기본 사용법

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	물리적 분리 (경계 마커, 검증, 가드, 문서)	(미커밋)	✅ 완료

---

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 스키마로 정의 → 코드 변경 없이 테넌트별 화면 커스터마이징