sam-react-prod/docs/dev/dev_plans/dev-toolbar-plan.md

# DevToolbar - 견적→출하 테스트 자동화 도구 계획

> **작성일**: 2026-01-20
> **목적**: 견적→수주→작업지시→완료→출하 전체 플로우를 빠르게 테스트하기 위한 자동 데이터 입력 도구
> **기준 문서**: 각 폼 컴포넌트 (QuoteRegistration, OrderRegistration, WorkOrderCreate, ShipmentCreate)
> **상태**: 🔄 진행중 (Serena ID: dev-toolbar-state)

---

## 📍 현재 진행 상태

| 항목 | 내용 |
|------|------|
| **마지막 완료 작업** | Phase 1 완료 (기반 구조 생성) |
| **다음 작업** | 2.1 QuoteRegistration에 useDevFill 연결 |
| **진행률** | 3/8 (37.5%) |
| **마지막 업데이트** | 2026-01-20 |

---

## 1. 개요

### 1.1 배경
- 견적 → 수주 → 작업지시 → 완료 → 출하까지 전체 프로세스 테스트 시 매번 수동 데이터 입력 필요
- 영업 데모 시 빠른 플로우 시연 필요
- 테스트 완료 후 쉽게 제거 가능해야 함

### 1.2 기준 원칙
```
┌─────────────────────────────────────────────────────────────────┐
│  🎯 핵심 원칙                                                    │
├─────────────────────────────────────────────────────────────────┤
│  1. 독립적 구현 - 기존 컴포넌트 최소 수정                         │
│  2. 온/오프 제어 - 환경변수로 완전 비활성화 가능                   │
│  3. 쉬운 제거 - 테스트 후 폴더 삭제 + import 제거로 완전 제거     │
│  4. 플로우 연결 - 이전 단계 ID를 다음 단계에 자동 전달            │
└─────────────────────────────────────────────────────────────────┘
```

### 1.3 변경 승인 정책

| 분류 | 예시 | 승인 |
|------|------|------|
| ✅ 즉시 가능 | dev 폴더 내 파일 추가/수정, 환경변수 추가 | 불필요 |
| ⚠️ 컨펌 필요 | 기존 컴포넌트에 useDevFill hook 추가, layout.tsx 수정 | **필수** |
| 🔴 금지 | 기존 컴포넌트 로직 변경, 프로덕션 코드 영향 | 별도 협의 |

### 1.4 준수 규칙
- 프론트엔드 전용 작업 (API 변경 없음)
- 환경변수 `NEXT_PUBLIC_DEV_TOOLBAR_ENABLED=true`로 제어

---

## 2. 대상 범위

### 2.1 Phase 1: 기반 구조 (완료)

| # | 작업 항목 | 상태 | 파일 |
|---|----------|:----:|------|
| 1.1 | DevFillContext.tsx 생성 | ✅ | `react/src/components/dev/DevFillContext.tsx` |
| 1.2 | useDevFill.ts hook 생성 | ✅ | `react/src/components/dev/useDevFill.ts` |
| 1.3 | DevToolbar.tsx 생성 | ✅ | `react/src/components/dev/DevToolbar.tsx` |
| 1.4 | 샘플 데이터 생성기 | ✅ | `react/src/components/dev/generators/*.ts` |
| 1.5 | index.ts export 정리 | ✅ | `react/src/components/dev/index.ts` |

### 2.2 Phase 2: 컴포넌트 연결 (진행중)

| # | 작업 항목 | 상태 | 파일 |
|---|----------|:----:|------|
| 2.1 | QuoteRegistration에 useDevFill 연결 | ⏳ | `react/src/components/quotes/QuoteRegistration.tsx` |
| 2.2 | OrderRegistration에 useDevFill 연결 | ⏳ | `react/src/components/orders/OrderRegistration.tsx` |
| 2.3 | WorkOrderCreate에 useDevFill 연결 | ⏳ | `react/src/components/production/WorkOrders/WorkOrderCreate.tsx` |
| 2.4 | WorkOrderDetail에 완료 버튼 연결 | ⏳ | `react/src/components/production/WorkOrders/WorkOrderDetail.tsx` |
| 2.5 | ShipmentCreate에 useDevFill 연결 | ⏳ | `react/src/components/outbound/ShipmentManagement/ShipmentCreate.tsx` |

### 2.3 Phase 3: 통합 및 설정

| # | 작업 항목 | 상태 | 파일 |
|---|----------|:----:|------|
| 3.1 | DevFillProvider를 layout.tsx에 추가 | ⏳ | `react/src/app/[locale]/(protected)/layout.tsx` |
| 3.2 | DevToolbar를 layout.tsx에 추가 | ⏳ | `react/src/app/[locale]/(protected)/layout.tsx` |
| 3.3 | 환경변수 설정 (.env.local) | ⏳ | `react/.env.local` |

### 2.4 Phase 4: 테스트 및 검증

| # | 작업 항목 | 상태 | 비고 |
|---|----------|:----:|------|
| 4.1 | 견적 페이지 테스트 | ⏳ | `/sales/quote-management/new` |
| 4.2 | 수주 페이지 테스트 | ⏳ | `/sales/order-management-sales/new` |
| 4.3 | 작업지시 페이지 테스트 | ⏳ | `/production/work-orders/create` |
| 4.4 | 작업완료 테스트 | ⏳ | `/production/work-orders/[id]` |
| 4.5 | 출하 페이지 테스트 | ⏳ | `/outbound/shipments/new` |
| 4.6 | 전체 플로우 테스트 | ⏳ | 견적→수주→작업지시→완료→출하 |

---

## 3. 아키텍처

### 3.1 파일 구조
```
react/src/components/dev/
├── DevFillContext.tsx     # Context Provider (상태 관리)
├── useDevFill.ts          # Hook (각 폼에서 사용)
├── DevToolbar.tsx         # 플로팅 UI (화면 하단)
├── index.ts               # Export 정리
└── generators/
    ├── index.ts           # 공통 유틸 (randomPick, randomInt 등)
    ├── quoteData.ts       # 견적 샘플 데이터
    ├── orderData.ts       # 수주 샘플 데이터
    ├── workOrderData.ts   # 작업지시 샘플 데이터
    └── shipmentData.ts    # 출하 샘플 데이터
```

### 3.2 데이터 흐름
```
┌─────────────────────────────────────────────────────────────────┐
│                     DevFillProvider (Context)                    │
│  ├── isEnabled: 환경변수 기반 활성화 상태                        │
│  ├── isVisible: 툴바 표시 상태 (localStorage)                   │
│  ├── currentPage: 현재 페이지 타입                              │
│  ├── flowData: { quoteId, orderId, workOrderId, lotNo }        │
│  └── fillFunctions: Map<PageType, FillFunction>                │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        DevToolbar (UI)                           │
│  [견적] → [수주] → [작업지시] → [완료] → [출하]                   │
│  현재 페이지에 해당하는 버튼만 활성화                             │
│  클릭 시 fillForm(pageType) 호출                                │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              각 폼 컴포넌트 (useDevFill hook)                    │
│  useDevFill('quote', (data) => setFormData(generateQuoteData())) │
│  - 마운트 시 fillFunction 등록                                   │
│  - DevToolbar 클릭 시 등록된 함수 실행                          │
│  - 폼에 샘플 데이터 자동 채움                                    │
└─────────────────────────────────────────────────────────────────┘
```

### 3.3 각 단계별 입력 필드

| 단계 | 주요 필드 | 샘플 데이터 |
|------|----------|------------|
| **견적** | 발주처, 현장명, 담당자, 연락처, 납기일, 품목(층수/부호/카테고리/제품명/사이즈/수량) | 랜덤 거래처, +7일 납기, 1~5개 품목 |
| **수주** | 견적선택 + 배송방식, 배송일, 수신자 | +14일 출고, +21일 납기 |
| **작업지시** | 수주선택 + 공정, 출고예정일, 우선순위 | 랜덤 공정, 1~3주 후 |
| **완료** | 버튼 클릭 | handleStatusChange('completed') |
| **출하** | 로트번호, 출고예정일, 우선순위, 배송방식 | 랜덤 로트, 오늘 날짜 |

---

## 4. 상세 작업 내용

### 4.1 Phase 1: 기반 구조 (✅ 완료)

#### 1.1 DevFillContext.tsx
- **상태**: ✅ 완료
- **파일**: `react/src/components/dev/DevFillContext.tsx`
- **주요 기능**:
  - `isEnabled`: 환경변수 기반 활성화
  - `isVisible`: localStorage 기반 표시 상태
  - `registerFillForm/unregisterFillForm`: 폼 함수 등록/해제
  - `fillForm`: 폼 채우기 실행
  - `flowData`: 플로우 간 데이터 전달

#### 1.2 useDevFill.ts
- **상태**: ✅ 완료
- **파일**: `react/src/components/dev/useDevFill.ts`
- **사용법**:
```typescript
useDevFill('quote', (data) => {
  setFormData(generateQuoteData({ clients, products }));
});
```

#### 1.3 DevToolbar.tsx
- **상태**: ✅ 완료
- **파일**: `react/src/components/dev/DevToolbar.tsx`
- **주요 기능**:
  - 화면 하단 플로팅 UI
  - 현재 페이지 자동 감지 (URL 기반)
  - 플로우 단계 버튼 (견적→수주→작업지시→완료→출하)
  - 숨기기/보이기 토글

#### 1.4 샘플 데이터 생성기
- **상태**: ✅ 완료
- **파일들**:
  - `generators/index.ts`: 공통 유틸 (randomPick, randomInt, randomPhone 등)
  - `generators/quoteData.ts`: 견적 데이터 (QuoteFormData)
  - `generators/orderData.ts`: 수주 데이터 (OrderFormData)
  - `generators/workOrderData.ts`: 작업지시 데이터
  - `generators/shipmentData.ts`: 출하 데이터 (ShipmentCreateFormData)

### 4.2 Phase 2: 컴포넌트 연결 (⏳ 대기)

각 컴포넌트에 다음 패턴으로 useDevFill 연결:

```typescript
// 1. import 추가
import { useDevFill } from '@/components/dev';
import { generateQuoteData } from '@/components/dev/generators/quoteData';

// 2. 컴포넌트 내부에서 hook 사용
useDevFill('quote', useCallback(() => {
  const sampleData = generateQuoteData({ clients, products });
  setFormData(sampleData);
}, [clients, products]));
```

### 4.3 Phase 3: 통합 및 설정 (⏳ 대기)

#### layout.tsx 수정
```typescript
import { DevFillProvider, DevToolbar } from '@/components/dev';

export default function ProtectedLayout({ children }) {
  return (
    <DevFillProvider>
      {/* 기존 레이아웃 */}
      {children}
      <DevToolbar />
    </DevFillProvider>
  );
}
```

#### 환경변수 설정
```bash
# react/.env.local
NEXT_PUBLIC_DEV_TOOLBAR_ENABLED=true
```

---

## 5. 컨펌 대기 목록

| # | 항목 | 변경 내용 | 영향 범위 | 상태 |
|---|------|----------|----------|------|
| 1 | QuoteRegistration.tsx | useDevFill hook 추가 (약 10줄) | 견적 등록 | ⏳ |
| 2 | OrderRegistration.tsx | useDevFill hook 추가 (약 10줄) | 수주 등록 | ⏳ |
| 3 | WorkOrderCreate.tsx | useDevFill hook 추가 (약 10줄) | 작업지시 등록 | ⏳ |
| 4 | WorkOrderDetail.tsx | useDevFill hook 추가 (약 10줄) | 작업지시 상세 | ⏳ |
| 5 | ShipmentCreate.tsx | useDevFill hook 추가 (약 10줄) | 출하 등록 | ⏳ |
| 6 | layout.tsx | DevFillProvider, DevToolbar 추가 | 전체 레이아웃 | ⏳ |

---

## 6. 변경 이력

| 날짜 | 항목 | 변경 내용 | 파일 | 승인 |
|------|------|----------|------|------|
| 2026-01-20 | 1.1~1.5 | Phase 1 기반 구조 생성 완료 | dev/*.ts, dev/*.tsx | ✅ |
| 2026-01-20 | - | 계획 문서 작성 | docs/dev_plans/dev-toolbar-plan.md | - |

---

## 7. 참고 문서

### 7.1 관련 컴포넌트 경로
- **견적**: `react/src/components/quotes/QuoteRegistration.tsx`
- **수주**: `react/src/components/orders/OrderRegistration.tsx`
- **작업지시**: `react/src/components/production/WorkOrders/WorkOrderCreate.tsx`
- **작업상세**: `react/src/components/production/WorkOrders/WorkOrderDetail.tsx`
- **출하**: `react/src/components/outbound/ShipmentManagement/ShipmentCreate.tsx`

### 7.2 폼 데이터 타입
- `QuoteFormData`: 견적 폼 데이터 (QuoteRegistration.tsx 내 정의)
- `OrderFormData`: 수주 폼 데이터 (OrderRegistration.tsx 내 정의)
- `ShipmentCreateFormData`: 출하 폼 데이터 (types.ts 내 정의)

---

## 8. 제거 방법

테스트 완료 후 다음 단계로 제거:

### Step 1: 환경변수 비활성화 (즉시 효과)
```bash
# react/.env.local
NEXT_PUBLIC_DEV_TOOLBAR_ENABLED=false
```

### Step 2: 코드 완전 제거 (선택)
```bash
# 1. dev 폴더 삭제
rm -rf react/src/components/dev/

# 2. layout.tsx에서 import 및 컴포넌트 제거
# - DevFillProvider 제거
# - DevToolbar 제거

# 3. 각 폼 컴포넌트에서 useDevFill 관련 코드 제거
# - import 문 제거
# - useDevFill hook 호출 제거
```

---

## 9. 검증 결과

> 작업 완료 후 이 섹션에 검증 결과 추가

### 9.1 테스트 케이스

| 페이지 | 테스트 항목 | 예상 결과 | 실제 결과 | 상태 |
|--------|----------|----------|----------|------|
| 견적 | DevToolbar "견적 채우기" 클릭 | 폼에 샘플 데이터 채워짐 | | ⏳ |
| 수주 | DevToolbar "수주 채우기" 클릭 | 폼에 샘플 데이터 채워짐 | | ⏳ |
| 작업지시 | DevToolbar "작업지시 채우기" 클릭 | 폼에 샘플 데이터 채워짐 | | ⏳ |
| 작업상세 | DevToolbar "완료 채우기" 클릭 | 완료 처리 실행 | | ⏳ |
| 출하 | DevToolbar "출하 채우기" 클릭 | 폼에 샘플 데이터 채워짐 | | ⏳ |
| 전체 플로우 | 견적→수주→작업지시→완료→출하 | 저장 버튼만 클릭하며 완료 | | ⏳ |

### 9.2 성공 기준

| 기준 | 달성 | 비고 |
|------|------|------|
| 각 페이지에서 DevToolbar 표시 | ⏳ | |
| 현재 페이지 자동 감지 | ⏳ | |
| 클릭 시 폼 데이터 자동 채움 | ⏳ | |
| 환경변수로 비활성화 가능 | ⏳ | |
| 전체 플로우 3분 내 완료 | ⏳ | 기존 15분 → 3분 |

---

## 10. 자기완결성 점검 결과

### 10.1 체크리스트 검증

| # | 검증 항목 | 상태 | 비고 |
|---|----------|:----:|------|
| 1 | 작업 목적이 명확한가? | ✅ | 1.1 배경에 명시 |
| 2 | 성공 기준이 정의되어 있는가? | ✅ | 9.2에 명시 |
| 3 | 작업 범위가 구체적인가? | ✅ | 2. 대상 범위에 파일 경로 포함 |
| 4 | 의존성이 명시되어 있는가? | ✅ | 프론트엔드 전용, API 없음 |
| 5 | 참고 파일 경로가 정확한가? | ✅ | 7.1에 명시 |
| 6 | 단계별 절차가 실행 가능한가? | ✅ | 4. 상세 작업 내용에 코드 예시 포함 |
| 7 | 검증 방법이 명시되어 있는가? | ✅ | 9.1 테스트 케이스 |
| 8 | 모호한 표현이 없는가? | ✅ | 구체적 파일 경로 및 코드 포함 |

### 10.2 새 세션 시뮬레이션 테스트

| 질문 | 답변 가능 | 참조 섹션 |
|------|:--------:|----------|
| Q1. 이 작업의 목적은 무엇인가? | ✅ | 1.1 배경 |
| Q2. 어디서부터 시작해야 하는가? | ✅ | 📍 현재 진행 상태 |
| Q3. 어떤 파일을 수정해야 하는가? | ✅ | 2. 대상 범위 |
| Q4. 작업 완료 확인 방법은? | ✅ | 9.1 테스트 케이스 |
| Q5. 막혔을 때 참고 문서는? | ✅ | 7. 참고 문서 |

**결과**: 5/5 통과 → ✅ 자기완결성 확보

---

*이 문서는 /plan 스킬로 생성되었습니다.*