From 37435d2cca714bb9873553dd8577943b5f65cd7e Mon Sep 17 00:00:00 2001
From: yoosangwook <swyoo@interplug.co.kr>
Date: Thu, 29 May 2025 10:32:10 +0900
Subject: [PATCH] feat: add documentation for Login component, project
 structure, and login process

- Introduced diagrams for the Login component structure, project architecture, and login sequence.
- Detailed state management, external hooks, event handling, and UI components in the Login documentation.
- Provided an overview of the component relationships and roles within the application architecture.
---
 diagram/Login.md    |  88 +++++++++++++++++++++++++
 diagram/mermaid.md  |  98 +++++++++++++++++++++++++++
 diagram/mermaid2.md | 125 +++++++++++++++++++++++++++++++++++
 diagram/mermaid3.md | 157 ++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 468 insertions(+)
 create mode 100644 diagram/Login.md
 create mode 100644 diagram/mermaid.md
 create mode 100644 diagram/mermaid2.md
 create mode 100644 diagram/mermaid3.md

diff --git a/diagram/Login.md b/diagram/Login.md
new file mode 100644
index 0000000..2e816ca
--- /dev/null
+++ b/diagram/Login.md
@@ -0,0 +1,88 @@
+# Login Component Structure
+
+## Component Diagram
+
+```mermaid
+graph TD
+    A[Login Component] --> B[State Management]
+    B --> B1[useState Hooks]
+    B1 --> B1a[pwShow: 비밀번호 표시 여부]
+    B1 --> B1b[idSave: ID 저장 여부]
+    B1 --> B1c[isPartners: Q.PARTNERS 여부]
+    B1 --> B1d[isLogin: 로그인 상태]
+
+    A --> C[Account Management]
+    C --> C1[useReducer]
+    C1 --> C1a[loginId]
+    C1 --> C1b[pwd]
+
+    A --> D[External Hooks]
+    D --> D1[useRouter]
+    D --> D2[useLocalStorage]
+    D --> D3[useSessionStore]
+    D --> D4[useAxios]
+    D --> D5[useQuery]
+
+    A --> E[Event Handlers]
+    E --> E1[handleLogin]
+    E --> E2[handleKeyDown]
+    E --> E3[validateLogin]
+
+    A --> F[Effects]
+    F --> F1[Login Success Effect]
+    F1 --> F1a[세션 저장]
+    F1 --> F1b[라우팅]
+    F --> F2[Email Validation Effect]
+    F2 --> F2a[Partners 모드 전환]
+
+    A --> G[UI Components]
+    G --> G1[Login Form]
+    G1 --> G1a[ID Input]
+    G1 --> G1b[Password Input]
+    G1 --> G1c[Checkboxes]
+    G1 --> G1d[Login Button]
+```
+
+## 주요 특징과 동작 방식
+
+### 1. 상태 관리
+
+- `useState`를 사용하여 UI 상태 관리 (비밀번호 표시, ID 저장, Partners 모드)
+- `useReducer`를 사용하여 계정 정보(loginId, pwd) 관리
+
+### 2. 외부 훅 통합
+
+- `useRouter`: 페이지 라우팅
+- `useLocalStorage`: 로컬 스토리지 데이터 관리
+- `useSessionStore`: 세션 상태 관리
+- `useAxios`: API 통신
+- `useQuery`: 로그인 API 호출 및 상태 관리
+
+### 3. 이벤트 처리
+
+- `handleLogin`: 로그인 시도
+- `handleKeyDown`: Enter 키 입력 처리
+- `validateLogin`: 입력값 유효성 검사
+
+### 4. 효과 처리
+
+- 로그인 성공 시 세션 저장 및 라우팅
+- 이메일 형식에 따른 Partners 모드 자동 전환
+
+### 5. UI 구성
+
+- ID/PW 입력 필드
+- 비밀번호 표시/숨김 토글
+- ID 저장 체크박스
+- Q.PARTNERS 토글
+- 로그인 버튼
+
+### 6. 보안 및 유효성 검사
+
+- 이메일 형식 검증
+- 필수 입력값 검증
+- API 응답 코드에 따른 처리 (200: 성공, 400: 실패)
+
+## 특징
+
+이 컴포넌트는 클라이언트 사이드에서 동작하며('use client'), 사용자 인증과 관련된 모든 로직을 포함하고 있습니다. 특히 Q.PARTNERS 모드와 일반 모드를 구분하여 다른 API 엔드포인트를 사용하는 특징이 있습니다.
diff --git a/diagram/mermaid.md b/diagram/mermaid.md
new file mode 100644
index 0000000..e6b5ef8
--- /dev/null
+++ b/diagram/mermaid.md
@@ -0,0 +1,98 @@
+# Project Structure Documentation
+
+## Component Relationship Diagram
+
+```mermaid
+graph TD
+    subgraph Root
+        A[RootLayout] --> B[ReactQueryProviders]
+        B --> C[EdgeProvider]
+        C --> D[HTML Structure]
+    end
+
+    subgraph Layout Components
+        D --> E[Header]
+        D --> F[Main Content]
+        D --> G[Footer]
+        D --> H[Float Button]
+        D --> I[PopupController]
+    end
+
+    subgraph Pages
+        F --> J[Login]
+        F --> K[Survey Sale]
+        F --> L[Suitable]
+        F --> M[Inquiry]
+        F --> N[Password Reset]
+        F --> O[PDF]
+    end
+
+    subgraph Providers
+        P1[ReactQueryProvider]
+        P2[EdgeProvider]
+    end
+
+    subgraph Components
+        C1[UI Components]
+        C2[Popup Components]
+        C3[PDF Components]
+        C4[Survey Components]
+        C5[Inquiry Components]
+    end
+
+    subgraph Utils
+        U1[Session Management]
+        U2[Mailer]
+        U3[API Routes]
+    end
+
+    %% Relationships
+    A --> P1
+    A --> P2
+    J --> U1
+    K --> C4
+    L --> C4
+    M --> C5
+    N --> U2
+    O --> C3
+```
+
+## Structure Explanation
+
+### 1. Root Layout
+
+- `RootLayout`이 전체 애플리케이션의 기본 구조를 정의
+- `ReactQueryProviders`와 `EdgeProvider`로 감싸져 있음
+
+### 2. Layout Components
+
+- Header, Footer, Float Button 등 공통 레이아웃 컴포넌트
+- `PopupController`로 팝업 관리
+
+### 3. Pages
+
+- Next.js App Router 기반의 페이지 구조
+- Login, Survey Sale, Suitable, Inquiry 등 주요 페이지들
+
+### 4. Providers
+
+- `ReactQueryProvider`: 데이터 페칭 관리
+- `EdgeProvider`: 세션 및 상태 관리
+
+### 5. Components
+
+- UI Components: 공통 UI 요소
+- Popup Components: 팝업 관련 컴포넌트
+- PDF Components: PDF 생성/관리 컴포넌트
+- Survey Components: 설문 관련 컴포넌트
+- Inquiry Components: 문의 관련 컴포넌트
+
+### 6. Utils
+
+- Session Management: 세션 관리
+- Mailer: 이메일 발송 기능
+- API Routes: 백엔드 API 엔드포인트
+
+## Architecture Overview
+
+이 구조는 Next.js의 App Router를 기반으로 하며, 컴포넌트 기반 아키텍처를 따르고 있습니다. 각 기능별로 모듈화가 잘 되어있고, 공통 컴포넌트와 유틸리티를 효율적으로 재사용할 수 있도록 구성되어 있습니다.
diff --git a/diagram/mermaid2.md b/diagram/mermaid2.md
new file mode 100644
index 0000000..5d8e561
--- /dev/null
+++ b/diagram/mermaid2.md
@@ -0,0 +1,125 @@
+# Login Process Documentation
+
+## Login Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant Login as Login Component
+    participant API as Auth API
+    participant QSP as QSP API
+    participant Session as Session Store
+    participant Router as Next Router
+
+    User->>Login: Enter credentials
+    Login->>Login: Validate input
+    alt Invalid Input
+        Login->>User: Show error message
+    else Valid Input
+        Login->>API: POST /api/auth
+        API->>QSP: POST /api/user/login
+        QSP-->>API: Return user data
+
+        alt Login Success
+            API->>Session: Create session
+            Session->>Session: Set user data
+            Session->>Session: Set role
+            API-->>Login: Return success response
+            Login->>Router: Redirect to home
+            Router->>User: Show home page
+        else Login Failed
+            API-->>Login: Return error response
+            Login->>User: Show error message
+        end
+    end
+```
+
+## Login Process Flow
+
+1. **User Input**
+
+   - User enters login credentials (ID and password)
+   - Optional: User can toggle Q.PARTNERS mode
+   - Optional: User can save ID
+
+2. **Input Validation**
+
+   - Checks if ID and password are not empty
+   - Validates email format for Q.PARTNERS mode
+
+3. **Authentication Request**
+
+   - Sends credentials to Auth API
+   - Auth API forwards request to QSP API
+   - QSP API validates credentials
+
+4. **Session Management**
+
+   - On successful login:
+     - Creates new session
+     - Stores user data
+     - Sets user role based on permissions
+     - Saves session to cookies
+
+5. **Response Handling**
+   - Success: Redirects to home page
+   - Failure: Shows error message
+
+## Role Assignment Logic
+
+The system assigns roles based on the following rules:
+
+- `T01`: If userId is 'T01'
+- `Admin`: If groupId is '60000'
+- `Admin_Sub`: If groupId is '70000' and builderNo is null
+- `Builder`: If groupId is '70000' and builderNo is not null
+- `User`: Default role for all other cases
+
+```mermaid
+graph TD
+subgraph Root
+A[RootLayout] --> B[ReactQueryProviders]
+B --> C[EdgeProvider]
+C --> D[HTML Structure]
+end
+    subgraph Layout Components
+        D --> E[Header]
+        D --> F[Main Content]
+        D --> G[Footer]
+        D --> H[Float Button]
+        D --> I[PopupController]
+    end
+    subgraph Pages
+        F --> J[Login]
+        F --> K[Survey Sale]
+        F --> L[Suitable]
+        F --> M[Inquiry]
+        F --> N[Password Reset]
+        F --> O[PDF]
+    end
+    subgraph Providers
+        P1[ReactQueryProvider]
+        P2[EdgeProvider]
+    end
+    subgraph Components
+        C1[UI Components]
+        C2[Popup Components]
+        C3[PDF Components]
+        C4[Survey Components]
+        C5[Inquiry Components]
+    end
+    subgraph Utils
+        U1[Session Management]
+        U2[Mailer]
+        U3[API Routes]
+    end
+    %% Relationships
+    A --> P1
+    A --> P2
+    J --> U1
+    K --> C4
+    L --> C4
+    M --> C5
+    N --> U2
+    O --> C3
+```
diff --git a/diagram/mermaid3.md b/diagram/mermaid3.md
new file mode 100644
index 0000000..cf9fd15
--- /dev/null
+++ b/diagram/mermaid3.md
@@ -0,0 +1,157 @@
+# Pages and Components Class Diagram
+
+## Class Diagram
+
+```mermaid
+classDiagram
+    class RootLayout {
+        +ReactNode children
+        +ReactNode header
+        +ReactNode footer
+        +ReactNode floatBtn
+        +ReactQueryProviders
+        +EdgeProvider
+        +PopupController
+    }
+
+    class Page {
+        <<interface>>
+        +ReactNode render()
+    }
+
+    class LoginPage {
+        +Login component
+        +handleLogin()
+        +validateInput()
+    }
+
+    class SurveySalePage {
+        +SurveySaleList
+        +SurveySaleDetail
+        +handleSurveySubmit()
+    }
+
+    class SuitablePage {
+        +SuitableList
+        +SuitableDetail
+        +handleSuitableSubmit()
+    }
+
+    class InquiryPage {
+        +InquiryList
+        +InquiryDetail
+        +handleInquirySubmit()
+    }
+
+    class PasswordResetPage {
+        +PasswordResetForm
+        +handlePasswordReset()
+    }
+
+    class PDFPage {
+        +PDFViewer
+        +PDFGenerator
+        +handlePDFGeneration()
+    }
+
+    class BaseComponent {
+        <<interface>>
+        +ReactNode render()
+    }
+
+    class UIComponent {
+        +Button
+        +Input
+        +Select
+        +Modal
+    }
+
+    class PopupComponent {
+        +PopupController
+        +PopupContent
+        +handlePopup()
+    }
+
+    class PDFComponent {
+        +PDFViewer
+        +PDFGenerator
+        +handlePDF()
+    }
+
+    class SurveyComponent {
+        +SurveyForm
+        +SurveyList
+        +handleSurvey()
+    }
+
+    class InquiryComponent {
+        +InquiryForm
+        +InquiryList
+        +handleInquiry()
+    }
+
+    %% Relationships
+    RootLayout --> Page
+    Page <|-- LoginPage
+    Page <|-- SurveySalePage
+    Page <|-- SuitablePage
+    Page <|-- InquiryPage
+    Page <|-- PasswordResetPage
+    Page <|-- PDFPage
+
+    BaseComponent <|-- UIComponent
+    BaseComponent <|-- PopupComponent
+    BaseComponent <|-- PDFComponent
+    BaseComponent <|-- SurveyComponent
+    BaseComponent <|-- InquiryComponent
+
+    LoginPage --> BaseComponent
+    SurveySalePage --> SurveyComponent
+    SuitablePage --> SurveyComponent
+    InquiryPage --> InquiryComponent
+    PasswordResetPage --> UIComponent
+    PDFPage --> PDFComponent
+
+    RootLayout --> PopupComponent
+```
+
+## Component Hierarchy
+
+1. **Root Layout**
+
+   - 최상위 레이아웃 컴포넌트
+   - ReactQuery와 Edge Provider를 포함
+   - 공통 레이아웃 요소 관리
+
+2. **Pages**
+
+   - LoginPage: 로그인 기능
+   - SurveySalePage: 설문 판매 관리
+   - SuitablePage: 적합성 관리
+   - InquiryPage: 문의 관리
+   - PasswordResetPage: 비밀번호 재설정
+   - PDFPage: PDF 생성 및 관리
+
+3. **Base Components**
+   - UIComponent: 기본 UI 요소
+   - PopupComponent: 팝업 관리
+   - PDFComponent: PDF 관련 기능
+   - SurveyComponent: 설문 관련 기능
+   - InquiryComponent: 문의 관련 기능
+
+## Component Relationships
+
+1. **Page-Component Relationship**
+
+   - 각 페이지는 필요한 컴포넌트들을 조합하여 구성
+   - 페이지별로 특화된 컴포넌트 사용
+
+2. **Component Inheritance**
+
+   - 모든 컴포넌트는 BaseComponent 인터페이스 구현
+   - 각 컴포넌트 타입별로 특화된 기능 제공
+
+3. **Layout Integration**
+   - RootLayout이 전체 페이지 구조 관리
+   - PopupComponent를 통한 모달 관리
+   - 공통 UI 요소의 일관성 유지