feat(autocomplete-search-input): 필드 자동 매핑 및 저장 위치 선택 기능 추가
- 필드 자동 매핑 기능 구현 * FieldMapping 타입 추가 (sourceField → targetField) * applyFieldMappings() 함수로 선택 시 자동 입력 * 여러 필드를 한 번에 자동으로 채움 (거래처 선택 → 주소/전화 자동 입력) - 값 필드 저장 위치 선택 기능 추가 * ValueFieldStorage 타입 추가 (targetTable, targetColumn) * 기본값(화면 연결 테이블) 또는 명시적 테이블/컬럼 지정 가능 * 중간 테이블, 이력 테이블 등 다중 테이블 저장 지원 - UI/UX 개선 * 모든 선택 필드를 Combobox 스타일로 통일 * 각 필드 아래 간략한 사용 설명 추가 * 저장 위치 동작 미리보기 박스 추가 - 문서 작성 * 사용_가이드.md 신규 작성 (실전 예제 3개 포함) * 빠른 시작 가이드, FAQ, 체크리스트 제공
This commit is contained in:
SeongHyun Kim
@@ -0,0 +1,300 @@
|
||||
# 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 컴포넌트를 쉽게 사용할 수 있습니다! 🎉
|
||||
|
||||
Reference in New Issue
Block a user