pray4skylark
239 lines
16 KiB
Markdown
239 lines
16 KiB
Markdown
# 화면 설계 명세서 (UI & Screen Specification)
|
||
|
||
**프론트엔드:** Next.js 14+ (App Router), TypeScript, Tailwind CSS, Pinia
|
||
|
||
## 1. 전역 레이아웃 (Global Layout)
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ GNB (Global Navigation Bar) │
|
||
│ ┌──────┬─────────────────────────────────┬──┐ │
|
||
│ │ Logo │ (검색/제목) │🔔│👤│ │
|
||
│ └──────┴─────────────────────────────────┴──┘ │
|
||
├──────┬──────────────────────────────────────────┤
|
||
│ LNB │ Content Area │
|
||
│ │ │
|
||
│ Menu │ (Page Component Rendering) │
|
||
│ 1 │ │
|
||
│ │ │
|
||
│ Menu │ │
|
||
│ 2 │ │
|
||
│ │ │
|
||
│ Menu │ │
|
||
│ 3 │ │
|
||
│ │ │
|
||
└──────┴──────────────────────────────────────────┘
|
||
```
|
||
|
||
### GNB (Global Navigation Bar)
|
||
- **알림 뱃지(🔔):** `GET /api/v1/notifications/unread` 폴링 — 0개면 숨김
|
||
- **프로필:** `GET /api/v1/employees/me` — 사용자명 및 권한 표시
|
||
|
||
### LNB (Left Navigation Bar) — RBAC 기반 동적 메뉴
|
||
| 메뉴 | EMPLOYEE | MANAGER | ADMIN |
|
||
|------|----------|---------|-------|
|
||
| 내 포트폴리오 | ✅ | ❌ | ❌ |
|
||
| SR 티켓 관리 | ✅ | ✅ | ✅ |
|
||
| 업무 보고서 | ✅ | ✅ | ✅ |
|
||
| 교육 현황 | ✅ | ✅ | ✅ |
|
||
| 프로젝트 관리 | ❌ | ✅ | ✅ |
|
||
| 장비 자산 관리 | ❌ | ✅ | ✅ |
|
||
| 직원 관리 | ❌ | ❌ | ✅ |
|
||
| 공통 코드 관리 | ❌ | ❌ | ✅ |
|
||
|
||
---
|
||
|
||
## 2. SR 티켓 칸반 보드 (`TicketBoardView.vue`)
|
||
|
||
### UI 구조
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ [필터 영역] │
|
||
│ 카테고리: [BUG ▼] 우선순위: [HIGH ▼] 검색: [________] │
|
||
├─────────┬──────────┬──────────┬──────────┬──────────────┤
|
||
│ OPEN │ ASSIGNED │ IN_PROG │ RESOLVED │ CLOSED │
|
||
│ (3) │ (2) │ (5) │ (8) │ (12) │
|
||
├─────────┼──────────┼──────────┼──────────┼──────────────┤
|
||
│ ┌─────┐ │ ┌─────┐ │ ┌─────┐ │ ┌─────┐ │ │
|
||
│ │Bug │ │ │High │ │ │Supp │ │ │Bug │ │ │
|
||
│ │DB │ │ │API │ │ │배포 │ │ │튜닝 │ │ │
|
||
│ │튜닝 │ │ │에러 │ │ │지원 │ │ │완료 │ │ │
|
||
│ │🔴⚠️ │ │ │ │ │ │ │ │ │ │ │ │
|
||
│ └─────┘ │ └─────┘ │ └─────┘ │ └─────┘ │ │
|
||
│ ┌─────┐ │ │ ┌─────┐ │ │ │
|
||
│ │Feat │ │ │ │Bug │ │ │ │
|
||
│ │화면 │ │ │ │SQL │ │ │ │
|
||
│ │개발 │ │ │ │튜닝 │ │ │ │
|
||
│ └─────┘ │ │ └─────┘ │ │ │
|
||
└─────────┴──────────┴──────────┴──────────┴──────────────┘
|
||
```
|
||
|
||
### 핵심 로직
|
||
- **칸반 컬럼:** 상태별 4단 (상단에 컬럼별 카운트)
|
||
- **기한 임박:** `dueDate - now < 24h` → 카드 좌상단 🔴 경고 레이블 + 애니메이션
|
||
- **드래그 앤 드롭:** 상태 전환 시 `PUT /api/v1/tickets/{id}/status?status=NEW_STATUS`
|
||
- **티켓 카드 클릭:** 라우터 push → `/tickets/{ticketId}` (상세 페이지)
|
||
|
||
---
|
||
|
||
## 3. SR 티켓 상세/타임라인 (`TicketDetailView.vue`)
|
||
|
||
### UI 구조
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ [← 뒤로] [삭제] [상태 변경: IN_PROGRESS ▼] │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 📋 티켓 정보 │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ 제목: 오라클 쿼리 튜닝 필요 │ │
|
||
│ │ 상태: OPEN | 우선순위: HIGH | 카테고리: BUG │ │
|
||
│ │ 요청자: 김개발 | 담당자: 미배정 | SLA: 2026-05-22 │ │
|
||
│ │ 설명: 실행 계획 상 Full Scan 발생 중... │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ 📎 첨부파일 │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ [execution_plan.png] [error_log.txt] │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ 💬 타임라인 │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ 2026-05-21 14:32 ｜ 김개발 │ │
|
||
│ │ 오라클 실행 계획 첨부합니다. │ │
|
||
│ │ 📎 [execution_plan.png] │ │
|
||
│ ├──────────────────────────────────────────────────┤ │
|
||
│ │ 2026-05-21 15:10 ｜ 이튜너 (본사) │ │
|
||
│ │ 인덱스 힌트 사용해보세요: /*+ INDEX() */ │ │
|
||
│ ├──────────────────────────────────────────────────┤ │
|
||
│ │ 2026-05-21 16:00 ｜ 김개발 │ │
|
||
│ │ 힌트 적용 후 3초→0.5초로 개선되었습니다! ✅ │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ 댓글 입력: [________________________________] 📎 │ │
|
||
│ │ [등록] │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 핵심 로직
|
||
- **댓글 등록:** `POST /api/v1/tickets/{id}/comments` → 타임라인 최하단 prepend
|
||
- **파일 업로드:** `<input type="file">` → S3/서버 업로드 → URL 반환 → 댓글 첨부
|
||
- **상태 전환 버튼:** 현재 상태에 따라 다음 가능한 액션 버튼 노출 (OPEN→ASSIGNED→IN_PROGRESS→RESOLVED→CLOSED)
|
||
- **종료된 티켓 봉인:** `status == CLOSED` 시 입력폼 비활성화 + 뱃지 표시
|
||
|
||
---
|
||
|
||
## 4. 장비 인벤토리 (`EquipmentInventoryView.vue`)
|
||
|
||
### UI 구조
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 📊 장비 현황 요약 │
|
||
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │
|
||
│ │전체 │ │가용 │ │사용중 │ │수리중 │ │폐기 │ │
|
||
│ │45 │ │12 │ │28 │ │3 │ │2 │ │
|
||
│ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │
|
||
│ │
|
||
│ [필터: LAPTOP ▼] [제조사: Apple ▼] [검색: ____________] │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ 자산코드 ｜ 모델명 ｜ 시리얼 ｜ 상태 ｜ 액션 │ │
|
||
│ ├──────────────────────────────────────────────────┤ │
|
||
│ │HQ-LP-001｜MacBook ｜F2G8... ｜IN_USE ｜[반납] │ │
|
||
│ │HQ-LP-002｜MacBook ｜H3J9... ｜AVAILABLE｜[지급] │ │
|
||
│ │HQ-MO-001｜LG 27UN880｜L7K2... ｜IN_USE ｜[반납] │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
|
||
--- 지급 모달 ---
|
||
┌──────────────────────────────────────────┐
|
||
│ 장비 지급: HQ-LP-002 MacBook Pro M3 │
|
||
│ │
|
||
│ 대상자 검색: [김_______] │
|
||
│ ┌──────────────────────────────────┐ │
|
||
│ │ 김코딩 (BACKEND, 파견중) │ │
|
||
│ │ 김개발 (DBA, 파견중) │ │
|
||
│ └──────────────────────────────────┘ │
|
||
│ │
|
||
│ 지급 상태 코멘트: [미개봉 신품________] │
|
||
│ [취소] [지급 확정] │
|
||
└──────────────────────────────────────────┘
|
||
```
|
||
|
||
### 핵심 로직
|
||
- **상태 요약 카드:** 각 상태별 장비 카운트 → `GET /api/v1/equipment/summary`
|
||
- **조건부 액션 버튼:** `AVAILABLE` → [지급], `IN_USE` → [반납], `REPAIRING` → [수리 완료]
|
||
- **사원 검색 자동완성:** `GET /api/v1/employees/search?keyword=` + **300ms 디바운싱**
|
||
- **낙관적 락 충돌:** 지급 시 `version` 불일치 → 409 → 토스트 "다른 사용자가 먼저 처리했습니다"
|
||
|
||
---
|
||
|
||
## 5. 업무 보고서 (`WorkReportView.vue`)
|
||
|
||
### UI 구조
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 📝 업무 보고서 작성 │
|
||
│ │
|
||
│ 보고 유형: [WEEKLY ▼] 기준일자: [2026-05-21] │
|
||
│ │
|
||
│ ✅ 완료 실적 (SR 자동 연동) │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ SR-2026-042: 오라클 인덱스 튜닝 (RESOLVED) │ │
|
||
│ │ SR-2026-043: 배포 파이프라인 오류 수정 (CLOSED) │ │
|
||
│ │ ※ 해당 주차 해결 완료한 SR 내역 자동 바인딩 │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ 완료 실적: [________________________________________] │
|
||
│ 차기 계획: [________________________________________] │
|
||
│ 특이사항: [_________________________________________] │
|
||
│ 본사 지원 요청: [___________________________________] │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ 관리자 피드백 (김매니저): 수고하셨습니다. ✅ │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ [임시저장] [제출하기] │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 결재 상태 흐름
|
||
```
|
||
DRAFT ── [제출] ──> SUBMITTED ── [승인] ──> APPROVED
|
||
│
|
||
└── [반려] ──> DRAFT (관리자 피드백 필요)
|
||
```
|
||
|
||
### 핵심 로직
|
||
- **SR 자동 연동:** 페이지 진입 시 `GET /api/v1/reports/sr-auto-complete?targetDate=...` → 해당 주차 해결 SR 바인딩
|
||
- **임시저장 vs 제출:** DRAFT → SUBMITTED 전환 전 벨리데이션 (필수 항목 체크)
|
||
- **결재 피드백:** `REJECTED` 상태에서 관리자 피드백 박스 조건부 렌더링
|
||
|
||
---
|
||
|
||
## 6. 상태 천이 다이어그램
|
||
|
||
### SR 티켓
|
||
```
|
||
OPEN ──[담당자 배정]──> ASSIGNED ──[처리시작]──> IN_PROGRESS ──[해결]──> RESOLVED ──[확인종료]──> CLOSED
|
||
│ │ │
|
||
└──[취소/삭제]──────────┴───────────────────────┴── (Soft Delete)
|
||
```
|
||
|
||
### 업무 보고서
|
||
```
|
||
DRAFT ──[제출]──> SUBMITTED ──[승인]──> APPROVED
|
||
│
|
||
└──[반려]──> DRAFT (+ 피드백)
|
||
```
|
||
|
||
### 장비
|
||
```
|
||
AVAILABLE ──[지급]──> IN_USE ──[반납]──> AVAILABLE
|
||
│ │
|
||
└──[고장접수]──> REPAIRING ──[수리완료]──> AVAILABLE
|
||
│
|
||
└──[폐기]──> RETIRED
|
||
```
|