(김준회) 공통 컴포넌트 이해를 위한 문서 추가

1 files changed, 123 insertions, 0 deletions

diff --git a/components/common/ship-type/README.md b/components/common/ship-type/README.md
new file mode 100644
index 00000000..4b50773d
--- /dev/null
+++ b/components/common/ship-type/README.md
@@ -0,0 +1,123 @@
+# 선종 선택기 (Ship Type Selector)
+
+선종 정보를 검색하고 선택할 수 있는 컴포넌트입니다.
+
+## 컴포넌트 구조
+
+```text
+components/common/ship-type/
+├── ship-type-service.ts      # 서버 액션 (선종 데이터 조회)
+├── ship-type-selector.tsx    # 선종 선택기 컴포넌트
+├── index.ts                  # 모듈 export
+└── README.md                 # 문서
+```
+
+## 데이터 소스
+
+**내부 PostgreSQL DB - `cmctb_cdnm` 테이블**
+
+- 조건: `CD_CLF = 'PSA330' AND DEL_YN = 'N'`
+- 선종코드: `CD` 컬럼
+- 선종명: `CDNM` 컬럼
+
+## 기본 사용법
+
+```tsx
+import { ShipTypeSelector, ShipTypeItem } from '@/components/common/ship-type'
+
+function MyComponent() {
+  const [selectedShipType, setSelectedShipType] = useState<ShipTypeItem | undefined>()
+
+  const handleShipTypeSelect = (shipType: ShipTypeItem) => {
+    setSelectedShipType(shipType)
+    console.log('선택된 선종:', shipType.CD, shipType.CDNM)
+  }
+
+  return (
+    <ShipTypeSelector
+      selectedShipType={selectedShipType}
+      onShipTypeSelect={handleShipTypeSelect}
+      placeholder="선종을 선택하세요"
+    />
+  )
+}
+```
+
+## Props
+
+### ShipTypeSelector
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `selectedShipType` | `ShipTypeItem \| undefined` | - | 현재 선택된 선종 |
+| `onShipTypeSelect` | `(shipType: ShipTypeItem) => void` | - | 선종 선택 시 호출되는 콜백 함수 |
+| `disabled` | `boolean` | `false` | 선택기 비활성화 여부 |
+| `placeholder` | `string` | `"선종을 선택하세요"` | 선택되지 않았을 때 표시할 텍스트 |
+| `className` | `string` | - | 추가 CSS 클래스 |
+
+## 타입 정의
+
+### ShipTypeItem
+
+```tsx
+interface ShipTypeItem {
+  CD: string        // 선종코드
+  CDNM: string      // 선종명
+  displayText: string // 표시용 텍스트 (CD + " - " + CDNM)
+}
+```
+
+### ShipTypeSearchOptions
+
+```tsx
+interface ShipTypeSearchOptions {
+  searchTerm?: string  // 검색어 (선종코드 또는 선종명)
+  limit?: number       // 조회 결과 제한 (기본값: 100)
+}
+```
+
+## 서버 액션
+
+### getShipTypes(options)
+
+선종 목록을 조회합니다.
+
+```tsx
+const result = await getShipTypes({
+  searchTerm: "CONT",
+  limit: 50
+})
+
+if (result.success) {
+  console.log('선종 목록:', result.data)
+} else {
+  console.error('오류:', result.error)
+}
+```
+
+### getShipTypeByCode(code)
+
+특정 선종코드로 선종 정보를 조회합니다.
+
+```tsx
+const shipType = await getShipTypeByCode("CONT")
+if (shipType) {
+  console.log('선종 정보:', shipType.CD, shipType.CDNM)
+}
+```
+
+## 특징
+
+- ✅ **즉시 검색**: 검색어 입력 시 실시간으로 결과 필터링
+- ✅ **디바운싱**: 300ms 디바운스로 API 호출 최적화
+- ✅ **서버 액션**: `useTransition`을 사용한 논블로킹 서버 호출
+- ✅ **페이지네이션**: 대량 데이터 지원 (기본 페이지당 10개)
+- ✅ **검색 최적화**: 선종코드와 선종명 모두 검색 가능
+- ✅ **사용자 친화적**: Dialog 기반 선택 UI
+
+## 주의사항
+
+- 선종 데이터는 약 50개 정도로 페이지네이션 없이도 충분히 처리 가능
+- 검색은 선종코드(`CD`)와 선종명(`CDNM`) 모두에서 수행됩니다
+- 대소문자 구분 없이 검색 가능 (ILIKE 사용)
+- `DEL_YN = 'N'` 조건으로 삭제되지 않은 선종만 조회