# 프론트엔드 구현 계획서 (frontend_plan.md)

**작성일:** 2026-07-05  
**상태:** 계획 수립 완료  
**목표:** POC → 정식 프로덕션 프론트엔드 구축 (백엔드 독립적 구현)

---

## 1. 전략 및 원칙

### 1.1 핵심 방침
- **UI-First 접근:** 기존 프로그램의 UI가 없으므로 **프론트엔드를 먼저 완성**
- **템플릿 기반 개발:** `ui_template/` 3개 파일(theme.css, locale.ts, elements.ts)만 사용
- **백엔드 독립성:** 각 페이지는 **Mock 데이터로 독립 실행 가능**하게 구현
- **점진적 마이그레이션:** 백엔드 구현 후 API 연결은 **페이지별 선택적으로**

### 1.2 기술 스택 (frontend.md 기반)
- **언어:** TypeScript / HTML5 Canvas (WebCAD)
- **스타일:** CSS 변수만 참조 (하드코딩 금지)
- **다국어:** `ui_template_locale.ts` 배열 방식 `[한국어, 영어]`
- **컴포넌트:** `ui_template_elements.ts` 팩토리 함수 (createButton, createInputField 등)
- **상태 관리:** Vanilla TS (프레임워크 미사용, 가볍고 빠름)

### 1.3 행동 제약 (frontend.md §1~4)
1. **색상/간격:** 모두 `var(--...)`로만 참조 (Hex/px 하드코딩 금지)
2. **컴포넌트:** `ui_template_elements.ts` 규격만 사용 (임의 스타일링 금지)
3. **텍스트:** **모든** 문자열은 `ui_template_locale.ts`에 **선(先) 등록**, 후(後) 컴포넌트에서 참조
4. **이벤트 핸들러:** `on[페이지]_[기능]_[액션]` 명명 (예: `onA01_Home_NewsLink_Click`)
5. **API 호출:** 호출 직전 `showLoadingOverlay()`, 완료 후 `hideLoadingOverlay()`

---

## 2. 페이지 구조 (18페이지 + 워크플로우)

### Phase A: 로그인 전 페이지 (A01~A08) — 2주
각 페이지는 2개 파일 구성:
- `A0X_PageName_UI_Page.ts` — HTML 구조 + 컴포넌트 조립 + 이벤트 핸들링
- `A0X_PageName_UI_Style.css` — 페이지 고유 스타일 (theme.css 변수만 사용)

#### A01_Home (홈)
- **목표:** 프로그램 소개, 최신 뉴스, 로그인/회원가입 링크
- **레이아웃:** 싱글 컬럼 (3단 레이아웃 미적용)
- **컴포넌트:** 제목, 뉴스 카드 그리드, CTA 버튼 쌍 (filled + ghost)
- **상태:** 뉴스 목록 (Mock 배열)

#### A02_ProgDetail (프로그램 상세)
- **목표:** 프로그램 기능 소개, 스크린샷, FAQ
- **레이아웃:** 싱글 컬럼, 섹션 구분
- **컴포넌트:** 아코디언 (FAQ), 탭 (기능별 설명)

#### A03_CompDetail (회사 상세)
- **목표:** 회사 정보, 팀, 연락처
- **컴포넌트:** 정보 카드, 팀 멤버 그리드

#### A04_NewsHistory (뉴스/이력)
- **목표:** 공지사항, 버전 이력 조회
- **컴포넌트:** 타임라인, 검색/필터

#### A05_EduDetail (교육)
- **목표:** 사용자 가이드, 튜토리얼 링크
- **컴포넌트:** 비디오 임베드, 문서 링크 그리드

#### A06_Login (로그인) ⭐ 핵심
- **목표:** 이메일/비밀번호 입력, JWT 토큰 저장 (Mock)
- **필드:** 이메일(email), 비밀번호(password)
- **유효성 검사:** 이메일 형식, 비밀번호 길이 (프론트 1차)
- **성공 시:** 토큰을 `localStorage`에 저장, B01_AccountDetail로 리다이렉트
- **상태 관리:** 로그인 상태 플래그 (`isLoggedIn`)

#### A07_Register (회원가입) ⭐ 핵심
- **목표:** 신규 사용자 계정 생성
- **필드:** 이메일, 비밀번호, 비밀번호 확인, 약관 동의
- **유효성:** 이메일 형식, 비밀번호 강도(8자 이상, 대문자/숫자 포함), 비밀번호 일치
- **성공 시:** 계정 생성 토스트 + A06_Login으로 이동

#### A08_Support (기술 지원)
- **목표:** 문의 양식 제출
- **필드:** 이름, 이메일, 주제, 메시지
- **제출 시:** 토스트 메시지 (Mock 성공)

---

### Phase B: 로그인 후 기초 (B01~B03) — 1.5주
JWT 인증 미들웨어 필수. 토큰 없으면 A01로 리다이렉트.

#### B01_AccountDetail (계정 상세)
- **목표:** 사용자 정보 조회/수정
- **필드:** 이름, 이메일, 전화, 회사명 (수정 토글)
- **섹션:** 계정 정보, 구독 상태, 다운로드 이력

#### B02_ProjRegister (프로젝트 등록)
- **목표:** 신규 프로젝트 생성
- **필드:** 프로젝트명, 고객사명, 프로젝트 설명
- **성공 시:** 프로젝트 ID 생성, 목록에 추가 (Mock), B03_FileInput으로 이동

#### B03_FileInput (파일 입력)
- **목표:** LAS, DEM, DWG 파일 업로드
- **UI:** Drag & Drop 박스 + 파일 목록 테이블
- **유효성:** 파일 확장자 검증 (.las, .dem, .dwg), 파일 크기 제한 (config_frontend.ts 참조)
- **성공 시:** 파일 목록 테이블 갱신, B04_wf1_Surface로 이동 가능

---

### Phase C: 워크플로우 (B04~B09) — 3주
**3단 레이아웃 (frontend.md §2) 준수 필수:**
- 상단: 페이지 타이틀 + 6단계 진행바
- 좌측: 입력 폼 + 파라미터 조정 (너비 고정 320px)
- 우측: WebCAD 뷰어 또는 그리드 (나머지 전체)

#### B04_wf1_Surface (지표면 분석)
- **상단:** "지표면 분석" 타이틀, 진행 Step 1/6 하이라이트
- **좌측:**
  - 파일 선택 드롭다운 (B03에서 업로드한 LAS 목록)
  - 메쉬 파라미터: Grid Size (숫자), Smoothing (슬라이더)
  - "분석 실행" 버튼 (filled)
- **우측:**
  - Canvas 영역 (WebGL 3D 뷰어 자리표)
  - 메쉬 정보 카드 (vertices, faces, bounds)
- **Mock:** 더미 메쉬 데이터 로드

#### B05_wf2_Route (경로 설계)
- **좌측:**
  - 지표면 선택 (B04 결과)
  - 경로점 추가 모드 토글
  - 경로 정보 (길이, 고도차)
- **우측:**
  - 2D 평면도 (Canvas, SVG 오버레이로 클릭 가능)
  - 경로점 시각화
- **Mock:** 기본 경로 1개 로드

#### B06_wf3_ProfileCross (종횡단 생성)
- **좌측:**
  - 경로 선택
  - 프로필 타입 선택 (종단도 / 횡단도)
  - 샘플링 거리 (숫자)
- **우측:**
  - 2D 그래프 영역 (SVG 선그래프)
  - 기울기, 높이차 등 정보

#### B07_wf4_DesignDetail (상세 설계)
- **좌측:**
  - 포장 재료 선택
  - 두께, 기울기, 배수 입력
  - Whitebox 토양 분석 옵션
- **우측:**
  - 단면도 (3D 미니 렌더링 또는 단면 다이어그램)

#### B08_wf5_Quantity (수량 산출)
- **좌측:**
  - 설계 정보 요약
  - 수량 계산 버튼
- **우측:**
  - 테이블 (포장재, 흙 깍기/쌓기 수량)
  - 합계 행

#### B09_wf6_Estimation (견적/문서)
- **좌측:**
  - 단가 입력 (포장재, 인건비 등)
  - PDF/DWG 생성 버튼
- **우측:**
  - 견적 요약 테이블 (항목, 수량, 단가, 금액)
  - 총액

---

### Phase D: 최종 페이지 (B10~B11) — 1주

#### B10_Payment (결재)
- **목표:** 견적 검토 및 승인
- **UI:** 견적 미리보기 + 승인/반려 버튼

#### B11_Status (상태/다운로드)
- **목표:** 프로젝트 최종 상태 조회
- **UI:** 진행 상태 배지, 산출물 다운로드 링크 테이블

---

## 3. 파일 구조 및 네이밍

```
A01_Home/
├── A01_Home_UI_Page.ts       # HTML 구조, 컴포넌트, 이벤트 핸들러
└── A01_Home_UI_Style.css     # 페이지 고유 스타일

B04_wf1_Surface/
├── B04_wf1_Surface_UI_View.ts    # WebCAD 뷰어 + 정보 카드
├── B04_wf1_Surface_UI_Form.ts    # 좌측 입력 폼
├── B04_wf1_Surface_UI_Style.css  # 통합 스타일
└── (API 라우터는 나중에)
```

---

## 4. 다국어 등록 전략

각 페이지 구현 시 **선(先) 등록** 프로토콜:

```typescript
// ui_template_locale.ts에 먼저 추가
export const ui_locales = {
  // ...
  A01_Home_Title: ["홈", "Home"],
  A01_Home_NewsSection: ["최신 소식", "Latest News"],
  // ...
};

// A01_Home_UI_Page.ts에서 참조
const title = ui_locales.A01_Home_Title[currentLanguageIndex];
```

---

## 5. Mock 데이터 및 상태 관리

각 페이지는 간단한 **로컬 상태 객체**로 관리:

```typescript
// A01_Home_UI_Page.ts
const state = {
  news: [
    { id: 1, title: "뉴스 1", date: "2026-07-05" },
    { id: 2, title: "뉴스 2", date: "2026-07-04" },
  ],
};
```

로그인 상태는 **글로벌 플래그**:
```typescript
// 모든 페이지에서 참조
const isLoggedIn = localStorage.getItem('authToken') !== null;
```

---

## 6. 구현 순서 및 일정

### Week 1: 로그인 전 기초 (A01, A06, A07)
1. **A01_Home** — 소개 페이지 (카드, 그리드)
2. **A06_Login** — 로그인 폼 + localStorage 토큰 저장
3. **A07_Register** — 회원가입 폼 + 유효성 검사

### Week 2: 로그인 전 상세 (A02~A05, A08)
4. **A02_ProgDetail** — 기능 소개 (아코디언, 탭)
5. **A03_CompDetail** — 회사 정보
6. **A04_NewsHistory** — 뉴스 목록 + 필터
7. **A05_EduDetail** — 튜토리얼
8. **A08_Support** — 문의 양식

### Week 3: 로그인 후 기초 (B01~B03)
9. **B01_AccountDetail** — 사용자 계정
10. **B02_ProjRegister** — 프로젝트 생성
11. **B03_FileInput** — 파일 업로드 + 드래그 드롭

### Week 4~5: 워크플로우 기초 (B04~B06)
12. **B04_wf1_Surface** — 지표면 분석 (3단 레이아웃, Canvas 뷰어)
13. **B05_wf2_Route** — 경로 설계 (2D 맵)
14. **B06_wf3_ProfileCross** — 종횡단 (그래프)

### Week 6: 워크플로우 후반 (B07~B09)
15. **B07_wf4_DesignDetail** — 상세 설계
16. **B08_wf5_Quantity** — 수량 산출 (테이블)
17. **B09_wf6_Estimation** — 견적 (테이블)

### Week 7: 최종 (B10~B11)
18. **B10_Payment** — 결재
19. **B11_Status** — 상태/다운로드

---

## 7. 검증 및 마무리

- **포맷팅:** 각 페이지 완성 후 `npx prettier --write` 실행
- **테스트:** 브라우저에서 각 페이지 수동 테스트 (Mock 데이터 로드 확인)
- **Git 커밋:** 페이지별 커밋 (예: `"feat: implement A01_Home page"`)

---

## 8. 백엔드 연결 (나중)

프론트엔드 완성 후, 각 페이지별로 **선택적 API 연결:**

```typescript
// A06_Login_UI_Page.ts에서
// 현재: localStorage에 Mock 토큰 저장
// 나중: fetchAPI("/api/a06/login", { email, password })로 교체
```

이 전략으로 **프론트엔드 완성도를 먼저 높이고**, 백엔드는 병렬로 또는 선택적으로 구축 가능합니다.

---

## 9. 참고 자료

- **design.md:** Wiza 스타일 (색상, 타이포그래피, 컴포넌트)
- **frontend.md:** UI 제약 조건 (테마 변수, 컴포넌트, i18n, 이벤트 명명)
- **ui_template/:** 3개 핵심 파일 (theme.css, locale.ts, elements.ts)
- **migration_plan.md:** 전체 5 Phase 계획 (이 계획은 Phase A~D = frontend 먼저)

---

**다음 단계:** Week 1 시작 → A01_Home 페이지 구현