docs: 프로젝트 문서화 및 개발 가이드 추가
- 데이터베이스 스키마 및 변경 로그 문서화 - 신규 페이지 개발 가이드 작성 - 모듈 아키텍처 설계 문서 추가 - 성능 최적화 전략 문서화 - 리팩토링 계획 및 진행 상황 정리 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 테스트 페이지
This commit is contained in:
Hyungi Ahn
478
MODULE_ARCHITECTURE.md
Normal file
478
MODULE_ARCHITECTURE.md
Normal file
@@ -0,0 +1,478 @@
|
||||
# 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
|
||||
|
||||
> 이 문서는 시스템 발전에 따라 지속적으로 업데이트됩니다.
|
||||
Reference in New Issue
Block a user