Commit @94ca85ee6dd51f97b2bc47ae27f2066b196fa1ed

임동욱 09-18

feat: 가맹몰 등록·수정을 열고 가맹몰 상세에서 업체 항목을 직접 입력하게 한다

가맹몰 관리 — [등록] 버튼과 수정 모달을 활성화해 백엔드 VO(MngrVocInsertReqVo/UpdateReqVo)
대로 JSON으로 보낸다. 예금주·입금은행(COM_BANK_CD)·계좌·업태(FRCS_BZSTAT_CD)·구분(FRCS_DV_CD)
항목을 더하고 주소·우편번호도 직접 고칠 수 있다. 백엔드는 아직 BizPlay(웹캐시) 위임이고
우리 DB 저장으로 바뀔 예정(사용자 공지)이라 응답의 가맹점 코드는 어느 모양이든 읽고, 없으면
목록에서 이름·연락처로 찾는다.

가맹몰 상세 — 업체명·연락처·우편번호([주소 검색])·주소·상세주소를 읽기 전용에서 입력으로
바꾼다(사용자 확정). 저장하면 가맹점을 만들거나(코드 없음) 바뀐 값만 고친(코드 있음) 뒤 상세를
붙인다. 가맹점 선택 화면은 빈 등록 폼으로 바뀐다. 우편번호 검색 도우미는 두 화면이 쓰므로
app/_components/postcode.ts로 옮긴다.

Co-Authored-By: Claude Fable 5.1

@94ca85ee6dd51f97b2bc47ae27f2066b196fa1ed

a565313

94ca85e

app/(protected)/(basic)/system/merchant-details/[frcsNo]/_components/merchant-detail-form.module.scss

--- app/(protected)/(basic)/system/merchant-details/[frcsNo]/_components/merchant-detail-form.module.scss

+++ app/(protected)/(basic)/system/merchant-details/[frcsNo]/_components/merchant-detail-form.module.scss

...	...	@@ -48,3 +48,9 @@
48	48	flex-direction: column;
49	49	gap: fox.gap(2);
50	50	}
	51	+
	52	+// 기획 BO-MAL-002의 [주소 검색] — 라벨 줄 없이 입력칸 아래선에 맞춰 선다.
	53	+.searchButton {
	54	+ display: flex;
	55	+ align-self: flex-end;
	56	+}

a565313

94ca85e

app/(protected)/(basic)/system/merchant-details/[frcsNo]/_components/merchant-detail-form.tsx

--- app/(protected)/(basic)/system/merchant-details/[frcsNo]/_components/merchant-detail-form.tsx

+++ app/(protected)/(basic)/system/merchant-details/[frcsNo]/_components/merchant-detail-form.tsx


 'use client';
 
 import { useRouter } from 'next/navigation';
-import { useActionState, useEffect, useState } from 'react';
+import { useActionState, useEffect, useState, useTransition } from 'react';
 import { FoxButton } from '@fox/core/components/fox-button';
 import { FoxButtonGroup } from '@fox/core/components/fox-button-group';
 import { FoxButtonPanel } from '@fox/core/components/fox-button-panel';

 import { FoxInput } from '@fox/core/components/fox-input';
 import { FoxPageHeader } from '@fox/core/components/fox-page-header';
 import { FoxSelect } from '@fox/core/components/fox-select';
+import { openPostcodeSearch } from '@/app/_components/postcode';
 import { submitFormAction } from '@/app/_hooks/submit-form-action';
 import { useBlockingAction } from '@/app/_hooks/use-blocking-action';
 import { useFeedback } from '@/app/_hooks/use-feedback';

   type MerchantDetailSummary,
 } from '@/lib/domain/merchant-detail';
 import {
+  ADDRESS_MAX_LENGTH,
   CLOSED_DAYS_MAX_LENGTH,
   DESCRIPTION_MAX_LENGTH,
   INITIAL_MERCHANT_DETAIL_FORM_STATE,
+  MERCHANT_NAME_MAX_LENGTH,
   SORT_ORDER_MAX,
 } from '@/lib/domain/merchant-detail-form';
 import { MERCHANT_DETAILS_PATH, merchantDetailPath } from '@/lib/domain/merchant-detail-query';
 import type { MerchantProduct } from '@/lib/domain/merchant-product';
-import { formatPhoneNumber } from '@/lib/domain/phone-number';
 import {
   deleteMerchantDetailAction,
   saveMerchantDetailAction,

 interface MerchantDetailFormProps {
   /** 상세가 있는 가맹점 — 고친다. */
   detail?: MerchantDetail;
-  /** 상세가 아직 없는데 가맹점은 정해진 경우(행의 [수정]) — 그 가맹점에 처음 만든다. */
+  /** 상세가 아직 없는데 가맹점은 있는 경우(행의 [수정]) — 그 가맹점에 처음 만든다. */
   merchant?: MerchantDetailSummary;
-  /** 가맹점도 정해지지 않은 경우([+ 업체 등록]) — 업체명 자리에서 하나를 고른다. */
-  candidates?: MerchantDetailSummary[];
   products?: MerchantProduct[];
   categories: CommonCode[];
   /** 메뉴 표의 배지 코드표(`FRCS_BADGE_CD`). */

 
 /**
  * 가맹몰 상세 — 기획 BO-MAL-002(등록)·003(수정)을 한 화면으로 합쳤다(사용자 확정). `detail`이 있으면
- * 고치고, `merchant`면 그 가맹점에 처음 만들고, 둘 다 없으면 업체명 자리에서 가맹점을 골라 만든다.
+ * 고치고, `merchant`면 그 가맹점에 처음 만들고, 둘 다 없으면 업체(가맹점)부터 새로 만든다.
  * 첫 저장 뒤에는 그 가맹점 주소로 옮겨 가되 화면 구성은 그대로라 바로 메뉴를 붙일 수 있고, 이후
  * 저장은 그 자리에 머문다.
  *
- * 업체명·연락처·우편번호·주소는 가맹점 원본이라 읽기 전용이다. 기획의 [주소 검색]은 가맹몰 관리
- * 화면의 것이라 여기서는 값을 바꾸지 않는다.
+ * 업체명·연락처·우편번호·주소는 여기서 직접 입력한다(사용자 확정) — 저장하면 액션이 가맹점을
+ * 만들거나(코드 없음) 바뀐 값을 고친(코드 있음) 뒤 상세를 붙인다. 바뀌었는지는 숨은 원본 값과 비교한다.
  */
 export function MerchantDetailForm({
   detail,
   merchant: fixedMerchant,
-  candidates = [],
   products = [],
   categories,
   badgeCodes = [],

   const isEdit = detail !== undefined;
   const errors = state.status === 'error' ? (state.errors ?? {}) : {};
 
-  // 가맹점이 정해져 있으면(상세가 있든 없든) 업체명은 읽기 전용이고, 아니면 여기서 고른다.
-  const pinned: MerchantDetailSummary | null = detail ?? fixedMerchant ?? null;
-  const [frcsNo, setFrcsNo] = useState(pinned?.id ?? '');
-  const merchant: MerchantDetailSummary | null =
-    pinned ?? candidates.find((row) => row.id === frcsNo) ?? null;
+  // 가맹점이 있으면(상세가 있든 없든) 그 코드로 고치고, 없으면 빈 코드로 보내 새로 만든다.
+  const merchant: MerchantDetailSummary | null = detail ?? fixedMerchant ?? null;
+  const frcsNo = merchant?.id ?? '';
+  const original = {
+    name: merchant?.name ?? '',
+    phoneNumber: merchant?.phoneNumber ?? '',
+    postalCode: merchant?.postalCode ?? '',
+    address: merchant?.address ?? '',
+    addressDetail: merchant?.addressDetail ?? '',
+  };
+  // 우편번호·주소는 검색으로 채우거나 직접 고친다.
+  const [postalCode, setPostalCode] = useState(original.postalCode);
+  const [address, setAddress] = useState(original.address);
+  const [isSearching, startSearching] = useTransition();
   const [categoryCode, setCategoryCode] = useState(detail?.categoryCode ?? '');
   const [visibility, setVisibility] = useState<string[]>([
     detail?.isVisible === false ? 'N' : 'Y',

       router.refresh();
     }
   }, [state, router, showToast]);
+
+  /** 기획 BO-MAL-002 [주소 검색] — 고른 주소로 우편번호·주소를 채운다. */
+  function searchAddress() {
+    startSearching(async () => {
+      let picked;
+      try {
+        picked = await openPostcodeSearch();
+      } catch {
+        showToast({ variant: 'danger', message: '주소 검색을 불러오지 못했습니다. 잠시 후 다시 시도해 주세요.' });
+        return;
+      }
+      if (!picked) return;
+      setPostalCode(picked.zonecode);
+      setAddress(picked.address);
+    });
+  }
 
   function toggleVisibility() {
     if (!detail) return;

       >
         <input type="hidden" name="frcsNo" value={frcsNo} />
         <input type="hidden" name="mode" value={isEdit ? 'edit' : 'create'} />
+        {/* 저장 시 업체 값이 바뀌었는지 비교할 원본 — 안 바뀌었으면 가맹점 수정 요청을 보내지 않는다. */}
+        <input type="hidden" name="originalname" value={original.name} />
+        <input type="hidden" name="originalphoneNumber" value={original.phoneNumber} />
+        <input type="hidden" name="originalpostalCode" value={original.postalCode} />
+        <input type="hidden" name="originaladdress" value={original.address} />
+        <input type="hidden" name="originaladdressDetail" value={original.addressDetail} />
 
         <FoxCard size="lg" title="기본 정보" className={styles.section}>
           <div className={styles.grid}>
             <div className={styles.fieldWide}>
-              {pinned ? (
-                <FoxInput size="md" label="업체명" requirement="required" value={pinned.name} readOnly state="view" />
-              ) : (
-                <>
-                  <FoxSelect
-                    size="md"
-                    label="업체명"
-                    requirement="required"
-                    placeholder="상세를 등록할 가맹점 선택"
-                    options={candidates.map((row) => ({ value: row.id, label: row.name }))}
-                    value={frcsNo}
-                    onValueChange={setFrcsNo}
-                    error={Boolean(errors.frcsNo)}
-                  />
-                  {errors.frcsNo && <FoxHelperText type="danger" message={errors.frcsNo} />}
-                  {candidates.length === 0 && (
-                    <FoxHelperText
-                      type="information"
-                      message="상세를 붙일 가맹점이 없습니다. 모든 가맹점에 상세가 등록돼 있습니다."
-                    />
-                  )}
-                </>
-              )}
+              <FoxInput
+                size="md"
+                name="name"
+                label="업체명"
+                requirement="required"
+                placeholder="예) 타볼라타"
+                defaultValue={original.name}
+                maxLength={MERCHANT_NAME_MAX_LENGTH}
+                invalid={Boolean(errors.name)}
+                message={errors.name}
+              />
             </div>
             <div className={styles.field}>
               <FoxSelect

             <div className={styles.field}>
               <FoxInput
                 size="md"
+                name="phoneNumber"
                 label="업체 연락처"
                 requirement="required"
-                value={formatOptionalValue(formatPhoneNumber(merchant?.phoneNumber ?? null))}
-                readOnly
-                state="view"
+                placeholder="0507-1413-6625"
+                defaultValue={original.phoneNumber}
+                invalid={Boolean(errors.phoneNumber)}
+                message={errors.phoneNumber}
               />
             </div>
           </div>
 
           <div className={styles.grid}>
             <div className={styles.fieldNarrow}>
-              <FoxInput size="md" label="우편번호" requirement="required" value={formatOptionalValue(merchant?.postalCode)} readOnly state="view" />
+              <FoxInput
+                size="md"
+                name="postalCode"
+                label="우편번호"
+                requirement="required"
+                placeholder="00000"
+                value={postalCode}
+                onChange={setPostalCode}
+                invalid={Boolean(errors.postalCode)}
+                message={errors.postalCode}
+              />
+            </div>
+            <div className={styles.searchButton}>
+              <FoxButton
+                type="default"
+                size="md"
+                label={isSearching ? '검색 중...' : '주소 검색'}
+                disabled={isSearching}
+                onAction={searchAddress}
+              />
             </div>
             <div className={styles.fieldWide}>
-              <FoxInput size="md" label="주소" value={formatOptionalValue(merchant?.address)} readOnly state="view" />
+              <FoxInput
+                size="md"
+                name="address"
+                label="주소"
+                placeholder="도로명 주소 (검색 결과 자동 입력)"
+                value={address}
+                onChange={setAddress}
+                maxLength={ADDRESS_MAX_LENGTH}
+                invalid={Boolean(errors.address)}
+                message={errors.address}
+              />
             </div>
             <div className={styles.field}>
-              <FoxInput size="md" label="상세주소" value={formatOptionalValue(merchant?.addressDetail)} readOnly state="view" />
+              <FoxInput
+                size="md"
+                name="addressDetail"
+                label="상세주소"
+                placeholder="건물명 · 층 · 호"
+                defaultValue={original.addressDetail}
+                maxLength={ADDRESS_MAX_LENGTH}
+              />
             </div>
           </div>
 

a565313

94ca85e

app/(protected)/(basic)/system/merchant-details/_actions.ts

--- app/(protected)/(basic)/system/merchant-details/_actions.ts

+++ app/(protected)/(basic)/system/merchant-details/_actions.ts


   createMerchantDetail,
   deleteMerchantDetail,
   fetchMerchantDetail,
+  findMerchantByName,
   updateMerchantDetail,
 } from '@/lib/data/repositories/merchant-detail-repository';
+import { createMerchant, updateMerchant } from '@/lib/data/repositories/merchant-repository';
 import {
   createMerchantProduct,
   deleteMerchantProduct,

 import {
   validateMerchantDetail,
   type MerchantDetailFormState,
+  type MerchantDetailMerchantValues,
   type MerchantDetailValues,
 } from '@/lib/domain/merchant-detail-form';
+import { DEFAULT_MERCHANT_DIVISION_CODE } from '@/lib/domain/merchant';
+import type { MerchantValues } from '@/lib/domain/merchant-form';
 import {
   MERCHANT_DETAILS_PATH,
   merchantDetailPath,

 // 백엔드가 삭제된 상세도 "있는 것"으로 보는 결함(보고함) — 409는 대개 이 경우다.
 const DETAIL_CONFLICT_MESSAGE =
   '이 가맹점에는 이미 상세가 있습니다. 삭제했던 상세라면 백엔드에서 정리해야 다시 등록할 수 있습니다.';
+const MERCHANT_NOT_FOUND_AFTER_CREATE_MESSAGE =
+  '업체는 등록됐지만 코드를 받지 못해 상세를 붙이지 못했습니다. 목록에 업체가 나타나면 [수정]으로 상세를 등록해 주세요.';
 const IMAGE_OVERSIZE_MESSAGE = `이미지는 장당 ${Math.floor(MAX_IMAGE_BYTES / (1024 * 1024))}MB까지 올릴 수 있습니다.`;
 const IMAGES_TOO_MANY_MESSAGE = `추가 이미지는 최대 ${MAX_EXTRA_IMAGES}장까지입니다.`;
 const REQUEST_OVERSIZE_MESSAGE = `한 번에 올리는 이미지의 합이 ${Math.floor(MAX_ATTACHMENT_BYTES / (1024 * 1024))}MB를 넘습니다. 나눠서 저장해 주세요.`;

   return uploadAttachments(bundle, FILE_MODULE.merchantImage.id);
 }
 
+function readMerchantValues(formData: FormData, prefix = ''): MerchantDetailMerchantValues {
+  return {
+    name: readString(formData, `${prefix}name`),
+    phoneNumber: readString(formData, `${prefix}phoneNumber`),
+    postalCode: readString(formData, `${prefix}postalCode`),
+    address: readString(formData, `${prefix}address`),
+    addressDetail: readString(formData, `${prefix}addressDetail`),
+  };
+}
+
+function isSameMerchant(a: MerchantDetailMerchantValues, b: MerchantDetailMerchantValues): boolean {
+  return (
+    a.name.trim() === b.name.trim() &&
+    a.phoneNumber.trim() === b.phoneNumber.trim() &&
+    a.postalCode.trim() === b.postalCode.trim() &&
+    a.address.trim() === b.address.trim() &&
+    a.addressDetail.trim() === b.addressDetail.trim()
+  );
+}
+
+/** 상세 화면이 받는 업체 항목을 가맹점 등록·수정 요청 값으로 — 나머지는 이 화면에 없어 비운다. */
+function toMerchantValues(frcsNo: string, values: MerchantDetailMerchantValues): MerchantValues {
+  return {
+    id: frcsNo,
+    brandName: '',
+    memo: '',
+    name: values.name,
+    categoryCode: '',
+    businessNumber: '',
+    ownerName: '',
+    phoneNumber: values.phoneNumber,
+    address: values.address,
+    addressDetail: values.addressDetail,
+    postalCode: values.postalCode,
+    latitude: '',
+    longitude: '',
+    bankHolderName: '',
+    bankCode: '',
+    accountNumber: '',
+    businessStatusCode: '',
+    divisionCode: DEFAULT_MERCHANT_DIVISION_CODE,
+    isVisible: true,
+  };
+}
+
+/**
+ * 업체(가맹점)를 만들거나 고치고 코드를 돌려준다.
+ * - 코드가 없으면 새로 만든다 — 응답에 코드가 없으면(BizPlay 위임 응답) 목록에서 이름으로 찾는다.
+ * - 코드가 있으면 값이 바뀌었을 때만 고친다 — BizPlay 위임 상태에선 불필요한 외부 호출을 피한다.
+ */
+async function saveMerchant(
+  frcsNo: string,
+  values: MerchantDetailMerchantValues,
+  original: MerchantDetailMerchantValues
+): Promise<string> {
+  if (frcsNo) {
+    if (!isSameMerchant(values, original)) {
+      await updateMerchant(frcsNo, toMerchantValues(frcsNo, values));
+    }
+    return frcsNo;
+  }
+  const created = await createMerchant(toMerchantValues('', values));
+  if (created) return created;
+  const found = await findMerchantByName(values.name, values.phoneNumber);
+  if (!found) {
+    throw new InputError(MERCHANT_NOT_FOUND_AFTER_CREATE_MESSAGE);
+  }
+  return found.id;
+}
+
 function readDetailValues(
   formData: FormData,
   thumbnailFileId: string,
   imageFileId: string
 ): MerchantDetailValues {
   return {
+    ...readMerchantValues(formData),
     frcsNo: readString(formData, 'frcsNo'),
     categoryCode: readString(formData, 'categoryCode'),
     description: readString(formData, 'description'),

 ): Promise<MerchantDetailFormState> {
   await verifySession();
 
-  const frcsNo = readString(formData, 'frcsNo');
   const isEdit = readString(formData, 'mode') === 'edit';
-  if (!frcsNo) {
-    return { status: 'error', errors: { frcsNo: '업체를 선택해 주세요.' } };
-  }
+  let frcsNo = readString(formData, 'frcsNo');
 
   let failed: MerchantDetailFormState | null = null;
   try {

       return { status: 'error', errors: validation.errors };
     }
 
+    // 업체 먼저(만들거나 고치고), 그 코드로 상세를 붙인다.
+    frcsNo = await saveMerchant(frcsNo, validation.values, readMerchantValues(formData, 'original'));
+    const values = { ...validation.values, frcsNo };
     if (isEdit) {
-      await updateMerchantDetail(validation.values);
+      await updateMerchantDetail(values);
     } else {
-      await createMerchantDetail(validation.values);
+      await createMerchantDetail(values);
     }
   } catch (error) {
     unstable_rethrow(error);

   }
   await updateMerchantDetail({
     frcsNo,
+    name: detail.name,
+    phoneNumber: detail.phoneNumber ?? '',
+    postalCode: detail.postalCode ?? '',
+    address: detail.address ?? '',
+    addressDetail: detail.addressDetail ?? '',
     categoryCode: detail.categoryCode,
     description: detail.description ?? '',
     openTime: detail.openTime ?? '',

a565313

94ca85e

app/(protected)/(basic)/system/merchant-details/new/page.tsx

--- app/(protected)/(basic)/system/merchant-details/new/page.tsx

+++ app/(protected)/(basic)/system/merchant-details/new/page.tsx


 import type { Metadata } from 'next';
 import { verifySession } from '@/lib/auth/dal';
 import { fetchCommonCodes } from '@/lib/data/repositories/common-code-repository';
-import { fetchMerchantDetailCandidates } from '@/lib/data/repositories/merchant-detail-repository';
 import { CODE_GROUP } from '@/lib/domain/common-code';
 import { MerchantDetailForm } from '../[frcsNo]/_components/merchant-detail-form';
 
 export const metadata: Metadata = { title: '가맹몰 상세 정보' };
 export const dynamic = 'force-dynamic';
 
-/** 등록 진입 — 아직 상세가 없는 가맹점 중 하나를 골라 상세를 붙인다. */
+/** 등록 진입 — 업체(가맹점)와 상세를 함께 새로 만든다. */
 export default async function Page() {
   await verifySession();
 
-  const [candidates, categories] = await Promise.all([
-    fetchMerchantDetailCandidates(),
-    fetchCommonCodes(CODE_GROUP.merchantType),
-  ]);
-
-  return <MerchantDetailForm candidates={candidates} categories={categories} />;
+  const categories = await fetchCommonCodes(CODE_GROUP.merchantType);
+  return <MerchantDetailForm categories={categories} />;
 }

a565313

94ca85e

app/(protected)/(basic)/system/merchants/_actions.ts

--- app/(protected)/(basic)/system/merchants/_actions.ts

+++ app/(protected)/(basic)/system/merchants/_actions.ts


 'use server';
 
+import { revalidatePath } from 'next/cache';
+import { unstable_rethrow } from 'next/navigation';
 import { verifySession } from '@/lib/auth/dal';
-import {
-  validateMerchant,
-  type MerchantFormState,
-} from '@/lib/domain/merchant-form';
+import { BackendRequestError } from '@/lib/http/backend-fetch';
+import { createMerchant, updateMerchant } from '@/lib/data/repositories/merchant-repository';
+import { validateMerchant, type MerchantFormState } from '@/lib/domain/merchant-form';
+import { MERCHANTS_PATH } from '@/lib/domain/merchant-query';
 
-/**
- * TODO(백엔드): 등록이 자체 저장에서 BizPlay 외부 가맹점 등록 API 위임으로 바뀌었다 —
- *   `POST /api/v1/mngr/voc`가 @RequestBody(JSON)가 되고 `bizPlayVocApiService.insertVoc`를
- *   부른다. 예금주명·입금은행코드·입금계좌번호·업태코드가 새로 필수인데 이 폼은 받지 않는다.
- *   항목이 정해질 때까지 등록을 막는다.
- *
- *   화면의 [등록] 버튼만 비활성화하면 막은 것이 아니다 — Server Action은 UI를 거치지 않고도
- *   직접 호출된다. 그래서 저장 직전에서 끊는다.
- */
-const DISABLED_MESSAGE =
-  '가맹점 등록은 현재 사용할 수 없습니다. 등록 항목이 확정되면 다시 열립니다.';
+const SAVE_FAILED_MESSAGE = '저장하지 못했습니다. 잠시 후 다시 시도해 주세요.';
 
 function readString(formData: FormData, key: string): string {
   const value = formData.get(key);

     postalCode: readString(formData, 'postalCode'),
     latitude: readString(formData, 'latitude'),
     longitude: readString(formData, 'longitude'),
+    bankHolderName: readString(formData, 'bankHolderName'),
+    bankCode: readString(formData, 'bankCode'),
+    accountNumber: readString(formData, 'accountNumber'),
+    businessStatusCode: readString(formData, 'businessStatusCode'),
+    divisionCode: readString(formData, 'divisionCode'),
     isVisible: readString(formData, 'isVisible') === 'Y',
   });
   if (!validation.ok) {
     return { status: 'error', errors: validation.errors };
   }
 
-  return { status: 'error', message: DISABLED_MESSAGE };
+  try {
+    if (validation.values.id) {
+      await updateMerchant(validation.values.id, validation.values);
+    } else {
+      await createMerchant(validation.values);
+    }
+  } catch (error) {
+    unstable_rethrow(error);
+    console.error('[merchants] 저장 실패', error);
+    const message =
+      error instanceof BackendRequestError && error.message ? error.message : SAVE_FAILED_MESSAGE;
+    return { status: 'error', message };
+  }
+
+  revalidatePath(MERCHANTS_PATH);
+  return { status: 'success' };
 }

a565313

94ca85e

app/(protected)/(basic)/system/merchants/_components/merchant-list.tsx

--- app/(protected)/(basic)/system/merchants/_components/merchant-list.tsx

+++ app/(protected)/(basic)/system/merchants/_components/merchant-list.tsx


 'use client';
 
 import { useRouter } from 'next/navigation';
+import { useState } from 'react';
 import { FoxButton } from '@fox/core/components/fox-button';
 import {
   FoxListContainer,

 import { FoxSelect } from '@fox/core/components/fox-select';
 import { FoxSelectText } from '@fox/core/components/fox-select-text';
 import { FoxStatusIndicator } from '@fox/core/components/fox-status-indicator';
-import type { CommonCode } from '@/lib/domain/common-code';
 import {
   formatAddressSummary,
   formatCategoryLabel,
   formatOptionalValue,
   formatVisibilityLabel,
   type Merchant,
+  type MerchantCodeTables,
 } from '@/lib/domain/merchant';
 import {
   MERCHANTS_EXCEL_PATH,

   type MerchantQuery,
   type MerchantSearchField,
 } from '@/lib/domain/merchant-query';
+import { MerchantFormModal } from './merchant-form-modal';
 import { MerchantRowActions } from './merchant-row-actions';
 import styles from './merchant-filter.module.scss';
 
 interface MerchantListProps {
   items: Merchant[];
-  /** 업종 코드표(`FRCS_TPBIZ_CD` 다음 `FRCS_CD`) — 업종 열과 상세 모달이 이름을 찾는다. */
-  businessCodes: CommonCode[];
+  /** 업종(열·모달)·업태·구분·은행 코드표 — 등록·수정 모달의 선택지. */
+  codeTables: MerchantCodeTables;
   query: MerchantQuery;
   currentPage: number;
   totalPages: number;

 
 export function MerchantList({
   items,
-  businessCodes,
+  codeTables,
   query,
   currentPage,
   totalPages,
   totalCount,
 }: MerchantListProps) {
   const router = useRouter();
+  const [isCreateOpen, setIsCreateOpen] = useState(false);
 
   function go(patch: Partial<MerchantQuery>) {
     router.replace(buildMerchantHref(query, { ...patch, page: 1 }));

       key: 'categoryCode',
       header: '업종',
       width: 100,
-      render: (row) => formatCategoryLabel(businessCodes, row.categoryCode),
+      render: (row) => formatCategoryLabel(codeTables.business, row.categoryCode),
     },
     {
       key: 'phoneNumber',

       key: 'actions',
       header: '관리',
       width: 120,
-      render: (row) => <MerchantRowActions merchant={row} businessCodes={businessCodes} />,
+      render: (row) => <MerchantRowActions merchant={row} codeTables={codeTables} />,
     },
   ];
 

                 label="엑셀다운로드"
               />
             </form>
-            {/* TODO(백엔드): 등록이 자체 저장에서 BizPlay 외부 가맹점 등록 API 위임으로 바뀌었다
-                (`POST /api/v1/mngr/voc`가 @RequestBody JSON이 되고 bizPlayVocApiService.insertVoc를
-                부른다). 예금주명·입금은행코드·입금계좌번호·업태코드가 새로 필요한데 이 폼은 받지
-                않는다. 항목이 정해지면 MerchantFormModal과 함께 다시 연다. */}
             <FoxButton
               type="primary"
               size="md"

                 <i className="fox-ico fox-ico-Plus" aria-hidden="true" />
               }
               label="등록"
-              disabled
+              onAction={() => setIsCreateOpen(true)}
             />
           </>
         }

           }
         }}
       />
+
+      {isCreateOpen && (
+        <MerchantFormModal codeTables={codeTables} onClose={() => setIsCreateOpen(false)} />
+      )}
     </>
   );
 }

a565313

94ca85e

app/(protected)/(basic)/system/merchants/_components/merchant-row-actions.tsx

--- app/(protected)/(basic)/system/merchants/_components/merchant-row-actions.tsx

+++ app/(protected)/(basic)/system/merchants/_components/merchant-row-actions.tsx


 import { FoxButtonGroup } from '@fox/core/components/fox-button-group';
 import { FoxIconButton } from '@fox/core/components/fox-icon-button';
 import { useFeedback } from '@/app/_hooks/use-feedback';
-import type { CommonCode } from '@/lib/domain/common-code';
-import type { Merchant } from '@/lib/domain/merchant';
+import type { Merchant, MerchantCodeTables } from '@/lib/domain/merchant';
 import { MerchantFormModal } from './merchant-form-modal';
 
 interface MerchantRowActionsProps {
   merchant: Merchant;
-  businessCodes: CommonCode[];
+  codeTables: MerchantCodeTables;
 }
 
 /**
- * 수정은 모달을 열어 등록된 내용을 보여 준다 — 백엔드에 수정 API가 없어 모달이 조회
- * 전용으로 뜬다(`merchant-form-modal.tsx`의 `IS_EDIT_ENABLED`). API가 생기면 그 한 줄만
- * 바꾸면 여기는 손대지 않아도 된다.
+ * 수정은 모달을 열어 고친다(`PUT /api/v1/mngr/voc`).
  *
- * TODO(백엔드): 삭제 API도 없다(`/api/v1/mngr/voc`는 목록·등록뿐). 시안의 자리는 두되
- * 눌러도 할 수 있는 일이 없어 사유를 알린다.
+ * TODO(백엔드): 삭제 API가 없다(`/api/v1/mngr/voc/{frcsNo}` DELETE는 가맹몰 상세를 지운다). 시안의
+ * 자리는 두되 눌러도 할 수 있는 일이 없어 사유를 알린다.
  *
  * 어느 행의 버튼인지는 각 버튼 라벨이 말한다 — 감싼 요소의 `aria-label`은 의미 없는
  * 요소에 붙어 읽히지 않을 수 있다(공통코드 행과 같은 방식).
  */
-export function MerchantRowActions({ merchant, businessCodes }: MerchantRowActionsProps) {
+export function MerchantRowActions({ merchant, codeTables }: MerchantRowActionsProps) {
   const { showToast } = useFeedback();
   const [isDetailOpen, setIsDetailOpen] = useState(false);
 

       {isDetailOpen && (
         <MerchantFormModal
           merchant={merchant}
-          businessCodes={businessCodes}
+          codeTables={codeTables}
           onClose={() => setIsDetailOpen(false)}
         />
       )}

a565313

94ca85e

app/(protected)/(basic)/system/merchants/page.tsx

--- app/(protected)/(basic)/system/merchants/page.tsx

+++ app/(protected)/(basic)/system/merchants/page.tsx


 import { fetchCommonCodes } from '@/lib/data/repositories/common-code-repository';
 import { fetchMerchants } from '@/lib/data/repositories/merchant-repository';
 import { CODE_GROUP } from '@/lib/domain/common-code';
+import type { MerchantCodeTables } from '@/lib/domain/merchant';
 import { parseMerchantQuery } from '@/lib/domain/merchant-query';
 import { MerchantList } from './_components/merchant-list';
 

   await verifySession();
 
   const query = parseMerchantQuery(await searchParams);
-  const [{ items, totalCount }, business, businessDetail] = await Promise.all([
-    fetchMerchants(query),
-    fetchCommonCodes(CODE_GROUP.merchantBusiness),
-    fetchCommonCodes(CODE_GROUP.merchantBusinessDetail),
-  ]);
-  // 앞쪽 표가 먼저 맞는다 — 2자리 값은 FRCS_TPBIZ_CD에서, 4자리 값은 FRCS_CD에서 이름을 찾는다.
-  const businessCodes = [...business, ...businessDetail];
+  const [{ items, totalCount }, business, businessDetail, businessStatus, division, bank] =
+    await Promise.all([
+      fetchMerchants(query),
+      fetchCommonCodes(CODE_GROUP.merchantBusiness),
+      fetchCommonCodes(CODE_GROUP.merchantBusinessDetail),
+      fetchCommonCodes(CODE_GROUP.merchantBusinessStatus),
+      fetchCommonCodes(CODE_GROUP.merchantDivision),
+      fetchCommonCodes(CODE_GROUP.bank),
+    ]);
+  const codeTables: MerchantCodeTables = {
+    // 앞쪽 표가 먼저 맞는다 — 2자리 값은 FRCS_TPBIZ_CD에서, 4자리 값은 FRCS_CD에서 이름을 찾는다.
+    business: [...business, ...businessDetail],
+    businessStatus,
+    division,
+    bank,
+  };
 
   const totalPages = Math.max(1, Math.ceil(totalCount / query.pageSize));
   const currentPage = Math.min(query.page, totalPages);

   return (
     <MerchantList
       items={items}
-      businessCodes={businessCodes}
+      codeTables={codeTables}
       query={query}
       currentPage={currentPage}
       totalPages={totalPages}

a565313

94ca85e

app/_components/postcode.ts (Renamed from app/(protected)/(basic)/system/merchants/_components/postcode.ts)

--- app/(protected)/(basic)/system/merchants/_components/postcode.ts

+++ app/_components/postcode.ts

No changes

a565313

94ca85e

lib/data/repositories/merchant-detail-repository.ts

--- lib/data/repositories/merchant-detail-repository.ts

+++ lib/data/repositories/merchant-detail-repository.ts


   return rows;
 }
 
-/** 등록 화면의 업체 선택지 — 아직 상세가 없는 가맹점 전부. */
-export async function fetchMerchantDetailCandidates(): Promise<MerchantDetailSummary[]> {
-  return (await fetchMergedSummaries()).filter((row) => !row.hasDetail);
+/**
+ * 방금 만든 가맹점의 코드 — 등록 응답에 코드가 없을 때 가맹점 목록에서 이름·연락처로 찾는다.
+ * 같은 이름이 여럿이면 가장 최근 것(목록이 등록일 내림차순).
+ */
+export async function findMerchantByName(
+  name: string,
+  phoneNumber: string
+): Promise<MerchantDetailSummary | null> {
+  const merchants = await fetchAllPages(`${VOC_PATH}/pagination`, toCandidate);
+  const digits = phoneNumber.replace(/\D/g, '');
+  return (
+    merchants.find(
+      (row) => row.name === name && (row.phoneNumber ?? '').replace(/\D/g, '') === digits
+    ) ??
+    merchants.find((row) => row.name === name) ??
+    null
+  );
 }
 
 /** 가맹점 한 건(상세 없이) — 가맹점 단건 API가 없어 목록에서 찾는다. */

a565313

94ca85e

lib/data/repositories/merchant-repository.ts

--- lib/data/repositories/merchant-repository.ts

+++ lib/data/repositories/merchant-repository.ts


  *
  * ```
  * GET  /api/v1/mngr/voc/pagination   searchCondition 1=가맹점명 2=사업자번호 3=상세주소
- * POST /api/v1/mngr/voc              어노테이션 없음 → form
+ * POST /api/v1/mngr/voc              @RequestBody MngrVocInsertReqVo
+ * PUT  /api/v1/mngr/voc              @RequestBody MngrVocUpdateReqVo (BaseVo + chgDvCd)
  * ```
  *
  * ⚠️ 백엔드 현황(보고함)
- * 1. **등록이 아직 동작하지 않는다.** 컨트롤러 `insert`의 본문이 전부 주석 처리돼 있고
- *    `return null;`이다 — 봉투 없는 빈 200이 온다. 그래서 저장해도 아무 일도 일어나지 않는다.
- * 2. **수정·삭제·단건 조회 API가 없다.** 목록과 등록 두 개뿐이다.
+ * 1. 등록·수정은 아직 BizPlay(웹캐시) 가맹점 API로 위임된다(1c7b0e0). 우리 DB에 저장하도록
+ *    바뀔 예정(사용자 공지)이라 요청은 그 VO 그대로 보내고, 응답에서 `frcsNo`가 오면 읽고 없으면
+ *    가맹점 목록에서 찾는다. 위임 상태에선 새 가맹점이 다음 날 동기화 뒤에야 목록에 나타난다.
+ * 2. **삭제·단건 조회 API가 없다.**
  * 3. 검색 필터가 어긋난다 — 업종 검색 파라미터는 `searchFrcsTpbizCd`인데 SQL은 `FRCS_DV_CD`를
  *    비교하고, 저장은 `frcsTpbizCd`로 받는다. 저장한 업종으로 검색이 걸리지 않는다.
  * 4. 목록 정렬이 이중 역순이다 — rnum이 등록일 내림차순인데 `ORDER BY RNUM DESC`로 다시

       postalCode: readString(raw, 'frcsPostZip'),
       latitude: readString(raw, 'lat'),
       longitude: readString(raw, 'lng'),
+      businessStatusCode: readString(raw, 'frcsBzstatCd').trim(),
+      divisionCode: readString(raw, 'frcsDvCd').trim(),
       // 조회 SQL이 USE_YN을 select하지 않는다(⚠️ 5). 값이 없으면 판단하지 않는다 —
       // 종전처럼 노출로 단정하면 「미노출」로 걸러 낸 행까지 전부 「노출」로 보인다.
       isVisible: readUseYn(raw),

     : [];
 }
 
-/**
- * TODO(백엔드): 아래 form 전송은 옛 계약이다. 지금 `POST /api/v1/mngr/voc`는 @RequestBody(JSON)
- *   `MngrVocInsertReqVo`를 받고 BizPlay 외부 API로 위임하며, 예금주명(bankDpstrNm)·입금은행코드
- *   (dpstBankCd)·입금계좌번호(dpstActNo)·업태코드(frcsBzstatCd)를 새로 요구한다. lat·lng는 요청
- *   VO에서 빠졌다. 등록 화면이 그 항목을 받게 되면 이 함수를 JSON으로 바꿔 다시 연결한다
- *   (현재 호출부 없음 — `_actions.ts` 참고).
- */
-export async function createMerchant(values: MerchantValues): Promise<void> {
+/** 백엔드 `MngrVocBaseVo` — 등록·수정 요청이 함께 쓰는 가맹점 필드. */
+function toMerchantPayload(values: MerchantValues): Record<string, unknown> {
+  return {
+    frcsNm: values.name,
+    rprsvNm: values.ownerName,
+    rprsvTelno: values.phoneNumber,
+    brno: values.businessNumber.replace(/-/g, ''),
+    bankDpstrNm: values.bankHolderName,
+    dpstBankCd: values.bankCode,
+    // 등록 VO(BizPlayVocInsertVo)는 dpstActno, 수정 VO(MngrVocBaseVo)는 dpstActNo다 — 둘 다 싣는다.
+    dpstActno: values.accountNumber,
+    dpstActNo: values.accountNumber,
+    frcsDvCd: values.divisionCode,
+    frcsPostAddr: values.address,
+    frcsDaddr: values.addressDetail,
+    frcsPostZip: values.postalCode,
+    [MERCHANT_CATEGORY_WRITE_FIELD]: values.categoryCode,
+    frcsBzstatCd: values.businessStatusCode,
+    // 요청 VO에 없어 무시된다. 컬럼이 생기면 그대로 저장되도록 미리 싣는다.
+    useYn: values.isVisible ? 'Y' : 'N',
+    brandNm: values.brandName,
+    memo: values.memo,
+    lat: values.latitude,
+    lng: values.longitude,
+  };
+}
+
+/** 등록 응답에서 가맹점 코드를 찾는다 — 문자열, `frcsNo`, BizPlay 응답(`repRec.FRCS_NO`) 어느 모양이든. */
+function readCreatedFrcsNo(data: unknown): string | null {
+  if (typeof data === 'string' && data !== '') return data;
+  if (!isRecord(data)) return null;
+  const direct = readString(data, 'frcsNo') || readString(data, 'FRCS_NO');
+  if (direct) return direct;
+  const repRec = data.repRec;
+  return isRecord(repRec) ? readString(repRec, 'FRCS_NO') || readString(repRec, 'frcsNo') || null : null;
+}
+
+/** 가맹점 등록. 백엔드가 코드를 돌려주면 그 값, 아니면 null이다. */
+export async function createMerchant(values: MerchantValues): Promise<string | null> {
   const accessToken = await getSessionAccessToken();
 
   const result = await backendFetch<unknown>(VOC_PATH, {
     method: 'POST',
-    form: {
-      frcsNm: values.name,
-      [MERCHANT_CATEGORY_WRITE_FIELD]: values.categoryCode,
-      // 요청 VO의 필드 이름이 대문자다(`private String BRNO`) — Spring이 그 이름으로 바인딩한다.
-      BRNO: values.businessNumber,
-      rprsvNm: values.ownerName,
-      rprsvTelno: values.phoneNumber,
-      frcsPostAddr: values.address,
-      frcsDaddr: values.addressDetail,
-      frcsPostZip: values.postalCode,
-      lat: values.latitude,
-      lng: values.longitude,
-      useYn: values.isVisible ? 'Y' : 'N',
-      // 요청 VO에 없어 무시된다. 컬럼이 생기면 그대로 저장되도록 미리 싣는다.
-      brandNm: values.brandName,
-      memo: values.memo,
-    },
+    body: toMerchantPayload(values),
+    accessToken: accessToken ?? undefined,
+    cache: 'no-store',
+    canHaveNullData: true,
+    canHaveEmptyBody: true,
+  });
+
+  if (!result.ok) {
+    throw new BackendRequestError(result);
+  }
+  return readCreatedFrcsNo(result.data);
+}
+
+/**
+ * 가맹점 수정. 수정 VO에는 `frcsNo`가 없다(BizPlay가 사업자번호로 식별) — 우리 DB 저장으로 바뀔 때를
+ * 위해 `frcsNo`도 싣는다. `chgDvCd`(변경구분)는 BizPlay 전용이라 비워 보낸다.
+ */
+export async function updateMerchant(frcsNo: string, values: MerchantValues): Promise<void> {
+  const accessToken = await getSessionAccessToken();
+
+  const result = await backendFetch<unknown>(VOC_PATH, {
+    method: 'PUT',
+    body: { frcsNo, chgDvCd: '', ...toMerchantPayload(values) },
     accessToken: accessToken ?? undefined,
     cache: 'no-store',
     canHaveNullData: true,

a565313

94ca85e

lib/domain/common-code.ts

--- lib/domain/common-code.ts

+++ lib/domain/common-code.ts


   merchantBusinessDetail: 'FRCS_CD',
   /** 가맹몰 메뉴 배지 — 앱 API가 `frcsBadge`의 쉼표 구분 코드를 이 그룹 이름으로 풀어 준다(백엔드 40f85c4). */
   merchantProductBadge: 'FRCS_BADGE_CD',
+  /** 가맹점 업태(`FRCS_BZSTAT_CD`) — 등록 요청 VO의 `frcsBzstatCd`. */
+  merchantBusinessStatus: 'FRCS_BZSTAT_CD',
+  /** 가맹점 구분(`FRCS_DV_CD`: 60 온라인 · 62 일반) — 등록 요청 VO의 `frcsDvCd`. */
+  merchantDivision: 'FRCS_DV_CD',
+  /** 입금 은행 — 등록 요청 VO의 `dpstBankCd`. */
+  bank: 'COM_BANK_CD',
 } as const;
 
 /** 값이 없는 항목의 화면 표기. */

a565313

94ca85e

lib/domain/merchant-detail-form.ts

--- lib/domain/merchant-detail-form.ts

+++ lib/domain/merchant-detail-form.ts


 /**
  * 가맹몰 상세 등록·수정 입력 규칙 — 순수 검증만 담는다.
  *
- * 기획 BO-MAL-002 ①의 필수 항목 중 업체명·연락처·우편번호는 가맹점 원본에서 오는 읽기 전용
- * 값이라 여기서 검사하지 않는다. 남는 필수는 카테고리·노출 상태·바우처 사용·대표이미지다.
+ * 기획 BO-MAL-002 ①의 필수 항목은 업체명·카테고리·업체 연락처·우편번호·노출 상태·바우처 사용·
+ * 대표이미지다. 업체 항목(업체명·연락처·우편번호·주소)은 이 화면에서 직접 입력한다(사용자 확정) —
+ * 가맹점이 없으면 새로 만들고, 있으면 함께 고친다.
  */
 
 export const DESCRIPTION_MAX_LENGTH = 200;
 export const CLOSED_DAYS_MAX_LENGTH = 100;
 export const SORT_ORDER_MAX = 9999;
+export const MERCHANT_NAME_MAX_LENGTH = 100;
+export const ADDRESS_MAX_LENGTH = 200;
 const TIME_PATTERN = /^([01]\d|2[0-3]):[0-5]\d$/;
+const POSTAL_CODE_PATTERN = /^\d{5}$/;
+const PHONE_PATTERN = /^[\d-]+$/;
 
-export type MerchantDetailValues = {
+/** 상세 화면이 함께 다루는 업체(가맹점) 항목 — 백엔드 `MngrVocBaseVo`의 일부. */
+export type MerchantDetailMerchantValues = {
+  name: string;
+  phoneNumber: string;
+  postalCode: string;
+  address: string;
+  addressDetail: string;
+};
+
+export type MerchantDetailValues = MerchantDetailMerchantValues & {
+  /** 비어 있으면 가맹점을 새로 만든다. */
   frcsNo: string;
   categoryCode: string;
   description: string;

 
 export type MerchantDetailFormErrors = Partial<
   Record<
-    | 'frcsNo'
+    | 'name'
+    | 'phoneNumber'
+    | 'postalCode'
+    | 'address'
     | 'categoryCode'
     | 'description'
     | 'openTime'

   categories: readonly CommonCode[]
 ): ValidationResult {
   const errors: MerchantDetailFormErrors = {};
+
+  const name = values.name.trim();
+  if (!name) {
+    errors.name = '업체명을 입력해 주세요.';
+  } else if (name.length > MERCHANT_NAME_MAX_LENGTH) {
+    errors.name = `업체명은 ${MERCHANT_NAME_MAX_LENGTH}자 이내로 입력해 주세요.`;
+  }
+
+  const phoneNumber = values.phoneNumber.trim();
+  if (!phoneNumber) {
+    errors.phoneNumber = '업체 연락처를 입력해 주세요.';
+  } else if (!PHONE_PATTERN.test(phoneNumber)) {
+    errors.phoneNumber = '연락처는 숫자와 -만 입력할 수 있습니다.';
+  }
+
+  const postalCode = values.postalCode.trim();
+  if (!postalCode) {
+    errors.postalCode = '우편번호를 입력해 주세요.';
+  } else if (!POSTAL_CODE_PATTERN.test(postalCode)) {
+    errors.postalCode = '우편번호는 숫자 5자리로 입력해 주세요.';
+  }
+
+  const address = values.address.trim();
+  const addressDetail = values.addressDetail.trim();
+  if (address.length > ADDRESS_MAX_LENGTH || addressDetail.length > ADDRESS_MAX_LENGTH) {
+    errors.address = `주소는 ${ADDRESS_MAX_LENGTH}자 이내로 입력해 주세요.`;
+  }
 
   if (!categories.some((code) => code.code === values.categoryCode)) {
     errors.categoryCode = '카테고리를 선택해 주세요.';

   }
   return {
     ok: true,
-    values: { ...values, description, openTime, closeTime, closedDays },
+    values: {
+      ...values,
+      name,
+      phoneNumber,
+      postalCode,
+      address,
+      addressDetail,
+      description,
+      openTime,
+      closeTime,
+      closedDays,
+    },
   };
 }

a565313

94ca85e

lib/domain/merchant-form.ts

--- lib/domain/merchant-form.ts

+++ lib/domain/merchant-form.ts


 export const OWNER_MAX_LENGTH = 50;
 export const ADDRESS_DETAIL_MAX_LENGTH = 200;
 export const MEMO_MAX_LENGTH = 500;
+export const ACCOUNT_NUMBER_MAX_LENGTH = 30;
 
 export interface MerchantValues {
   id: string;

   postalCode: string;
   latitude: string;
   longitude: string;
+  /** 백엔드 등록 요청 VO(`MngrVocInsertReqVo`)의 예금주명·입금은행코드·입금계좌번호·업태·구분. */
+  bankHolderName: string;
+  bankCode: string;
+  accountNumber: string;
+  businessStatusCode: string;
+  divisionCode: string;
   isVisible: boolean;
 }
 
 export type MerchantFormErrors = Partial<
-  Record<'name' | 'categoryCode' | 'phoneNumber' | 'address' | 'businessNumber', string>
+  Record<
+    'name' | 'categoryCode' | 'phoneNumber' | 'address' | 'postalCode' | 'businessNumber' | 'accountNumber',
+    string
+  >
 >;
 
 export type MerchantFormState =

   }
 
   if (!values.address.trim()) {
-    errors.address = '주소 검색을 진행해 주세요.';
+    errors.address = '주소를 검색하거나 입력해 주세요.';
+  }
+
+  const postalCode = values.postalCode.trim();
+  if (postalCode && !/^\d{5}$/.test(postalCode)) {
+    errors.postalCode = '우편번호는 숫자 5자리로 입력해 주세요.';
   }
 
   const businessNumber = values.businessNumber.trim();
   if (businessNumber && !BUSINESS_NUMBER_PATTERN.test(businessNumber)) {
     errors.businessNumber = '사업자등록번호는 000-00-00000 형식으로 입력해 주세요.';
+  }
+
+  const accountNumber = values.accountNumber.trim();
+  if (accountNumber && !/^[\d-]+$/.test(accountNumber)) {
+    errors.accountNumber = '계좌번호는 숫자와 -만 입력할 수 있습니다.';
   }
 
   if (Object.keys(errors).length > 0) {

       businessNumber,
       address: values.address.trim(),
       addressDetail: values.addressDetail.trim().slice(0, ADDRESS_DETAIL_MAX_LENGTH),
+      postalCode,
+      bankHolderName: values.bankHolderName.trim().slice(0, OWNER_MAX_LENGTH),
+      bankCode: values.bankCode.trim(),
+      accountNumber: accountNumber.slice(0, ACCOUNT_NUMBER_MAX_LENGTH),
+      businessStatusCode: values.businessStatusCode.trim(),
+      divisionCode: values.divisionCode.trim(),
     },
   };
 }

a565313

94ca85e

lib/domain/merchant.ts

--- lib/domain/merchant.ts

+++ lib/domain/merchant.ts


   postalCode: string;
   latitude: string;
   longitude: string;
+  /** 백엔드 `frcsBzstatCd` — 업태 코드(`FRCS_BZSTAT_CD`). */
+  businessStatusCode: string;
+  /** 백엔드 `frcsDvCd` — 가맹점 구분(`FRCS_DV_CD`). */
+  divisionCode: string;
   /** 백엔드 `useYn`. develop 목록엔 없어 `null`(모름)이고 feature/voc부터 온다. */
   isVisible: boolean | null;
 }
 
+/** 가맹몰 등록·수정 폼이 쓰는 코드표 넷 — 화면이 한 번에 받아 모달까지 내려보낸다. */
+export type MerchantCodeTables = {
+  /** 업종(`FRCS_TPBIZ_CD` 다음 `FRCS_CD`). */
+  business: CommonCode[];
+  businessStatus: CommonCode[];
+  division: CommonCode[];
+  bank: CommonCode[];
+};
+
+/** 가맹점 구분 기본값 — 관리자가 만드는 가맹점은 일반가맹점이다. */
+export const DEFAULT_MERCHANT_DIVISION_CODE = '62';
+
 export const EMPTY_FIELD_PLACEHOLDER = '-';
 
 export function formatOptionalValue(

Add a comment

Open 0
Closed 0

List

...	...	@@ -14,8 +14,10 @@
14	14	createMerchantDetail,
15	15	deleteMerchantDetail,
16	16	fetchMerchantDetail,
	17	+ findMerchantByName,
17	18	updateMerchantDetail,
18	19	} from '@/lib/data/repositories/merchant-detail-repository';
	20	+import { createMerchant, updateMerchant } from '@/lib/data/repositories/merchant-repository';
19	21	import {
20	22	createMerchantProduct,
21	23	deleteMerchantProduct,
...	...	@@ -33,8 +35,11 @@
33	35	import {
34	36	validateMerchantDetail,
35	37	type MerchantDetailFormState,
	38	+ type MerchantDetailMerchantValues,
36	39	type MerchantDetailValues,
37	40	} from '@/lib/domain/merchant-detail-form';
	41	+import { DEFAULT_MERCHANT_DIVISION_CODE } from '@/lib/domain/merchant';
	42	+import type { MerchantValues } from '@/lib/domain/merchant-form';
38	43	import {
39	44	MERCHANT_DETAILS_PATH,
40	45	merchantDetailPath,
...	...	@@ -60,6 +65,8 @@
60	65	// 백엔드가 삭제된 상세도 "있는 것"으로 보는 결함(보고함) — 409는 대개 이 경우다.
61	66	const DETAIL_CONFLICT_MESSAGE =
62	67	'이 가맹점에는 이미 상세가 있습니다. 삭제했던 상세라면 백엔드에서 정리해야 다시 등록할 수 있습니다.';
	68	+const MERCHANT_NOT_FOUND_AFTER_CREATE_MESSAGE =
	69	+ '업체는 등록됐지만 코드를 받지 못해 상세를 붙이지 못했습니다. 목록에 업체가 나타나면 [수정]으로 상세를 등록해 주세요.';
63	70	const IMAGE_OVERSIZE_MESSAGE = `이미지는 장당 ${Math.floor(MAX_IMAGE_BYTES / (1024 * 1024))}MB까지 올릴 수 있습니다.`;
64	71	const IMAGES_TOO_MANY_MESSAGE = `추가 이미지는 최대 ${MAX_EXTRA_IMAGES}장까지입니다.`;
65	72	const REQUEST_OVERSIZE_MESSAGE = `한 번에 올리는 이미지의 합이 ${Math.floor(MAX_ATTACHMENT_BYTES / (1024 * 1024))}MB를 넘습니다. 나눠서 저장해 주세요.`;
...	...	@@ -238,12 +245,83 @@
238	245	return uploadAttachments(bundle, FILE_MODULE.merchantImage.id);
239	246	}
240	247
	248	+function readMerchantValues(formData: FormData, prefix = ''): MerchantDetailMerchantValues {
	249	+ return {
	250	+ name: readString(formData, `${prefix}name`),
	251	+ phoneNumber: readString(formData, `${prefix}phoneNumber`),
	252	+ postalCode: readString(formData, `${prefix}postalCode`),
	253	+ address: readString(formData, `${prefix}address`),
	254	+ addressDetail: readString(formData, `${prefix}addressDetail`),
	255	+ };
	256	+}
	257	+
	258	+function isSameMerchant(a: MerchantDetailMerchantValues, b: MerchantDetailMerchantValues): boolean {
	259	+ return (
	260	+ a.name.trim() === b.name.trim() &&
	261	+ a.phoneNumber.trim() === b.phoneNumber.trim() &&
	262	+ a.postalCode.trim() === b.postalCode.trim() &&
	263	+ a.address.trim() === b.address.trim() &&
	264	+ a.addressDetail.trim() === b.addressDetail.trim()
	265	+ );
	266	+}
	267	+
	268	+/** 상세 화면이 받는 업체 항목을 가맹점 등록·수정 요청 값으로 — 나머지는 이 화면에 없어 비운다. */
	269	+function toMerchantValues(frcsNo: string, values: MerchantDetailMerchantValues): MerchantValues {
	270	+ return {
	271	+ id: frcsNo,
	272	+ brandName: '',
	273	+ memo: '',
	274	+ name: values.name,
	275	+ categoryCode: '',
	276	+ businessNumber: '',
	277	+ ownerName: '',
	278	+ phoneNumber: values.phoneNumber,
	279	+ address: values.address,
	280	+ addressDetail: values.addressDetail,
	281	+ postalCode: values.postalCode,
	282	+ latitude: '',
	283	+ longitude: '',
	284	+ bankHolderName: '',
	285	+ bankCode: '',
	286	+ accountNumber: '',
	287	+ businessStatusCode: '',
	288	+ divisionCode: DEFAULT_MERCHANT_DIVISION_CODE,
	289	+ isVisible: true,
	290	+ };
	291	+}
	292	+
	293	+/**
	294	+ * 업체(가맹점)를 만들거나 고치고 코드를 돌려준다.
	295	+ * - 코드가 없으면 새로 만든다 — 응답에 코드가 없으면(BizPlay 위임 응답) 목록에서 이름으로 찾는다.
	296	+ * - 코드가 있으면 값이 바뀌었을 때만 고친다 — BizPlay 위임 상태에선 불필요한 외부 호출을 피한다.
	297	+ */
	298	+async function saveMerchant(
	299	+ frcsNo: string,
	300	+ values: MerchantDetailMerchantValues,
	301	+ original: MerchantDetailMerchantValues
	302	+): Promise<string> {
	303	+ if (frcsNo) {
	304	+ if (!isSameMerchant(values, original)) {
	305	+ await updateMerchant(frcsNo, toMerchantValues(frcsNo, values));
	306	+ }
	307	+ return frcsNo;
	308	+ }
	309	+ const created = await createMerchant(toMerchantValues('', values));
	310	+ if (created) return created;
	311	+ const found = await findMerchantByName(values.name, values.phoneNumber);
	312	+ if (!found) {
	313	+ throw new InputError(MERCHANT_NOT_FOUND_AFTER_CREATE_MESSAGE);
	314	+ }
	315	+ return found.id;
	316	+}
	317	+
241	318	function readDetailValues(
242	319	formData: FormData,
243	320	thumbnailFileId: string,
244	321	imageFileId: string
245	322	): MerchantDetailValues {
246	323	return {
	324	+ ...readMerchantValues(formData),
247	325	frcsNo: readString(formData, 'frcsNo'),
248	326	categoryCode: readString(formData, 'categoryCode'),
249	327	description: readString(formData, 'description'),
...	...	@@ -264,11 +342,8 @@
264	342	): Promise<MerchantDetailFormState> {
265	343	await verifySession();
266	344
267		- const frcsNo = readString(formData, 'frcsNo');
268	345	const isEdit = readString(formData, 'mode') === 'edit';
269		- if (!frcsNo) {
270		- return { status: 'error', errors: { frcsNo: '업체를 선택해 주세요.' } };
271		- }
	346	+ let frcsNo = readString(formData, 'frcsNo');
272	347
273	348	let failed: MerchantDetailFormState \| null = null;
274	349	try {
...	...	@@ -286,10 +361,13 @@
286	361	return { status: 'error', errors: validation.errors };
287	362	}
288	363
	364	+ // 업체 먼저(만들거나 고치고), 그 코드로 상세를 붙인다.
	365	+ frcsNo = await saveMerchant(frcsNo, validation.values, readMerchantValues(formData, 'original'));
	366	+ const values = { ...validation.values, frcsNo };
289	367	if (isEdit) {
290		- await updateMerchantDetail(validation.values);
	368	+ await updateMerchantDetail(values);
291	369	} else {
292		- await createMerchantDetail(validation.values);
	370	+ await createMerchantDetail(values);
293	371	}
294	372	} catch (error) {
295	373	unstable_rethrow(error);
...	...	@@ -356,6 +434,11 @@
356	434	}
357	435	await updateMerchantDetail({
358	436	frcsNo,
	437	+ name: detail.name,
	438	+ phoneNumber: detail.phoneNumber ?? '',
	439	+ postalCode: detail.postalCode ?? '',
	440	+ address: detail.address ?? '',
	441	+ addressDetail: detail.addressDetail ?? '',
359	442	categoryCode: detail.categoryCode,
360	443	description: detail.description ?? '',
361	444	openTime: detail.openTime ?? '',

...	...	@@ -297,9 +297,23 @@
297	297	return rows;
298	298	}
299	299
300		-/** 등록 화면의 업체 선택지 — 아직 상세가 없는 가맹점 전부. */
301		-export async function fetchMerchantDetailCandidates(): Promise<MerchantDetailSummary[]> {
302		- return (await fetchMergedSummaries()).filter((row) => !row.hasDetail);
	300	+/**
	301	+ * 방금 만든 가맹점의 코드 — 등록 응답에 코드가 없을 때 가맹점 목록에서 이름·연락처로 찾는다.
	302	+ * 같은 이름이 여럿이면 가장 최근 것(목록이 등록일 내림차순).
	303	+ */
	304	+export async function findMerchantByName(
	305	+ name: string,
	306	+ phoneNumber: string
	307	+): Promise<MerchantDetailSummary \| null> {
	308	+ const merchants = await fetchAllPages(`${VOC_PATH}/pagination`, toCandidate);
	309	+ const digits = phoneNumber.replace(/\D/g, '');
	310	+ return (
	311	+ merchants.find(
	312	+ (row) => row.name === name && (row.phoneNumber ?? '').replace(/\D/g, '') === digits
	313	+ ) ??
	314	+ merchants.find((row) => row.name === name) ??
	315	+ null
	316	+ );
303	317	}
304	318
305	319	/** 가맹점 한 건(상세 없이) — 가맹점 단건 API가 없어 목록에서 찾는다. */

...	...	@@ -1,7 +1,7 @@
1	1	'use client';
2	2
3	3	import { useRouter } from 'next/navigation';
4		-import { useActionState, useEffect, useState } from 'react';
	4	+import { useActionState, useEffect, useState, useTransition } from 'react';
5	5	import { FoxButton } from '@fox/core/components/fox-button';
6	6	import { FoxButtonGroup } from '@fox/core/components/fox-button-group';
7	7	import { FoxButtonPanel } from '@fox/core/components/fox-button-panel';
...	...	@@ -11,6 +11,7 @@
11	11	import { FoxInput } from '@fox/core/components/fox-input';
12	12	import { FoxPageHeader } from '@fox/core/components/fox-page-header';
13	13	import { FoxSelect } from '@fox/core/components/fox-select';
	14	+import { openPostcodeSearch } from '@/app/_components/postcode';
14	15	import { submitFormAction } from '@/app/_hooks/submit-form-action';
15	16	import { useBlockingAction } from '@/app/_hooks/use-blocking-action';
16	17	import { useFeedback } from '@/app/_hooks/use-feedback';
...	...	@@ -24,14 +25,15 @@
24	25	type MerchantDetailSummary,
25	26	} from '@/lib/domain/merchant-detail';
26	27	import {
	28	+ ADDRESS_MAX_LENGTH,
27	29	CLOSED_DAYS_MAX_LENGTH,
28	30	DESCRIPTION_MAX_LENGTH,
29	31	INITIAL_MERCHANT_DETAIL_FORM_STATE,
	32	+ MERCHANT_NAME_MAX_LENGTH,
30	33	SORT_ORDER_MAX,
31	34	} from '@/lib/domain/merchant-detail-form';
32	35	import { MERCHANT_DETAILS_PATH, merchantDetailPath } from '@/lib/domain/merchant-detail-query';
33	36	import type { MerchantProduct } from '@/lib/domain/merchant-product';
34		-import { formatPhoneNumber } from '@/lib/domain/phone-number';
35	37	import {
36	38	deleteMerchantDetailAction,
37	39	saveMerchantDetailAction,
...	...	@@ -45,10 +47,8 @@
45	47	interface MerchantDetailFormProps {
46	48	/** 상세가 있는 가맹점 — 고친다. */
47	49	detail?: MerchantDetail;
48		- /** 상세가 아직 없는데 가맹점은 정해진 경우(행의 [수정]) — 그 가맹점에 처음 만든다. */
	50	+ /** 상세가 아직 없는데 가맹점은 있는 경우(행의 [수정]) — 그 가맹점에 처음 만든다. */
49	51	merchant?: MerchantDetailSummary;
50		- /** 가맹점도 정해지지 않은 경우([+ 업체 등록]) — 업체명 자리에서 하나를 고른다. */
51		- candidates?: MerchantDetailSummary[];
52	52	products?: MerchantProduct[];
53	53	categories: CommonCode[];
54	54	/** 메뉴 표의 배지 코드표(`FRCS_BADGE_CD`). */
...	...	@@ -57,17 +57,16 @@
57	57
58	58	/**
59	59	* 가맹몰 상세 — 기획 BO-MAL-002(등록)·003(수정)을 한 화면으로 합쳤다(사용자 확정). `detail`이 있으면
60		- * 고치고, `merchant`면 그 가맹점에 처음 만들고, 둘 다 없으면 업체명 자리에서 가맹점을 골라 만든다.
	60	+ * 고치고, `merchant`면 그 가맹점에 처음 만들고, 둘 다 없으면 업체(가맹점)부터 새로 만든다.
61	61	* 첫 저장 뒤에는 그 가맹점 주소로 옮겨 가되 화면 구성은 그대로라 바로 메뉴를 붙일 수 있고, 이후
62	62	* 저장은 그 자리에 머문다.
63	63	*
64		- * 업체명·연락처·우편번호·주소는 가맹점 원본이라 읽기 전용이다. 기획의 [주소 검색]은 가맹몰 관리
65		- * 화면의 것이라 여기서는 값을 바꾸지 않는다.
	64	+ * 업체명·연락처·우편번호·주소는 여기서 직접 입력한다(사용자 확정) — 저장하면 액션이 가맹점을
	65	+ * 만들거나(코드 없음) 바뀐 값을 고친(코드 있음) 뒤 상세를 붙인다. 바뀌었는지는 숨은 원본 값과 비교한다.
66	66	*/
67	67	export function MerchantDetailForm({
68	68	detail,
69	69	merchant: fixedMerchant,
70		- candidates = [],
71	70	products = [],
72	71	categories,
73	72	badgeCodes = [],
...	...	@@ -82,11 +81,20 @@
82	81	const isEdit = detail !== undefined;
83	82	const errors = state.status === 'error' ? (state.errors ?? {}) : {};
84	83
85		- // 가맹점이 정해져 있으면(상세가 있든 없든) 업체명은 읽기 전용이고, 아니면 여기서 고른다.
86		- const pinned: MerchantDetailSummary \| null = detail ?? fixedMerchant ?? null;
87		- const [frcsNo, setFrcsNo] = useState(pinned?.id ?? '');
88		- const merchant: MerchantDetailSummary \| null =
89		- pinned ?? candidates.find((row) => row.id === frcsNo) ?? null;
	84	+ // 가맹점이 있으면(상세가 있든 없든) 그 코드로 고치고, 없으면 빈 코드로 보내 새로 만든다.
	85	+ const merchant: MerchantDetailSummary \| null = detail ?? fixedMerchant ?? null;
	86	+ const frcsNo = merchant?.id ?? '';
	87	+ const original = {
	88	+ name: merchant?.name ?? '',
	89	+ phoneNumber: merchant?.phoneNumber ?? '',
	90	+ postalCode: merchant?.postalCode ?? '',
	91	+ address: merchant?.address ?? '',
	92	+ addressDetail: merchant?.addressDetail ?? '',
	93	+ };
	94	+ // 우편번호·주소는 검색으로 채우거나 직접 고친다.
	95	+ const [postalCode, setPostalCode] = useState(original.postalCode);
	96	+ const [address, setAddress] = useState(original.address);
	97	+ const [isSearching, startSearching] = useTransition();
90	98	const [categoryCode, setCategoryCode] = useState(detail?.categoryCode ?? '');
91	99	const [visibility, setVisibility] = useState<string[]>([
92	100	detail?.isVisible === false ? 'N' : 'Y',
...	...	@@ -103,6 +111,22 @@
103	111	router.refresh();
104	112	}
105	113	}, [state, router, showToast]);
	114	+
	115	+ /** 기획 BO-MAL-002 [주소 검색] — 고른 주소로 우편번호·주소를 채운다. */
	116	+ function searchAddress() {
	117	+ startSearching(async () => {
	118	+ let picked;
	119	+ try {
	120	+ picked = await openPostcodeSearch();
	121	+ } catch {
	122	+ showToast({ variant: 'danger', message: '주소 검색을 불러오지 못했습니다. 잠시 후 다시 시도해 주세요.' });
	123	+ return;
	124	+ }
	125	+ if (!picked) return;
	126	+ setPostalCode(picked.zonecode);
	127	+ setAddress(picked.address);
	128	+ });
	129	+ }
106	130
107	131	function toggleVisibility() {
108	132	if (!detail) return;
...	...	@@ -166,33 +190,27 @@
166	190	>
167	191	<input type="hidden" name="frcsNo" value={frcsNo} />
168	192	<input type="hidden" name="mode" value={isEdit ? 'edit' : 'create'} />
	193	+ {/* 저장 시 업체 값이 바뀌었는지 비교할 원본 — 안 바뀌었으면 가맹점 수정 요청을 보내지 않는다. */}
	194	+ <input type="hidden" name="originalname" value={original.name} />
	195	+ <input type="hidden" name="originalphoneNumber" value={original.phoneNumber} />
	196	+ <input type="hidden" name="originalpostalCode" value={original.postalCode} />
	197	+ <input type="hidden" name="originaladdress" value={original.address} />
	198	+ <input type="hidden" name="originaladdressDetail" value={original.addressDetail} />
169	199
170	200	<FoxCard size="lg" title="기본 정보" className={styles.section}>
171	201	<div className={styles.grid}>
172	202	<div className={styles.fieldWide}>
173		- {pinned ? (
174		- <FoxInput size="md" label="업체명" requirement="required" value={pinned.name} readOnly state="view" />
175		- ) : (
176		- <>
177		- <FoxSelect
178		- size="md"
179		- label="업체명"
180		- requirement="required"
181		- placeholder="상세를 등록할 가맹점 선택"
182		- options={candidates.map((row) => ({ value: row.id, label: row.name }))}
183		- value={frcsNo}
184		- onValueChange={setFrcsNo}
185		- error={Boolean(errors.frcsNo)}
186		- />
187		- {errors.frcsNo && <FoxHelperText type="danger" message={errors.frcsNo} />}
188		- {candidates.length === 0 && (
189		- <FoxHelperText
190		- type="information"
191		- message="상세를 붙일 가맹점이 없습니다. 모든 가맹점에 상세가 등록돼 있습니다."
192		- />
193		- )}
194		- </>
195		- )}
	203	+ <FoxInput
	204	+ size="md"
	205	+ name="name"
	206	+ label="업체명"
	207	+ requirement="required"
	208	+ placeholder="예) 타볼라타"
	209	+ defaultValue={original.name}
	210	+ maxLength={MERCHANT_NAME_MAX_LENGTH}
	211	+ invalid={Boolean(errors.name)}
	212	+ message={errors.name}
	213	+ />
196	214	</div>
197	215	<div className={styles.field}>
198	216	<FoxSelect
...	...	@@ -211,24 +229,62 @@
211	229	<div className={styles.field}>
212	230	<FoxInput
213	231	size="md"
	232	+ name="phoneNumber"
214	233	label="업체 연락처"
215	234	requirement="required"
216		- value={formatOptionalValue(formatPhoneNumber(merchant?.phoneNumber ?? null))}
217		- readOnly
218		- state="view"
	235	+ placeholder="0507-1413-6625"
	236	+ defaultValue={original.phoneNumber}
	237	+ invalid={Boolean(errors.phoneNumber)}
	238	+ message={errors.phoneNumber}
219	239	/>
220	240	</div>
221	241	</div>
222	242
223	243	<div className={styles.grid}>
224	244	<div className={styles.fieldNarrow}>
225		- <FoxInput size="md" label="우편번호" requirement="required" value={formatOptionalValue(merchant?.postalCode)} readOnly state="view" />
	245	+ <FoxInput
	246	+ size="md"
	247	+ name="postalCode"
	248	+ label="우편번호"
	249	+ requirement="required"
	250	+ placeholder="00000"
	251	+ value={postalCode}
	252	+ onChange={setPostalCode}
	253	+ invalid={Boolean(errors.postalCode)}
	254	+ message={errors.postalCode}
	255	+ />
	256	+ </div>
	257	+ <div className={styles.searchButton}>
	258	+ <FoxButton
	259	+ type="default"
	260	+ size="md"
	261	+ label={isSearching ? '검색 중...' : '주소 검색'}
	262	+ disabled={isSearching}
	263	+ onAction={searchAddress}
	264	+ />
226	265	</div>
227	266	<div className={styles.fieldWide}>
228		- <FoxInput size="md" label="주소" value={formatOptionalValue(merchant?.address)} readOnly state="view" />
	267	+ <FoxInput
	268	+ size="md"
	269	+ name="address"
	270	+ label="주소"
	271	+ placeholder="도로명 주소 (검색 결과 자동 입력)"
	272	+ value={address}
	273	+ onChange={setAddress}
	274	+ maxLength={ADDRESS_MAX_LENGTH}
	275	+ invalid={Boolean(errors.address)}
	276	+ message={errors.address}
	277	+ />
229	278	</div>
230	279	<div className={styles.field}>
231		- <FoxInput size="md" label="상세주소" value={formatOptionalValue(merchant?.addressDetail)} readOnly state="view" />
	280	+ <FoxInput
	281	+ size="md"
	282	+ name="addressDetail"
	283	+ label="상세주소"
	284	+ placeholder="건물명 · 층 · 호"
	285	+ defaultValue={original.addressDetail}
	286	+ maxLength={ADDRESS_MAX_LENGTH}
	287	+ />
232	288	</div>
233	289	</div>
234	290

...	...	@@ -1,21 +1,16 @@
1	1	import type { Metadata } from 'next';
2	2	import { verifySession } from '@/lib/auth/dal';
3	3	import { fetchCommonCodes } from '@/lib/data/repositories/common-code-repository';
4		-import { fetchMerchantDetailCandidates } from '@/lib/data/repositories/merchant-detail-repository';
5	4	import { CODE_GROUP } from '@/lib/domain/common-code';
6	5	import { MerchantDetailForm } from '../[frcsNo]/_components/merchant-detail-form';
7	6
8	7	export const metadata: Metadata = { title: '가맹몰 상세 정보' };
9	8	export const dynamic = 'force-dynamic';
10	9
11		-/** 등록 진입 — 아직 상세가 없는 가맹점 중 하나를 골라 상세를 붙인다. */
	10	+/** 등록 진입 — 업체(가맹점)와 상세를 함께 새로 만든다. */
12	11	export default async function Page() {
13	12	await verifySession();
14	13
15		- const [candidates, categories] = await Promise.all([
16		- fetchMerchantDetailCandidates(),
17		- fetchCommonCodes(CODE_GROUP.merchantType),
18		- ]);
19		-
20		- return <MerchantDetailForm candidates={candidates} categories={categories} />;
	14	+ const categories = await fetchCommonCodes(CODE_GROUP.merchantType);
	15	+ return <MerchantDetailForm categories={categories} />;
21	16	}

...	...	@@ -1,22 +1,14 @@
1	1	'use server';
2	2
	3	+import { revalidatePath } from 'next/cache';
	4	+import { unstable_rethrow } from 'next/navigation';
3	5	import { verifySession } from '@/lib/auth/dal';
4		-import {
5		- validateMerchant,
6		- type MerchantFormState,
7		-} from '@/lib/domain/merchant-form';
	6	+import { BackendRequestError } from '@/lib/http/backend-fetch';
	7	+import { createMerchant, updateMerchant } from '@/lib/data/repositories/merchant-repository';
	8	+import { validateMerchant, type MerchantFormState } from '@/lib/domain/merchant-form';
	9	+import { MERCHANTS_PATH } from '@/lib/domain/merchant-query';
8	10
9		-/**
10		- * TODO(백엔드): 등록이 자체 저장에서 BizPlay 외부 가맹점 등록 API 위임으로 바뀌었다 —
11		- * `POST /api/v1/mngr/voc`가 @RequestBody(JSON)가 되고 `bizPlayVocApiService.insertVoc`를
12		- * 부른다. 예금주명·입금은행코드·입금계좌번호·업태코드가 새로 필수인데 이 폼은 받지 않는다.
13		- * 항목이 정해질 때까지 등록을 막는다.
14		- *
15		- * 화면의 [등록] 버튼만 비활성화하면 막은 것이 아니다 — Server Action은 UI를 거치지 않고도
16		- * 직접 호출된다. 그래서 저장 직전에서 끊는다.
17		- */
18		-const DISABLED_MESSAGE =
19		- '가맹점 등록은 현재 사용할 수 없습니다. 등록 항목이 확정되면 다시 열립니다.';
	11	+const SAVE_FAILED_MESSAGE = '저장하지 못했습니다. 잠시 후 다시 시도해 주세요.';
20	12
21	13	function readString(formData: FormData, key: string): string {
22	14	const value = formData.get(key);
...	...	@@ -43,11 +35,31 @@
43	35	postalCode: readString(formData, 'postalCode'),
44	36	latitude: readString(formData, 'latitude'),
45	37	longitude: readString(formData, 'longitude'),
	38	+ bankHolderName: readString(formData, 'bankHolderName'),
	39	+ bankCode: readString(formData, 'bankCode'),
	40	+ accountNumber: readString(formData, 'accountNumber'),
	41	+ businessStatusCode: readString(formData, 'businessStatusCode'),
	42	+ divisionCode: readString(formData, 'divisionCode'),
46	43	isVisible: readString(formData, 'isVisible') === 'Y',
47	44	});
48	45	if (!validation.ok) {
49	46	return { status: 'error', errors: validation.errors };
50	47	}
51	48
52		- return { status: 'error', message: DISABLED_MESSAGE };
	49	+ try {
	50	+ if (validation.values.id) {
	51	+ await updateMerchant(validation.values.id, validation.values);
	52	+ } else {
	53	+ await createMerchant(validation.values);
	54	+ }
	55	+ } catch (error) {
	56	+ unstable_rethrow(error);
	57	+ console.error('[merchants] 저장 실패', error);
	58	+ const message =
	59	+ error instanceof BackendRequestError && error.message ? error.message : SAVE_FAILED_MESSAGE;
	60	+ return { status: 'error', message };
	61	+ }
	62	+
	63	+ revalidatePath(MERCHANTS_PATH);
	64	+ return { status: 'success' };
53	65	}

...	...	@@ -17,10 +17,11 @@
17	17	import { FoxSelect } from '@fox/core/components/fox-select';
18	18	import { submitFormAction } from '@/app/_hooks/submit-form-action';
19	19	import { useFeedback } from '@/app/_hooks/use-feedback';
20		-import type { CommonCode } from '@/lib/domain/common-code';
21	20	import {
	21	+ DEFAULT_MERCHANT_DIVISION_CODE,
22	22	formatOptionalValue,
23	23	type Merchant,
	24	+ type MerchantCodeTables,
24	25	} from '@/lib/domain/merchant';
25	26	import {
26	27	ADDRESS_DETAIL_MAX_LENGTH,
...	...	@@ -28,32 +29,27 @@
28	29	INITIAL_MERCHANT_FORM_STATE,
29	30	MEMO_MAX_LENGTH,
30	31	NAME_MAX_LENGTH,
	32	+ ACCOUNT_NUMBER_MAX_LENGTH,
31	33	OWNER_MAX_LENGTH,
32	34	} from '@/lib/domain/merchant-form';
33	35	import { saveMerchantAction } from '../_actions';
34		-import { openPostcodeSearch } from './postcode';
	36	+import { openPostcodeSearch } from '@/app/_components/postcode';
35	37	import styles from './merchant-form.module.scss';
36		-
37		-/**
38		- * 백엔드에 가맹점 수정 API가 없어(`/api/v1/mngr/voc`는 목록·등록뿐) 수정 모달을 조회
39		- * 전용으로 연다. API가 생기면 이 한 줄만 `true`로 바꾸면 된다 — 입력칸·저장 버튼이
40		- * 전부 이 값에 걸려 있고 폼 자체는 그대로 살아 있다.
41		- */
42		-const IS_EDIT_ENABLED = false;
43	38
44	39	interface MerchantFormModalProps {
45	40	merchant?: Merchant;
46		- /** 업종 코드표 — 선택지이자 조회 전용일 때의 이름 출처. */
47		- businessCodes: CommonCode[];
	41	+ /** 업종·업태·구분·은행 코드표 — 선택지. */
	42	+ codeTables: MerchantCodeTables;
48	43	onClose: () => void;
49	44	}
50	45
51		-export function MerchantFormModal({ merchant, businessCodes, onClose }: MerchantFormModalProps) {
	46	+/**
	47	+ * 가맹몰(가맹점) 등록·수정 모달 — 기획 MCH_002_p·MCH_003_p. 모든 항목을 고칠 수 있다(사용자 확정).
	48	+ * 요청은 백엔드 `MngrVocInsertReqVo`/`MngrVocUpdateReqVo`대로 보낸다 — 지금은 BizPlay(웹캐시)로
	49	+ * 위임되고 곧 우리 DB 저장으로 바뀐다.
	50	+ */
	51	+export function MerchantFormModal({ merchant, codeTables, onClose }: MerchantFormModalProps) {
52	52	const isEdit = Boolean(merchant);
53		- const isReadOnly = isEdit && !IS_EDIT_ENABLED;
54		- // 조회 전용일 때 입력칸마다 얹는다. `state="view"`는 시안의 조회 상태로, 잠긴 것(disabled)과
55		- // 달리 "볼 수만 있는 값"으로 보이게 한다.
56		- const viewProps = isReadOnly ? ({ readOnly: true, state: 'view' } as const) : null;
57	53	const { showToast } = useFeedback();
58	54	const formRef = useRef<HTMLFormElement>(null);
59	55	const [state, formAction, isPending] = useActionState(
...	...	@@ -62,12 +58,17 @@
62	58	);
63	59
64	60	const [categoryCode, setCategoryCode] = useState(merchant?.categoryCode ?? '');
	61	+ const [businessStatusCode, setBusinessStatusCode] = useState(merchant?.businessStatusCode ?? '');
	62	+ const [divisionCode, setDivisionCode] = useState(
	63	+ merchant?.divisionCode \|\| DEFAULT_MERCHANT_DIVISION_CODE
	64	+ );
	65	+ const [bankCode, setBankCode] = useState('');
65	66	// 조회 응답에 useYn이 없어 기존 가맹점은 값을 모른다 — 그때는 어느 쪽도 고르지 않는다.
66	67	// 신규 등록만 「노출」로 시작한다.
67	68	const [isVisible, setIsVisible] = useState<boolean \| null>(
68	69	merchant === undefined ? true : merchant.isVisible
69	70	);
70		- // 주소·좌표는 검색 결과가 채운다(기획 ③ Read Only).
	71	+ // 주소·우편번호는 검색으로 채우거나 직접 고친다. 좌표는 검색 결과만 채운다.
71	72	const [address, setAddress] = useState(merchant?.address ?? '');
72	73	const [postalCode, setPostalCode] = useState(merchant?.postalCode ?? '');
73	74	const [latitude, setLatitude] = useState(merchant?.latitude ?? '');
...	...	@@ -123,23 +124,19 @@
123	124	dismissible={false}
124	125	open
125	126	size="md"
126		- title={isReadOnly ? '가맹점 정보' : isEdit ? '가맹점 수정' : '가맹점 등록'}
	127	+ title={isEdit ? '가맹몰 수정' : '가맹몰 등록'}
127	128	onClose={onClose}
128	129	actions={
129		- isReadOnly ? (
130		- <FoxButton type="default" size="md" label="닫기" onAction={onClose} />
131		- ) : (
132		- <>
133		- <FoxButton type="default" size="md" label="취소" onAction={onClose} />
134		- <FoxButton
135		- type="primary"
136		- size="md"
137		- label={isPending ? '저장 중...' : isEdit ? '수정' : '등록'}
138		- disabled={isPending}
139		- onAction={() => formRef.current?.requestSubmit()}
140		- />
141		- </>
142		- )
	130	+ <>
	131	+ <FoxButton type="default" size="md" label="취소" onAction={onClose} />
	132	+ <FoxButton
	133	+ type="primary"
	134	+ size="md"
	135	+ label={isPending ? '저장 중...' : isEdit ? '수정' : '등록'}
	136	+ disabled={isPending}
	137	+ onAction={() => formRef.current?.requestSubmit()}
	138	+ />
	139	+ </>
143	140	}
144	141	>
145	142	<form
...	...	@@ -149,9 +146,10 @@
149	146	>
150	147	<input type="hidden" name="id" value={merchant?.id ?? ''} />
151	148	<input type="hidden" name="categoryCode" value={categoryCode} />
	149	+ <input type="hidden" name="businessStatusCode" value={businessStatusCode} />
	150	+ <input type="hidden" name="divisionCode" value={divisionCode} />
	151	+ <input type="hidden" name="bankCode" value={bankCode} />
152	152	<input type="hidden" name="isVisible" value={isVisible ? 'Y' : 'N'} />
153		- <input type="hidden" name="address" value={address} />
154		- <input type="hidden" name="postalCode" value={postalCode} />
155	153	<input type="hidden" name="latitude" value={latitude} />
156	154	<input type="hidden" name="longitude" value={longitude} />
157	155
...	...	@@ -172,7 +170,6 @@
172	170	항목이라 화면에서는 지우지 않고, 값이 없으면 `-`로 보여준다(사용자 확정). */}
173	171	<div className={styles.field}>
174	172	<FoxInput
175		- {...viewProps}
176	173	size="md"
177	174	name="brandName"
178	175	label="브랜드명"
...	...	@@ -184,7 +181,6 @@
184	181
185	182	<div className={styles.field}>
186	183	<FoxInput
187		- {...viewProps}
188	184	size="md"
189	185	name="name"
190	186	label="가맹점명"
...	...	@@ -198,25 +194,44 @@
198	194	</div>
199	195
200	196	<div className={styles.field}>
	197	+ <div className={styles.pair}>
	198	+ <FoxSelect
	199	+ size="md"
	200	+ label="업종"
	201	+ requirement="required"
	202	+ options={codeTables.business.map((code) => ({ value: code.code, label: code.label }))}
	203	+ value={categoryCode}
	204	+ onValueChange={setCategoryCode}
	205	+ placeholder="선택"
	206	+ error={Boolean(errors.categoryCode)}
	207	+ hint={errors.categoryCode}
	208	+ />
	209	+ <FoxSelect
	210	+ size="md"
	211	+ label="업태"
	212	+ options={codeTables.businessStatus.map((code) => ({ value: code.code, label: code.label }))}
	213	+ value={businessStatusCode}
	214	+ onValueChange={setBusinessStatusCode}
	215	+ placeholder="선택"
	216	+ />
	217	+ </div>
	218	+ </div>
	219	+
	220	+ <div className={styles.field}>
201	221	<FoxSelect
202		- readOnly={isReadOnly}
203	222	size="md"
204		- label="업종"
205		- requirement="required"
206		- options={businessCodes.map((code) => ({ value: code.code, label: code.label }))}
207		- value={categoryCode}
208		- onValueChange={setCategoryCode}
	223	+ label="가맹점 구분"
	224	+ options={codeTables.division.map((code) => ({ value: code.code, label: code.label }))}
	225	+ value={divisionCode}
	226	+ onValueChange={setDivisionCode}
209	227	placeholder="선택"
210		- error={Boolean(errors.categoryCode)}
211		- hint={errors.categoryCode}
212	228	/>
213	229	</div>
214	230
215	231	<div className={styles.field}>
216	232	<div className={styles.pair}>
217	233	<FoxInput
218		- {...viewProps}
219		- size="md"
	234	+ size="md"
220	235	name="businessNumber"
221	236	label="사업자등록번호"
222	237	defaultValue={merchant?.businessNumber ?? ''}
...	...	@@ -225,8 +240,7 @@
225	240	message={errors.businessNumber}
226	241	/>
227	242	<FoxInput
228		- {...viewProps}
229		- size="md"
	243	+ size="md"
230	244	name="ownerName"
231	245	label="대표자명"
232	246	defaultValue={merchant?.ownerName ?? ''}
...	...	@@ -238,7 +252,6 @@
238	252
239	253	<div className={styles.field}>
240	254	<FoxInput
241		- {...viewProps}
242	255	size="md"
243	256	name="phoneNumber"
244	257	label="전화번호"
...	...	@@ -257,24 +270,31 @@
257	270	<div className={styles.addressRow}>
258	271	<FoxInput
259	272	size="md"
260		- aria-label="주소"
261		- value={address}
262		- readOnly
263		- state="view"
264		- placeholder="주소 검색을 진행해주세요."
	273	+ name="postalCode"
	274	+ aria-label="우편번호"
	275	+ value={postalCode}
	276	+ onChange={setPostalCode}
	277	+ placeholder="우편번호"
	278	+ invalid={Boolean(errors.postalCode)}
	279	+ message={errors.postalCode}
265	280	/>
266		- {!isReadOnly && (
267		- <FoxButton
268		- type="secondary"
269		- size="md"
270		- label={isSearching ? '검색 중...' : '주소 검색'}
271		- disabled={isSearching}
272		- onAction={searchAddress}
273		- />
274		- )}
	281	+ <FoxButton
	282	+ type="secondary"
	283	+ size="md"
	284	+ label={isSearching ? '검색 중...' : '주소 검색'}
	285	+ disabled={isSearching}
	286	+ onAction={searchAddress}
	287	+ />
275	288	</div>
276	289	<FoxInput
277		- {...viewProps}
	290	+ size="md"
	291	+ name="address"
	292	+ aria-label="주소"
	293	+ value={address}
	294	+ onChange={setAddress}
	295	+ placeholder="주소 검색으로 채우거나 직접 입력하세요."
	296	+ />
	297	+ <FoxInput
278	298	size="md"
279	299	name="addressDetail"
280	300	aria-label="상세주소"
...	...	@@ -310,19 +330,47 @@
310	330	</div>
311	331
312	332	<div className={styles.field}>
	333	+ <FoxFormLabel as="span">정산 계좌</FoxFormLabel>
	334	+ <div className={styles.pair}>
	335	+ <FoxSelect
	336	+ size="md"
	337	+ aria-label="입금 은행"
	338	+ options={codeTables.bank.map((code) => ({ value: code.code, label: code.label }))}
	339	+ value={bankCode}
	340	+ onValueChange={setBankCode}
	341	+ placeholder="은행 선택"
	342	+ />
	343	+ <FoxInput
	344	+ size="md"
	345	+ name="bankHolderName"
	346	+ aria-label="예금주명"
	347	+ placeholder="예금주명"
	348	+ maxLength={OWNER_MAX_LENGTH}
	349	+ />
	350	+ </div>
	351	+ <FoxInput
	352	+ size="md"
	353	+ name="accountNumber"
	354	+ aria-label="입금계좌번호"
	355	+ placeholder="입금계좌번호 (숫자와 -)"
	356	+ maxLength={ACCOUNT_NUMBER_MAX_LENGTH}
	357	+ invalid={Boolean(errors.accountNumber)}
	358	+ message={errors.accountNumber}
	359	+ />
	360	+ </div>
	361	+
	362	+ <div className={styles.field}>
313	363	<FoxFormLabel as="span" requirement="required">
314	364	사용여부
315	365	</FoxFormLabel>
316	366	<FoxRadioGroup name="visibility" size="md" label="사용여부">
317	367	<FoxRadio
318		- disabled={isReadOnly}
319	368	value="Y"
320	369	label="노출"
321	370	checked={isVisible === true}
322	371	onChange={() => setIsVisible(true)}
323	372	/>
324	373	<FoxRadio
325		- disabled={isReadOnly}
326	374	value="N"
327	375	label="미노출"
328	376	checked={isVisible === false}
...	...	@@ -333,7 +381,6 @@
333	381
334	382	<div className={styles.field}>
335	383	<FoxInput
336		- {...viewProps}
337	384	size="md"
338	385	name="memo"
339	386	label="메모"

...	...	@@ -1,6 +1,7 @@
1	1	'use client';
2	2
3	3	import { useRouter } from 'next/navigation';
	4	+import { useState } from 'react';
4	5	import { FoxButton } from '@fox/core/components/fox-button';
5	6	import {
6	7	FoxListContainer,
...	...	@@ -9,13 +10,13 @@
9	10	import { FoxSelect } from '@fox/core/components/fox-select';
10	11	import { FoxSelectText } from '@fox/core/components/fox-select-text';
11	12	import { FoxStatusIndicator } from '@fox/core/components/fox-status-indicator';
12		-import type { CommonCode } from '@/lib/domain/common-code';
13	13	import {
14	14	formatAddressSummary,
15	15	formatCategoryLabel,
16	16	formatOptionalValue,
17	17	formatVisibilityLabel,
18	18	type Merchant,
	19	+ type MerchantCodeTables,
19	20	} from '@/lib/domain/merchant';
20	21	import {
21	22	MERCHANTS_EXCEL_PATH,
...	...	@@ -27,13 +28,14 @@
27	28	type MerchantQuery,
28	29	type MerchantSearchField,
29	30	} from '@/lib/domain/merchant-query';
	31	+import { MerchantFormModal } from './merchant-form-modal';
30	32	import { MerchantRowActions } from './merchant-row-actions';
31	33	import styles from './merchant-filter.module.scss';
32	34
33	35	interface MerchantListProps {
34	36	items: Merchant[];
35		- /** 업종 코드표(`FRCS_TPBIZ_CD` 다음 `FRCS_CD`) — 업종 열과 상세 모달이 이름을 찾는다. */
36		- businessCodes: CommonCode[];
	37	+ /** 업종(열·모달)·업태·구분·은행 코드표 — 등록·수정 모달의 선택지. */
	38	+ codeTables: MerchantCodeTables;
37	39	query: MerchantQuery;
38	40	currentPage: number;
39	41	totalPages: number;
...	...	@@ -45,13 +47,14 @@
45	47
46	48	export function MerchantList({
47	49	items,
48		- businessCodes,
	50	+ codeTables,
49	51	query,
50	52	currentPage,
51	53	totalPages,
52	54	totalCount,
53	55	}: MerchantListProps) {
54	56	const router = useRouter();
	57	+ const [isCreateOpen, setIsCreateOpen] = useState(false);
55	58
56	59	function go(patch: Partial<MerchantQuery>) {
57	60	router.replace(buildMerchantHref(query, { ...patch, page: 1 }));
...	...	@@ -76,7 +79,7 @@
76	79	key: 'categoryCode',
77	80	header: '업종',
78	81	width: 100,
79		- render: (row) => formatCategoryLabel(businessCodes, row.categoryCode),
	82	+ render: (row) => formatCategoryLabel(codeTables.business, row.categoryCode),
80	83	},
81	84	{
82	85	key: 'phoneNumber',
...	...	@@ -114,7 +117,7 @@
114	117	key: 'actions',
115	118	header: '관리',
116	119	width: 120,
117		- render: (row) => <MerchantRowActions merchant={row} businessCodes={businessCodes} />,
	120	+ render: (row) => <MerchantRowActions merchant={row} codeTables={codeTables} />,
118	121	},
119	122	];
120	123
...	...	@@ -203,10 +206,6 @@
203	206	label="엑셀다운로드"
204	207	/>
205	208	</form>
206		- {/* TODO(백엔드): 등록이 자체 저장에서 BizPlay 외부 가맹점 등록 API 위임으로 바뀌었다
207		- (`POST /api/v1/mngr/voc`가 @RequestBody JSON이 되고 bizPlayVocApiService.insertVoc를
208		- 부른다). 예금주명·입금은행코드·입금계좌번호·업태코드가 새로 필요한데 이 폼은 받지
209		- 않는다. 항목이 정해지면 MerchantFormModal과 함께 다시 연다. */}
210	209	<FoxButton
211	210	type="primary"
212	211	size="md"
...	...	@@ -214,7 +213,7 @@
214	213	<i className="fox-ico fox-ico-Plus" aria-hidden="true" />
215	214	}
216	215	label="등록"
217		- disabled
	216	+ onAction={() => setIsCreateOpen(true)}
218	217	/>
219	218	</>
220	219	}
...	...	@@ -233,6 +232,10 @@
233	232	}
234	233	}}
235	234	/>
	235	+
	236	+ {isCreateOpen && (
	237	+ <MerchantFormModal codeTables={codeTables} onClose={() => setIsCreateOpen(false)} />
	238	+ )}
236	239	</>
237	240	);
238	241	}

...	...	@@ -4,27 +4,24 @@
4	4	import { FoxButtonGroup } from '@fox/core/components/fox-button-group';
5	5	import { FoxIconButton } from '@fox/core/components/fox-icon-button';
6	6	import { useFeedback } from '@/app/_hooks/use-feedback';
7		-import type { CommonCode } from '@/lib/domain/common-code';
8		-import type { Merchant } from '@/lib/domain/merchant';
	7	+import type { Merchant, MerchantCodeTables } from '@/lib/domain/merchant';
9	8	import { MerchantFormModal } from './merchant-form-modal';
10	9
11	10	interface MerchantRowActionsProps {
12	11	merchant: Merchant;
13		- businessCodes: CommonCode[];
	12	+ codeTables: MerchantCodeTables;
14	13	}
15	14
16	15	/**
17		- * 수정은 모달을 열어 등록된 내용을 보여 준다 — 백엔드에 수정 API가 없어 모달이 조회
18		- * 전용으로 뜬다(`merchant-form-modal.tsx`의 `IS_EDIT_ENABLED`). API가 생기면 그 한 줄만
19		- * 바꾸면 여기는 손대지 않아도 된다.
	16	+ * 수정은 모달을 열어 고친다(`PUT /api/v1/mngr/voc`).
20	17	*
21		- * TODO(백엔드): 삭제 API도 없다(`/api/v1/mngr/voc`는 목록·등록뿐). 시안의 자리는 두되
22		- * 눌러도 할 수 있는 일이 없어 사유를 알린다.
	18	+ * TODO(백엔드): 삭제 API가 없다(`/api/v1/mngr/voc/{frcsNo}` DELETE는 가맹몰 상세를 지운다). 시안의
	19	+ * 자리는 두되 눌러도 할 수 있는 일이 없어 사유를 알린다.
23	20	*
24	21	* 어느 행의 버튼인지는 각 버튼 라벨이 말한다 — 감싼 요소의 `aria-label`은 의미 없는
25	22	* 요소에 붙어 읽히지 않을 수 있다(공통코드 행과 같은 방식).
26	23	*/
27		-export function MerchantRowActions({ merchant, businessCodes }: MerchantRowActionsProps) {
	24	+export function MerchantRowActions({ merchant, codeTables }: MerchantRowActionsProps) {
28	25	const { showToast } = useFeedback();
29	26	const [isDetailOpen, setIsDetailOpen] = useState(false);
30	27
...	...	@@ -55,7 +52,7 @@
55	52	{isDetailOpen && (
56	53	<MerchantFormModal
57	54	merchant={merchant}
58		- businessCodes={businessCodes}
	55	+ codeTables={codeTables}
59	56	onClose={() => setIsDetailOpen(false)}
60	57	/>
61	58	)}

...	...	@@ -3,6 +3,7 @@
3	3	import { fetchCommonCodes } from '@/lib/data/repositories/common-code-repository';
4	4	import { fetchMerchants } from '@/lib/data/repositories/merchant-repository';
5	5	import { CODE_GROUP } from '@/lib/domain/common-code';
	6	+import type { MerchantCodeTables } from '@/lib/domain/merchant';
6	7	import { parseMerchantQuery } from '@/lib/domain/merchant-query';
7	8	import { MerchantList } from './_components/merchant-list';
8	9
...	...	@@ -20,13 +21,22 @@
20	21	await verifySession();
21	22
22	23	const query = parseMerchantQuery(await searchParams);
23		- const [{ items, totalCount }, business, businessDetail] = await Promise.all([
24		- fetchMerchants(query),
25		- fetchCommonCodes(CODE_GROUP.merchantBusiness),
26		- fetchCommonCodes(CODE_GROUP.merchantBusinessDetail),
27		- ]);
28		- // 앞쪽 표가 먼저 맞는다 — 2자리 값은 FRCS_TPBIZ_CD에서, 4자리 값은 FRCS_CD에서 이름을 찾는다.
29		- const businessCodes = [...business, ...businessDetail];
	24	+ const [{ items, totalCount }, business, businessDetail, businessStatus, division, bank] =
	25	+ await Promise.all([
	26	+ fetchMerchants(query),
	27	+ fetchCommonCodes(CODE_GROUP.merchantBusiness),
	28	+ fetchCommonCodes(CODE_GROUP.merchantBusinessDetail),
	29	+ fetchCommonCodes(CODE_GROUP.merchantBusinessStatus),
	30	+ fetchCommonCodes(CODE_GROUP.merchantDivision),
	31	+ fetchCommonCodes(CODE_GROUP.bank),
	32	+ ]);
	33	+ const codeTables: MerchantCodeTables = {
	34	+ // 앞쪽 표가 먼저 맞는다 — 2자리 값은 FRCS_TPBIZ_CD에서, 4자리 값은 FRCS_CD에서 이름을 찾는다.
	35	+ business: [...business, ...businessDetail],
	36	+ businessStatus,
	37	+ division,
	38	+ bank,
	39	+ };
30	40
31	41	const totalPages = Math.max(1, Math.ceil(totalCount / query.pageSize));
32	42	const currentPage = Math.min(query.page, totalPages);
...	...	@@ -34,7 +44,7 @@
34	44	return (
35	45	<MerchantList
36	46	items={items}
37		- businessCodes={businessCodes}
	47	+ codeTables={codeTables}
38	48	query={query}
39	49	currentPage={currentPage}
40	50	totalPages={totalPages}

...	...	@@ -14,13 +14,15 @@
14	14	*
15	15	* ```
16	16	* GET /api/v1/mngr/voc/pagination searchCondition 1=가맹점명 2=사업자번호 3=상세주소
17		- * POST /api/v1/mngr/voc 어노테이션 없음 → form
	17	+ * POST /api/v1/mngr/voc @RequestBody MngrVocInsertReqVo
	18	+ * PUT /api/v1/mngr/voc @RequestBody MngrVocUpdateReqVo (BaseVo + chgDvCd)
18	19	* ```
19	20	*
20	21	* ⚠️ 백엔드 현황(보고함)
21		- * 1. 등록이 아직 동작하지 않는다. 컨트롤러 `insert`의 본문이 전부 주석 처리돼 있고
22		- * `return null;`이다 — 봉투 없는 빈 200이 온다. 그래서 저장해도 아무 일도 일어나지 않는다.
23		- * 2. 수정·삭제·단건 조회 API가 없다. 목록과 등록 두 개뿐이다.
	22	+ * 1. 등록·수정은 아직 BizPlay(웹캐시) 가맹점 API로 위임된다(1c7b0e0). 우리 DB에 저장하도록
	23	+ * 바뀔 예정(사용자 공지)이라 요청은 그 VO 그대로 보내고, 응답에서 `frcsNo`가 오면 읽고 없으면
	24	+ * 가맹점 목록에서 찾는다. 위임 상태에선 새 가맹점이 다음 날 동기화 뒤에야 목록에 나타난다.
	25	+ * 2. 삭제·단건 조회 API가 없다.
24	26	* 3. 검색 필터가 어긋난다 — 업종 검색 파라미터는 `searchFrcsTpbizCd`인데 SQL은 `FRCS_DV_CD`를
25	27	* 비교하고, 저장은 `frcsTpbizCd`로 받는다. 저장한 업종으로 검색이 걸리지 않는다.
26	28	* 4. 목록 정렬이 이중 역순이다 — rnum이 등록일 내림차순인데 `ORDER BY RNUM DESC`로 다시
...	...	@@ -83,6 +85,8 @@
83	85	postalCode: readString(raw, 'frcsPostZip'),
84	86	latitude: readString(raw, 'lat'),
85	87	longitude: readString(raw, 'lng'),
	88	+ businessStatusCode: readString(raw, 'frcsBzstatCd').trim(),
	89	+ divisionCode: readString(raw, 'frcsDvCd').trim(),
86	90	// 조회 SQL이 USE_YN을 select하지 않는다(⚠️ 5). 값이 없으면 판단하지 않는다 —
87	91	// 종전처럼 노출로 단정하면 「미노출」로 걸러 낸 행까지 전부 「노출」로 보인다.
88	92	isVisible: readUseYn(raw),
...	...	@@ -163,35 +167,72 @@
163	167	: [];
164	168	}
165	169
166		-/**
167		- * TODO(백엔드): 아래 form 전송은 옛 계약이다. 지금 `POST /api/v1/mngr/voc`는 @RequestBody(JSON)
168		- * `MngrVocInsertReqVo`를 받고 BizPlay 외부 API로 위임하며, 예금주명(bankDpstrNm)·입금은행코드
169		- * (dpstBankCd)·입금계좌번호(dpstActNo)·업태코드(frcsBzstatCd)를 새로 요구한다. lat·lng는 요청
170		- * VO에서 빠졌다. 등록 화면이 그 항목을 받게 되면 이 함수를 JSON으로 바꿔 다시 연결한다
171		- * (현재 호출부 없음 — `_actions.ts` 참고).
172		- */
173		-export async function createMerchant(values: MerchantValues): Promise<void> {
	170	+/** 백엔드 `MngrVocBaseVo` — 등록·수정 요청이 함께 쓰는 가맹점 필드. */
	171	+function toMerchantPayload(values: MerchantValues): Record<string, unknown> {
	172	+ return {
	173	+ frcsNm: values.name,
	174	+ rprsvNm: values.ownerName,
	175	+ rprsvTelno: values.phoneNumber,
	176	+ brno: values.businessNumber.replace(/-/g, ''),
	177	+ bankDpstrNm: values.bankHolderName,
	178	+ dpstBankCd: values.bankCode,
	179	+ // 등록 VO(BizPlayVocInsertVo)는 dpstActno, 수정 VO(MngrVocBaseVo)는 dpstActNo다 — 둘 다 싣는다.
	180	+ dpstActno: values.accountNumber,
	181	+ dpstActNo: values.accountNumber,
	182	+ frcsDvCd: values.divisionCode,
	183	+ frcsPostAddr: values.address,
	184	+ frcsDaddr: values.addressDetail,
	185	+ frcsPostZip: values.postalCode,
	186	+ [MERCHANT_CATEGORY_WRITE_FIELD]: values.categoryCode,
	187	+ frcsBzstatCd: values.businessStatusCode,
	188	+ // 요청 VO에 없어 무시된다. 컬럼이 생기면 그대로 저장되도록 미리 싣는다.
	189	+ useYn: values.isVisible ? 'Y' : 'N',
	190	+ brandNm: values.brandName,
	191	+ memo: values.memo,
	192	+ lat: values.latitude,
	193	+ lng: values.longitude,
	194	+ };
	195	+}
	196	+
	197	+/** 등록 응답에서 가맹점 코드를 찾는다 — 문자열, `frcsNo`, BizPlay 응답(`repRec.FRCS_NO`) 어느 모양이든. */
	198	+function readCreatedFrcsNo(data: unknown): string \| null {
	199	+ if (typeof data === 'string' && data !== '') return data;
	200	+ if (!isRecord(data)) return null;
	201	+ const direct = readString(data, 'frcsNo') \|\| readString(data, 'FRCS_NO');
	202	+ if (direct) return direct;
	203	+ const repRec = data.repRec;
	204	+ return isRecord(repRec) ? readString(repRec, 'FRCS_NO') \|\| readString(repRec, 'frcsNo') \|\| null : null;
	205	+}
	206	+
	207	+/** 가맹점 등록. 백엔드가 코드를 돌려주면 그 값, 아니면 null이다. */
	208	+export async function createMerchant(values: MerchantValues): Promise<string \| null> {
174	209	const accessToken = await getSessionAccessToken();
175	210
176	211	const result = await backendFetch<unknown>(VOC_PATH, {
177	212	method: 'POST',
178		- form: {
179		- frcsNm: values.name,
180		- [MERCHANT_CATEGORY_WRITE_FIELD]: values.categoryCode,
181		- // 요청 VO의 필드 이름이 대문자다(`private String BRNO`) — Spring이 그 이름으로 바인딩한다.
182		- BRNO: values.businessNumber,
183		- rprsvNm: values.ownerName,
184		- rprsvTelno: values.phoneNumber,
185		- frcsPostAddr: values.address,
186		- frcsDaddr: values.addressDetail,
187		- frcsPostZip: values.postalCode,
188		- lat: values.latitude,
189		- lng: values.longitude,
190		- useYn: values.isVisible ? 'Y' : 'N',
191		- // 요청 VO에 없어 무시된다. 컬럼이 생기면 그대로 저장되도록 미리 싣는다.
192		- brandNm: values.brandName,
193		- memo: values.memo,
194		- },
	213	+ body: toMerchantPayload(values),
	214	+ accessToken: accessToken ?? undefined,
	215	+ cache: 'no-store',
	216	+ canHaveNullData: true,
	217	+ canHaveEmptyBody: true,
	218	+ });
	219	+
	220	+ if (!result.ok) {
	221	+ throw new BackendRequestError(result);
	222	+ }
	223	+ return readCreatedFrcsNo(result.data);
	224	+}
	225	+
	226	+/**
	227	+ * 가맹점 수정. 수정 VO에는 `frcsNo`가 없다(BizPlay가 사업자번호로 식별) — 우리 DB 저장으로 바뀔 때를
	228	+ * 위해 `frcsNo`도 싣는다. `chgDvCd`(변경구분)는 BizPlay 전용이라 비워 보낸다.
	229	+ */
	230	+export async function updateMerchant(frcsNo: string, values: MerchantValues): Promise<void> {
	231	+ const accessToken = await getSessionAccessToken();
	232	+
	233	+ const result = await backendFetch<unknown>(VOC_PATH, {
	234	+ method: 'PUT',
	235	+ body: { frcsNo, chgDvCd: '', ...toMerchantPayload(values) },
195	236	accessToken: accessToken ?? undefined,
196	237	cache: 'no-store',
197	238	canHaveNullData: true,

...	...	@@ -51,6 +51,12 @@
51	51	merchantBusinessDetail: 'FRCS_CD',
52	52	/** 가맹몰 메뉴 배지 — 앱 API가 `frcsBadge`의 쉼표 구분 코드를 이 그룹 이름으로 풀어 준다(백엔드 40f85c4). */
53	53	merchantProductBadge: 'FRCS_BADGE_CD',
	54	+ /** 가맹점 업태(`FRCS_BZSTAT_CD`) — 등록 요청 VO의 `frcsBzstatCd`. */
	55	+ merchantBusinessStatus: 'FRCS_BZSTAT_CD',
	56	+ /** 가맹점 구분(`FRCS_DV_CD`: 60 온라인 · 62 일반) — 등록 요청 VO의 `frcsDvCd`. */
	57	+ merchantDivision: 'FRCS_DV_CD',
	58	+ /** 입금 은행 — 등록 요청 VO의 `dpstBankCd`. */
	59	+ bank: 'COM_BANK_CD',
54	60	} as const;
55	61
56	62	/** 값이 없는 항목의 화면 표기. */

...	...	@@ -3,16 +3,31 @@
3	3	/**
4	4	* 가맹몰 상세 등록·수정 입력 규칙 — 순수 검증만 담는다.
5	5	*
6		- * 기획 BO-MAL-002 ①의 필수 항목 중 업체명·연락처·우편번호는 가맹점 원본에서 오는 읽기 전용
7		- * 값이라 여기서 검사하지 않는다. 남는 필수는 카테고리·노출 상태·바우처 사용·대표이미지다.
	6	+ * 기획 BO-MAL-002 ①의 필수 항목은 업체명·카테고리·업체 연락처·우편번호·노출 상태·바우처 사용·
	7	+ * 대표이미지다. 업체 항목(업체명·연락처·우편번호·주소)은 이 화면에서 직접 입력한다(사용자 확정) —
	8	+ * 가맹점이 없으면 새로 만들고, 있으면 함께 고친다.
8	9	*/
9	10
10	11	export const DESCRIPTION_MAX_LENGTH = 200;
11	12	export const CLOSED_DAYS_MAX_LENGTH = 100;
12	13	export const SORT_ORDER_MAX = 9999;
	14	+export const MERCHANT_NAME_MAX_LENGTH = 100;
	15	+export const ADDRESS_MAX_LENGTH = 200;
13	16	const TIME_PATTERN = /^([01]\d\|2[0-3]):[0-5]\d$/;
	17	+const POSTAL_CODE_PATTERN = /^\d{5}$/;
	18	+const PHONE_PATTERN = /^[\d-]+$/;
14	19
15		-export type MerchantDetailValues = {
	20	+/** 상세 화면이 함께 다루는 업체(가맹점) 항목 — 백엔드 `MngrVocBaseVo`의 일부. */
	21	+export type MerchantDetailMerchantValues = {
	22	+ name: string;
	23	+ phoneNumber: string;
	24	+ postalCode: string;
	25	+ address: string;
	26	+ addressDetail: string;
	27	+};
	28	+
	29	+export type MerchantDetailValues = MerchantDetailMerchantValues & {
	30	+ /** 비어 있으면 가맹점을 새로 만든다. */
16	31	frcsNo: string;
17	32	categoryCode: string;
18	33	description: string;
...	...	@@ -29,7 +44,10 @@
29	44
30	45	export type MerchantDetailFormErrors = Partial<
31	46	Record<
32		- \| 'frcsNo'
	47	+ \| 'name'
	48	+ \| 'phoneNumber'
	49	+ \| 'postalCode'
	50	+ \| 'address'
33	51	\| 'categoryCode'
34	52	\| 'description'
35	53	\| 'openTime'
...	...	@@ -61,6 +79,33 @@
61	79	categories: readonly CommonCode[]
62	80	): ValidationResult {
63	81	const errors: MerchantDetailFormErrors = {};
	82	+
	83	+ const name = values.name.trim();
	84	+ if (!name) {
	85	+ errors.name = '업체명을 입력해 주세요.';
	86	+ } else if (name.length > MERCHANT_NAME_MAX_LENGTH) {
	87	+ errors.name = `업체명은 ${MERCHANT_NAME_MAX_LENGTH}자 이내로 입력해 주세요.`;
	88	+ }
	89	+
	90	+ const phoneNumber = values.phoneNumber.trim();
	91	+ if (!phoneNumber) {
	92	+ errors.phoneNumber = '업체 연락처를 입력해 주세요.';
	93	+ } else if (!PHONE_PATTERN.test(phoneNumber)) {
	94	+ errors.phoneNumber = '연락처는 숫자와 -만 입력할 수 있습니다.';
	95	+ }
	96	+
	97	+ const postalCode = values.postalCode.trim();
	98	+ if (!postalCode) {
	99	+ errors.postalCode = '우편번호를 입력해 주세요.';
	100	+ } else if (!POSTAL_CODE_PATTERN.test(postalCode)) {
	101	+ errors.postalCode = '우편번호는 숫자 5자리로 입력해 주세요.';
	102	+ }
	103	+
	104	+ const address = values.address.trim();
	105	+ const addressDetail = values.addressDetail.trim();
	106	+ if (address.length > ADDRESS_MAX_LENGTH \|\| addressDetail.length > ADDRESS_MAX_LENGTH) {
	107	+ errors.address = `주소는 ${ADDRESS_MAX_LENGTH}자 이내로 입력해 주세요.`;
	108	+ }
64	109
65	110	if (!categories.some((code) => code.code === values.categoryCode)) {
66	111	errors.categoryCode = '카테고리를 선택해 주세요.';
...	...	@@ -103,6 +148,17 @@
103	148	}
104	149	return {
105	150	ok: true,
106		- values: { ...values, description, openTime, closeTime, closedDays },
	151	+ values: {
	152	+ ...values,
	153	+ name,
	154	+ phoneNumber,
	155	+ postalCode,
	156	+ address,
	157	+ addressDetail,
	158	+ description,
	159	+ openTime,
	160	+ closeTime,
	161	+ closedDays,
	162	+ },
107	163	};
108	164	}

...	...	@@ -3,6 +3,7 @@
3	3	export const OWNER_MAX_LENGTH = 50;
4	4	export const ADDRESS_DETAIL_MAX_LENGTH = 200;
5	5	export const MEMO_MAX_LENGTH = 500;
	6	+export const ACCOUNT_NUMBER_MAX_LENGTH = 30;
6	7
7	8	export interface MerchantValues {
8	9	id: string;
...	...	@@ -19,11 +20,20 @@
19	20	postalCode: string;
20	21	latitude: string;
21	22	longitude: string;
	23	+ /** 백엔드 등록 요청 VO(`MngrVocInsertReqVo`)의 예금주명·입금은행코드·입금계좌번호·업태·구분. */
	24	+ bankHolderName: string;
	25	+ bankCode: string;
	26	+ accountNumber: string;
	27	+ businessStatusCode: string;
	28	+ divisionCode: string;
22	29	isVisible: boolean;
23	30	}
24	31
25	32	export type MerchantFormErrors = Partial<
26		- Record<'name' \| 'categoryCode' \| 'phoneNumber' \| 'address' \| 'businessNumber', string>
	33	+ Record<
	34	+ 'name' \| 'categoryCode' \| 'phoneNumber' \| 'address' \| 'postalCode' \| 'businessNumber' \| 'accountNumber',
	35	+ string
	36	+ >
27	37	>;
28	38
29	39	export type MerchantFormState =
...	...	@@ -64,12 +74,22 @@
64	74	}
65	75
66	76	if (!values.address.trim()) {
67		- errors.address = '주소 검색을 진행해 주세요.';
	77	+ errors.address = '주소를 검색하거나 입력해 주세요.';
	78	+ }
	79	+
	80	+ const postalCode = values.postalCode.trim();
	81	+ if (postalCode && !/^\d{5}$/.test(postalCode)) {
	82	+ errors.postalCode = '우편번호는 숫자 5자리로 입력해 주세요.';
68	83	}
69	84
70	85	const businessNumber = values.businessNumber.trim();
71	86	if (businessNumber && !BUSINESS_NUMBER_PATTERN.test(businessNumber)) {
72	87	errors.businessNumber = '사업자등록번호는 000-00-00000 형식으로 입력해 주세요.';
	88	+ }
	89	+
	90	+ const accountNumber = values.accountNumber.trim();
	91	+ if (accountNumber && !/^[\d-]+$/.test(accountNumber)) {
	92	+ errors.accountNumber = '계좌번호는 숫자와 -만 입력할 수 있습니다.';
73	93	}
74	94
75	95	if (Object.keys(errors).length > 0) {
...	...	@@ -88,6 +108,12 @@
88	108	businessNumber,
89	109	address: values.address.trim(),
90	110	addressDetail: values.addressDetail.trim().slice(0, ADDRESS_DETAIL_MAX_LENGTH),
	111	+ postalCode,
	112	+ bankHolderName: values.bankHolderName.trim().slice(0, OWNER_MAX_LENGTH),
	113	+ bankCode: values.bankCode.trim(),
	114	+ accountNumber: accountNumber.slice(0, ACCOUNT_NUMBER_MAX_LENGTH),
	115	+ businessStatusCode: values.businessStatusCode.trim(),
	116	+ divisionCode: values.divisionCode.trim(),
91	117	},
92	118	};
93	119	}

...	...	@@ -26,10 +26,26 @@
26	26	postalCode: string;
27	27	latitude: string;
28	28	longitude: string;
	29	+ /** 백엔드 `frcsBzstatCd` — 업태 코드(`FRCS_BZSTAT_CD`). */
	30	+ businessStatusCode: string;
	31	+ /** 백엔드 `frcsDvCd` — 가맹점 구분(`FRCS_DV_CD`). */
	32	+ divisionCode: string;
29	33	/** 백엔드 `useYn`. develop 목록엔 없어 `null`(모름)이고 feature/voc부터 온다. */
30	34	isVisible: boolean \| null;
31	35	}
32	36
	37	+/** 가맹몰 등록·수정 폼이 쓰는 코드표 넷 — 화면이 한 번에 받아 모달까지 내려보낸다. */
	38	+export type MerchantCodeTables = {
	39	+ /** 업종(`FRCS_TPBIZ_CD` 다음 `FRCS_CD`). */
	40	+ business: CommonCode[];
	41	+ businessStatus: CommonCode[];
	42	+ division: CommonCode[];
	43	+ bank: CommonCode[];
	44	+};
	45	+
	46	+/** 가맹점 구분 기본값 — 관리자가 만드는 가맹점은 일반가맹점이다. */
	47	+export const DEFAULT_MERCHANT_DIVISION_CODE = '62';
	48	+
33	49	export const EMPTY_FIELD_PLACEHOLDER = '-';
34	50
35	51	export function formatOptionalValue(

Delete comment