# M-Project 모듈 아키텍처 문서

## 개요
리팩토링된 M-Project의 모듈 구조와 연결점을 설명하는 문서입니다.

---

## 전체 아키텍처

```
frontend/
├── index.html                 # 로그인 페이지
├── app.html                   # 통합 메인 애플리케이션
└── static/
    └── js/
        ├── core/              # 핵심 시스템 모듈
        │   ├── api.js         # API 통신 (기존)
        │   ├── permissions.js # 권한 관리 시스템 (신규)
        │   ├── router.js      # 라우팅 시스템 (예정)
        │   └── events.js      # 이벤트 시스템 (예정)
        ├── components/        # 재사용 가능한 UI 컴포넌트 (예정)
        ├── modules/           # 기능별 모듈 (예정)
        ├── utils/             # 유틸리티 함수들
        │   ├── date-utils.js  # 날짜 관련 유틸리티 (기존)
        │   └── image-utils.js # 이미지 관련 유틸리티 (기존)
        └── app.js             # 메인 애플리케이션 (신규)
```

---

## 핵심 모듈 상세

### 1. 권한 관리 시스템 (`core/permissions.js`)

#### 클래스: `PermissionManager`

**주요 기능:**
- 사용자 권한 체크
- UI 요소 권한 제어
- 동적 메뉴 생성
- 개별 권한 관리

**주요 메서드:**
```javascript
// 권한 체크
hasPermission(permission: string): boolean
hasAnyPermission(permissions: Array<string>): boolean
hasAllPermissions(permissions: Array<string>): boolean

// UI 제어
controlElement(selector: string, permission: string, action: string): void

// 메뉴 구성
getMenuConfig(): Array<MenuItem>

// 권한 관리
grantPermission(userId: number, permission: string, notes?: string): Promise
revokePermission(userId: number, permission: string, notes?: string): Promise
```

**연결점:**
- `app.js`에서 사용자 설정 시 초기화
- 모든 모듈에서 권한 체크 시 사용
- 전역 함수로 노출: `hasPermission()`, `controlElement()` 등

### 2. 메인 애플리케이션 (`app.js`)

#### 클래스: `App`

**주요 기능:**
- 애플리케이션 초기화
- 라우팅 관리
- 모듈 로딩
- UI 상태 관리

**주요 메서드:**
```javascript
// 초기화
init(): Promise<void>
checkAuth(): Promise<void>
loadAPIScript(): Promise<void>

// 라우팅
handleRouteChange(): Promise<void>
navigateTo(path: string): void
loadModule(module: string, action?: string): Promise<void>

// UI 관리
updateUserDisplay(): void
createNavigationMenu(): void
toggleSidebar(): void

// 모달 관리
showPasswordChangeModal(): void
hidePasswordChangeModal(): void
```

**연결점:**
- `permissions.js`와 연동하여 권한 기반 UI 구성
- `api.js`를 동적으로 로드하여 API 통신 활성화
- 각 모듈을 동적으로 로드하고 실행

---

## 데이터 흐름

### 1. 애플리케이션 시작 흐름

```mermaid
graph TD
    A[app.html 로드] --> B[App 클래스 초기화]
    B --> C[인증 확인]
    C --> D[API 스크립트 로드]
    D --> E[권한 시스템 초기화]
    E --> F[UI 초기화]
    F --> G[라우터 초기화]
    G --> H[대시보드 표시]
```

### 2. 권한 체크 흐름

```mermaid
graph TD
    A[권한 체크 요청] --> B{사용자 로그인?}
    B -->|No| C[권한 없음 반환]
    B -->|Yes| D{super_admin?}
    D -->|Yes| E[모든 권한 허용]
    D -->|No| F[개별 권한 확인]
    F --> G{개별 권한 존재?}
    G -->|Yes| H[개별 권한 값 반환]
    G -->|No| I[기본 권한 매트릭스 확인]
    I --> J[권한 결과 반환]
```

### 3. 모듈 로딩 흐름

```mermaid
graph TD
    A[라우트 변경] --> B[모듈명 추출]
    B --> C{모듈 로드됨?}
    C -->|Yes| D[모듈 실행]
    C -->|No| E[모듈 스크립트 로드]
    E --> F[모듈 인스턴스 생성]
    F --> G[모듈 캐시 저장]
    G --> D[모듈 실행]
    D --> H[콘텐츠 렌더링]
```

---

## 이벤트 시스템 (예정)

### EventBus 클래스

**목적:** 모듈 간 느슨한 결합을 위한 이벤트 기반 통신

**주요 이벤트:**
```javascript
// 사용자 관련
'user.login'           // 사용자 로그인
'user.logout'          // 사용자 로그아웃
'user.permission.changed' // 권한 변경

// 데이터 관련
'issue.created'        // 부적합 사항 생성
'issue.updated'        // 부적합 사항 업데이트
'issue.deleted'        // 부적합 사항 삭제
'project.created'      // 프로젝트 생성
'project.updated'      // 프로젝트 업데이트

// UI 관련
'modal.open'           // 모달 열기
'modal.close'          // 모달 닫기
'notification.show'    // 알림 표시
```

**사용 예시:**
```javascript
// 이벤트 발생
eventBus.emit('issue.created', { id: 123, title: '새 부적합' });

// 이벤트 수신
eventBus.on('issue.created', (data) => {
    console.log('새 부적합 사항:', data);
    refreshIssueList();
});
```

---

## 상태 관리 시스템 (예정)

### StateManager 클래스

**목적:** 애플리케이션 전역 상태 관리

**상태 구조:**
```javascript
{
    user: {
        id: number,
        username: string,
        role: string,
        permissions: Array<string>
    },
    projects: Array<Project>,
    issues: Array<Issue>,
    currentProject: Project | null,
    ui: {
        sidebarCollapsed: boolean,
        currentPage: string,
        loading: boolean
    }
}
```

**사용 예시:**
```javascript
// 상태 설정
stateManager.setState('user', userData);

// 상태 구독
stateManager.subscribe('user', (user) => {
    updateUserDisplay(user);
});

// 상태 조회
const currentUser = stateManager.getState('user');
```

---

## 모듈 개발 가이드

### 1. 새 모듈 생성 규칙

**파일 구조:**
```
modules/
└── [module-name]/
    ├── [module-name].js     # 메인 모듈 파일
    ├── [module-name].css    # 모듈 전용 스타일 (선택)
    └── components/          # 모듈 내 컴포넌트 (선택)
```

**모듈 클래스 템플릿:**
```javascript
class ModuleNameModule {
    constructor() {
        this.name = 'module-name';
        this.permissions = ['module.view']; // 필요한 권한
    }

    // 필수 메서드: 콘텐츠 렌더링
    async render(action = 'list') {
        // 권한 체크
        if (!hasPermission(this.permissions[0])) {
            return '<div class="text-center p-8">접근 권한이 없습니다.</div>';
        }

        // 액션별 처리
        switch (action) {
            case 'list':
                return await this.renderList();
            case 'create':
                return await this.renderCreate();
            case 'edit':
                return await this.renderEdit();
            default:
                return await this.renderList();
        }
    }

    async renderList() {
        // 목록 화면 HTML 반환
        return `<div>목록 화면</div>`;
    }

    async renderCreate() {
        // 생성 화면 HTML 반환
        return `<div>생성 화면</div>`;
    }

    async renderEdit() {
        // 편집 화면 HTML 반환
        return `<div>편집 화면</div>`;
    }

    // 이벤트 핸들러 등록
    bindEvents() {
        // 이벤트 리스너 등록
    }

    // 정리 작업
    destroy() {
        // 이벤트 리스너 제거 등
    }
}

// 전역 등록 (필수)
window.ModuleNameModule = ModuleNameModule;
```

### 2. 모듈 간 통신

**권장 방법:**
1. **EventBus 사용** (모듈 간 느슨한 결합)
2. **StateManager 사용** (공유 상태 관리)
3. **API 직접 호출** (데이터 조회/수정)

**비권장 방법:**
- 직접적인 모듈 참조
- 전역 변수 사용
- DOM 직접 조작으로 통신

### 3. 권한 체크 패턴

**UI 요소 제어:**
```javascript
// 버튼 표시/숨김
controlElement('.create-btn', 'issues.create', 'show');

// 입력 필드 활성/비활성
controlElement('.edit-form input', 'issues.edit', 'disable');
```

**조건부 렌더링:**
```javascript
if (hasPermission('issues.delete')) {
    html += '<button class="delete-btn">삭제</button>';
}
```

**다중 권한 체크:**
```javascript
if (hasAnyPermission(['issues.edit', 'issues.delete'])) {
    html += '<div class="action-buttons">...</div>';
}
```

---

## API 연동 패턴

### 1. 기존 API 사용

```javascript
// 기존 API 객체 사용
const issues = await IssuesAPI.getAll();
const projects = await ProjectsAPI.getAll();
```

### 2. 에러 처리

```javascript
try {
    const data = await API.call();
    // 성공 처리
} catch (error) {
    console.error('API 호출 실패:', error);
    app.showError('데이터를 불러올 수 없습니다.');
}
```

### 3. 로딩 상태 관리

```javascript
app.showLoading();
try {
    const data = await API.call();
    // 데이터 처리
} finally {
    app.hideLoading();
}
```

---

## 성능 최적화 가이드

### 1. 모듈 지연 로딩

- 필요한 시점에만 모듈 로드
- 사용하지 않는 모듈은 로드하지 않음
- 모듈 캐싱으로 중복 로드 방지

### 2. 이벤트 리스너 관리

- 모듈 파괴 시 이벤트 리스너 제거
- 전역 이벤트 리스너 최소화
- 이벤트 위임 패턴 사용

### 3. DOM 조작 최적화

- 가상 DOM 또는 DocumentFragment 사용
- 일괄 DOM 업데이트
- 불필요한 리렌더링 방지

---

## 테스트 전략

### 1. 단위 테스트

- 각 모듈의 핵심 로직 테스트
- 권한 체크 로직 테스트
- API 호출 모킹

### 2. 통합 테스트

- 모듈 간 상호작용 테스트
- 라우팅 테스트
- 권한 기반 UI 테스트

### 3. E2E 테스트

- 사용자 시나리오 테스트
- 권한별 접근 테스트
- 크로스 브라우저 테스트

---

## 배포 및 버전 관리

### 1. 버전 관리 전략

- 모듈별 독립적 버전 관리
- 호환성 매트릭스 유지
- 점진적 업그레이드 지원

### 2. 캐시 관리

- 모듈별 캐시 버스팅
- 버전 기반 캐시 무효화
- CDN 캐시 전략

### 3. 모니터링

- 모듈 로딩 성능 모니터링
- 에러 추적 및 로깅
- 사용자 행동 분석

---

## 마이그레이션 가이드

### 기존 코드에서 새 구조로 이전

1. **권한 체크 코드 변경**
   ```javascript
   // 기존
   if (currentUser.role === 'admin') { ... }
   
   // 신규
   if (hasPermission('users.edit')) { ... }
   ```

2. **페이지 이동 코드 변경**
   ```javascript
   // 기존
   window.location.href = 'admin.html';
   
   // 신규
   app.navigateTo('#users/list');
   ```

3. **모듈화 적용**
   - 기능별로 코드 분리
   - 공통 로직 유틸리티로 이동
   - 이벤트 기반 통신으로 변경

---

**작성일:** 2025-10-25  
**작성자:** AI Assistant  
**버전:** 1.0  

> 이 문서는 시스템 발전에 따라 지속적으로 업데이트됩니다.