@axboot-mcp/mcp-server 1.0.0

package/src/docs//354/202/254/354/232/251/353/262/225/FormModal-/354/202/254/354/232/251/353/262/225.md

@@ -0,0 +1,1155 @@
+# FormModal 컴포넌트 사용법
+
+FormModal은 AXBoot 프레임워크 기반의 모달 창에서 폼 데이터를 등록/수정/삭제할 수 있는 표준화된 컴포넌트 패턴입니다. AXModal과 Ant Design Form을 조합하여 일관성 있는 사용자 경험을 제공합니다.
+
+## 기본 구조
+
+```tsx
+import { AXModal } from "@core/components/AXModal";
+import { Loading } from "@core/components/common";
+import { useModalStore } from "@axboot/stores";
+import { Form, Button, Input, Space } from "antd";
+
+interface DtoItem extends YourDataType {}
+
+export interface ModalRequest {
+  query?: Record<string, any>;
+}
+
+export interface ModalResponse {
+  save?: boolean;
+  delete?: boolean;
+}
+
+interface Props {
+  open: boolean;
+  onOk: (value: ModalResponse) => ModalResponse;
+  onCancel: (reason?: any) => void;
+  params: ModalRequest;
+  afterClose: () => void;
+}
+
+function FormModal({ open, onOk, onCancel, afterClose, params }: Props) {
+  // Modal 구현
+}
+
+export async function openFormModal(params: ModalRequest = {}) {
+  const openModal = useModalStore.getState().openModal;
+  return await openModal<ModalResponse>((open, resolve, reject, onClose, afterClose) => (
+    <FormModal open={open} onOk={resolve} onCancel={reject} afterClose={afterClose} params={params} />
+  ));
+}
+```
+
+## 사용 예시
+
+### 1. 기본 CRUD 모달 (부서 관리)
+
+```tsx
+import { AXModal } from "@core/components/AXModal";
+import { Loading } from "@core/components/common";
+import { confirmDialog } from "@core/components/dialogs";
+import { useAntApp } from "@core/hooks";
+import { useModalStore } from "@axboot/stores";
+import { Button, Col, Form, Input, Radio, Row, Space } from "antd";
+import { useDidMountEffect, useI18n } from "hooks";
+import React, { useState } from "react";
+import { errorHandling } from "utils";
+import { TrtmntDept, TrtmntDeptService } from "../../../../services";
+
+interface DtoItem extends TrtmntDept {}
+
+function FormModal({ open, onOk, onCancel, afterClose, params }: Props) {
+  const { t } = useI18n();
+  const { messageApi } = useAntApp();
+
+  const [deleteSpinning, setDeleteSpinning] = useState(false);
+  const [saveSpinning, setSaveSpinning] = useState(false);
+  const [form] = Form.useForm();
+
+  // 저장 처리
+  const handleSave = React.useCallback(async () => {
+    try {
+      await form.validateFields();
+      setSaveSpinning(true);
+      const formValues = form.getFieldsValue();
+
+      await TrtmntDeptService.postTrtmntDeptSaveTrtmntDept({
+        ...formValues,
+      });
+
+      onOk({ save: true });
+    } catch (e) {
+      await errorHandling(e);
+    } finally {
+      setSaveSpinning(false);
+    }
+  }, [form, onOk]);
+
+  // 삭제 처리
+  const handleDelete = React.useCallback(async () => {
+    try {
+      await confirmDialog({
+        content: t("정말 삭제하시겠습니까?"),
+      });
+
+      if (!params.query?.trtmntDeptNo) return;
+      setDeleteSpinning(true);
+
+      await TrtmntDeptService.postTrtmntDeptDeleteTrtmntDept({
+        trtmntDeptNo: params.query.trtmntDeptNo,
+      });
+
+      onOk({ delete: true });
+    } catch (e) {
+      await errorHandling(e);
+    } finally {
+      setDeleteSpinning(false);
+    }
+  }, [onOk, params.query?.trtmntDeptNo, t]);
+
+  // 초기 데이터 설정
+  useDidMountEffect(() => {
+    form.setFieldsValue(params.query);
+  });
+
+  return (
+    <AXModal width={350} {...{ open, onCancel, onOk: onOk as any, afterClose }}>
+      <AXModal.Header title={params.query ? "부서 수정" : "부서 등록"} />
+
+      <AXModal.Body>
+        <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>
+            <Col xs={24} sm={12}>
+              <FormItem label={t("사용여부")} name="useYn" rules={[{ required: true }]}>
+                <Radio.Group
+                  options={[
+                    { value: "Y", label: "Y" },
+                    { value: "N", label: "N" },
+                  ]}
+                />
+              </FormItem>
+            </Col>
+          </Row>
+        </Form>
+      </AXModal.Body>
+
+      <AXModal.Footer>
+        <Space>
+          <Button type="primary" onClick={form.submit} loading={saveSpinning}>
+            {t("btn.저장")}
+          </Button>
+          <Button onClick={handleDelete} loading={deleteSpinning} color="danger" variant="solid">
+            {t("btn.삭제")}
+          </Button>
+          <Button onClick={onCancel}>{t("btn.취소")}</Button>
+        </Space>
+      </AXModal.Footer>
+    </AXModal>
+  );
+}
+```
+
+### 2. 복합 탭 구조 모달 (제품 마스터)
+
+```tsx
+import { AXModal } from "@core/components/AXModal";
+import { Loading } from "@core/components/common";
+import { confirmDialog } from "@core/components/dialogs";
+import { useAntApp } from "@core/hooks";
+import { useModalStore } from "@axboot/stores";
+import { Button, Form, Input, Radio, Select, Space, Tabs } from "antd";
+import { useDidMountEffect, useI18n } from "hooks";
+import React, { useState } from "react";
+import { errorHandling } from "utils";
+import { ProdgrpMstRes, ProductGroupMasterService } from "../../../../services";
+
+interface DtoItem extends ProdgrpMstRes {}
+
+function FormModal({ open, onOk, onCancel, afterClose, params }: Props) {
+  const { t } = useI18n();
+  const { messageApi } = useAntApp();
+  const [form] = Form.useForm();
+
+  const [saveSpinning, setSaveSpinning] = useState(false);
+  const [duplSpinning, setDuplSpinning] = useState(false);
+  const [duplCheck, setDuplCheck] = useState(false);
+  const [activeTabType, setActiveTabType] = useState("스펙");
+  const [saveRequestValue, setSaveRequestValue] = React.useState<DtoItem>({});
+
+  // 폼 값 변경 감지
+  const onValuesChange = React.useCallback(
+    (_changedValues: any, values: Record<string, any>) => {
+      if ("prodgrpMastrNm" in _changedValues) {
+        setDuplCheck(false);
+      }
+      setSaveRequestValue({ ...saveRequestValue, ...values });
+    },
+    [saveRequestValue],
+  );
+
+  // 중복확인 처리
+  const handleDuplication = React.useCallback(async () => {
+    try {
+      setDuplSpinning(true);
+      const nm = form.getFieldValue("prodgrpMastrNm");
+
+      if (!nm) {
+        throw new Error("제품군 마스터명을 입력해 주세요.");
+      }
+
+      const result = await ProductGroupMasterService.postProductGroupMasterDuplprodgrpMstNm({
+        prodgrpMastrNm: nm,
+      });
+
+      setDuplCheck(result.rs.duplYn === "N");
+
+      if (result.rs.duplYn === "Y") {
+        messageApi.error("이미 사용중인 이름입니다.");
+      } else if (result.rs.duplYn === "N") {
+        messageApi.info("사용할 수 있는 이름입니다.");
+      }
+    } catch (e) {
+      await errorHandling(e);
+    } finally {
+      setDuplSpinning(false);
+    }
+  }, [form, messageApi]);
+
+  // 저장 처리
+  const handleSave = React.useCallback(async () => {
+    try {
+      setSaveSpinning(true);
+      await form.validateFields();
+
+      if (!duplCheck) {
+        throw new Error("제품군마스터명 중복확인을 해주세요.");
+      }
+
+      const values = form.getFieldsValue();
+      const dto01 = (values.specItmDtos || saveRequestValue.specItmDtos) ?? [];
+      const dto02 = (values.indvdlztnItmDtos || saveRequestValue.indvdlztnItmDtos) ?? [];
+
+      if (dto01.length === 0 && dto02.length === 0) {
+        throw new Error("하나 이상의 항목을 입력해 주세요");
+      }
+
+      const apiParams: DtoItem = {
+        ...values,
+        specItmDtos: dto01.map((item, idx) => ({ ...item, expsrSn: idx })),
+        indvdlztnItmDtos: dto02.map((item, idx) => ({ ...item, expsrSn: idx })),
+      };
+
+      await ProductGroupMasterService.postProductGroupMasterSaveprodgrpMst(apiParams);
+      onOk({ save: true });
+    } catch (e) {
+      await errorHandling(e);
+    } finally {
+      setSaveSpinning(false);
+    }
+  }, [duplCheck, form, onOk, saveRequestValue]);
+
+  return (
+    <AXModal width={1200} {...{ open, onCancel, onOk: onOk as any, afterClose }}>
+      <AXModal.Header title={params.query ? "제품군 마스터 수정" : "제품군 마스터 등록"}>
+        <Space>
+          <Button onClick={onCancel}>{t("btn.취소")}</Button>
+          <Button type="primary" onClick={handleSave} loading={saveSpinning}>
+            {t("btn.저장")}
+          </Button>
+        </Space>
+      </AXModal.Header>
+
+      <AXModal.Body>
+        <Form<DtoItem>
+          form={form}
+          layout="vertical"
+          onFinish={handleSave}
+          onValuesChange={onValuesChange}
+          initialValues={{
+            useYn: "N",
+            bassExpsrYn: "N",
+            specItmDtos: [],
+            indvdlztnItmDtos: [],
+          }}
+        >
+          <Row gutter={24}>
+            <Col span={10}>
+              <FormItem label={t("제품군마스터명")} required>
+                <Space.Compact style={{ width: "100%" }}>
+                  <FormItem name="prodgrpMastrNm" rules={[{ required: true }]} noStyle>
+                    <Input />
+                  </FormItem>
+                  <Button onClick={handleDuplication} loading={duplSpinning} disabled={duplCheck}>
+                    중복확인
+                  </Button>
+                </Space.Compact>
+              </FormItem>
+            </Col>
+            <Col>
+              <FormItem name="useYn" label="사용여부" rules={[{ required: true }]}>
+                <Radio.Group
+                  options={[
+                    { value: "Y", label: "Y" },
+                    { value: "N", label: "N" },
+                  ]}
+                />
+              </FormItem>
+            </Col>
+          </Row>
+
+          {/* 탭 구조 */}
+          <Tabs
+            items={Object.values(MasterDetailTabType).map((value) => ({
+              key: value,
+              label: value,
+            }))}
+            activeKey={activeTabType}
+            type="line"
+            size="small"
+            onChange={(key) => {
+              setActiveTabType(key as MasterDetailTabType);
+            }}
+          />
+
+          <MasterDetailPanel tabType={activeTabType} form={form} />
+        </Form>
+      </AXModal.Body>
+    </AXModal>
+  );
+}
+```
+
+### 3. 파일 업로드 기능 모달 (앱 배너)
+
+```tsx
+import { AXModal } from "@core/components/AXModal";
+import { Loading } from "@core/components/common";
+import { DtPicker } from "@core/components/dtPicker";
+import { DtPickerType } from "@core/components/dtPicker/types";
+import { useAntApp } from "@core/hooks";
+import { useModalStore } from "@axboot/stores";
+import { Button, Form, Input, Switch, InputNumber } from "antd";
+import { useUploadService } from "hooks/useUploadService";
+import React, { useState } from "react";
+import { errorHandling, dateRangeToDts } from "utils";
+import { AppBanner, AppBannerMgmtService } from "services";
+import { ImgFileUploaderById } from "components/formItems/ImgFileUploaderById";
+import { UploadGuideLine } from "components/common/UploadGuideLine";
+
+interface DtoItem extends Omit<AppBanner, "dspyYn"> {
+  dt_range?: [string, string];
+  dspyYn?: string | boolean;
+}
+
+function FormModal({ open, onOk, onCancel, afterClose, params }: Props) {
+  const { t } = useI18n();
+  const { messageApi } = useAntApp();
+  const [form] = Form.useForm<DtoItem>();
+  const [saveSpinning, setSaveSpinning] = useState(false);
+
+  // 파일 업로드 서비스
+  const {
+    flUploadId: img_flUploadId,
+    files: img_files,
+    commitFiles: img_commitFiles,
+    setFiles: img_setFiles,
+    uploadFile: img_uploadFile,
+    setDeleted: img_setDeleted,
+    handleDownload: img_handleDownload,
+    spinning: img_spinning,
+  } = useUploadService({ flUploadId: params.query?.imageFlNo });
+
+  // 저장 처리
+  const handleSave = React.useCallback(async () => {
+    try {
+      setSaveSpinning(true);
+      const values = await form.validateFields();
+
+      const saved_img_files = img_files?.filter((item) => item.__status__ !== "D")?.[0];
+
+      const saveItem: AppBanner = {
+        ...params.query,
+        ...values,
+        ...dateRangeToDts(values.dt_range, {
+          expsrBgnDtm: DT_FORMAT.DATETIME,
+          expsrEndDtm: DT_FORMAT.DATETIME,
+        }),
+        imageFlNo: img_flUploadId,
+        imageFlSn: saved_img_files?.flSn || 1,
+        dspyYn: values.dspyYn ? "Y" : "N",
+      };
+
+      if (!saved_img_files) {
+        throw new Error(t("이미지를 등록해주세요."));
+      }
+
+      await img_commitFiles();
+      await AppBannerMgmtService.postAppBannerMgmtSave(saveItem);
+
+      messageApi.success(t("저장되었습니다."));
+      onOk({ save: true });
+    } catch (e) {
+      await errorHandling(e);
+    } finally {
+      setSaveSpinning(false);
+    }
+  }, [form, params.query, img_files, img_flUploadId, img_commitFiles, onOk, messageApi, t]);
+
+  return (
+    <AXModal width={1000} {...{ open, onCancel, onOk: onOk as any, afterClose }}>
+      <AXModal.Header title={isEditMode ? t("앱 스플래시 배너 수정") : t("앱 스플래시 배너 등록")}>
+        <Button type="primary" onClick={handleSave} loading={saveSpinning}>
+          {t("btn.저장")}
+        </Button>
+      </AXModal.Header>
+
+      <AXModal.Body>
+        <Form form={form} layout="vertical" onFinish={handleSave}>
+          <Row gutter={16}>
+            <Col span={12}>
+              <FormItem name="appBannerNm" label={t("배너명")} rules={[{ required: true }]}>
+                <Input placeholder={t("배너명을 입력하세요")} />
+              </FormItem>
+            </Col>
+            <Col span={12}>
+              <FormItem name="dspyYn" label={t("전시여부")} valuePropName="checked">
+                <Switch checkedChildren="전시" unCheckedChildren="미전시" />
+              </FormItem>
+            </Col>
+            <Col span={12}>
+              <FormItem
+                name="dt_range"
+                label={t("노출기간")}
+                rules={[{ required: true, message: t("노출기간을 선택해주세요") }]}
+              >
+                <DtPicker type={DtPickerType.DATE_RANGE} placeholder={[t("노출 시작일시"), t("노출 종료일시")]} />
+              </FormItem>
+            </Col>
+            <Col span={12}>
+              <FormItem name="expsrSecndValue" label={t("배너노출시간설정")} rules={[{ required: true }]}>
+                <InputNumber
+                  min={1}
+                  max={60}
+                  addonAfter="초"
+                  placeholder={t("노출할 초값을 입력하세요")}
+                  style={{ width: "20%" }}
+                />
+              </FormItem>
+            </Col>
+            <Col span={12}>
+              <FormItem label={t("스플래시 배너 이미지")} required>
+                <div style={{ display: "flex", alignItems: "flex-start", gap: "16px" }}>
+                  <div style={{ flex: "0 0 auto" }}>
+                    <ImgFileUploaderById
+                      value={img_files}
+                      spinning={img_spinning}
+                      onChange={img_setFiles}
+                      handleUpload={img_uploadFile}
+                      handleDelete={img_setDeleted}
+                      handleDownload={img_handleDownload}
+                      accept="image/png,image/svg+xml"
+                    />
+                  </div>
+                  <div style={{ flex: "1 1 auto" }}>
+                    <UploadGuideLine type="appSplashBanner" />
+                  </div>
+                </div>
+              </FormItem>
+            </Col>
+          </Row>
+        </Form>
+      </AXModal.Body>
+    </AXModal>
+  );
+}
+```
+
+### 4. 복합 데이터 처리 모달 (타임딜 혜택)
+
+```tsx
+import { AXModal } from "@core/components/AXModal";
+import { Loading } from "@core/components/common";
+import { useAntApp } from "@core/hooks";
+import { useModalStore } from "@axboot/stores";
+import { Button, Form, Input, InputNumber, Select, Table, Space } from "antd";
+import { useDidMountEffect, useI18n } from "hooks";
+import React, { useState, useCallback } from "react";
+import { errorHandling } from "utils";
+import { BnefResTimeDeal, BnefService, PrdRes } from "../../../../services";
+import { openSelectProductModal } from "../../../../modals/select-product/SelectProductModal";
+
+interface PrdItem extends PrdRes {}
+interface DtoItem extends BnefResTimeDeal {
+  dateRange?: [string, string];
+  bnefDscntStupValue?: number;
+  bnefDscntStupTpcd?: string;
+  bnefStupQty?: number;
+  sleLmttStupYn?: string;
+  amtTrncClcd?: string;
+}
+
+function FormModal({ open, onOk, onCancel, afterClose, params }: Props) {
+  const { t } = useI18n();
+  const { messageApi } = useAntApp();
+  const [form] = Form.useForm();
+
+  const [prdList, setPrdList] = React.useState<PrdItem[]>([]);
+  const [discountValues, setDiscountValues] = React.useState({
+    bnefDscntStupValue: undefined,
+    bnefDscntStupTpcd: "10",
+    amtTrncClcd: "10",
+  });
+  const [saveSpinning, setSaveSpinning] = useState(false);
+
+  // 할인가 계산 함수
+  const calculateDiscountedPrice = React.useCallback(
+    (salePrice: number, discountValue: number, discountType: string, truncationType: string) => {
+      if (!discountValue || discountValue === 0) {
+        return salePrice;
+      }
+
+      let discountedPrice: number;
+
+      if (discountType === "10") { // 정률할인
+        discountedPrice = salePrice * (1 - discountValue / 100);
+      } else { // 정액할인
+        discountedPrice = salePrice - discountValue;
+      }
+
+      // 절삭 처리
+      if (truncationType === "10") { // 원단위 절삭
+        discountedPrice = Math.floor(discountedPrice);
+      } else if (truncationType === "20") { // 십원단위 절삭
+        discountedPrice = Math.floor(discountedPrice / 10) * 10;
+      } else if (truncationType === "30") { // 백원단위 절삭
+        discountedPrice = Math.floor(discountedPrice / 100) * 100;
+      }
+
+      return Math.max(discountedPrice, 0);
+    },
+    [],
+  );
+
+  // 상품 선택 모달
+  const handleSelectProduct = useCallback(async () => {
+    try {
+      const result = await openSelectProductModal({});
+      if (result?.selectedProducts) {
+        const newProducts = result.selectedProducts.map((product: PrdRes) => ({
+          ...product,
+          discountedPrice: calculateDiscountedPrice(
+            product.salePrc || 0,
+            discountValues.bnefDscntStupValue || 0,
+            discountValues.bnefDscntStupTpcd || "10",
+            discountValues.amtTrncClcd || "10"
+          ),
+        }));
+        setPrdList([...prdList, ...newProducts]);
+      }
+    } catch (e) {
+      await errorHandling(e);
+    }
+  }, [prdList, calculateDiscountedPrice, discountValues]);
+
+  // 상품 목록 컬럼 정의
+  const productColumns = [
+    {
+      title: "이미지",
+      dataIndex: "thumbImgUrl",
+      width: 80,
+      render: (url: string) => <ThumbPreview url={url} size={50} />,
+    },
+    {
+      title: "상품명",
+      dataIndex: "prdNm",
+      width: 200,
+    },
+    {
+      title: "정가",
+      dataIndex: "stdPrc",
+      width: 100,
+      render: (value: number) => formatterNumber(value),
+    },
+    {
+      title: "판매가",
+      dataIndex: "salePrc",
+      width: 100,
+      render: (value: number) => formatterNumber(value),
+    },
+    {
+      title: "할인가",
+      dataIndex: "discountedPrice",
+      width: 100,
+      render: (value: number) => formatterNumber(value),
+    },
+    {
+      title: "관리",
+      width: 80,
+      render: (_: any, record: PrdItem, index: number) => (
+        <Button
+          size="small"
+          danger
+          onClick={() => {
+            const newList = [...prdList];
+            newList.splice(index, 1);
+            setPrdList(newList);
+          }}
+        >
+          삭제
+        </Button>
+      ),
+    },
+  ];
+
+  // 저장 처리
+  const handleSave = React.useCallback(async () => {
+    try {
+      setSaveSpinning(true);
+      const values = await form.validateFields();
+
+      if (prdList.length === 0) {
+        throw new Error("상품을 선택해주세요.");
+      }
+
+      const saveData = {
+        ...values,
+        ...discountValues,
+        prdList: prdList.map(item => ({
+          prdNo: item.prdNo,
+          discountedPrice: item.discountedPrice,
+        })),
+      };
+
+      await BnefService.postBnefSaveTimeDeal(saveData);
+      messageApi.success(t("저장되었습니다."));
+      onOk({ save: true });
+    } catch (e) {
+      await errorHandling(e);
+    } finally {
+      setSaveSpinning(false);
+    }
+  }, [form, prdList, discountValues, onOk, messageApi, t]);
+
+  return (
+    <AXModal width={1400} {...{ open, onCancel, onOk: onOk as any, afterClose }}>
+      <AXModal.Header title="타임딜 혜택 설정">
+        <Space>
+          <Button onClick={onCancel}>{t("btn.취소")}</Button>
+          <Button type="primary" onClick={handleSave} loading={saveSpinning}>
+            {t("btn.저장")}
+          </Button>
+        </Space>
+      </AXModal.Header>
+
+      <AXModal.Body>
+        <Form form={form} layout="vertical">
+          {/* 기본 정보 */}
+          <Divider orientation="left">기본 정보</Divider>
+          <Row gutter={16}>
+            <Col span={8}>
+              <FormItem name="bnefNm" label="혜택명" rules={[{ required: true }]}>
+                <Input />
+              </FormItem>
+            </Col>
+            <Col span={8}>
+              <FormItem name="dateRange" label="이벤트 기간" rules={[{ required: true }]}>
+                <DtPicker type={DtPickerType.DATE_TIME_RANGE} />
+              </FormItem>
+            </Col>
+          </Row>
+
+          {/* 할인 설정 */}
+          <Divider orientation="left">할인 설정</Divider>
+          <Row gutter={16}>
+            <Col span={6}>
+              <FormItem label="할인 타입">
+                <Select
+                  value={discountValues.bnefDscntStupTpcd}
+                  onChange={(value) => setDiscountValues(prev => ({ ...prev, bnefDscntStupTpcd: value }))}
+                  options={[
+                    { value: "10", label: "정률할인(%)" },
+                    { value: "20", label: "정액할인(원)" },
+                  ]}
+                />
+              </FormItem>
+            </Col>
+            <Col span={6}>
+              <FormItem label="할인 값">
+                <InputNumber
+                  style={{ width: "100%" }}
+                  value={discountValues.bnefDscntStupValue}
+                  onChange={(value) => setDiscountValues(prev => ({ ...prev, bnefDscntStupValue: value }))}
+                  min={0}
+                  addonAfter={discountValues.bnefDscntStupTpcd === "10" ? "%" : "원"}
+                />
+              </FormItem>
+            </Col>
+            <Col span={6}>
+              <FormItem label="절삭 단위">
+                <Select
+                  value={discountValues.amtTrncClcd}
+                  onChange={(value) => setDiscountValues(prev => ({ ...prev, amtTrncClcd: value }))}
+                  options={[
+                    { value: "10", label: "원단위" },
+                    { value: "20", label: "십원단위" },
+                    { value: "30", label: "백원단위" },
+                  ]}
+                />
+              </FormItem>
+            </Col>
+          </Row>
+
+          {/* 상품 목록 */}
+          <Divider orientation="left">적용 상품</Divider>
+          <Space style={{ marginBottom: 16 }}>
+            <Button onClick={handleSelectProduct}>상품 선택</Button>
+            <span>총 {prdList.length}개 상품</span>
+          </Space>
+
+          <Table
+            columns={productColumns}
+            dataSource={prdList}
+            rowKey="prdNo"
+            pagination={false}
+            size="small"
+            scroll={{ y: 300 }}
+          />
+        </Form>
+      </AXModal.Body>
+    </AXModal>
+  );
+}
+```
+
+### 5. 읽기 전용 상세보기 모달 (다이렉트 렌탈)
+
+```tsx
+import { AXModal } from "@core/components/AXModal";
+import { Loading } from "@core/components/common";
+import { useAntApp } from "@core/hooks";
+import { useModalStore } from "@axboot/stores";
+import { Button, Descriptions, Form, Input, Space } from "antd";
+import { useDidMountEffect, useI18n, useLink } from "hooks";
+import React, { useState } from "react";
+import { errorHandling } from "utils";
+import { RmsOrderDrt, RmsOrderDrtService, MemberService } from "services";
+import { useAppMenu } from "../../../../router";
+
+interface DtoItem extends RmsOrderDrt {}
+
+export function FormModal({ open, onOk, onCancel, afterClose, params }: Props) {
+  const { t } = useI18n();
+  const { messageApi } = useAntApp();
+  const [form] = Form.useForm();
+
+  const [saveSpinning, setSaveSpinning] = React.useState(false);
+  const [detailSpinning, setDetailSpinning] = useState(false);
+  const [memberTypeLabel, setMemberTypeLabel] = useState<string>("");
+  const { MENUS_LIST } = useAppMenu();
+  const { linkByMenu } = useLink();
+
+  // 저장 처리 (메모만 수정 가능)
+  const handleSave = React.useCallback(async () => {
+    setSaveSpinning(true);
+    try {
+      const formValues = await form.validateFields();
+
+      if (params.query?.ifSn) {
+        await RmsOrderDrtService.postRmsOrderDrtUpdatermsOrderDrtMemo({
+          ifSn: params.query.ifSn,
+          mngrMemoCtnts: formValues.mngrMemoCtnts || "",
+        });
+
+        messageApi.success(t("저장되었습니다."));
+        onOk({ save: true });
+      }
+    } catch (err: any) {
+      await errorHandling(err);
+    } finally {
+      setSaveSpinning(false);
+    }
+  }, [messageApi, t, form, params.query, onOk]);
+
+  // 상세 정보 로드
+  useDidMountEffect(() => {
+    (async () => {
+      if (params.query?.ifSn) {
+        setDetailSpinning(true);
+        try {
+          const result = await RmsOrderDrtService.postRmsOrderDrtDetailRmsOrderDrt({
+            ifSn: params.query.ifSn,
+          });
+          form.setFieldsValue(result.rs);
+
+          // 회원구분 조회
+          if (params.query?.usrNo) {
+            try {
+              const memberResult = await MemberService.postMemberDtlViewMember({
+                usrNo: params.query.usrNo,
+              });
+              if (memberResult.rs?.usrTpcd) {
+                const usrTpcdLabel = USR_TPCD?.options?.find(
+                  (code) => code.value === memberResult.rs.usrTpcd
+                )?.label || "";
+                const niasLabel = memberResult.rs.niasYn === "Y" ? "(통합회원)" : "";
+                setMemberTypeLabel(usrTpcdLabel + niasLabel);
+              }
+            } catch (err) {
+              setMemberTypeLabel("");
+            }
+          }
+        } catch (err) {
+          await errorHandling(err);
+        } finally {
+          setDetailSpinning(false);
+        }
+      }
+    })();
+  });
+
+  // 연관 메뉴로 이동
+  const handleLink = React.useCallback(
+    async (progId, no) => {
+      const menu = MENUS_LIST.find((m) => m.progId === progId);
+      if (!menu) return;
+      linkByMenu(menu, { USR_NO: no });
+    },
+    [MENUS_LIST, linkByMenu],
+  );
+
+  return (
+    <AXModal width={1400} {...{ open, onCancel, onOk: onOk as any, afterClose }}>
+      <AXModal.Header title={t("다이렉트렌탈 주문내역 상세")}>
+        <Space>
+          <Button type="primary" onClick={handleSave} loading={saveSpinning}>
+            {t("저장")}
+          </Button>
+          <Button onClick={onCancel}>{t("취소")}</Button>
+        </Space>
+      </AXModal.Header>
+
+      <AXModal.Body>
+        <Form form={form} layout="vertical">
+          {/* 신청정보 */}
+          <FormTitle>신청정보</FormTitle>
+          <Descriptions
+            bordered
+            column={3}
+            size="small"
+            style={{ width: "100%" }}
+            styles={{
+              label: { textAlign: "left", minWidth: 100, width: 140 },
+              content: { textAlign: "left" }
+            }}
+            items={[
+              { label: t("주문번호"), children: params.query?.ifId },
+              {
+                label: t("회원명"),
+                children: (
+                  <a onClick={() => handleLink("MEMBER_LIST", params.query?.usrNo)}>
+                    {params.query?.usrNm}
+                  </a>
+                )
+              },
+              { label: t("회원구분"), children: memberTypeLabel },
+              { label: t("신청일시"), children: dayjs(params.query?.appDtm).format("YYYY-MM-DD HH:mm:ss") },
+              { label: t("연락처"), children: params.query?.usrHpNo },
+              { label: t("이메일"), children: params.query?.usrEmailAddr },
+              // ... 더 많은 필드들
+            ]}
+          />
+
+          {/* 관리자 메모 (편집 가능) */}
+          <FormTitle style={{ marginTop: 24 }}>관리자 메모</FormTitle>
+          <FormItem name="mngrMemoCtnts">
+            <Input.TextArea rows={4} placeholder="관리자 메모를 입력하세요" />
+          </FormItem>
+        </Form>
+
+        <Loading active={detailSpinning} />
+      </AXModal.Body>
+    </AXModal>
+  );
+}
+
+const FormTitle = styled.div`
+  font-size: 16px;
+  font-weight: bold;
+  margin: 16px 0 8px 0;
+  padding: 8px 0;
+  border-bottom: 1px solid #d9d9d9;
+`;
+```
+
+## 주요 패턴
+
+### 1. 상태 관리
+
+```tsx
+// 로딩 상태
+const [saveSpinning, setSaveSpinning] = useState(false);
+const [deleteSpinning, setDeleteSpinning] = useState(false);
+const [detailSpinning, setDetailSpinning] = useState(false);
+
+// 폼 관리
+const [form] = Form.useForm();
+
+// 커스텀 상태
+const [duplCheck, setDuplCheck] = useState(false);
+const [activeTabType, setActiveTabType] = useState("기본");
+```
+
+### 2. 데이터 로딩
+
+```tsx
+useDidMountEffect(() => {
+  if (params.query?.id) {
+    // 수정 모드 - 상세 데이터 로드
+    (async () => {
+      try {
+        setDetailSpinning(true);
+        const result = await YourService.getDetail({ id: params.query.id });
+        form.setFieldsValue(result.data);
+      } catch (e) {
+        await errorHandling(e);
+      } finally {
+        setDetailSpinning(false);
+      }
+    })();
+  } else {
+    // 신규 모드 - 기본값 설정
+    form.setFieldsValue({ status: "Y", priority: 1 });
+  }
+});
+```
+
+### 3. 저장/삭제 처리
+
+```tsx
+const handleSave = React.useCallback(async () => {
+  try {
+    setSaveSpinning(true);
+    const values = await form.validateFields();
+
+    // 데이터 가공
+    const saveData = {
+      ...params.query, // 기존 데이터 (수정 시)
+      ...values,       // 폼 데이터
+      // 추가 처리 로직
+    };
+
+    await YourService.save(saveData);
+    messageApi.success(t("저장되었습니다."));
+    onOk({ save: true });
+  } catch (e) {
+    await errorHandling(e);
+  } finally {
+    setSaveSpinning(false);
+  }
+}, [form, params, onOk]);
+
+const handleDelete = React.useCallback(async () => {
+  try {
+    await confirmDialog({
+      content: t("정말 삭제하시겠습니까?"),
+    });
+
+    setDeleteSpinning(true);
+    await YourService.delete({ id: params.query.id });
+
+    messageApi.success(t("삭제되었습니다."));
+    onOk({ delete: true });
+  } catch (e) {
+    await errorHandling(e);
+  } finally {
+    setDeleteSpinning(false);
+  }
+}, [params.query?.id, onOk]);
+```
+
+### 4. 파일 업로드 통합
+
+```tsx
+// useUploadService 훅 사용
+const {
+  flUploadId,
+  files,
+  commitFiles,
+  setFiles,
+  uploadFile,
+  setDeleted,
+  handleDownload,
+  spinning: fileSpinning,
+} = useUploadService({
+  flUploadId: params.query?.fileUploadId
+});
+
+// 저장 시 파일 커밋
+const handleSave = React.useCallback(async () => {
+  try {
+    const values = await form.validateFields();
+
+    // 파일 검증
+    const savedFiles = files?.filter((item) => item.__status__ !== "D");
+    if (savedFiles?.length === 0) {
+      throw new Error(t("파일을 업로드해주세요."));
+    }
+
+    // 파일 커밋
+    await commitFiles();
+
+    // 데이터 저장
+    const saveData = {
+      ...values,
+      fileUploadId: flUploadId,
+      fileSeq: savedFiles[0]?.flSn || 1,
+    };
+
+    await YourService.save(saveData);
+    onOk({ save: true });
+  } catch (e) {
+    await errorHandling(e);
+  }
+}, [form, files, commitFiles, flUploadId, onOk]);
+```
+
+## 모달 호출 방법
+
+```tsx
+// 신규 등록
+const handleNew = async () => {
+  const result = await openFormModal({});
+  if (result?.save) {
+    await refreshList();
+  }
+};
+
+// 수정
+const handleEdit = async (item: DataType) => {
+  const result = await openFormModal({
+    query: item
+  });
+  if (result?.save || result?.delete) {
+    await refreshList();
+  }
+};
+
+// 복사 모드
+const handleCopy = async (item: DataType) => {
+  const result = await openFormModal({
+    query: { ...item, id: undefined },
+    copyMode: "true"
+  });
+  if (result?.save) {
+    await refreshList();
+  }
+};
+```
+
+## 주요 컴포넌트
+
+### Form 컴포넌트들
+- **Input**: 텍스트 입력
+- **InputNumber**: 숫자 입력
+- **Select**: 드롭다운 선택
+- **Radio.Group**: 라디오 버튼
+- **Switch**: 토글 스위치
+- **DtPicker**: 날짜/시간 선택
+- **ImgFileUploaderById**: 이미지 업로드
+- **MultiFileUploaderById**: 다중 파일 업로드
+- **SynapEditorMiniComponent**: 에디터
+
+### 레이아웃 컴포넌트들
+- **Row, Col**: 그리드 레이아웃
+- **Space**: 간격 조정
+- **Divider**: 구분선
+- **Tabs**: 탭 구조
+- **Descriptions**: 설명 목록
+- **Table**: 데이터 테이블
+
+## 모범 사례
+
+### 1. 일관된 인터페이스
+```tsx
+export interface ModalRequest {
+  query?: Record<string, any>;
+  copyMode?: boolean;
+}
+
+export interface ModalResponse {
+  save?: boolean;
+  delete?: boolean;
+}
+```
+
+### 2. 에러 처리
+```tsx
+try {
+  // 작업 수행
+} catch (e) {
+  await errorHandling(e); // 통합 에러 처리
+} finally {
+  setSpinning(false);
+}
+```
+
+### 3. 폼 검증
+```tsx
+// 기본 검증
+<FormItem name="name" rules={[{ required: true }]}>
+  <Input />
+</FormItem>
+
+// 커스텀 검증
+const handleSave = async () => {
+  await form.validateFields();
+
+  // 추가 검증 로직
+  if (!customValidation) {
+    throw new Error("커스텀 검증 실패");
+  }
+
+  // 저장 처리
+};
+```
+
+### 4. 로딩 상태
+```tsx
+<Button type="primary" onClick={handleSave} loading={saveSpinning}>
+  {t("btn.저장")}
+</Button>
+
+<Loading active={detailSpinning} />
+```
+
+## 주의사항
+
+1. **메모리 누수 방지**: `useDidMountEffect` 사용으로 마운트 시에만 실행
+2. **상태 초기화**: 모달이 닫힐 때 상태 정리
+3. **폼 검증**: 필수 필드와 커스텀 검증 로직 구현
+4. **에러 처리**: 통합된 `errorHandling` 함수 사용
+5. **로딩 상태**: 사용자 경험을 위한 적절한 로딩 표시
+6. **권한 체크**: `programFn`을 통한 기능별 권한 확인
+7. **다국어 지원**: `useI18n` 훅 활용
+
+이러한 패턴을 따라서 일관성 있고 유지보수하기 쉬운 FormModal을 구현할 수 있습니다.