120 lines
7.4 KiB
Markdown
120 lines
7.4 KiB
Markdown
# 인터페이스 및 UI 제어 명세서 (frontend.md)
|
|
|
|
## 1. 글로벌 테마 변수 강제 (Theme Constraints)
|
|
* **임의 색상 지정 금지:** 하드코딩된 Hex 코드 직접 입력 금지.
|
|
* **CSS 변수 필수 참조:** 테마 전환(라이트/다크) 및 일관성을 위해 `ui_template_theme.css` 선언 변수(`var(--color-bg)`, `var(--color-text)` 등)만 사용.
|
|
* **신규 컴포넌트/템플릿:** 신규 컴포넌트나 템플릿이 필요한 경우`.agent\design.md` 파일을 참고하여 양식을 `ui_template\ui_template_elements.ts`, `ui_template\ui_template_locale.ts`, `ui_template\ui_template_theme.css` 양식화하여 사용할 것
|
|
|
|
## 2. UI 요소 및 레이아웃 제약 (Layout Constraints)
|
|
* **공통 컴포넌트 최우선:** 임의 스타일링 금지. `ui_template_elements.ts` 규격 및 공통 컴포넌트 최우선 상속/참조.
|
|
* **3단 기본 레이아웃 준수:** 워크플로우 페이지 기본 배치 강제 (예외 요청 제외)
|
|
1. 상단 영역: 페이지 타이틀 및 현재 진행 단계 상태
|
|
2. 좌측 패널: 데이터 입력 폼 및 설정 제어 영역 (너비 고정)
|
|
3. 우측 영역: WebCAD 도면 뷰어 또는 결과 데이터 그리드 (나머지 전체 너비)
|
|
|
|
### 2.1 공통 컴포넌트 목록 (`ui_template_elements.ts`)
|
|
* **기본:** `createButton`, `createInputField`, `createCard`, `createTag`, `createWorkflowShell`
|
|
* **오버레이/알림:** `showLoadingOverlay`, `hideLoadingOverlay`, `showToast`
|
|
* **스플라인 차트:** `createLineChart(opts)` — 외부 라이브러리 없이 인라인 SVG로 시계열 렌더링
|
|
- **곡선:** Catmull-Rom → 3차 베지어 변환으로 스플라인(부드러운 곡선) 렌더
|
|
- **색상:** `--color-chart-0~3` 테마 변수 사용 (하드코딩 금지)
|
|
- **범례:** 그래프 영역 우상단에 반투명 오버레이 배치 (`opts.series[].name`)
|
|
- **X축:** `opts.xLabels` 전달 시 양끝 포함 5개 라벨 균등 표기
|
|
- **결측:** `series[].values`에 `null` 포함 시 해당 구간 선 끊김 처리
|
|
- 데이터 2점 미만이면 빈 상태(`—`) 반환
|
|
- 사용 예: B01_Dashboard 리소스 현황(CPU/메모리/디스크 30일 추이, X축=시간)
|
|
|
|
---
|
|
|
|
## 3. 인덱스 기반 다국어 제어 (i18n Constraints)
|
|
* **텍스트 하드코딩 금지:** 라벨, 버튼 문구, 안내 메시지 등 모든 UI 문자열의 컴포넌트 내 직접 입력 절대 금지.
|
|
* **🚨 동시 수정 프로토콜 (선언 후 구현):**
|
|
1. **선(先) 등록:** 신규 문구 필요 시, `ui_template_locale.ts` 최하단에 키와 언어 배열 `[한국어, 영어]` 우선 추가.
|
|
2. **후(後) 참조:** 컴포넌트 내 `ui_locales.키값[현재언어인덱스]` 형태로만 호출.
|
|
* *제약 조건:* UI 수정 요청 시 다국어 파일 업데이트 코드 미제시 경우 가이드 위반(에러) 처리.
|
|
|
|
---
|
|
|
|
## 4. JS/TS 코드 제어 및 상태 (Logic Constraints)
|
|
* **이벤트 핸들러 명명법:** `on[페이지명]_[기능명]_[액션]` 패턴 필수 준수. (예: `onB04_Surface_Calculate_Click`)
|
|
* **비동기 상태 제어:** API 호출 시 즉시 로딩 스피너(Overlay) 활성화, 통신 완료(성공/실패) 후 해제 로직 필수 포함.
|
|
* **1차 유효성 검사:** 백엔드 전송 전 빈 값 및 데이터 타입(숫자 범위 등) 프론트엔드 선 검증, 에러 시 입력창 하단 표기.
|
|
|
|
```typescript
|
|
export const ui_locales = {
|
|
A01_Home_Title: ["반갑습니다", "Welcome"],
|
|
B04_wf1_Surface_Btn: ["지표면 분석 실행", "Run Surface Analysis"]
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 인증, 인가, 역할 및 라우팅 (Authentication, Authorization, Roles & Routing)
|
|
|
|
### 5.1 세션 쿠키 기반 인증
|
|
* **방식:** HttpOnly Secure 세션 쿠키 (localStorage 토큰 미사용)
|
|
* **API 통신:** 모든 API 요청에 `credentials: "include"` 설정으로 쿠키 자동 전송
|
|
* **로그아웃:** `/auth/logout` API 호출 → 서버 세션 삭제 → 쿠키 자동 제거
|
|
* **인증 갱신:** 로그인 시 `users.auth_expires_at = NOW() + 3개월` 자동 설정
|
|
- 유효한 인증: `auth_expires_at > NOW()` → 바로 대시보드 이동
|
|
- 만료된 인증: `auth_expires_at <= NOW()` → 재인증 모달 표시
|
|
|
|
### 5.1.1 역할 기반 대시보드 렌더링
|
|
* **USER 역할:**
|
|
- 프로젝트 리스트 섹션
|
|
- 회사 정보 섹션 (회사 생성/연결 팝업)
|
|
- 기본정보 & 보안 섹션
|
|
|
|
* **ADMIN 역할:**
|
|
- 프로젝트 리스트 섹션 (회사 전체 프로젝트)
|
|
- 회사 정보 섹션
|
|
- 팀원 관리 섹션
|
|
- 가입 요청 섹션
|
|
- 기본정보 & 보안 섹션
|
|
|
|
* **SYSTEM_ADMIN 역할:**
|
|
- 리소스 현황 섹션 (CPU, MEM, DISK, 활성 사용자/프로젝트)
|
|
- 회사 관리 섹션 (전체 회사 리스트 + 추가/수정/삭제)
|
|
- 사용자 관리 섹션 (전체 사용자 + 역할 변경 + 회사 할당)
|
|
- 가입 요청 관리 섹션 (전체 가입 신청 + 승인/거절)
|
|
- 시스템 로그 섹션 (필터링 지원)
|
|
- 리소스 모니터링 그래프 (시계열 데이터)
|
|
- 기본정보 & 보안 섹션
|
|
|
|
### 5.2 라우팅 가드
|
|
* **인증 확인:** `isAuthenticated()` 함수로 세션 유효성 검사 (PROTECTED_ROUTES 진입 전)
|
|
* **회사 연결 확인:** B02~B11 워크플로우 진입 시 `fetchDashboardMe()` 호출 → `company_id` + `status` 확인
|
|
- `status` 확인:
|
|
- NO_COMPANY: B01_Dashboard로 강제 리다이렉트 (회사 연결 필요)
|
|
- PENDING: B01_Dashboard로 강제 리다이렉트 (승인 대기 중)
|
|
- ACTIVE: 워크플로우 진입 허용
|
|
- `company_id` 없으면 B01_Dashboard로 리다이렉트
|
|
* **역할 기반 라우팅:**
|
|
- SYSTEM_ADMIN: 모든 페이지 접근 가능
|
|
- ADMIN: B01_Dashboard (관리 섹션) + B02~B11 워크플로우 접근 가능
|
|
- USER: B01_Dashboard (사용자 섹션) + B02~B11 워크플로우 접근 가능
|
|
* **상태 전이:**
|
|
- 회원가입 후 이메일 인증 완료: `users.status = 'NO_COMPANY'` (로그인 가능, 회사 미연결)
|
|
- 회사 생성: `users.status = 'ACTIVE'`, `company_id` 세팅, `role = 'ADMIN'`, `is_master = TRUE`
|
|
- 회사 참여 신청: `users.status = 'PENDING'` (관리자 승인 대기)
|
|
- 관리자 승인: `users.status = 'ACTIVE'`, `company_id` 세팅
|
|
|
|
### 5.3 대시보드 권한 기반 UI 제어 (B01_Dashboard)
|
|
* **권한 검증 헬퍼 필수:** `.agent/plan_dashboard_management.md` 섹션 9의 헬퍼 함수 참고
|
|
- `canEditProject(user, project)` - 프로젝트 수정 권한
|
|
- `canDeleteProject(user)` - 프로젝트 삭제 권한 (SYSTEM_ADMIN만)
|
|
- `canAddUser(user)` - 사용자 추가 권한
|
|
- `canChangeRole(user, targetUser)` - 역할 변경 권한 (ADMIN: USER↔ADMIN만, SYSTEM_ADMIN 제외)
|
|
- `canDeleteUser(user, targetUser)` - 사용자 삭제 권한 (마지막 ADMIN 보호)
|
|
- `canManageAutomation(user, automation)` - 자동화 로직 관리 권한
|
|
- `isLastAdmin(company, excludeUserId)` - 회사의 마지막 ADMIN 확인
|
|
|
|
* **UI 컴포넌트 구현:** 권한에 따라 버튼/필드 표시/비활성화
|
|
- 프로젝트: 수정 모달, 삭제 확인 모달 (삭제는 SYSTEM_ADMIN만)
|
|
- 사용자: 추가 모달 (가입 계정 목록), 수정 모달, 역할변경 모달, 삭제 확인 모달
|
|
- 자동화 로직: 생성/수정/삭제 모달 (ADMIN/SYSTEM_ADMIN만)
|
|
- 모든 삭제 모달에 경고 메시지 포함 (되돌릴 수 없음)
|
|
|
|
* **다국어 반영:** 계획서 8장의 모든 키를 `ui_template_locale.ts`에 추가 후 컴포넌트에서 `L(키)` 사용
|
|
- 모달 제목, 버튼 레이블, 확인 메시지, 오류 메시지 모두 다국어 처리
|
|
- 하드코딩된 문구 절대 금지 |