d3333c4dc2
- 데이터베이스 스키마 및 변경 로그 문서화 - 신규 페이지 개발 가이드 작성 - 모듈 아키텍처 설계 문서 추가 - 성능 최적화 전략 문서화 - 리팩토링 계획 및 진행 상황 정리 Documentation: - DATABASE_SCHEMA.md: 전체 DB 스키마 구조 - DB_CHANGE_LOG.md: 마이그레이션 변경 이력 - DEVELOPMENT_GUIDE.md: 신규 기능 개발 표준 - MODULE_ARCHITECTURE.md: 프론트엔드 모듈 구조 - PERFORMANCE_OPTIMIZATION.md: 성능 최적화 가이드 - REFACTORING_PLAN.md: 리팩토링 진행 상황 Test Files: - app.html, app.js: SPA 테스트 파일 - test_api.html: API 테스트 페이지
479 lines
11 KiB
Markdown
479 lines
11 KiB
Markdown
# 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
|
|
|
|
> 이 문서는 시스템 발전에 따라 지속적으로 업데이트됩니다.
|