# AutocompleteSearchInput 컴포넌트 사용 가이드

## 📌 이 컴포넌트는 무엇인가요?

검색 가능한 드롭다운 선택 박스입니다.
거래처, 품목, 직원 등을 검색해서 선택할 때 사용합니다.

---

## ⚙️ 패널 설정 방법

### 1. 기본 검색 설정 (필수)

#### 테이블명
- **의미**: 어디서 검색할 것인가?
- **예시**: `customer_mng` (거래처 테이블)

#### 표시 필드
- **의미**: 사용자에게 무엇을 보여줄 것인가?
- **예시**: `customer_name` → 화면에 "삼성전자" 표시

#### 값 필드
- **의미**: 실제로 어떤 값을 가져올 것인가?
- **예시**: `customer_code` → "CUST-0001" 가져오기

#### 검색 필드 (선택)
- **의미**: 어떤 컬럼으로 검색할 것인가?
- **예시**: `customer_name`, `customer_code` 추가
- **동작**: 이름으로도 검색, 코드로도 검색 가능

---

### 2. 값 필드 저장 위치 (고급, 선택)

#### 저장 테이블
- **기본값**: 화면의 연결 테이블에 자동 저장
- **변경 시**: 다른 테이블에 저장 가능

#### 저장 컬럼
- **기본값**: 컴포넌트의 바인딩 필드
- **변경 시**: 다른 컬럼에 저장 가능

> 💡 **대부분은 기본값을 사용하면 됩니다!**

---

## 📖 사용 예제

### 예제 1: 거래처 선택 (가장 일반적)

#### 패널 설정
```
테이블명: customer_mng
표시 필드: customer_name
값 필드: customer_code
검색 필드: customer_name, customer_code
플레이스홀더: 거래처명 또는 코드 입력
```

#### 동작
```
사용자 입력: "삼성"
드롭다운 표시: "삼성전자", "삼성물산", ...
선택: "삼성전자"
저장 값: "CUST-0001" (customer_code)
```

#### 결과
```
order_mng 테이블
┌───────────┬───────────────┐
│ order_id  │ customer_code │
├───────────┼───────────────┤
│ ORD-0001  │ CUST-0001     │ ✅
└───────────┴───────────────┘
```

---

### 예제 2: 거래처명을 직접 저장

#### 패널 설정
```
테이블명: customer_mng
표시 필드: customer_name
값 필드: customer_name         ← 이름을 가져옴
플레이스홀더: 거래처명 입력
```

#### 동작
```
사용자 선택: "삼성전자"
저장 값: "삼성전자" (customer_name)
```

#### 결과
```
order_mng 테이블
┌───────────┬───────────────┐
│ order_id  │ customer_name │
├───────────┼───────────────┤
│ ORD-0001  │ 삼성전자       │ ✅
└───────────┴───────────────┘
```

---

### 예제 3: 품목 선택 (추가 정보 표시)

#### 패널 설정
```
테이블명: item_mng
표시 필드: item_name
값 필드: item_code
검색 필드: item_name, item_code, category
플레이스홀더: 품목명, 코드, 카테고리로 검색

추가 정보 표시: ON
추가 필드: item_code, unit_price
```

#### 동작
```
드롭다운:
┌────────────────────────────┐
│ 삼성 노트북                 │
│ item_code: ITEM-0123       │
│ unit_price: 1,500,000      │
├────────────────────────────┤
│ LG 그램 노트북              │
│ item_code: ITEM-0124       │
│ unit_price: 1,800,000      │
└────────────────────────────┘
```

---

## 🎯 필드 선택 가이드

### 언제 표시 필드 ≠ 값 필드 인가?

**대부분의 경우 (권장)**
```
표시 필드: customer_name  (이름 - 사람이 읽기 쉬움)
값 필드: customer_code    (코드 - 데이터베이스에 저장)

이유:
✅ 외래키 관계 유지
✅ 데이터 무결성
✅ 이름이 바뀌어도 코드는 그대로
```

### 언제 표시 필드 = 값 필드 인가?

**특수한 경우**
```
표시 필드: customer_name
값 필드: customer_name

사용 케이스:
- 이름 자체를 저장해야 할 때
- 외래키가 필요 없을 때
- 간단한 참조용 데이터
```

---

## 💡 자주 묻는 질문

### Q1. 저장 위치를 설정하지 않으면?

**A**: 자동으로 화면의 연결 테이블에 바인딩 필드로 저장됩니다.

```
화면: 수주 등록 (연결 테이블: order_mng)
컴포넌트 바인딩 필드: customer_code

→ order_mng.customer_code에 자동 저장 ✅
```

---

### Q2. 값 필드와 저장 위치의 차이는?

**A**: 
- **값 필드**: 검색 테이블에서 무엇을 가져올지
- **저장 위치**: 가져온 값을 어디에 저장할지

```
값 필드: customer_mng.customer_code (어떤 값?)
저장 위치: order_mng.customer_code (어디에?)
```

---

### Q3. 검색 필드는 왜 여러 개 추가하나요?

**A**: 여러 방법으로 검색할 수 있게 하기 위해서입니다.

```
검색 필드: [customer_name, customer_code]

사용자가 "삼성" 입력 → customer_name에서 검색
사용자가 "CUST" 입력 → customer_code에서 검색
```

---

### Q4. 추가 정보 표시는 언제 사용하나요?

**A**: 선택할 때 참고할 정보를 함께 보여주고 싶을 때 사용합니다.

```
추가 정보 표시: ON
추가 필드: [address, phone]

드롭다운:
┌────────────────────────────┐
│ 삼성전자                    │
│ address: 서울시 서초구      │
│ phone: 02-1234-5678        │
└────────────────────────────┘
```

---

## 🚀 빠른 시작

### 1단계: 기본 설정만 입력

```
테이블명: [검색할 테이블]
표시 필드: [사용자에게 보여줄 컬럼]
값 필드: [저장할 컬럼]
```

### 2단계: 화면 디자이너에서 바인딩 필드 설정

```
컴포넌트 ID: customer_search
바인딩 필드: customer_code
```

### 3단계: 완료!

이제 사용자가 선택하면 자동으로 저장됩니다.

---

## ✅ 체크리스트

설정 전:
- [ ] 어느 테이블에서 검색할지 알고 있나요?
- [ ] 사용자에게 무엇을 보여줄지 정했나요?
- [ ] 어떤 값을 저장할지 정했나요?

설정 후:
- [ ] 검색이 정상적으로 되나요?
- [ ] 드롭다운에 원하는 항목이 보이나요?
- [ ] 선택 후 값이 저장되나요?

---

## 📊 설정 패턴 비교

| 패턴 | 표시 필드 | 값 필드 | 사용 케이스 |
|------|----------|---------|------------|
| 1 | customer_name | customer_code | 이름 표시, 코드 저장 (일반적) |
| 2 | customer_name | customer_name | 이름 표시, 이름 저장 (특수) |
| 3 | item_name | item_code | 품목명 표시, 품목코드 저장 |
| 4 | employee_name | employee_id | 직원명 표시, ID 저장 |

---

## 🎨 실전 팁

### 1. 검색 필드는 2-3개가 적당
```
✅ 좋음: [name, code]
✅ 좋음: [name, code, category]
❌ 과함: [name, code, address, phone, email, ...]
```

### 2. 플레이스홀더는 구체적으로
```
❌ "검색..."
✅ "거래처명 또는 코드 입력"
✅ "품목명, 코드, 카테고리로 검색"
```

### 3. 추가 정보는 선택에 도움되는 것만
```
✅ 도움됨: 가격, 주소, 전화번호
❌ 불필요: 등록일, 수정일, ID
```

---

이 가이드로 autocomplete-search-input 컴포넌트를 쉽게 사용할 수 있습니다! 🎉