@axboot-mcp/mcp-server 1.0.0

package/src/docs//354/202/254/354/232/251/353/262/225/Search-/354/273/264/355/217/254/353/204/214/355/212/270-/354/202/254/354/232/251/353/262/225.md

@@ -0,0 +1,738 @@
+# Search 컴포넌트 사용법 가이드
+
+AXBoot의 Search 컴포넌트 시스템은 검색 폼을 쉽게 구성할 수 있는 통합 솔루션입니다. 다양한 입력 타입과 레이아웃을 지원하며, TypeScript로 완전히 구현되어 있습니다.
+
+## 목차
+1. [개요](#개요)
+2. [기본 사용법](#기본-사용법)
+3. [SearchParamType 종류](#searchparamtype-종류)
+4. [개별 컴포넌트 사용법](#개별-컴포넌트-사용법)
+5. [고급 기능](#고급-기능)
+6. [스타일링](#스타일링)
+7. [실제 사용 예제](#실제-사용-예제)
+
+## 개요
+
+Search 컴포넌트 시스템은 다음과 같은 구조로 구성되어 있습니다:
+
+- **SearchParams**: 메인 컨테이너 컴포넌트
+- **SearchParam**: 개별 검색 파라미터 컴포넌트 (타입별 라우팅)
+- **SearchParamType**: 검색 파라미터 타입 enum
+- **개별 컴포넌트들**: 각 타입별 구현체
+
+### 주요 특징
+- 🔧 **TypeScript 완전 지원**: 타입 안정성 보장
+- 🎨 **다양한 입력 타입**: INPUT, SELECT, DATE_RANGE, CHECKBOX 등
+- 📱 **반응형 디자인**: 다양한 화면 크기 지원
+- 🚀 **성능 최적화**: debounce와 memoization 활용
+- 🎯 **쉬운 사용법**: 선언적 설정으로 빠른 구현
+
+## 기본 사용법
+
+### 1. 기본 설정
+
+```typescript
+import { SearchParams, IParam, SearchParamType } from "@core/components/search";
+import { Form } from "antd";
+
+// 검색 파라미터 정의
+const searchParams: IParam[] = [
+  {
+    name: "keyword",
+    type: SearchParamType.INPUT,
+    label: "키워드",
+    placeholder: "검색어를 입력하세요",
+    width: 200
+  },
+  {
+    name: "status",
+    type: SearchParamType.SELECT,
+    label: "상태",
+    options: [
+      { label: "전체", value: "" },
+      { label: "활성", value: "Y" },
+      { label: "비활성", value: "N" }
+    ]
+  }
+];
+
+// 컴포넌트에서 사용
+function MySearchForm() {
+  const [form] = Form.useForm();
+  const [paramsValue, setParamsValue] = useState({});
+
+  const handleSearch = () => {
+    console.log("검색 실행:", paramsValue);
+  };
+
+  return (
+    <SearchParams
+      form={form}
+      params={searchParams}
+      paramsValue={paramsValue}
+      onChangeParamsValue={setParamsValue}
+      onSearch={handleSearch}
+    />
+  );
+}
+```
+
+### 2. 필수 Props
+
+| Prop | 타입 | 설명 |
+|------|------|------|
+| `form` | FormInstance | Ant Design Form 인스턴스 |
+| `params` | IParam[] | 검색 파라미터 배열 |
+| `paramsValue` | ParamsValue | 현재 검색 값 |
+| `onChangeParamsValue` | Function | 값 변경 핸들러 |
+| `onSearch` | Function | 검색 실행 핸들러 |
+
+## SearchParamType 종류
+
+### 지원하는 검색 파라미터 타입
+
+```typescript
+export enum SearchParamType {
+  INPUT,                    // 텍스트 입력
+  DATE_RANGE,              // 날짜 범위
+  TIME_RANGE,              // 시간 범위
+  NUMBER_RANGE,            // 숫자 범위
+  SELECT,                  // 단일 선택
+  SELECT_MULTI,            // 다중 선택
+  CHECKBOX,                // 체크박스 그룹
+  DATE,                    // 단일 날짜
+  VALUES_FINDER,           // 값 찾기 (검색 기능 포함)
+  SUBMIT_BUTTON,           // 제출 버튼
+  BUTTON,                  // 일반 버튼
+  CASCADE,                 // 계층형 선택
+  RADIO,                   // 라디오 버튼
+  DTPICKER_DATE,          // DatePicker 날짜
+  DTPICKER_DATE_RANGE,    // DatePicker 날짜 범위
+  LINE_BREAK,             // 줄 바꿈
+  GAP,                    // 간격
+  GROUP,                  // 그룹
+}
+```
+
+## 개별 컴포넌트 사용법
+
+### 1. INPUT - 텍스트 입력
+
+```typescript
+{
+  name: "searchKeyword",
+  type: SearchParamType.INPUT,
+  label: "검색어",
+  placeholder: "검색어를 입력하세요",
+  width: 200,
+  allowClear: true,
+  autoFocus: false
+}
+```
+
+**특징**:
+- 자동 완성 및 클리어 버튼 지원
+- autoFocus 옵션으로 자동 포커스
+- 최소 너비 100px 보장
+
+### 2. SELECT - 단일 선택
+
+```typescript
+{
+  name: "category",
+  type: SearchParamType.SELECT,
+  label: "카테고리",
+  width: 150,
+  options: [
+    { label: "전체", value: "" },
+    { label: "공지사항", value: "notice" },
+    { label: "FAQ", value: "faq" }
+  ],
+  showSearch: true,
+  allowClear: true,
+  defaultValue: ""
+}
+```
+
+**특징**:
+- showSearch로 검색 기능 활성화
+- 동적 로딩 상태 지원
+- 기본값 설정 가능
+
+### 3. SELECT_MULTI - 다중 선택
+
+```typescript
+{
+  name: "tags",
+  type: SearchParamType.SELECT_MULTI,
+  label: "태그",
+  options: [
+    { label: "긴급", value: "urgent" },
+    { label: "중요", value: "important" },
+    { label: "일반", value: "normal" }
+  ],
+  config: {
+    maxTagCount: "responsive",
+    mode: "multiple"
+  }
+}
+```
+
+**특징**:
+- 반응형 태그 표시
+- 커스텀 설정 지원
+
+### 4. DATE_RANGE - 날짜 범위
+
+```typescript
+{
+  name: "dateRange",
+  type: SearchParamType.DATE_RANGE,
+  label: "기간",
+  placeholder: ["시작일", "종료일"],
+  picker: "date" as DateType,
+  allowClear: true
+}
+```
+
+**특징**:
+- 빠른 선택 버튼 (오늘, 3일, 7일)
+- 월/분기별 선택 지원
+- 커스텀 포맷 설정
+
+### 5. CHECKBOX - 체크박스 그룹
+
+```typescript
+{
+  name: "permissions",
+  type: SearchParamType.CHECKBOX,
+  label: "권한",
+  options: [
+    { label: "읽기", value: "read" },
+    { label: "쓰기", value: "write" },
+    { label: "삭제", value: "delete" }
+  ],
+  checkAllItem: true
+}
+```
+
+**특징**:
+- 전체 선택/해제 기능
+- indeterminate 상태 지원
+
+### 6. RADIO - 라디오 버튼
+
+```typescript
+{
+  name: "status",
+  type: SearchParamType.RADIO,
+  label: "상태",
+  options: [
+    { label: "전체", value: "" },
+    { label: "활성", value: "Y" },
+    { label: "비활성", value: "N" }
+  ],
+  defaultValue: ""
+}
+```
+
+**특징**:
+- 단일 선택만 가능
+- 기본값 설정 지원
+
+### 7. VALUES_FINDER - 값 찾기
+
+```typescript
+{
+  name: "userIds",
+  type: SearchParamType.VALUES_FINDER,
+  label: "사용자",
+  placeholder: "사용자를 선택하세요",
+  width: 250,
+  onSearch: async () => {
+    // API 호출로 사용자 목록 조회
+    const response = await UserService.getUsers();
+    return response.data.map(user => ({
+      label: user.name,
+      value: user.id
+    }));
+  },
+  config: {
+    single: false // 다중 선택 허용
+  }
+}
+```
+
+**특징**:
+- 동적 데이터 로딩
+- 검색 버튼 내장
+- 단일/다중 선택 지원
+
+### 8. BUTTON - 일반 버튼
+
+```typescript
+{
+  type: SearchParamType.BUTTON,
+  label: "초기화",
+  icon: <ReloadOutlined />,
+  onClick: () => {
+    form.resetFields();
+    setParamsValue({});
+  }
+}
+```
+
+### 9. SUBMIT_BUTTON - 제출 버튼
+
+```typescript
+{
+  type: SearchParamType.SUBMIT_BUTTON,
+  label: "검색",
+  icon: <SearchOutlined />
+}
+```
+
+### 10. LINE_BREAK - 줄 바꿈
+
+```typescript
+{ type: SearchParamType.LINE_BREAK }
+```
+
+## 고급 기능
+
+### 1. 그룹핑 (GROUP)
+
+```typescript
+{
+  type: SearchParamType.GROUP,
+  children: [
+    {
+      name: "minPrice",
+      type: SearchParamType.INPUT,
+      placeholder: "최소 금액"
+    },
+    {
+      name: "maxPrice",
+      type: SearchParamType.INPUT,
+      placeholder: "최대 금액"
+    }
+  ]
+}
+```
+
+### 2. 조건부 표시
+
+```typescript
+{
+  name: "advancedOption",
+  type: SearchParamType.SELECT,
+  label: "고급 옵션",
+  hidden: !showAdvanced, // 동적으로 숨김/표시
+  options: advancedOptions
+}
+```
+
+### 3. 커스텀 스타일링
+
+```typescript
+{
+  name: "customField",
+  type: SearchParamType.INPUT,
+  label: "커스텀 필드",
+  style: {
+    backgroundColor: "#f5f5f5",
+    borderRadius: "8px"
+  }
+}
+```
+
+### 4. 동적 옵션 로딩
+
+```typescript
+const [categoryOptions, setCategoryOptions] = useState([]);
+
+useEffect(() => {
+  const loadCategories = async () => {
+    const categories = await CategoryService.getAll();
+    setCategoryOptions(categories.map(cat => ({
+      label: cat.name,
+      value: cat.id
+    })));
+  };
+  loadCategories();
+}, []);
+
+const params: IParam[] = [
+  {
+    name: "categoryId",
+    type: SearchParamType.SELECT,
+    label: "카테고리",
+    options: categoryOptions,
+    loading: categoryOptions.length === 0
+  }
+];
+```
+
+## 스타일링
+
+### 1. 기본 Props로 스타일링
+
+```typescript
+<SearchParams
+  form={form}
+  params={params}
+  paramsValue={paramsValue}
+  onChangeParamsValue={setParamsValue}
+  onSearch={handleSearch}
+  size="small"              // 크기: small, middle, large
+  variant="filled"          // 스타일: filled, outlined, borderless
+  labelMinWidth={100}       // 라벨 최소 너비
+  align="flex-start"        // 정렬: flex-start, center, flex-end
+  style={{                  // 커스텀 스타일
+    background: "#fafafa",
+    padding: "16px",
+    borderRadius: "8px"
+  }}
+/>
+```
+
+### 2. 추가 버튼 영역
+
+```typescript
+const ExtraButtons = () => (
+  <>
+    <Button type="default" onClick={handleReset}>
+      초기화
+    </Button>
+    <Button type="primary" onClick={handleExport}>
+      내보내기
+    </Button>
+  </>
+);
+
+<SearchParams
+  // ... other props
+  extraButtons={ExtraButtons}
+/>
+```
+
+## 실제 사용 예제
+
+### 1. 사용자 관리 검색폼
+
+```typescript
+import React, { useState } from 'react';
+import { Form, Button } from 'antd';
+import { SearchParams, IParam, SearchParamType } from '@core/components/search';
+import { UserService } from 'services';
+
+export function UserSearchForm() {
+  const [form] = Form.useForm();
+  const [paramsValue, setParamsValue] = useState({});
+  const [loading, setLoading] = useState(false);
+
+  const searchParams: IParam[] = [
+    {
+      name: "searchType",
+      type: SearchParamType.SELECT,
+      label: "검색 구분",
+      width: 120,
+      options: [
+        { label: "통합회원ID", value: "UNITY_MBER_USR_LOGIN_ID" },
+        { label: "기존회원ID", value: "USR_LOGIN_ID" },
+        { label: "전화번호", value: "USR_TELNO" },
+        { label: "핸드폰번호", value: "USR_HP_NO" }
+      ],
+      showSearch: false,
+      allowClear: false,
+      defaultValue: "UNITY_MBER_USR_LOGIN_ID"
+    },
+    {
+      name: "keyword",
+      type: SearchParamType.INPUT,
+      placeholder: "검색어를 입력하세요",
+      width: 200,
+      autoFocus: true
+    },
+    {
+      name: "userStatus",
+      type: SearchParamType.SELECT_MULTI,
+      label: "회원상태",
+      options: [
+        { label: "활성", value: "Y" },
+        { label: "비활성", value: "N" },
+        { label: "탈퇴", value: "W" }
+      ],
+      config: {
+        maxTagCount: "responsive"
+      }
+    },
+    { type: SearchParamType.LINE_BREAK },
+    {
+      name: "joinDateRange",
+      type: SearchParamType.DATE_RANGE,
+      label: "가입 기간",
+      placeholder: ["시작일", "종료일"]
+    },
+    {
+      name: "loginYn",
+      type: SearchParamType.RADIO,
+      label: "로그인 여부",
+      options: [
+        { label: "전체", value: "" },
+        { label: "로그인", value: "Y" },
+        { label: "미로그인", value: "N" }
+      ],
+      defaultValue: ""
+    }
+  ];
+
+  const handleSearch = async () => {
+    setLoading(true);
+    try {
+      const result = await UserService.searchUsers(paramsValue);
+      console.log('검색 결과:', result);
+    } catch (error) {
+      console.error('검색 실패:', error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleReset = () => {
+    form.resetFields();
+    setParamsValue({});
+  };
+
+  const ExtraButtons = () => (
+    <>
+      <Button onClick={handleReset}>초기화</Button>
+      <Button type="primary" onClick={handleSearch} loading={loading}>
+        검색
+      </Button>
+    </>
+  );
+
+  return (
+    <SearchParams
+      form={form}
+      params={searchParams}
+      paramsValue={paramsValue}
+      onChangeParamsValue={setParamsValue}
+      onSearch={handleSearch}
+      spinning={loading}
+      size="middle"
+      extraButtons={ExtraButtons}
+      style={{
+        background: "#fff",
+        padding: "20px",
+        borderRadius: "8px",
+        marginBottom: "16px"
+      }}
+    />
+  );
+}
+```
+
+### 2. 주문 관리 검색폼
+
+```typescript
+export function OrderSearchForm() {
+  const [form] = Form.useForm();
+  const [paramsValue, setParamsValue] = useState({});
+
+  const searchParams: IParam[] = [
+    {
+      name: "orderNo",
+      type: SearchParamType.INPUT,
+      label: "주문번호",
+      placeholder: "주문번호 입력",
+      width: 150
+    },
+    {
+      name: "orderStatus",
+      type: SearchParamType.CHECKBOX,
+      label: "주문상태",
+      options: [
+        { label: "접수", value: "ORDER" },
+        { label: "결제완료", value: "PAID" },
+        { label: "배송중", value: "SHIPPING" },
+        { label: "완료", value: "COMPLETED" },
+        { label: "취소", value: "CANCELLED" }
+      ],
+      checkAllItem: true
+    },
+    {
+      name: "customerFinder",
+      type: SearchParamType.VALUES_FINDER,
+      label: "고객",
+      placeholder: "고객을 검색하세요",
+      width: 250,
+      onSearch: async () => {
+        const customers = await CustomerService.searchCustomers();
+        return customers.map(customer => ({
+          label: `${customer.name} (${customer.email})`,
+          value: customer.id
+        }));
+      }
+    },
+    { type: SearchParamType.LINE_BREAK },
+    {
+      type: SearchParamType.GROUP,
+      children: [
+        {
+          name: "minAmount",
+          type: SearchParamType.INPUT,
+          placeholder: "최소 금액",
+          width: 100
+        },
+        {
+          name: "maxAmount",
+          type: SearchParamType.INPUT,
+          placeholder: "최대 금액",
+          width: 100
+        }
+      ]
+    },
+    {
+      name: "orderDateRange",
+      type: SearchParamType.DTPICKER_DATE_RANGE,
+      label: "주문일",
+      format: "YYYY-MM-DD",
+      isTimeSelector: false
+    }
+  ];
+
+  return (
+    <SearchParams
+      form={form}
+      params={searchParams}
+      paramsValue={paramsValue}
+      onChangeParamsValue={setParamsValue}
+      onSearch={() => console.log('주문 검색:', paramsValue)}
+      labelMinWidth={80}
+      size="small"
+    />
+  );
+}
+```
+
+### 3. 커스텀 검색 컴포넌트 확장
+
+```typescript
+// 커스텀 검색 파라미터 컴포넌트
+export const CustomSearchParam: SearchParamComponent = ({
+  name,
+  label,
+  options,
+  width,
+  style
+}) => {
+  return (
+    <Form.Item
+      name={name}
+      label={label}
+      style={{ marginBottom: 0, ...style }}
+    >
+      <CustomComponent
+        options={options}
+        style={{ width }}
+      />
+    </Form.Item>
+  );
+};
+
+// SearchParam enum에 추가
+export enum SearchParamType {
+  // ... 기존 타입들
+  CUSTOM = 'CUSTOM'
+}
+
+// SearchParamComponents에 추가
+const SearchParamComponents = {
+  // ... 기존 컴포넌트들
+  [SearchParamType.CUSTOM]: CustomSearchParam
+};
+```
+
+## 성능 최적화 팁
+
+### 1. 검색 디바운스
+
+SearchParams는 기본적으로 100ms debounce를 적용합니다:
+
+```typescript
+const onValuesChange = React.useMemo(
+  () => debounce((changedValues: any, values: Record<string, any>) => {
+    onChangeParamsValue?.(values, changedValues);
+  }, 100),
+  [onChangeParamsValue]
+);
+```
+
+### 2. 옵션 메모이제이션
+
+```typescript
+const categoryOptions = useMemo(() =>
+  categories.map(cat => ({
+    label: cat.name,
+    value: cat.id
+  })),
+  [categories]
+);
+```
+
+### 3. 조건부 렌더링
+
+```typescript
+const params = useMemo(() => [
+  {
+    name: "basicField",
+    type: SearchParamType.INPUT,
+    label: "기본 필드"
+  },
+  ...(showAdvanced ? [
+    {
+      name: "advancedField",
+      type: SearchParamType.SELECT,
+      label: "고급 필드",
+      options: advancedOptions
+    }
+  ] : [])
+], [showAdvanced, advancedOptions]);
+```
+
+## 에러 처리
+
+### 1. 폼 검증
+
+```typescript
+const handleSearch = async () => {
+  try {
+    await form.validateFields();
+    const values = form.getFieldsValue();
+    // 검색 실행
+  } catch (errorInfo) {
+    console.log('검증 실패:', errorInfo);
+  }
+};
+```
+
+### 2. API 에러 처리
+
+```typescript
+const handleSearch = async () => {
+  try {
+    setLoading(true);
+    const result = await SearchService.search(paramsValue);
+    setSearchResults(result.data);
+  } catch (error) {
+    message.error('검색 중 오류가 발생했습니다.');
+    console.error('Search error:', error);
+  } finally {
+    setLoading(false);
+  }
+};
+```
+
+이 가이드를 통해 AXBoot Search 컴포넌트 시스템을 효과적으로 활용하여 다양한 검색 인터페이스를 구현할 수 있습니다.