vexplor/frontend/docs/CLI_컴포넌트_생성_가이드.md

# 컴포넌트 자동 생성 CLI 가이드

화면 관리 시스템의 컴포넌트를 자동으로 생성하는 CLI 도구 사용법입니다.

## 사용법

```bash
node scripts/create-component.js <컴포넌트이름> <표시이름> <설명> <카테고리> [웹타입]
```

### 파라미터

| 파라미터 | 필수 | 설명 | 예시 |
|---------|-----|------|------|
| 컴포넌트이름 | ✅ | kebab-case 형식의 컴포넌트 ID | `text-input`, `date-picker` |
| 표시이름 | ✅ | 한글 표시명 | `텍스트 입력`, `날짜 선택` |
| 설명 | ✅ | 컴포넌트 설명 | `텍스트를 입력하는 컴포넌트` |
| 카테고리 | ✅ | 컴포넌트 카테고리 | `input`, `display`, `action` |
| 웹타입 | ⭕ | 기본 웹타입 (기본값: text) | `text`, `number`, `button` |

### 카테고리 옵션

| 카테고리 | 설명 | 아이콘 |
|---------|-----|-------|
| `input` | 입력 컴포넌트 | Edit |
| `display` | 표시 컴포넌트 | Eye |
| `action` | 액션/버튼 컴포넌트 | MousePointer |
| `layout` | 레이아웃 컴포넌트 | Layout |
| `form` | 폼 관련 컴포넌트 | FormInput |
| `chart` | 차트 컴포넌트 | BarChart |
| `media` | 미디어 컴포넌트 | Image |
| `navigation` | 네비게이션 컴포넌트 | Menu |
| `feedback` | 피드백 컴포넌트 | Bell |
| `utility` | 유틸리티 컴포넌트 | Settings |

### 웹타입 옵션

| 웹타입 | 설명 | 적용 대상 |
|-------|-----|----------|
| `text` | 텍스트 입력 | 기본 텍스트 필드 |
| `number` | 숫자 입력 | 숫자 전용 필드 |
| `email` | 이메일 입력 | 이메일 검증 필드 |
| `password` | 비밀번호 입력 | 패스워드 필드 |
| `textarea` | 다중행 텍스트 | 텍스트 영역 |
| `select` | 선택박스 | 드롭다운 선택 |
| `button` | 버튼 | 클릭 액션 |
| `checkbox` | 체크박스 | 불린 값 선택 |
| `radio` | 라디오 버튼 | 단일 선택 |
| `date` | 날짜 선택 | 날짜 피커 |
| `file` | 파일 업로드 | 파일 선택 |

## 사용 예시

### 1. 기본 텍스트 입력 컴포넌트

```bash
node scripts/create-component.js text-input "텍스트 입력" "기본 텍스트 입력 컴포넌트" input text
```

### 2. 숫자 입력 컴포넌트

```bash
node scripts/create-component.js number-input "숫자 입력" "숫자만 입력 가능한 컴포넌트" input number
```

### 3. 버튼 컴포넌트

```bash
node scripts/create-component.js action-button "액션 버튼" "사용자 액션을 처리하는 버튼" action button
```

### 4. 차트 컴포넌트

```bash
node scripts/create-component.js bar-chart "막대 차트" "데이터를 막대 그래프로 표시" chart
```

### 5. 이미지 표시 컴포넌트

```bash
node scripts/create-component.js image-viewer "이미지 뷰어" "이미지를 표시하는 컴포넌트" media
```

## 생성되는 파일들

CLI를 실행하면 다음 파일들이 자동으로 생성됩니다:

```
lib/registry/components/[컴포넌트이름]/
├── index.ts                    # 컴포넌트 정의 및 메타데이터
├── [컴포넌트이름]Component.tsx  # 메인 컴포넌트 파일
├── [컴포넌트이름]Renderer.tsx   # 자동 등록 렌더러
├── [컴포넌트이름]ConfigPanel.tsx # 설정 패널 UI
├── types.ts                    # TypeScript 타입 정의
└── README.md                   # 컴포넌트 문서
```

## 자동 처리되는 작업들

### ✅ 자동 등록

- `lib/registry/components/index.ts`에 import 구문 자동 추가
- 컴포넌트 레지스트리에 자동 등록
- 브라우저에서 즉시 사용 가능

### ✅ 타입 안전성

- TypeScript 인터페이스 자동 생성
- 컴포넌트 설정 타입 정의
- Props 타입 안전성 보장

### ✅ 설정 패널

- 웹타입별 맞춤 설정 UI 자동 생성
- 공통 설정 (disabled, required, readonly) 포함
- 실시간 설정 값 업데이트

### ✅ 문서화

- 자동 생성된 README.md
- 사용법 및 설정 옵션 문서
- 개발자 정보 및 CLI 명령어 기록

## CLI 실행 후 확인사항

### 1. 브라우저에서 확인

```javascript
// 개발자 도구에서 확인
__COMPONENT_REGISTRY__.get("컴포넌트이름")
```

### 2. 컴포넌트 패널에서 테스트

1. 화면 디자이너 열기
2. 컴포넌트 패널에서 새 컴포넌트 확인
3. 드래그앤드롭으로 캔버스에 추가
4. 속성 편집 패널에서 설정 테스트

### 3. 설정 패널 동작 확인

- 속성 변경 시 실시간 반영 여부
- 필수/선택 설정들의 정상 동작
- 웹타입별 특화 설정 확인

## 트러블슈팅

### import 자동 추가 실패

만약 index.ts에 import가 자동 추가되지 않았다면:

```typescript
// lib/registry/components/index.ts에 수동 추가
import "./컴포넌트이름/컴포넌트이름Renderer";
```

### 컴포넌트가 패널에 나타나지 않는 경우

1. 브라우저 새로고침
2. 개발자 도구에서 오류 확인
3. import 구문 확인
4. TypeScript 컴파일 오류 확인

### 설정 패널이 제대로 작동하지 않는 경우

1. 타입 정의 확인 (`types.ts`)
2. ConfigPanel 컴포넌트 확인
3. 웹타입별 설정 로직 확인

## 고급 사용법

### 사용자 정의 옵션

```bash
# 크기 지정
node scripts/create-component.js my-component "내 컴포넌트" "설명" display --size=300x50

# 태그 추가
node scripts/create-component.js my-component "내 컴포넌트" "설명" display --tags=tag1,tag2,tag3

# 작성자 지정
node scripts/create-component.js my-component "내 컴포넌트" "설명" display --author="개발자명"
```

### 생성 후 커스터마이징

1. **컴포넌트 로직 수정**: `[컴포넌트이름]Component.tsx`
2. **설정 패널 확장**: `[컴포넌트이름]ConfigPanel.tsx`
3. **타입 정의 확장**: `types.ts`
4. **렌더러 로직 수정**: `[컴포넌트이름]Renderer.tsx`

## 베스트 프랙티스

### 네이밍 규칙

- **컴포넌트이름**: kebab-case (예: `text-input`, `date-picker`)
- **표시이름**: 명확한 한글명 (예: "텍스트 입력", "날짜 선택")
- **설명**: 구체적이고 명확한 설명

### 카테고리 선택

- 컴포넌트의 주된 용도에 맞는 카테고리 선택
- 일관성 있는 카테고리 분류
- 사용자가 찾기 쉬운 카테고리 구조

### 웹타입 선택

- 컴포넌트의 데이터 타입에 맞는 웹타입 선택
- 기본 동작과 검증 로직 고려
- 확장 가능성 고려

## 결론

이 CLI 도구를 사용하면 화면 관리 시스템에 새로운 컴포넌트를 빠르고 일관성 있게 추가할 수 있습니다. 자동 생성된 템플릿을 기반으로 비즈니스 로직에 집중하여 개발할 수 있습니다.

더 자세한 정보는 [컴포넌트 시스템 가이드](./컴포넌트_시스템_가이드.md)를 참조하세요.