M-Project/MODULE_ARCHITECTURE.md

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 요소 권한 제어
• 동적 메뉴 생성
• 개별 권한 관리

주요 메서드:

// 권한 체크
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 상태 관리

주요 메서드:

// 초기화
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. 애플리케이션 시작 흐름

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

2. 권한 체크 흐름

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. 모듈 로딩 흐름

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

---

이벤트 시스템 (예정)

EventBus 클래스

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

주요 이벤트:

// 사용자 관련
'user.login'           // 사용자 로그인
'user.logout'          // 사용자 로그아웃
'user.permission.changed' // 권한 변경

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

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

사용 예시:

// 이벤트 발생
eventBus.emit('issue.created', { id: 123, title: '새 부적합' });

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

---

상태 관리 시스템 (예정)

StateManager 클래스

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

상태 구조:

{
    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
    }
}

사용 예시:

// 상태 설정
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/          # 모듈 내 컴포넌트 (선택)

모듈 클래스 템플릿:

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 요소 제어:

// 버튼 표시/숨김
controlElement('.create-btn', 'issues.create', 'show');

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

조건부 렌더링:

if (hasPermission('issues.delete')) {
    html += '<button class="delete-btn">삭제</button>';
}

다중 권한 체크:

if (hasAnyPermission(['issues.edit', 'issues.delete'])) {
    html += '<div class="action-buttons">...</div>';
}

---

API 연동 패턴

1. 기존 API 사용

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

2. 에러 처리

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

3. 로딩 상태 관리

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. 권한 체크 코드 변경

   // 기존
   if (currentUser.role === 'admin') { ... }
   
   // 신규
   if (hasPermission('users.edit')) { ... }
   

2. 페이지 이동 코드 변경

   // 기존
   window.location.href = 'admin.html';
   
   // 신규
   app.navigateTo('#users/list');
   

3. 모듈화 적용

   • 기능별로 코드 분리
   • 공통 로직 유틸리티로 이동
   • 이벤트 기반 통신으로 변경

---

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

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