@axboot-mcp/mcp-server 1.0.0

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

@@ -0,0 +1,903 @@
+# FormItem 사용법 가이드
+
+## 개요
+
+FormItem은 Ant Design의 Form.Item 컴포넌트를 TypeScript 제네릭과 함께 사용하는 패턴입니다. AXBoot 프로젝트에서는 타입 안전성을 위해 `const FormItem = Form.Item<DtoItem>;` 형태로 정의하여 사용합니다.
+
+## 기본 정의 패턴
+
+```typescript
+interface DtoItem extends SomeInterface {}
+const FormItem = Form.Item<DtoItem>;
+```
+
+## 사용 케이스별 정리
+
+### 1. 기본 입력 필드 (Basic Input Fields)
+
+#### 1.1 필수 입력 필드
+```tsx
+<FormItem
+  name={"itemName"}
+  label={t("항목명")}
+  rules={[{ required: true }]}
+>
+  <Input />
+</FormItem>
+```
+
+#### 1.2 최대 길이 제한
+```tsx
+<FormItem
+  name={"description"}
+  label={t("설명")}
+  rules={[
+    { required: true },
+    { max: 100, message: t("최대 100자까지 입력 가능합니다.") }
+  ]}
+>
+  <Input.TextArea rows={3} maxLength={100} />
+</FormItem>
+```
+
+#### 1.3 정규식 패턴 검증
+```tsx
+<FormItem
+  name={"email"}
+  label={t("이메일")}
+  rules={[
+    { required: true },
+    { type: 'email', message: t("올바른 이메일 형식을 입력하세요.") }
+  ]}
+>
+  <Input />
+</FormItem>
+```
+
+### 2. 선택 필드 (Selection Fields)
+
+#### 2.1 Select 드롭다운
+```tsx
+<FormItem
+  name={"categoryCode"}
+  label={t("카테고리")}
+  rules={[{ required: true }]}
+>
+  <Select
+    options={categoryOptions}
+    placeholder={t("카테고리를 선택하세요")}
+  />
+</FormItem>
+```
+
+#### 2.2 Radio Group
+```tsx
+<FormItem
+  name={"useYn"}
+  label={t("사용여부")}
+  rules={[{ required: true }]}
+>
+  <Radio.Group
+    options={[
+      { value: "Y", label: "Y" },
+      { value: "N", label: "N" }
+    ]}
+  />
+</FormItem>
+```
+
+#### 2.3 Checkbox (Switch)
+```tsx
+<FormItem
+  name={"displayYn"}
+  label={t("전시여부")}
+  valuePropName="checked"
+>
+  <Switch
+    checkedChildren="전시"
+    unCheckedChildren="미전시"
+  />
+</FormItem>
+```
+
+### 3. 숫자 입력 필드 (Number Fields)
+
+#### 3.1 기본 숫자 입력
+```tsx
+<FormItem
+  name={"quantity"}
+  label={t("수량")}
+  rules={[{ required: true }]}
+>
+  <InputNumber
+    min={1}
+    max={999}
+    style={{ width: "100%" }}
+  />
+</FormItem>
+```
+
+#### 3.2 단위가 있는 숫자 입력
+```tsx
+<FormItem
+  name={"exposureTime"}
+  label={t("노출시간")}
+  rules={[{ required: true }]}
+>
+  <InputNumber
+    min={1}
+    max={60}
+    addonAfter="초"
+    placeholder={t("노출할 초값을 입력하세요")}
+    style={{ width: "50%" }}
+  />
+</FormItem>
+```
+
+### 4. 날짜/시간 필드 (Date/Time Fields)
+
+#### 4.1 날짜 범위 선택
+```tsx
+<FormItem
+  name={"dateRange"}
+  label={t("기간")}
+  rules={[{ required: true }]}
+>
+  <DtPicker
+    type={DtPickerType.DATE_RANGE}
+    placeholder={[t("시작일"), t("종료일")]}
+  />
+</FormItem>
+```
+
+#### 4.2 단일 날짜 선택
+```tsx
+<FormItem
+  name={"targetDate"}
+  label={t("대상일자")}
+  rules={[{ required: true }]}
+>
+  <DtPicker
+    type={DtPickerType.DATE}
+  />
+</FormItem>
+```
+
+### 5. 파일 업로드 (File Upload)
+
+#### 5.1 이미지 파일 업로드
+```tsx
+<FormItem
+  label={t("이미지")}
+  required
+>
+  <div style={{ display: "flex", alignItems: "flex-start", gap: "16px" }}>
+    <div style={{ flex: "0 0 auto" }}>
+      <ImgFileUploaderById
+        value={files}
+        spinning={uploading}
+        onChange={setFiles}
+        handleUpload={uploadFile}
+        handleDelete={setDeleted}
+        handleDownload={handleDownload}
+        accept="image/png,image/svg+xml"
+      />
+    </div>
+    <div style={{ flex: "1 1 auto" }}>
+      <UploadGuideLine type="banner" />
+    </div>
+  </div>
+</FormItem>
+```
+
+### 6. 조건부 렌더링 (Conditional Rendering)
+
+#### 6.1 Form.useWatch를 활용한 조건부 필드
+```tsx
+const watchedValue = Form.useWatch("parentField", form);
+
+return (
+  <>
+    <FormItem name={"parentField"} label={t("부모필드")}>
+      <Select options={parentOptions} />
+    </FormItem>
+
+    {watchedValue === "specific_value" && (
+      <FormItem
+        name={"childField"}
+        label={t("자식필드")}
+        rules={[{ required: true }]}
+      >
+        <Input />
+      </FormItem>
+    )}
+  </>
+);
+```
+
+#### 6.2 조건부 필수 입력 검증
+```tsx
+<FormItem
+  name={"conditionalField"}
+  label={t("조건부 필드")}
+  rules={[{ required: watchedValue === "Y" }]}
+>
+  <Input />
+</FormItem>
+```
+
+### 7. 동적 폼 필드 (Dynamic Form Fields)
+
+#### 7.1 shouldUpdate를 사용한 동적 렌더링
+```tsx
+<FormItem
+  shouldUpdate={(prevValues, currentValues) =>
+    prevValues.triggerField !== currentValues.triggerField
+  }
+>
+  {({ getFieldValue }) => {
+    const triggerValue = getFieldValue("triggerField");
+    return triggerValue === "show" ? (
+      <FormItem name={"dynamicField"} label={t("동적필드")}>
+        <Input />
+      </FormItem>
+    ) : null;
+  }}
+</FormItem>
+```
+
+#### 7.2 배열 형태의 동적 필드
+```tsx
+<Form.List name="items">
+  {(fields, { add, remove }) => (
+    <>
+      {fields.map(({ key, name, ...restField }) => (
+        <Row key={key} gutter={16}>
+          <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)}
+            >
+              삭제
+            </Button>
+          </Col>
+        </Row>
+      ))}
+      <Button type="dashed" onClick={() => add()} block>
+        + 항목 추가
+      </Button>
+    </>
+  )}
+</Form.List>
+```
+
+### 8. 숨김 필드 (Hidden Fields)
+
+#### 8.1 noStyle 속성 사용
+```tsx
+<FormItem name={"hiddenId"} noStyle>
+  <Input type="hidden" />
+</FormItem>
+```
+
+#### 8.2 기본값이 있는 숨김 필드
+```tsx
+<FormItem
+  name={"defaultValue"}
+  noStyle
+  initialValue="default"
+>
+  <Input type="hidden" />
+</FormItem>
+```
+
+### 9. 복합 입력 필드 (Complex Input Fields)
+
+#### 9.1 여러 컴포넌트 조합
+```tsx
+<FormItem label={t("가격 범위")}>
+  <Input.Group compact>
+    <FormItem
+      name={"minPrice"}
+      noStyle
+      rules={[{ required: true }]}
+    >
+      <InputNumber
+        placeholder="최소가격"
+        style={{ width: '50%' }}
+      />
+    </FormItem>
+    <FormItem
+      name={"maxPrice"}
+      noStyle
+      rules={[{ required: true }]}
+    >
+      <InputNumber
+        placeholder="최대가격"
+        style={{ width: '50%' }}
+      />
+    </FormItem>
+  </Input.Group>
+</FormItem>
+```
+
+#### 9.2 주소 입력 필드
+```tsx
+<FormItem label={t("주소")}>
+  <Row gutter={8}>
+    <Col span={6}>
+      <FormItem name={"zipCode"} noStyle>
+        <Input placeholder="우편번호" />
+      </FormItem>
+    </Col>
+    <Col span={4}>
+      <Button onClick={openAddressModal}>
+        주소검색
+      </Button>
+    </Col>
+    <Col span={14}>
+      <FormItem name={"address"} noStyle>
+        <Input placeholder="상세주소" />
+      </FormItem>
+    </Col>
+  </Row>
+</FormItem>
+```
+
+### 10. 커스텀 검증 (Custom Validation)
+
+#### 10.1 비동기 검증
+```tsx
+<FormItem
+  name={"username"}
+  label={t("사용자명")}
+  rules={[
+    { required: true },
+    {
+      validator: async (_, value) => {
+        if (value) {
+          const exists = await checkUsernameExists(value);
+          if (exists) {
+            return Promise.reject(new Error('이미 존재하는 사용자명입니다.'));
+          }
+        }
+        return Promise.resolve();
+      }
+    }
+  ]}
+>
+  <Input />
+</FormItem>
+```
+
+#### 10.2 다른 필드와의 비교 검증
+```tsx
+<FormItem
+  name={"confirmPassword"}
+  label={t("비밀번호 확인")}
+  dependencies={['password']}
+  rules={[
+    { required: true },
+    ({ getFieldValue }) => ({
+      validator(_, value) {
+        if (!value || getFieldValue('password') === value) {
+          return Promise.resolve();
+        }
+        return Promise.reject(new Error('비밀번호가 일치하지 않습니다.'));
+      },
+    })
+  ]}
+>
+  <Input.Password />
+</FormItem>
+```
+
+## 고급 활용 패턴
+
+### 1. 레이아웃과 스타일링
+
+#### 1.1 반응형 레이아웃
+```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>
+```
+
+#### 1.2 인라인 폼 항목
+```tsx
+<FormItem label={t("기간 설정")}>
+  <Flex gap="small" align="center">
+    <FormItem name={"startDate"} noStyle>
+      <DatePicker />
+    </FormItem>
+    <span>~</span>
+    <FormItem name={"endDate"} noStyle>
+      <DatePicker />
+    </FormItem>
+  </Flex>
+</FormItem>
+```
+
+### 2. 접근성과 UX 향상
+
+#### 2.1 툴팁과 도움말
+```tsx
+<FormItem
+  name={"complexField"}
+  label={t("복잡한 필드")}
+  tooltip="이 필드는 특별한 규칙이 있습니다."
+  rules={[{ required: true }]}
+>
+  <Input placeholder="규칙에 맞게 입력하세요" />
+</FormItem>
+```
+
+#### 2.2 Extra 정보 제공
+```tsx
+<FormItem
+  name={"passwordField"}
+  label={t("비밀번호")}
+  extra="8자 이상, 영문/숫자/특수문자 포함"
+  rules={[
+    { required: true },
+    { min: 8, message: "8자 이상 입력하세요" }
+  ]}
+>
+  <Input.Password />
+</FormItem>
+```
+
+### 3. 성능 최적화
+
+#### 3.1 preserve 속성 사용
+```tsx
+<FormItem
+  name={"preservedField"}
+  label={t("보존 필드")}
+  preserve={false}  // 언마운트 시 값 제거
+>
+  <Input />
+</FormItem>
+```
+
+#### 3.2 dependencies 최적화
+```tsx
+<FormItem
+  name={"dependentField"}
+  label={t("의존 필드")}
+  dependencies={['triggerField']}  // 특정 필드 변경시만 리렌더링
+  rules={[
+    ({ getFieldValue }) => ({
+      validator(_, value) {
+        const trigger = getFieldValue('triggerField');
+        // 조건부 검증 로직
+        return Promise.resolve();
+      }
+    })
+  ]}
+>
+  <Input />
+</FormItem>
+```
+
+## 프로젝트 실제 폼 검증 로직 (Real-world Validation Patterns)
+
+프로젝트에서 실제 사용되는 다양한 폼 검증 패턴들을 케이스별로 정리했습니다.
+
+### 1. 기본 검증 규칙들
+
+#### 필수 입력 검증
+```tsx
+// 기본 필수 입력
+<FormItem name="itemName" label={t("항목명")} rules={[{ required: true }]}>
+  <Input />
+</FormItem>
+
+// 커스텀 메시지가 있는 필수 입력
+<FormItem
+  name="mngrMemoCtnts"
+  rules={[
+    {
+      required: true,
+      message: t("관리자 메모를 입력해주세요."),
+    }
+  ]}
+>
+  <Input.TextArea />
+</FormItem>
+```
+
+#### 길이 제한 검증 (order.subscription.direct-rental/FormModal.tsx)
+```tsx
+<FormItem
+  name="mngrMemoCtnts"
+  rules={[
+    {
+      required: true,
+      message: t("관리자 메모를 입력해주세요."),
+    },
+    {
+      max: 2000,
+      message: t("관리자 메모는 최대 2000자까지 입력 가능합니다."),
+    },
+  ]}
+>
+  <Input.TextArea rows={3} maxLength={2000} placeholder="관리자 메모를 입력하세요..." />
+</FormItem>
+```
+
+### 2. 비밀번호 검증 패턴
+
+#### 비밀번호 복잡도 검증 (ResetPwdModal.tsx)
+```tsx
+<FormItem
+  name="usrPw"
+  label={t("새비밀번호")}
+  rules={[
+    { required: true },
+    ({}) => ({
+      validator(_, value) {
+        const checkList = checkPasswordValidation(
+          value,
+          form.getFieldsValue().usrLoginId,
+          form.getFieldsValue().usrHpNo,
+        );
+        if (checkList.length === 0) {
+          return Promise.resolve();
+        }
+        return Promise.reject(new Error(checkList[0].message));
+      },
+    }),
+  ]}
+  hasFeedback
+>
+  <Input.Password placeholder="영문자, 숫자, 특수문자를 조합하여 8자리 이상을 입력해 주세요" />
+</FormItem>
+```
+
+#### 비밀번호 확인 검증 (ChangePasswordModal.tsx)
+```tsx
+<FormItem
+  name="usrPw2"
+  label={t("새비밀번호 확인")}
+  dependencies={["usrPw"]}
+  hasFeedback
+  rules={[
+    { required: true },
+    ({ getFieldValue }) => ({
+      validator(_, value) {
+        if (!value || getFieldValue("usrPw") === value) {
+          return Promise.resolve();
+        }
+        return Promise.reject(new Error("비밀번호가 일치하지 않습니다."));
+      },
+    }),
+  ]}
+>
+  <Input.Password placeholder="새비밀번호를 다시한번 입력해 주세요" />
+</FormItem>
+```
+
+### 3. 날짜/시간 검증 패턴
+
+#### 날짜 범위 검증 (benefit.live-deal/FormModal.tsx)
+```tsx
+<FormItem
+  name="dateRange"
+  style={{ margin: 0 }}
+  rules={[
+    { required: true, message: "나비엔라이브 기간을 설정해주세요." },
+    ({ getFieldValue: _ }) => ({
+      validator(__, value) {
+        if (value && value[0] && value[1]) {
+          const startDate = dayjs(value[0]);
+          const endDate = dayjs(value[1]);
+          const now = dayjs();
+
+          // 신규 등록 시 과거 날짜 체크
+          if (startDate.isBefore(now, "minute") && !params.query?.bnefNo) {
+            return Promise.reject(new Error("시작일시는 현재 시간 이후로 설정해주세요."));
+          }
+
+          // 종료일이 시작일보다 늦어야 함
+          if (endDate.isBefore(startDate) || endDate.isSame(startDate)) {
+            return Promise.reject(new Error("종료일시는 시작일시보다 늦어야 합니다."));
+          }
+        }
+        return Promise.resolve();
+      },
+    }),
+  ]}
+>
+  <DtPicker type={DtPickerType.DATE_RANGE} isTimeSelector allowClear />
+</FormItem>
+```
+
+### 4. 조건부 검증 패턴
+
+#### 다른 필드 값에 따른 조건부 검증 (benefit.live-deal/FormModal.tsx)
+```tsx
+<FormItem
+  name="sleLmttStupYn"
+  rules={[
+    { required: true },
+    {
+      validator: () => {
+        // 제품이 선택되지 않은 경우 검증 실패
+        if (products.length === 0) {
+          return Promise.reject(new Error(t("제품을 선택해주세요.")));
+        }
+        return Promise.resolve();
+      },
+    },
+  ]}
+  style={{ margin: 0 }}
+>
+  <Radio.Group
+    options={[
+      { label: "미사용", value: "N" },
+      { label: "사용", value: "Y" },
+    ]}
+  />
+</FormItem>
+```
+
+#### Watch를 활용한 조건부 필수 검증
+```tsx
+const watchedValue = Form.useWatch("parentField", form);
+
+<FormItem
+  name="childField"
+  label={t("자식 필드")}
+  rules={[{ required: watchedValue === "Y" }]}
+>
+  <Input />
+</FormItem>
+```
+
+### 5. 복합 검증 패턴
+
+#### 배열/리스트 검증
+```tsx
+<FormItem
+  name="itemList"
+  rules={[
+    {
+      validator: (_, value) => {
+        if (!value || value.length === 0) {
+          return Promise.reject(new Error(t("최소 1개 이상 선택해주세요.")));
+        }
+        if (value.length > 10) {
+          return Promise.reject(new Error(t("최대 10개까지 선택 가능합니다.")));
+        }
+        return Promise.resolve();
+      },
+    },
+  ]}
+>
+  <Select mode="multiple" options={options} />
+</FormItem>
+```
+
+#### 숫자 범위 검증
+```tsx
+<FormItem
+  name="quantity"
+  label={t("수량")}
+  rules={[
+    { required: true },
+    {
+      type: "number",
+      min: 1,
+      max: 999,
+      message: t("1~999 사이의 숫자를 입력해주세요."),
+    },
+  ]}
+>
+  <InputNumber style={{ width: "100%" }} />
+</FormItem>
+```
+
+### 6. 실시간 검증과 피드백
+
+#### hasFeedback 속성 활용
+```tsx
+<FormItem
+  name="email"
+  label={t("이메일")}
+  rules={[
+    { required: true },
+    { type: "email", message: t("올바른 이메일 형식을 입력하세요.") },
+  ]}
+  hasFeedback  // 실시간 검증 결과 표시
+>
+  <Input />
+</FormItem>
+```
+
+#### 정규식 패턴 검증 (주석 처리된 예시)
+```tsx
+<FormItem
+  name="password"
+  rules={[
+    { required: true },
+    // 정규식 패턴 예시 (실제 프로젝트에서는 커스텀 validator 사용)
+    // {
+    //   pattern: /^(?=.*[a-zA-Z])(?=.*[0-9])(?=.*[!@#$%^&*()_+|~\-={}[\]:";'<>?,./\\]).{8,16}$/,
+    //   message: "8~16자 영문+숫자+특수문자를 조합하여 사용하세요.",
+    // },
+  ]}
+>
+  <Input.Password />
+</FormItem>
+```
+
+### 7. 에러 처리 및 사용자 경험
+
+#### 검증 실패 시 첫 번째 필드로 스크롤
+```tsx
+<Form
+  form={form}
+  layout="vertical"
+  onFinish={handleSubmit}
+  scrollToFirstError  // 검증 실패 시 첫 번째 오류 필드로 스크롤
+>
+  {/* FormItem들 */}
+</Form>
+```
+
+#### 동적 검증 메시지
+```tsx
+<FormItem
+  name="customField"
+  rules={[
+    {
+      validator: (_, value) => {
+        if (!value) {
+          return Promise.reject(new Error(t("필수 입력 항목입니다.")));
+        }
+        if (value.length < 3) {
+          return Promise.reject(new Error(t("최소 3자 이상 입력해주세요.")));
+        }
+        if (!/^[a-zA-Z0-9]+$/.test(value)) {
+          return Promise.reject(new Error(t("영문과 숫자만 입력 가능합니다.")));
+        }
+        return Promise.resolve();
+      },
+    },
+  ]}
+>
+  <Input />
+</FormItem>
+```
+
+### 8. 검증 유틸리티 활용
+
+프로젝트에서는 공통 검증 함수들을 활용합니다:
+
+```tsx
+import { checkPasswordValidation } from "utils/validation";
+
+// 비밀번호 검증 함수 활용
+<FormItem
+  name="password"
+  rules={[
+    { required: true },
+    ({}) => ({
+      validator(_, value) {
+        const checkList = checkPasswordValidation(value);
+        if (checkList.length === 0) {
+          return Promise.resolve();
+        }
+        return Promise.reject(new Error(checkList[0].message));
+      },
+    }),
+  ]}
+>
+  <Input.Password />
+</FormItem>
+```
+
+### 9. 종합 검증 예시
+
+실제 프로젝트에서 사용되는 복합적인 검증 패턴:
+
+```tsx
+<FormItem
+  name="complexField"
+  label={t("복합 검증 필드")}
+  dependencies={["relatedField"]}
+  rules={[
+    { required: true, message: t("필수 입력 항목입니다.") },
+    { max: 100, message: t("최대 100자까지 입력 가능합니다.") },
+    ({ getFieldValue }) => ({
+      validator: async (_, value) => {
+        // 관련 필드 값 확인
+        const relatedValue = getFieldValue("relatedField");
+
+        // 조건부 검증
+        if (relatedValue === "special" && value.length < 10) {
+          return Promise.reject(new Error(t("특수 모드에서는 10자 이상 입력해야 합니다.")));
+        }
+
+        // 비동기 검증 (서버 확인)
+        if (value) {
+          try {
+            const isValid = await validateFieldOnServer(value);
+            if (!isValid) {
+              return Promise.reject(new Error(t("서버 검증에 실패했습니다.")));
+            }
+          } catch (error) {
+            return Promise.reject(new Error(t("검증 중 오류가 발생했습니다.")));
+          }
+        }
+
+        return Promise.resolve();
+      },
+    }),
+  ]}
+  hasFeedback
+>
+  <Input />
+</FormItem>
+```
+
+## 모범 사례 (Best Practices)
+
+### 1. 타입 안전성 확보
+- 항상 `const FormItem = Form.Item<DtoItem>` 패턴 사용
+- 인터페이스 확장을 통한 타입 정의
+
+### 2. 검증 규칙 일관성
+- 공통 검증 규칙을 상수로 정의
+- 메시지는 i18n을 통한 다국어 지원
+- 프로젝트의 `checkPasswordValidation` 같은 공통 유틸리티 활용
+
+### 3. 성능 고려사항
+- shouldUpdate 사용 시 필요한 경우에만 적용
+- dependencies를 정확히 명시하여 불필요한 리렌더링 방지
+
+### 4. 접근성 향상
+- label, placeholder 적절히 활용
+- 필수 필드 명시적 표현
+- 에러 메시지 명확하게 제공
+- `hasFeedback` 속성으로 실시간 피드백 제공
+
+### 5. 검증 패턴별 활용 가이드
+- **기본 검증**: required, max, min, type 등 기본 규칙 활용
+- **비밀번호**: dependencies와 getFieldValue를 활용한 확인 필드 구현
+- **날짜**: dayjs를 활용한 시간 비교 로직
+- **조건부**: 다른 상태나 필드에 따른 동적 검증
+- **복합**: 여러 조건을 조합한 복잡한 검증 로직
+
+### 6. 코드 재사용성
+- 공통 FormItem 패턴을 컴포넌트화
+- 비슷한 검증 로직의 경우 훅으로 분리
+- 검증 유틸리티 함수 활용
+
+이러한 검증 패턴들을 조합하여 사용자에게 명확한 피드백을 제공하고, 데이터 무결성을 보장할 수 있습니다.