# 관리 페이지 표준 가이드 (Admin Page Standard)
> **작성일**: 2026-01-26
> **버전**: 1.0.0
> **용도**: 관리자 페이지(Admin Pages) 통합 개발 표준
---
## 📋 목차
1. [용어 정의](#1-용어-정의)
2. [페이지 유형 분류](#2-페이지-유형-분류)
3. [표준 레이아웃 구조](#3-표준-레이아웃-구조)
4. [HTML 구조 템플릿](#4-html-구조-템플릿)
5. [CSS 클래스 규칙](#5-css-클래스-규칙)
6. [JavaScript 규칙](#6-javascript-규칙)
7. [파일 네이밍 규칙](#7-파일-네이밍-규칙)
8. [체크리스트](#8-체크리스트)
---
## 1. 용어 정의
### 1.1 관리 페이지 (Admin Page)
**정의**: 데이터의 CRUD(Create, Read, Update, Delete) 작업을 수행하는 관리자 전용 페이지
**특징**:
- 2단 레이아웃 (사이드바 + 메인 콘텐츠)
- 카드/그리드 방식의 데이터 표시
- 검색, 필터, 통계 기능 포함
- 모달을 통한 추가/수정 기능
**명명 규칙**: `{엔티티}-management` 또는 `{엔티티}s.html`
**예시**:
- ✅ 프로젝트 관리 (`projects.html`)
- ✅ 작업자 관리 (`workers.html`)
- ✅ 코드 관리 (`codes.html`)
### 1.2 관리 페이지의 구성 요소
| 용어 | 영문 | 설명 | 클래스명 |
|------|------|------|----------|
| 사이드바 | Sidebar | 좌측 네비게이션 메뉴 | `.sidebar` |
| 메인 콘텐츠 | Main Content | 우측 콘텐츠 영역 | `.main-content` |
| 페이지 헤더 | Page Header | 타이틀 + 액션 버튼 | `.page-header` |
| 검색 섹션 | Search Section | 검색바 + 필터 | `.search-section` |
| 통계 카드 | Statistics | 데이터 통계 표시 | `.project-stats`, `.stat-item` |
| 데이터 그리드 | Data Grid | 카드/테이블 그리드 | `.projects-grid` |
| 데이터 카드 | Data Card | 개별 데이터 표시 카드 | `.project-card` |
---
## 2. 페이지 유형 분류
### 2.1 Type A: 카드 그리드 관리 페이지
**용도**: 시각적으로 정보를 표시하고 관리하는 페이지
**레이아웃**:
```
┌─────────┬────────────────────────────────┐
│ │ 페이지 헤더 (타이틀 + 버튼) │
│ ├────────────────────────────────┤
│ 사이드바 │ 검색 섹션 (검색바 + 필터) │
│ ├────────────────────────────────┤
│ │ 통계 (활성/비활성/총) │
│ ├────────────────────────────────┤
│ │ [카드1] [카드2] [카드3] │
│ │ [카드4] [카드5] [카드6] │
│ │ 데이터 카드 그리드 │
└─────────┴────────────────────────────────┘
```
**적용 페이지**:
- 프로젝트 관리 (`projects.html`)
- 작업자 관리 (`workers.html`)
**그리드 설정**:
- 기본: 3열 (`grid-template-columns: repeat(3, 1fr)`)
- 카드 높이: 고정 420px
### 2.2 Type B: 테이블 관리 페이지
**용도**: 텍스트 중심의 데이터를 테이블 형태로 관리
**레이아웃**:
```
┌─────────┬────────────────────────────────┐
│ │ 페이지 헤더 (타이틀 + 버튼) │
│ ├────────────────────────────────┤
│ 사이드바 │ 검색 섹션 (검색바 + 필터) │
│ ├────────────────────────────────┤
│ │ ┌──────────────────────────┐ │
│ │ │ 테이블 헤더 │ │
│ │ ├──────────────────────────┤ │
│ │ │ 데이터 행 1 │ │
│ │ │ 데이터 행 2 │ │
│ │ │ 데이터 행 3 │ │
│ │ └──────────────────────────┘ │
└─────────┴────────────────────────────────┘
```
**적용 가능 페이지**:
- 로그 관리
- 권한 관리
### 2.3 Type C: 탭 기반 관리 페이지
**용도**: 여러 카테고리의 데이터를 탭으로 구분하여 관리
**레이아웃**:
```
┌─────────┬────────────────────────────────┐
│ │ 페이지 헤더 (타이틀 + 버튼) │
│ ├────────────────────────────────┤
│ 사이드바 │ [탭1] [탭2] [탭3] [탭4] │
│ ├────────────────────────────────┤
│ │ 검색 섹션 │
│ ├────────────────────────────────┤
│ │ 현재 탭의 콘텐츠 표시 │
│ │ (테이블 또는 카드) │
└─────────┴────────────────────────────────┘
```
**적용 페이지**:
- 코드 관리 (`codes.html`)
---
## 3. 표준 레이아웃 구조
### 3.1 2단 레이아웃 (Sidebar + Main)
**CSS Flexbox 구조**:
```css
.page-container {
display: flex; /* 가로 배치 */
min-height: calc(100vh - 80px);
}
.sidebar {
width: 240px; /* 고정 너비 */
min-width: 240px;
flex-shrink: 0; /* 줄어들지 않음 */
}
.main-content {
flex: 1; /* 나머지 공간 차지 */
padding: 2rem;
}
```
### 3.2 반응형 Breakpoints
| 화면 크기 | 사이드바 | 그리드 열 | 비고 |
|----------|---------|----------|------|
| 1400px+ | 240px | 3열 | 대형 데스크탑 |
| 1200px ~ 1399px | 240px | 3열 | 일반 데스크탑 |
| 1024px ~ 1199px | 240px | 2열 | 중형 화면 |
| 768px ~ 1023px | 200px | 2열 | 태블릿 |
| 767px 이하 | 숨김 | 1열 | 모바일 |
---
## 4. HTML 구조 템플릿
### 4.1 기본 HTML 템플릿
```html
{엔티티명} 관리 | (주)테크니컬코리아
```
---
## 5. CSS 클래스 규칙
### 5.1 필수 클래스 목록
| 클래스명 | 용도 | 부모 | 필수 여부 |
|---------|------|------|----------|
| `.page-container` | 전체 레이아웃 컨테이너 | `` | ✅ 필수 |
| `.sidebar` | 사이드바 | `.page-container` | ✅ 필수 |
| `.main-content` | 메인 콘텐츠 영역 | `.page-container` | ✅ 필수 |
| `.dashboard-main` | 대시보드 메인 | `.main-content` | ✅ 필수 |
| `.page-header` | 페이지 헤더 | `.dashboard-main` | ✅ 필수 |
| `.search-section` | 검색 영역 | `.dashboard-main` | ✅ 필수 |
| `.projects-section` | 데이터 섹션 | `.dashboard-main` | ✅ 필수 |
| `.projects-grid` | 데이터 그리드 | `.projects-section` | ✅ 필수 |
| `.project-card` | 개별 카드 | `.projects-grid` | ✅ 필수 |
### 5.2 클래스 네이밍 규칙
**패턴**: `{영역}-{요소}-{수식어}`
**예시**:
- ✅ `.page-header` (페이지 헤더)
- ✅ `.search-section` (검색 섹션)
- ✅ `.stat-item` (통계 항목)
- ✅ `.menu-item` (메뉴 항목)
- ✅ `.btn-primary` (주요 버튼)
**금지**:
- ❌ `.header1`, `.section2` (숫자 사용)
- ❌ `.pageHeader` (camelCase)
- ❌ `.Page_Header` (underscore + PascalCase)
### 5.3 카드 표준 스타일
```css
.project-card {
background: #ffffff;
border: 1px solid #e2e8f0;
border-radius: 0.75rem;
padding: 1.5rem;
height: 420px; /* 고정 높이 */
min-height: 420px;
max-height: 420px;
display: flex;
flex-direction: column;
cursor: pointer;
transition: all 0.2s ease;
}
.project-card:hover {
border-color: #2563eb;
box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
transform: translateY(-4px);
}
```
---
## 6. JavaScript 규칙
### 6.1 파일 구조
각 관리 페이지는 독립적인 JavaScript 파일을 가져야 합니다.
**파일명 패턴**: `{entity}-management.js`
**예시**:
- `/js/project-management.js`
- `/js/worker-management.js`
- `/js/code-management.js`
### 6.2 필수 함수 목록
모든 관리 페이지는 다음 함수를 구현해야 합니다:
```javascript
// 1. 페이지 초기화
function initializePage() { }
// 2. 데이터 로드
async function load{Entities}() { }
// 3. 데이터 렌더링
function render{Entities}() { }
// 4. 검색
function search{Entities}() { }
// 5. 필터
function filter{Entities}() { }
// 6. 모달 열기
function open{Entity}Modal() { }
// 7. 모달 닫기
function close{Entity}Modal() { }
// 8. 데이터 저장
async function save{Entity}() { }
// 9. 데이터 삭제
async function delete{Entity}(id) { }
// 10. 목록 새로고침
function refresh{Entity}List() { }
```
### 6.3 네이밍 규칙
**함수명**: camelCase
- ✅ `loadProjects()`, `openWorkerModal()`
- ❌ `load_projects()`, `OpenWorkerModal()`
**변수명**: camelCase
- ✅ `allProjects`, `currentEditingProject`
- ❌ `all_projects`, `CurrentEditingProject`
**상수**: UPPER_SNAKE_CASE
- ✅ `API_BASE_URL`, `DEFAULT_PAGE_SIZE`
- ❌ `apiBaseUrl`, `defaultPageSize`
---
## 7. 파일 네이밍 규칙
### 7.1 디렉터리 구조
```
/pages/admin/
├── index.html # 관리 대시보드
├── projects.html # 프로젝트 관리
├── workers.html # 작업자 관리
├── codes.html # 코드 관리
└── {entity}s.html # 새 관리 페이지
/css/
├── design-system.css # 디자인 시스템
└── admin-pages.css # 관리 페이지 공통 CSS
/js/
├── project-management.js
├── worker-management.js
├── code-management.js
└── {entity}-management.js
```
### 7.2 파일명 규칙
**HTML 파일**:
- 복수형 사용: `{entities}.html`
- ✅ `projects.html`, `workers.html`
- ❌ `project.html`, `worker.html`
**JavaScript 파일**:
- 하이픈 구분: `{entity}-management.js`
- ✅ `project-management.js`
- ❌ `projectManagement.js`, `project_management.js`
**CSS 파일**:
- 공통: `admin-pages.css` (모든 관리 페이지가 공유)
- 개별: 필요시 `{entity}-page.css`
---
## 8. 체크리스트
새로운 관리 페이지를 생성할 때 다음 체크리스트를 확인하세요:
### 8.1 HTML 체크리스트
- [ ] 2단 레이아웃 구조 (사이드바 + 메인)
- [ ] 사이드바 메뉴에 현재 페이지 active 표시
- [ ] 페이지 헤더 (타이틀 + 설명 + 액션 버튼)
- [ ] 검색 섹션 (검색바 + 필터)
- [ ] 통계 섹션 (활성/비활성/총)
- [ ] 데이터 그리드 (3열 기본)
- [ ] 모달 (추가/수정/삭제)
- [ ] CSS 버전 쿼리스트링 (`?v=6`)
- [ ] JavaScript 모듈 로드
### 8.2 CSS 체크리스트
- [ ] `.page-container { display: flex }` 적용
- [ ] `.sidebar` 고정 너비 (240px)
- [ ] `.main-content { flex: 1 }` 적용
- [ ] `.projects-grid` 3열 그리드
- [ ] 카드 고정 높이 (420px)
- [ ] 반응형 breakpoints 구현
- [ ] 호버 효과 구현
### 8.3 JavaScript 체크리스트
- [ ] 10개 필수 함수 구현
- [ ] API 연동 (GET, POST, PUT, DELETE)
- [ ] 에러 핸들링
- [ ] 로딩 상태 표시
- [ ] 검색/필터 기능
- [ ] 모달 열기/닫기
- [ ] 데이터 유효성 검사
### 8.4 접근성 체크리스트
- [ ] 키보드 네비게이션 지원
- [ ] 버튼에 적절한 `title` 속성
- [ ] 로딩 중 상태 표시
- [ ] 에러 메시지 명확히 표시
- [ ] 모바일 반응형 지원
---
## 9. 예시 코드
### 9.1 카드 렌더링 (JavaScript)
```javascript
function renderProjects() {
const projectsHtml = filteredProjects.map(project => {
const isInactive = project.is_active === 0 || project.is_active === false;
return `
${project.job_no || 'Job No. 없음'}
${project.project_name}
상태${project.status}
PM${project.pm || '-'}
`;
}).join('');
document.getElementById('projectsGrid').innerHTML = projectsHtml;
}
```
---
## 10. 버전 히스토리
| 버전 | 날짜 | 변경 내용 |
|------|------|----------|
| 1.0.0 | 2026-01-26 | 초기 버전 작성 |
---
## 11. 참고 자료
- [DOCUMENTATION_STANDARD.md](./DOCUMENTATION_STANDARD.md) - 문서 작성 표준
- [TBM_DEPLOYMENT_GUIDE.md](./TBM_DEPLOYMENT_GUIDE.md) - TBM 배포 가이드
- `/css/admin-pages.css` - 관리 페이지 공통 CSS
- `/pages/admin/projects.html` - 프로젝트 관리 참고 구현
---
**문서 작성자**: Claude Code
**최종 수정일**: 2026-01-26