98 lines
4.2 KiB
Markdown
98 lines
4.2 KiB
Markdown
# SOKUREE 플랫폼 모듈화 아키텍처 가이드 (Modular Architecture Guide)
|
|
|
|
본 문서는 SOKUREE 플랫폼의 "느슨한 결합(Loose Coupling)"과 "높은 응집도(High Cohesion)" 원칙을 실현하기 위한 모듈화 아키텍처 설계 및 개발 가이드를 제공합니다.
|
|
|
|
---
|
|
|
|
## 1. 아키텍처 설계 원칙
|
|
|
|
### 1.1 Minimal Platform Scope (최소 플랫폼 범위)
|
|
플랫폼(Core/Platform)은 전체 시스템의 뼈대만 관리하며, 각 비즈니스 모듈의 내부 구현에는 관여하지 않습니다.
|
|
- **플랫폼 역할**: 전체 레이아웃(헤더, 사이드바), 인증 및 세션 관리, 동적 모듈 로딩, 공통 디자인 토큰 제공.
|
|
- **모듈 역할**: 비즈니스 로직, 독립적인 UI 구성, 자체 라우팅 정보 정의.
|
|
|
|
### 1.2 Inversion of Control (제어의 역전)
|
|
플랫폼이 모듈을 직접 import 하여 배치하는 대신, 모듈이 자신의 정보를 플랫폼에 주입(Injection)하는 방식으로 동작합니다. 이를 통해 새로운 모듈 추가 시 플랫폼 코드 수정을 최소화합니다.
|
|
|
|
---
|
|
|
|
## 2. 폴더 구조 (Project Structure)
|
|
|
|
```text
|
|
src/
|
|
├── core/ # 플랫폼의 뇌 (핵심 비즈니스 규칙 및 인터페이스)
|
|
│ └── types.ts # IModuleDefinition 등 공통 타입 정의
|
|
├── platform/ # 플랫폼의 뼈대 (UI 레이아웃 및 인프라)
|
|
│ ├── App.tsx # 메인 앱 엔트리 및 레이아웃 구성
|
|
│ ├── ModuleLoader.tsx # 모듈 라우트를 동적으로 결합하는 컴포넌트
|
|
│ └── styles/
|
|
│ └── global.css # CSS Variables (Design Tokens) 선언
|
|
├── modules/ # 비즈니스 모듈 (독립적인 영역)
|
|
│ ├── asset/ # 자산 관리 모듈
|
|
│ ├── cctv/ # CCTV 모듈
|
|
│ └── ...
|
|
└── shared/ # 공통 유틸리티 및 컴포넌트 (선택 사항)
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 핵심 인터페이스 (Core Interfaces)
|
|
|
|
### 3.1 IModuleDefinition
|
|
모듈이 플랫폼에 등록되기 위해 반드시 준수해야 하는 규격입니다.
|
|
|
|
```typescript
|
|
export interface IModuleDefinition {
|
|
moduleName: string; // 모듈 식별자 (Global Unique)
|
|
basePath: string; // 모듈의 기본 URL 경로 (예: '/asset')
|
|
routes: IModuleRoute[]; // 모듈 내부의 세부 라우팅 정보
|
|
requiredRoles?: string[]; // (Optional) 접근을 위한 권한 정보
|
|
}
|
|
```
|
|
|
|
### 3.2 IModuleRoute
|
|
모듈 내 개별 페이지 및 메뉴 구성을 위한 정보입니다.
|
|
|
|
```typescript
|
|
export interface IModuleRoute {
|
|
path: string; // basePath 이후의 상대 경로
|
|
element: ReactNode; // 렌더링할 컴포넌트
|
|
label?: string; // 메뉴에 표시될 이름
|
|
icon?: ReactNode; // 메뉴 아이콘
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. 디자인 시스템 (Design Tokens)
|
|
|
|
플랫폼은 모듈의 스타일 라이브러리 선택권(Tailwind, CSS-in-JS 등)을 존중하면서도 통일성을 유지하기 위해 **CSS Variables**를 사용합니다.
|
|
|
|
- **위치**: `src/platform/styles/global.css`
|
|
- **사용 방법**:
|
|
```css
|
|
/* 모듈 내부 CSS */
|
|
.my-component {
|
|
background-color: var(--sokuree-brand-primary);
|
|
padding: var(--sokuree-spacing-md);
|
|
border-radius: var(--sokuree-radius-md);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 새 모듈 추가 방법 (Quick Start)
|
|
|
|
1. **모듈 정의 생성**: `src/modules/[moduleName]/index.ts` (또는 유사한 위치)에서 `IModuleDefinition` 객체를 내보냅니다.
|
|
2. **라우트 정의**: 모듈 내부에서 사용할 페이지들을 `routes` 배열에 추가합니다.
|
|
3. **플랫폼 등록**: `src/platform/App.tsx`의 `sampleModules` (또는 실제 서버에서 받아온 모듈 리스트)에 위 객체를 추가합니다.
|
|
4. **확인**: 사이드바 메뉴에 자동으로 노출되며 해당 경로 접근 시 정상 렌더링되는지 확인합니다.
|
|
|
|
---
|
|
|
|
## 6. 향후 고려 사항
|
|
|
|
- **Dynamic Import**: 모듈이 많아질 경우 `React.lazy`를 통한 코드 분할(Code Splitting) 적용.
|
|
- **Error Boundary**: 특정 모듈의 런타임 에러가 플랫폼 전체로 전파되지 않도록 `ModuleLoader` 내부에 에러 처리 로직 강화.
|
|
- **Shared Context**: 플랫폼이 제공하는 사용자 정보 등을 모듈이 쉽게 꺼내 쓸 수 있는 Hook 제공.
|