@axboot-mcp/mcp-server 1.0.0

package/src/docs//354/202/254/354/232/251/353/262/225/AntD-/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,1515 @@
+# Ant Design 컴포넌트 사용법 가이드
+
+## 개요
+
+이 문서는 네이비언하우스 FE-BO 프로젝트에서 실제 사용되고 있는 Ant Design 컴포넌트들의 사용 사례와 패턴을 정리한 가이드입니다.
+
+## 1. 폼 관련 컴포넌트 (Form Components)
+
+### 1.1 Form & Form.Item
+
+#### 기본 사용 패턴
+```tsx
+// 프로젝트 표준 패턴
+const FormItem = Form.Item<DtoItem>;
+
+function FormModal() {
+  const [form] = Form.useForm<DtoItem>();
+
+  return (
+    <Form
+      form={form}
+      layout="vertical"
+      onFinish={handleSave}
+      initialValues={{ useYn: "Y" }}
+    >
+      <FormItem
+        name="itemName"
+        label={t("항목명")}
+        rules={[{ required: true }]}
+      >
+        <Input />
+      </FormItem>
+    </Form>
+  );
+}
+```
+
+#### 실제 사용 예시 (department/FormModal.tsx)
+```tsx
+<Form form={form} layout="vertical" onFinish={handleSave} initialValues={{ useYn: "Y" }}>
+  <FormItem name="trtmntDeptNo" noStyle>
+    <Input type="hidden" />
+  </FormItem>
+
+  <Row gutter={12}>
+    <Col span={24}>
+      <FormItem name="trtmntDeptNm" label={t("부서명")} rules={[{ required: true }]}>
+        <Input />
+      </FormItem>
+    </Col>
+    <Col span={24}>
+      <FormItem
+        name="pgSvcMidValue"
+        label={t("MID")}
+        rules={[{ required: true }]}
+        tooltip="KG이니시스의 MID정보를 입력해 주세요."
+      >
+        <Input />
+      </FormItem>
+    </Col>
+  </Row>
+</Form>
+```
+
+### 1.2 Input
+
+#### 기본 텍스트 입력
+```tsx
+<FormItem name="title" label={t("제목")} rules={[{ required: true }]}>
+  <Input placeholder={t("제목을 입력하세요")} />
+</FormItem>
+```
+
+#### TextArea 사용
+```tsx
+<FormItem name="description" label={t("설명")}>
+  <Input.TextArea
+    rows={3}
+    maxLength={2000}
+    placeholder={t("설명을 입력하세요")}
+  />
+</FormItem>
+```
+
+#### Password 입력
+```tsx
+<FormItem name="password" label={t("비밀번호")}>
+  <Input.Password />
+</FormItem>
+```
+
+#### 숨김 필드
+```tsx
+<FormItem name="hiddenId" noStyle>
+  <Input type="hidden" />
+</FormItem>
+```
+
+### 1.3 InputNumber
+
+#### 기본 숫자 입력
+```tsx
+<FormItem name="quantity" label={t("수량")} rules={[{ required: true }]}>
+  <InputNumber
+    min={1}
+    max={999}
+    style={{ width: "100%" }}
+  />
+</FormItem>
+```
+
+#### 단위가 있는 숫자 입력 (system.app-banner/FormModal.tsx)
+```tsx
+<FormItem name="expsrSecndValue" label={t("배너노출시간설정")} rules={[{ required: true }]}>
+  <InputNumber
+    min={1}
+    max={60}
+    addonAfter="초"
+    placeholder={t("노출할 초값을 입력하세요")}
+    style={{ width: "20%" }}
+  />
+</FormItem>
+```
+
+### 1.4 Select
+
+#### 기본 셀렉트 박스
+```tsx
+<FormItem name="categoryCode" label={t("카테고리")} rules={[{ required: true }]}>
+  <Select
+    options={categoryOptions}
+    placeholder={t("카테고리를 선택하세요")}
+  />
+</FormItem>
+```
+
+#### 컴팩트 스타일의 셀렉트 (benefit.time-deal/FormModal.tsx)
+```tsx
+<Space.Compact>
+  <Select
+    value={getFieldValue("bnefDscntStupTpcd")}
+    options={[
+      { label: "%", value: "10" },
+      { label: "원", value: "20" }
+    ]}
+    style={{ width: 80 }}
+    onChange={(value) => setFieldValue("bnefDscntStupTpcd", value)}
+  />
+  <Button>{t("할인")}</Button>
+</Space.Compact>
+```
+
+### 1.5 Radio
+
+#### 기본 라디오 그룹
+```tsx
+<FormItem name="useYn" label={t("사용여부")} rules={[{ required: true }]}>
+  <Radio.Group
+    options={[
+      { value: "Y", label: "Y" },
+      { value: "N", label: "N" }
+    ]}
+  />
+</FormItem>
+```
+
+#### 인라인 라디오 그룹 (system.app-banner/FormModal.tsx)
+```tsx
+<FormItem name="urlTrgtTpcd" label={t("링크 대상")}>
+  <Radio.Group>
+    <Radio value="">없음</Radio>
+    {URL_TRGT_TPCD?.options?.map((option) => (
+      <Radio key={option.value} value={option.value}>
+        {option.label}
+      </Radio>
+    ))}
+  </Radio.Group>
+</FormItem>
+```
+
+### 1.6 Switch
+
+#### 토글 스위치 (system.app-banner/FormModal.tsx)
+```tsx
+<FormItem name="dspyYn" label={t("전시여부")} valuePropName="checked">
+  <Switch
+    checkedChildren="전시"
+    unCheckedChildren="미전시"
+  />
+</FormItem>
+```
+
+### 1.7 날짜/시간 컴포넌트 (Date & Time Components)
+
+프로젝트에서는 Ant Design의 기본 DatePicker 대신 커스텀 `DtPicker` 컴포넌트를 주로 사용합니다.
+
+#### DtPicker 타입 정의
+```typescript
+export enum DtPickerType {
+  DATE = 0,        // 단일 날짜
+  DATE_RANGE = 1,  // 날짜 범위
+  MONTH = 2,       // 월 선택
+  YEAR = 3,        // 연도 선택
+}
+```
+
+#### 날짜 범위 선택 (system.app-banner/FormModal.tsx)
+```tsx
+import { DtPicker } from "@core/components/dtPicker";
+import { DtPickerType } from "@core/components/dtPicker/types";
+
+<FormItem
+  name="dt_range"
+  label={t("노출기간")}
+  rules={[{ required: true, message: t("노출기간을 선택해주세요") }]}
+>
+  <DtPicker
+    type={DtPickerType.DATE_RANGE}
+    placeholder={[t("노출 시작일시"), t("노출 종료일시")]}
+  />
+</FormItem>
+```
+
+#### 단일 날짜 선택 (press-media/PressMediaModal.tsx)
+```tsx
+<FormItem name="bbscttBgnDt" label={t("노출 일자 지정")} rules={[{ required: true }]}>
+  <DtPicker
+    type={DtPickerType.DATE}
+    isTimeSelector    // 시간 선택 포함
+    allowClear        // 클리어 버튼 표시
+  />
+</FormItem>
+```
+
+#### 월/연도 선택
+```tsx
+// 월 선택
+<FormItem name="targetMonth" label={t("대상월")}>
+  <DtPicker type={DtPickerType.MONTH} />
+</FormItem>
+
+// 연도 선택
+<FormItem name="targetYear" label={t("대상연도")}>
+  <DtPicker type={DtPickerType.YEAR} />
+</FormItem>
+```
+
+#### 검색 화면용 날짜 프리셋 (DtPickerPresetRender)
+검색 화면에서는 `DtPickerPresetRender`를 사용하여 일반적인 날짜 범위 프리셋을 제공합니다.
+
+```tsx
+import { DtPickerPresetRender } from "components/presetRender/DtPickerPresetRender";
+
+// 검색 파라미터에서 사용
+const searchParams: SearchParams = [
+  {
+    prop: "dateRange",
+    label: t("기간"),
+    type: SearchParamType.DATE_RANGE,
+    defaultValue: [],
+    presetRender: DtPickerPresetRender({ type: "all" }),
+  },
+  // 기타 검색 파라미터들...
+];
+```
+
+#### DtPickerPresetRender 타입
+```tsx
+// 모든 프리셋 (오늘, 어제, 이번주, 지난주, 이번달, 지난달, 최근 3개월)
+presetRender: DtPickerPresetRender({ type: "all" })
+
+// 기본 프리셋 (오늘, 어제, 이번주, 이번달)
+presetRender: DtPickerPresetRender({ type: "basic" })
+
+// 커스텀 프리셋
+presetRender: DtPickerPresetRender({})
+```
+
+#### 날짜 데이터 처리 패턴
+```tsx
+// 폼에서 날짜 범위를 API 파라미터로 변환
+import { dateRangeToDts } from "utils";
+import { DT_FORMAT } from "@types";
+
+const handleSave = async () => {
+  const values = await form.validateFields();
+
+  const saveItem = {
+    ...values,
+    // 날짜 범위를 시작일/종료일로 분리
+    ...dateRangeToDts(values.dt_range, {
+      expsrBgnDtm: DT_FORMAT.DATETIME,
+      expsrEndDtm: DT_FORMAT.DATETIME,
+    }),
+  };
+
+  await ApiService.save(saveItem);
+};
+
+// 폼 초기값 설정 시
+const formValues = {
+  ...params.query,
+  // API에서 받은 시작일/종료일을 날짜 범위로 결합
+  dt_range: params.query.expsrBgnDtm && params.query.expsrEndDtm
+    ? [params.query.expsrBgnDtm, params.query.expsrEndDtm]
+    : undefined,
+};
+form.setFieldsValue(formValues);
+```
+
+#### 날짜 제한 옵션들
+
+프로젝트에서는 다양한 날짜 제한 패턴을 사용할 수 있습니다.
+
+```tsx
+import dayjs from "dayjs";
+
+// 과거 날짜 선택 불가 (오늘 이후만 선택 가능)
+<FormItem name="futureDate" label={t("미래 날짜")}>
+  <DatePicker
+    disabledDate={(date) => date && date < dayjs().startOf('day')}
+    placeholder={t("오늘 이후 날짜만 선택 가능")}
+  />
+</FormItem>
+
+// 미래 날짜 선택 불가 (오늘 이전만 선택 가능)
+<FormItem name="pastDate" label={t("과거 날짜")}>
+  <DatePicker
+    disabledDate={(date) => date && date > dayjs().endOf('day')}
+    placeholder={t("오늘 이전 날짜만 선택 가능")}
+  />
+</FormItem>
+
+// 특정 기간 내에서만 선택 가능
+<FormItem name="limitedDate" label={t("제한 날짜")}>
+  <DatePicker
+    disabledDate={(date) => {
+      const startDate = dayjs().subtract(30, 'day');
+      const endDate = dayjs().add(30, 'day');
+      return date && (date < startDate || date > endDate);
+    }}
+    placeholder={t("30일 전후 범위에서만 선택 가능")}
+  />
+</FormItem>
+
+// 주말 선택 불가
+<FormItem name="weekdayOnly" label={t("평일만")}>
+  <DatePicker
+    disabledDate={(date) => {
+      const day = date.day();
+      return day === 0 || day === 6; // 일요일(0), 토요일(6)
+    }}
+    placeholder={t("평일만 선택 가능")}
+  />
+</FormItem>
+
+// 특정 날짜들 선택 불가
+<FormItem name="excludeSpecificDates" label={t("제외 날짜")}>
+  <DatePicker
+    disabledDate={(date) => {
+      const disabledDates = [
+        '2024-01-01', // 신정
+        '2024-12-25', // 크리스마스
+      ];
+      return disabledDates.includes(date.format('YYYY-MM-DD'));
+    }}
+    placeholder={t("공휴일 제외")}
+  />
+</FormItem>
+```
+
+#### 날짜 범위 제한 패턴
+
+```tsx
+// 날짜 범위에서 시작일 이후에만 종료일 선택 가능
+const [startDate, setStartDate] = useState(null);
+
+<Row gutter={16}>
+  <Col span={12}>
+    <FormItem name="startDate" label={t("시작일")}>
+      <DatePicker
+        onChange={(date) => setStartDate(date)}
+        disabledDate={(date) => date && date < dayjs().startOf('day')}
+      />
+    </FormItem>
+  </Col>
+  <Col span={12}>
+    <FormItem name="endDate" label={t("종료일")}>
+      <DatePicker
+        disabledDate={(date) => {
+          if (!startDate) return date && date < dayjs().startOf('day');
+          return date && (date < dayjs(startDate) || date < dayjs().startOf('day'));
+        }}
+      />
+    </FormItem>
+  </Col>
+</Row>
+
+// RangePicker에서 날짜 제한
+<FormItem name="dateRange" label={t("기간")}>
+  <DatePicker.RangePicker
+    disabledDate={(date) => date && date < dayjs().startOf('day')}
+    placeholder={[t("시작일"), t("종료일")]}
+  />
+</FormItem>
+```
+
+#### 시간 제한 옵션들
+
+```tsx
+// 특정 시간대만 선택 가능
+<FormItem name="businessHours" label={t("업무시간")}>
+  <DatePicker
+    showTime
+    disabledTime={(date) => ({
+      disabledHours: () => {
+        const hours = [];
+        for (let i = 0; i < 9; i++) hours.push(i);  // 9시 이전
+        for (let i = 18; i < 24; i++) hours.push(i); // 18시 이후
+        return hours;
+      },
+      disabledMinutes: () => [],
+      disabledSeconds: () => [],
+    })}
+  />
+</FormItem>
+
+// 현재 시간 이후만 선택 가능
+<FormItem name="futureDateTime" label={t("미래 일시")}>
+  <DatePicker
+    showTime
+    disabledDate={(date) => date && date < dayjs().startOf('day')}
+    disabledTime={(date) => {
+      if (date && dayjs(date).isSame(dayjs(), 'day')) {
+        const currentHour = dayjs().hour();
+        const currentMinute = dayjs().minute();
+        return {
+          disabledHours: () => Array.from({ length: currentHour }, (_, i) => i),
+          disabledMinutes: (selectedHour) =>
+            selectedHour === currentHour
+              ? Array.from({ length: currentMinute }, (_, i) => i)
+              : [],
+          disabledSeconds: () => [],
+        };
+      }
+      return {};
+    }}
+  />
+</FormItem>
+```
+
+#### DtPicker에서 날짜 제한 (프로젝트 커스텀)
+
+프로젝트의 DtPicker는 내부적으로 일부 제한사항이 구현되어 있습니다:
+
+```tsx
+// 내부 구현 예시 (DateRangePicker.tsx 참고)
+disabledDate={(date) => {
+  return !!dayjs(date).isAfter(dayjs("9999-12-31")) || !!dayjs(date).isBefore(dayjs(firstDate));
+}}
+```
+
+#### Ant Design 기본 DatePicker 사용 (필요시)
+```tsx
+import { DatePicker } from "antd";
+
+// 단일 날짜
+<FormItem name="date" label={t("날짜")}>
+  <DatePicker />
+</FormItem>
+
+// 날짜 범위
+<FormItem name="dateRange" label={t("기간")}>
+  <DatePicker.RangePicker />
+</FormItem>
+
+// 시간 포함 날짜
+<FormItem name="datetime" label={t("일시")}>
+  <DatePicker showTime />
+</FormItem>
+
+// 월 선택
+<FormItem name="month" label={t("월")}>
+  <DatePicker picker="month" />
+</FormItem>
+
+// 연도 선택
+<FormItem name="year" label={t("연도")}>
+  <DatePicker picker="year" />
+</FormItem>
+```
+
+## 2. 레이아웃 컴포넌트 (Layout Components)
+
+### 2.1 Row & Col
+
+#### 반응형 그리드 레이아웃
+```tsx
+<Row gutter={16}>
+  <Col xs={24} sm={12} md={8}>
+    <FormItem name="field1" label={t("필드1")}>
+      <Input />
+    </FormItem>
+  </Col>
+  <Col xs={24} sm={12} md={8}>
+    <FormItem name="field2" label={t("필드2")}>
+      <Input />
+    </FormItem>
+  </Col>
+  <Col xs={24} sm={24} md={8}>
+    <FormItem name="field3" label={t("필드3")}>
+      <Input />
+    </FormItem>
+  </Col>
+</Row>
+```
+
+#### 기본 2컬럼 레이아웃 (department/FormModal.tsx)
+```tsx
+<Row gutter={12}>
+  <Col span={24}>
+    <FormItem name="trtmntDeptNm" label={t("부서명")}>
+      <Input />
+    </FormItem>
+  </Col>
+  <Col xs={24} sm={12}>
+    <FormItem name="useYn" label={t("사용여부")}>
+      <Radio.Group options={[...]} />
+    </FormItem>
+  </Col>
+</Row>
+```
+
+### 2.2 Space
+
+#### 기본 간격 조정
+```tsx
+<Space>
+  <Button type="primary" onClick={handleSave}>
+    {t("저장")}
+  </Button>
+  <Button onClick={onCancel}>
+    {t("취소")}
+  </Button>
+</Space>
+```
+
+#### 컴팩트 스타일 (benefit.time-deal/FormModal.tsx)
+```tsx
+<Space.Compact>
+  <Select options={options} style={{ width: 80 }} />
+  <Button>{t("할인")}</Button>
+</Space.Compact>
+```
+
+### 2.3 Flex
+
+#### 정렬과 간격 조정 (benefit.time-deal/FormModal.tsx)
+```tsx
+<Flex gap={8} align="center">
+  <FormItem name="field1" style={{ margin: 0 }}>
+    <Input />
+  </FormItem>
+  <span>~</span>
+  <FormItem name="field2" style={{ margin: 0 }}>
+    <Input />
+  </FormItem>
+</Flex>
+```
+
+### 2.4 Divider
+
+#### 섹션 구분
+```tsx
+<Divider orientation="left">{t("기본 정보")}</Divider>
+<Form>
+  {/* 폼 필드들 */}
+</Form>
+
+<Divider orientation="left">{t("추가 정보")}</Divider>
+<Form>
+  {/* 추가 폼 필드들 */}
+</Form>
+```
+
+## 3. 데이터 표시 컴포넌트 (Data Display)
+
+### 3.1 Table
+
+#### 기본 테이블 (StatisticsListData.tsx)
+```tsx
+const columns: TableColumnsType<DtoItem> = [
+  {
+    title: <div style={{ textAlign: "center" }}>번호</div>,
+    dataIndex: "num",
+    key: "num",
+    width: 80,
+    align: "center",
+  },
+  {
+    title: <div style={{ textAlign: "center" }}>세부항목</div>,
+    dataIndex: "cstItmNm",
+    key: "cstItmNm",
+    sorter: (a, b) => (a.cstItmNm ?? "").localeCompare(b.cstItmNm ?? ""),
+  },
+  {
+    title: <div style={{ textAlign: "center" }}>제품금액(원)</div>,
+    dataIndex: "amt",
+    key: "amt",
+    width: 150,
+    align: "right",
+    render: (value) => toMoney(value),
+    sorter: (a, b) => (a.amt ?? 0) - (b.amt ?? 0),
+  }
+];
+
+<Table<DtoItem>
+  columns={columns}
+  dataSource={listData}
+  pagination={false}
+  size="small"
+/>
+```
+
+### 3.2 Descriptions
+
+#### 상세 정보 표시 (order.subscription.direct-rental/FormModal.tsx)
+```tsx
+<Descriptions
+  bordered
+  column={3}
+  size="small"
+  style={{ width: "100%" }}
+  styles={{
+    label: { textAlign: "left", minWidth: 100, width: 140 },
+    content: { textAlign: "left" }
+  }}
+  className="fixed-descriptions"
+  items={[
+    { label: t("주문번호"), children: params.query?.ifId },
+    {
+      label: t("주문일자"),
+      children: params.query?.creatDtm
+        ? dayjs(params.query.creatDtm).format("YYYY-MM-DD HH:mm")
+        : "-",
+    },
+    {
+      label: t("주문자명/아이디"),
+      children: (
+        <Space>
+          {`${params.query?.usrNm || ""}(${params.query?.rmsUsrId || ""})`}
+          <Button type="default" size="small" onClick={handleLink}>
+            CRM
+          </Button>
+        </Space>
+      ),
+    },
+    { label: t("휴대폰"), children: params.query?.usrHpNo },
+    { label: t("이메일"), span: 2, children: params.query?.email || "-" },
+  ]}
+/>
+```
+
+#### 중첩된 Descriptions.Item
+```tsx
+<Descriptions.Item
+  label={
+    <span>
+      <span style={{ color: "#ff4d4f", fontSize: "12px", marginRight: "4px" }}>*</span>
+      {t("할인 설정")}
+    </span>
+  }
+>
+  <Flex gap={8} align="center">
+    <FormItem name="discountType" style={{ margin: 0 }}>
+      <Select options={discountOptions} />
+    </FormItem>
+  </Flex>
+</Descriptions.Item>
+```
+
+## 4. 내비게이션 컴포넌트 (Navigation)
+
+### 4.1 Tabs
+
+#### 기본 탭 (MemberInstallerDetailDrawer.tsx)
+```tsx
+<Tabs
+  items={Object.values(MemberInstallerTabType).map((value) => ({
+    key: value,
+    label: value,
+  }))}
+  activeKey={activeTabType}
+  type="line"
+  size="small"
+  onChange={(key) => setActiveTabType(key as MemberInstallerTabType)}
+/>
+```
+
+#### 동적 탭 콘텐츠
+```tsx
+const tabItems = [
+  {
+    key: '1',
+    label: t('기본정보'),
+    children: <BasicInfoPanel />,
+  },
+  {
+    key: '2',
+    label: t('상세정보'),
+    children: <DetailInfoPanel />,
+  },
+];
+
+<Tabs items={tabItems} />
+```
+
+## 5. 피드백 컴포넌트 (Feedback)
+
+### 5.1 Button
+
+#### 기본 버튼 스타일
+```tsx
+// Primary 버튼
+<Button type="primary" onClick={handleSave} loading={saveSpinning}>
+  {t("저장")}
+</Button>
+
+// Default 버튼
+<Button onClick={onCancel}>
+  {t("취소")}
+</Button>
+
+// Danger 버튼
+<Button onClick={handleDelete} loading={deleteSpinning} danger>
+  {t("삭제")}
+</Button>
+
+// Link 스타일 버튼
+<Button type="link" onClick={handleEdit}>
+  {t("수정")}
+</Button>
+
+// Text 버튼 (아이콘과 함께)
+<Button type="text" onClick={onClose} icon={<IconClose />} />
+```
+
+#### 크기별 버튼
+```tsx
+// 작은 버튼
+<Button type="default" size="small" onClick={handleAction}>
+  CRM
+</Button>
+
+// 큰 버튼
+<Button type="primary" size="large">
+  {t("확인")}
+</Button>
+```
+
+### 5.2 Modal (AXModal 사용)
+
+프로젝트에서는 Ant Design Modal 대신 커스텀 AXModal을 주로 사용하지만, 기본 패턴은 유사합니다.
+
+```tsx
+<AXModal width={1400} {...{ open, onCancel, onOk: onOk as any, afterClose }}>
+  <AXModal.Header title={t("제목")}>
+    <Button type="primary" onClick={handleSave}>
+      {t("저장")}
+    </Button>
+    <Button onClick={onCancel}>
+      {t("취소")}
+    </Button>
+  </AXModal.Header>
+
+  <AXModal.Body>
+    {/* 모달 콘텐츠 */}
+  </AXModal.Body>
+
+  <AXModal.Footer>
+    {/* 푸터 버튼들 */}
+  </AXModal.Footer>
+</AXModal>
+```
+
+## 6. 기타 유틸리티 컴포넌트
+
+### 6.1 Popover
+
+#### 정보 표시용 팝오버
+```tsx
+<Popover
+  content={<div>{t("도움말 내용")}</div>}
+  title={t("도움말")}
+  trigger="hover"
+>
+  <Button type="link" icon={<InfoIcon />} />
+</Popover>
+```
+
+### 6.2 Tooltip
+
+#### 간단한 툴팁
+```tsx
+<Tooltip title={t("이 기능에 대한 설명입니다.")}>
+  <Button icon={<QuestionIcon />} />
+</Tooltip>
+```
+
+### 6.3 Tag
+
+#### 상태 표시용 태그
+```tsx
+<Tag color={status === 'active' ? 'green' : 'red'}>
+  {status === 'active' ? t('활성') : t('비활성')}
+</Tag>
+```
+
+### 6.4 Badge
+
+#### 알림 배지
+```tsx
+<Badge count={5} size="small">
+  <Button icon={<NotificationIcon />} />
+</Badge>
+```
+
+## 7. 누락되었던 주요 컴포넌트들
+
+### 7.1 Tree
+
+Tree 컴포넌트는 계층적 데이터를 트리 구조로 표시하는 데 사용됩니다. 프로젝트에서는 메뉴 관리, 카테고리 관리 등에 활용됩니다.
+
+#### 기본 트리 구조 (MenuDirectory.tsx 참고)
+```tsx
+import { Tree } from "antd";
+import { TreeProps } from "antd/lib/tree";
+
+interface TreeNode {
+  key: string;
+  title: string;
+  children?: TreeNode[];
+  isLeaf?: boolean;
+  icon?: string;
+}
+
+const treeData: TreeNode[] = [
+  {
+    key: '0',
+    title: '루트 메뉴',
+    children: [
+      {
+        key: '0:0',
+        title: '하위 메뉴 1',
+        isLeaf: true,
+      },
+      {
+        key: '0:1',
+        title: '하위 메뉴 2',
+        children: [
+          {
+            key: '0:1:0',
+            title: '세부 메뉴',
+            isLeaf: true,
+          },
+        ],
+      },
+    ],
+  },
+];
+
+<Tree
+  treeData={treeData}
+  defaultExpandAll
+  onSelect={(selectedKeys, info) => {
+    console.log('선택된 노드:', selectedKeys, info);
+  }}
+/>
+```
+
+#### 드래그 앤 드롭 지원 트리 (CategoryDirectory.tsx 참고)
+```tsx
+const onDrop: TreeProps["onDrop"] = useCallback((info) => {
+  const {
+    dropPosition,
+    dropToGap,
+    node: { seqPath: dropNodeKey },
+    dragNode: { seqPath: dragNodeKey },
+  } = info;
+
+  console.log('드래그 앤 드롭:', { dropPosition, dropToGap, dropNodeKey, dragNodeKey });
+
+  // 트리 구조 업데이트 로직
+  const newTreeData = updateTreeData(treeData, dragNodeKey, dropNodeKey);
+  setTreeData(newTreeData);
+}, [treeData]);
+
+<Tree
+  draggable
+  blockNode
+  onDrop={onDrop}
+  treeData={treeData}
+  expandedKeys={expandedKeys}
+  onExpand={(keys) => setExpandedKeys(keys)}
+  onSelect={(selectedKeys, info) => {
+    setSelectedItem(info.node);
+  }}
+/>
+```
+
+#### 커스텀 트리 노드 렌더링
+```tsx
+const renderTreeNode = (nodeData) => (
+  <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+    <MenuIcon type={nodeData.icon} />
+    <span>{nodeData.title}</span>
+    <Space size={4}>
+      <Tooltip title={t("추가")}>
+        <Button
+          type="text"
+          size="small"
+          icon={<IconAdd />}
+          onClick={(e) => {
+            e.stopPropagation();
+            handleAddNode(nodeData.key);
+          }}
+        />
+      </Tooltip>
+      <Tooltip title={t("삭제")}>
+        <Button
+          type="text"
+          size="small"
+          icon={<IconBin />}
+          onClick={(e) => {
+            e.stopPropagation();
+            handleDelNode(nodeData.key);
+          }}
+        />
+      </Tooltip>
+    </Space>
+  </div>
+);
+
+<Tree
+  treeData={treeData.map(node => ({
+    ...node,
+    title: renderTreeNode(node),
+  }))}
+/>
+```
+
+### 7.2 Drawer
+
+Drawer는 화면 측면에서 슬라이드되는 패널입니다. 프로젝트에서는 AXDrawer로 커스터마이징되어 사용됩니다.
+
+#### 기본 Drawer (AXDrawer.tsx 참고)
+```tsx
+import { AXDrawer } from "@core/components/AXDrawer";
+
+function DetailDrawer({ open, onClose, selectedItem }) {
+  const [width, setWidth] = useState(70);
+
+  return (
+    <AXDrawer
+      widthPercent={width}
+      onResize={(w) => setWidth(w)}
+      styles={{
+        minWidth: 1000,
+      }}
+      open={open}
+      onClose={onClose}
+      loading={!selectedItem}
+    >
+      <AXDrawer.Header>
+        <h2>{t("상세 정보")}</h2>
+        <Space>
+          <Button type="primary" onClick={handleSave}>
+            {t("저장")}
+          </Button>
+          <Button type="text" onClick={onClose} icon={<IconClose />} />
+        </Space>
+      </AXDrawer.Header>
+
+      <AXDrawer.Body>
+        {/* 드로어 내용 */}
+        <Form form={form}>
+          <FormItem name="title" label={t("제목")}>
+            <Input />
+          </FormItem>
+          {/* 기타 폼 필드들 */}
+        </Form>
+      </AXDrawer.Body>
+    </AXDrawer>
+  );
+}
+```
+
+#### 리사이즈 가능한 Drawer
+```tsx
+const [drawerWidth, setDrawerWidth] = useState(50);
+
+<AXDrawer
+  widthPercent={drawerWidth}
+  onResize={(width) => setDrawerWidth(width)}
+  open={open}
+  onClose={onClose}
+>
+  <AXDrawer.Header>
+    <h2>리사이즈 가능한 드로어</h2>
+  </AXDrawer.Header>
+  <AXDrawer.Body>
+    <p>드로어 우측 경계를 드래그하여 크기를 조절할 수 있습니다.</p>
+  </AXDrawer.Body>
+</AXDrawer>
+```
+
+### 7.3 Upload
+
+파일 업로드 컴포넌트는 다양한 형태로 활용됩니다.
+
+#### 기본 파일 업로드 (MultiFileUploader.tsx 참고)
+```tsx
+import { Upload, Button } from "antd";
+import { UploadOutlined } from "@ant-design/icons";
+import type { UploadProps } from "antd";
+
+const uploadProps: UploadProps = {
+  action: '/api/upload',
+  listType: 'text',
+  multiple: true,
+  onChange: (info) => {
+    const { status } = info.file;
+    if (status === 'done') {
+      console.log('업로드 성공:', info.file.name);
+    } else if (status === 'error') {
+      console.log('업로드 실패:', info.file.name);
+    }
+  },
+};
+
+<Upload {...uploadProps}>
+  <Button icon={<UploadOutlined />}>
+    {t("파일 업로드")}
+  </Button>
+</Upload>
+```
+
+#### 이미지 업로드 (드래그 앤 드롭)
+```tsx
+const { Dragger } = Upload;
+
+<Dragger
+  name="file"
+  multiple
+  action="/api/upload"
+  accept="image/*"
+  listType="picture"
+  onChange={(info) => {
+    const { status } = info.file;
+    if (status === 'uploading') {
+      console.log('업로드 중:', info.fileList);
+    }
+    if (status === 'done') {
+      console.log('업로드 완료:', info.file.name);
+    }
+  }}
+>
+  <p className="ant-upload-drag-icon">
+    <UploadOutlined />
+  </p>
+  <p className="ant-upload-text">
+    {t("클릭하거나 파일을 여기로 드래그하세요")}
+  </p>
+  <p className="ant-upload-hint">
+    {t("단일 또는 다중 파일 업로드를 지원합니다")}
+  </p>
+</Dragger>
+```
+
+#### 커스텀 업로드 버튼
+```tsx
+<Upload
+  customRequest={({ file, onSuccess, onError }) => {
+    // 커스텀 업로드 로직
+    uploadFile(file)
+      .then(response => {
+        onSuccess(response);
+      })
+      .catch(error => {
+        onError(error);
+      });
+  }}
+  showUploadList={false}
+>
+  <Button type="primary" icon={<UploadOutlined />}>
+    {t("커스텀 업로드")}
+  </Button>
+</Upload>
+```
+
+### 7.4 Transfer
+
+Transfer 컴포넌트는 두 그룹 간의 데이터 이동을 위해 사용됩니다.
+
+#### 기본 Transfer
+```tsx
+import { Transfer } from "antd";
+
+const [targetKeys, setTargetKeys] = useState<string[]>([]);
+const [selectedKeys, setSelectedKeys] = useState<string[]>([]);
+
+const mockData = Array.from({ length: 20 }).map((_, i) => ({
+  key: i.toString(),
+  title: `항목 ${i + 1}`,
+  description: `설명 ${i + 1}`,
+}));
+
+<Transfer
+  dataSource={mockData}
+  titles={[t('사용 가능'), t('선택된 항목')]}
+  targetKeys={targetKeys}
+  selectedKeys={selectedKeys}
+  onChange={(nextTargetKeys) => {
+    setTargetKeys(nextTargetKeys);
+  }}
+  onSelectChange={(sourceSelectedKeys, targetSelectedKeys) => {
+    setSelectedKeys([...sourceSelectedKeys, ...targetSelectedKeys]);
+  }}
+  render={(item) => item.title}
+/>
+```
+
+### 7.5 Cascader
+
+Cascader는 계층적 선택을 위한 컴포넌트입니다.
+
+#### 기본 Cascader
+```tsx
+import { Cascader } from "antd";
+
+const options = [
+  {
+    value: 'seoul',
+    label: '서울',
+    children: [
+      {
+        value: 'gangnam',
+        label: '강남구',
+      },
+      {
+        value: 'gangbuk',
+        label: '강북구',
+      },
+    ],
+  },
+  {
+    value: 'busan',
+    label: '부산',
+    children: [
+      {
+        value: 'haeundae',
+        label: '해운대구',
+      },
+    ],
+  },
+];
+
+<FormItem name="location" label={t("지역")}>
+  <Cascader
+    options={options}
+    placeholder={t("지역을 선택하세요")}
+    changeOnSelect
+  />
+</FormItem>
+```
+
+### 7.6 TreeSelect
+
+TreeSelect는 트리 형태의 드롭다운 선택기입니다.
+
+#### 기본 TreeSelect
+```tsx
+import { TreeSelect } from "antd";
+
+const treeData = [
+  {
+    title: '전체',
+    value: 'all',
+    children: [
+      {
+        title: '카테고리 1',
+        value: 'category1',
+        children: [
+          {
+            title: '하위 카테고리 1-1',
+            value: 'subcategory1-1',
+          },
+        ],
+      },
+      {
+        title: '카테고리 2',
+        value: 'category2',
+      },
+    ],
+  },
+];
+
+<FormItem name="category" label={t("카테고리")}>
+  <TreeSelect
+    style={{ width: '100%' }}
+    dropdownStyle={{ maxHeight: 400, overflow: 'auto' }}
+    treeData={treeData}
+    placeholder={t("카테고리를 선택하세요")}
+    treeDefaultExpandAll
+  />
+</FormItem>
+```
+
+### 7.7 AutoComplete
+
+AutoComplete는 자동 완성 입력 컴포넌트입니다.
+
+#### 기본 AutoComplete
+```tsx
+import { AutoComplete } from "antd";
+
+const [options, setOptions] = useState<{value: string}[]>([]);
+
+const onSearch = (searchText: string) => {
+  const filteredOptions = mockData
+    .filter(item => item.includes(searchText))
+    .map(item => ({ value: item }));
+  setOptions(filteredOptions);
+};
+
+<FormItem name="search" label={t("검색")}>
+  <AutoComplete
+    options={options}
+    onSearch={onSearch}
+    placeholder={t("검색어를 입력하세요")}
+    filterOption={(inputValue, option) =>
+      option!.value.toUpperCase().indexOf(inputValue.toUpperCase()) !== -1
+    }
+  />
+</FormItem>
+```
+
+### 7.8 기타 유용한 컴포넌트들
+
+#### Slider (범위 슬라이더)
+```tsx
+import { Slider } from "antd";
+
+<FormItem name="range" label={t("범위")}>
+  <Slider
+    range
+    min={0}
+    max={100}
+    defaultValue={[20, 50]}
+    marks={{
+      0: '0',
+      25: '25',
+      50: '50',
+      75: '75',
+      100: '100',
+    }}
+  />
+</FormItem>
+```
+
+#### Rate (평점)
+```tsx
+import { Rate } from "antd";
+
+<FormItem name="rating" label={t("평점")}>
+  <Rate allowHalf defaultValue={2.5} />
+</FormItem>
+```
+
+#### Mention (멘션)
+```tsx
+import { Mentions } from "antd";
+
+const { Option } = Mentions;
+
+<FormItem name="comment" label={t("댓글")}>
+  <Mentions
+    rows={3}
+    placeholder={t("@사용자명을 입력하면 멘션됩니다")}
+  >
+    <Option value="user1">사용자1</Option>
+    <Option value="user2">사용자2</Option>
+    <Option value="user3">사용자3</Option>
+  </Mentions>
+</FormItem>
+```
+
+## 8. 고급 사용 패턴
+
+### 7.1 조건부 렌더링과 함께 사용
+
+```tsx
+const watchedValue = Form.useWatch("parentField", form);
+
+return (
+  <>
+    <FormItem name="parentField" label={t("부모필드")}>
+      <Select options={parentOptions} />
+    </FormItem>
+
+    {watchedValue === "specific_value" && (
+      <Row gutter={16}>
+        <Col span={12}>
+          <FormItem name="childField1" label={t("자식필드1")}>
+            <Input />
+          </FormItem>
+        </Col>
+        <Col span={12}>
+          <FormItem name="childField2" label={t("자식필드2")}>
+            <Select options={childOptions} />
+          </FormItem>
+        </Col>
+      </Row>
+    )}
+  </>
+);
+```
+
+### 7.2 shouldUpdate 패턴
+
+```tsx
+<Form.Item
+  shouldUpdate={(prevValues, currentValues) =>
+    prevValues.triggerField !== currentValues.triggerField
+  }
+>
+  {({ getFieldValue }) => {
+    const triggerValue = getFieldValue("triggerField");
+    return (
+      <Row gutter={16}>
+        <Col span={triggerValue === "Y" ? 12 : 24}>
+          <FormItem name="conditionalField1">
+            <Input />
+          </FormItem>
+        </Col>
+        {triggerValue === "Y" && (
+          <Col span={12}>
+            <FormItem name="conditionalField2">
+              <Select options={options} />
+            </FormItem>
+          </Col>
+        )}
+      </Row>
+    );
+  }}
+</Form.Item>
+```
+
+### 7.3 복합 입력 컴포넌트
+
+```tsx
+<FormItem label={t("기간 설정")}>
+  <Input.Group compact>
+    <FormItem name="startDate" noStyle rules={[{ required: true }]}>
+      <DatePicker placeholder="시작일" style={{ width: '50%' }} />
+    </FormItem>
+    <FormItem name="endDate" noStyle rules={[{ required: true }]}>
+      <DatePicker placeholder="종료일" style={{ width: '50%' }} />
+    </FormItem>
+  </Input.Group>
+</FormItem>
+```
+
+### 7.4 동적 리스트 관리
+
+```tsx
+<Form.List name="items">
+  {(fields, { add, remove }) => (
+    <>
+      {fields.map(({ key, name, ...restField }) => (
+        <Row key={key} gutter={16} align="middle">
+          <Col span={20}>
+            <FormItem
+              {...restField}
+              name={[name, 'itemName']}
+              label={t("항목명")}
+              rules={[{ required: true }]}
+            >
+              <Input />
+            </FormItem>
+          </Col>
+          <Col span={4}>
+            <Button
+              type="link"
+              danger
+              onClick={() => remove(name)}
+              icon={<DeleteIcon />}
+            >
+              삭제
+            </Button>
+          </Col>
+        </Row>
+      ))}
+      <Button
+        type="dashed"
+        onClick={() => add()}
+        block
+        icon={<PlusIcon />}
+      >
+        + 항목 추가
+      </Button>
+    </>
+  )}
+</Form.List>
+```
+
+## 8. 성능 최적화 팁
+
+### 8.1 Form.Item preserve 속성
+```tsx
+<FormItem
+  name="temporaryField"
+  preserve={false}  // 컴포넌트 언마운트 시 값 제거
+>
+  <Input />
+</FormItem>
+```
+
+### 8.2 Table 가상화
+```tsx
+<Table
+  virtual
+  scroll={{ y: 400 }}  // 높이 제한으로 가상 스크롤 활성화
+  dataSource={largeDataset}
+  columns={columns}
+/>
+```
+
+### 8.3 Select 검색 최적화
+```tsx
+<Select
+  showSearch
+  filterOption={(input, option) =>
+    (option?.label ?? '').toLowerCase().includes(input.toLowerCase())
+  }
+  options={options}
+/>
+```
+
+## 9. 접근성 개선
+
+### 9.1 적절한 라벨링
+```tsx
+<FormItem
+  name="field"
+  label={t("필수 입력 필드")}
+  required  // 시각적 필수 표시
+  rules={[{ required: true, message: t("이 필드는 필수입니다.") }]}
+>
+  <Input aria-describedby="field-help" />
+</FormItem>
+<div id="field-help">{t("이 필드에 대한 추가 설명")}</div>
+```
+
+### 9.2 키보드 내비게이션
+```tsx
+<Space>
+  <Button tabIndex={1} onClick={handleSave}>
+    {t("저장")}
+  </Button>
+  <Button tabIndex={2} onClick={handleCancel}>
+    {t("취소")}
+  </Button>
+</Space>
+```
+
+## 10. 프로젝트 특화 패턴
+
+### 10.1 다국어 지원 (i18n)
+모든 텍스트는 `useI18n` 훅을 통해 다국어 처리:
+```tsx
+const { t } = useI18n();
+
+<FormItem name="title" label={t("제목")}>
+  <Input placeholder={t("제목을 입력하세요")} />
+</FormItem>
+```
+
+### 10.2 코드 스토어 활용
+공통 코드는 `useCodeStore`를 통해 관리:
+```tsx
+const SLE_TPCD = useCodeStore((s) => s.SLE_TPCD);
+
+<FormItem name="saleType" label={t("판매유형")}>
+  <Select options={SLE_TPCD?.options} />
+</FormItem>
+```
+
+### 10.3 에러 처리 패턴
+```tsx
+const handleSave = useCallback(async () => {
+  try {
+    setSaveSpinning(true);
+    const values = await form.validateFields();
+    await ApiService.save(values);
+    messageApi.success(t("저장되었습니다."));
+  } catch (err) {
+    await errorHandling(err);  // 프로젝트 공통 에러 처리
+  } finally {
+    setSaveSpinning(false);
+  }
+}, [form, messageApi, t]);
+```
+
+이 가이드를 참고하여 일관성 있고 효율적인 Ant Design 컴포넌트를 사용하시기 바랍니다.