인터페이스 및 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 양식화하여 사용할 것

공통 컴포넌트 최우선: 임의 스타일링 금지. ui_template_elements.ts 규격 및 공통 컴포넌트 최우선 상속/참조.
3단 기본 레이아웃 준수: 워크플로우 페이지 기본 배치 강제 (예외 요청 제외)
1. 상단 영역: 페이지 타이틀 및 현재 진행 단계 상태
2. 좌측 패널: 데이터 입력 폼 및 설정 제어 영역 (너비 고정)
3. 우측 영역: WebCAD 도면 뷰어 또는 결과 데이터 그리드 (나머지 전체 너비)

기본: 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축=시간)

텍스트 하드코딩 금지: 라벨, 버튼 문구, 안내 메시지 등 모든 UI 문자열의 컴포넌트 내 직접 입력 절대 금지.
🚨 동시 수정 프로토콜 (선언 후 구현):
1. 선(先) 등록: 신규 문구 필요 시, ui_template_locale.ts 최하단에 키와 언어 배열 [한국어, 영어] 우선 추가.
2. 후(後) 참조: 컴포넌트 내 ui_locales.키값[현재언어인덱스] 형태로만 호출.
- 제약 조건: UI 수정 요청 시 다국어 파일 업데이트 코드 미제시 경우 가이드 위반(에러) 처리.

이벤트 핸들러 명명법: on[페이지명]_[기능명]_[액션] 패턴 필수 준수. (예: onB04_Surface_Calculate_Click)
비동기 상태 제어: API 호출 시 즉시 로딩 스피너(Overlay) 활성화, 통신 완료(성공/실패) 후 해제 로직 필수 포함.
1차 유효성 검사: 백엔드 전송 전 빈 값 및 데이터 타입(숫자 범위 등) 프론트엔드 선 검증, 에러 시 입력창 하단 표기.

export const ui_locales = {
  A01_Home_Title: ["반갑습니다", "Welcome"],
  B04_wf1_Surface_Btn: ["지표면 분석 실행", "Run Surface Analysis"]
};

방식: HttpOnly Secure 세션 쿠키 (localStorage 토큰 미사용)
API 통신: 모든 API 요청에 credentials: "include" 설정으로 쿠키 자동 전송
로그아웃: /auth/logout API 호출 → 서버 세션 삭제 → 쿠키 자동 제거
인증 갱신: 로그인 시 users.auth_expires_at = NOW() + 3개월 자동 설정
- 유효한 인증: auth_expires_at > NOW() → 바로 대시보드 이동
- 만료된 인증: auth_expires_at <= NOW() → 재인증 모달 표시

USER 역할:
- 프로젝트 리스트 섹션
- 회사 정보 섹션 (회사 생성/연결 팝업)
- 기본정보 & 보안 섹션
ADMIN 역할:
- 프로젝트 리스트 섹션 (회사 전체 프로젝트)
- 회사 정보 섹션
- 팀원 관리 섹션
- 가입 요청 섹션
- 기본정보 & 보안 섹션
SYSTEM_ADMIN 역할:
- 리소스 현황 섹션 (CPU, MEM, DISK, 활성 사용자/프로젝트)
- 회사 관리 섹션 (전체 회사 리스트 + 추가/수정/삭제)
- 사용자 관리 섹션 (전체 사용자 + 역할 변경 + 회사 할당)
- 가입 요청 관리 섹션 (전체 가입 신청 + 승인/거절)
- 시스템 로그 섹션 (필터링 지원)
- 리소스 모니터링 그래프 (시계열 데이터)
- 기본정보 & 보안 섹션

인증 확인: 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 세팅