@farmzone/fz-template-react 1.0.5 → 1.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farmzone/fz-template-react",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Farmzone React 프로젝트 보일러플레이트 생성 CLI",
   "type": "module",
   "bin": {

package/template/package.json

@@ -1,7 +1,6 @@
 {
   "name": "__PROJECT_NAME__",
-  "private": true,
-  "version": "1.0.5",
+  "version": "1.0.6",
   "type": "module",
   "scripts": {
     "dev": "vite --host 0.0.0.0 --port 5000",

package/template/src/app/api/queries.ts

@@ -65,7 +65,12 @@ export const useGetSample = (id: number | null) => {
 export const usePostSample = () => {
   const queryClient = useQueryClient();
   return useMutation({
-    mutationFn: (data: SampleForm) => apiInstance.post<Sample>("/samples", data).then((r) => r.data),
+    mutationFn: async ({ data, files }: { data: SampleForm; files?: Array<File> }) => {
+      const formData = new FormData();
+      formData.append("request", JSON.stringify(data));
+      files?.forEach((f) => formData.append("files", f));
+      return (await apiFormDataInstance.post<Sample>("/samples", formData)).data;
+    },
     onSuccess: () => {
       void queryClient.invalidateQueries({ queryKey: [SAMPLE_QUERY_KEY] });
       toast.success(COMMON_MESSAGES.SAVE_SUCCESS);
@@ -76,8 +81,12 @@ export const usePostSample = () => {
 export const usePutSample = () => {
   const queryClient = useQueryClient();
   return useMutation({
-    mutationFn: ({ id, data }: { id: number; data: SampleForm }) =>
-      apiInstance.put<Sample>(`/samples/${id}`, data).then((r) => r.data),
+    mutationFn: async ({ id, data, files }: { id: number; data: SampleForm; files?: Array<File> }) => {
+      const formData = new FormData();
+      formData.append("request", JSON.stringify(data));
+      files?.forEach((f) => formData.append("files", f));
+      return (await apiFormDataInstance.put<Sample>(`/samples/${id}`, formData)).data;
+    },
     onSuccess: () => {
       void queryClient.invalidateQueries({ queryKey: [SAMPLE_QUERY_KEY] });
       toast.success(COMMON_MESSAGES.UPDATE_SUCCESS);

package/template/src/pages/post/detail/index.tsx

@@ -8,7 +8,6 @@ import {
   Button,
   confirmModal,
   FilePreviewViewer,
-  getFileLabel,
   toast,
   useFilePreviewViewer,
 } from "@farmzone/fz-react-ui";
@@ -301,21 +300,19 @@ export default function PostDetailPage() {
                 <p className="whitespace-pre-wrap text-sm leading-7 text-gray-800">{post.content}</p>
               </div>
 
-              {/* TODO fix issues */}
               {/* 첨부파일 미리보기 뷰어 */}
               {postFiles.length > 0 && (
                 <>
-                  <div className="grid grid-cols-2 gap-2 w-full">
-                    {postFiles
-                      .map((postFile) => postFile.filePath)
-                      .map((img, idx) => (
-                        <FilePreviewCard
-                          key={idx}
-                          src={img}
-                          fileName={getFileLabel(img, idx)}
-                          onClick={() => filePreview.open(idx)}
-                        />
-                      ))}
+                  <div className="m-4 grid grid-cols-8 gap-2 w-full">
+                    {postFiles.map((postFile, idx) => (
+                      <FilePreviewCard
+                        key={idx}
+                        src={blobUrls[idx] ?? ""}
+                        fileName={previewFileNames[idx] ?? postFile.fileName}
+                        fileType={previewFileTypes[idx]}
+                        onClick={() => filePreview.open(idx)}
+                      />
+                    ))}
                   </div>
                   <FilePreviewViewer
                     {...filePreview.viewerProps}
@@ -399,7 +396,7 @@ export default function PostDetailPage() {
                                 <div className="flex-1 space-y-0.5">
                                   <div className="flex items-center gap-2">
                                     <span className="text-sm font-semibold text-gray-800">
-                                      {reply.userName}
+                                      {reply.userName || "알수없음"}
                                     </span>
                                     <span className="text-xs text-gray-400">
                                       {formatDateTime(reply.createdAt)}
@@ -454,7 +451,7 @@ export default function PostDetailPage() {
                                         <div className="flex-1 space-y-0.5">
                                           <div className="flex items-center gap-2">
                                             <span className="text-sm font-semibold text-gray-800">
-                                              {deepReply.userName}
+                                              {deepReply.userName || "알수없음"}
                                             </span>
                                             <span className="text-xs text-gray-400">
                                               {formatDateTime(deepReply.createdAt)}

package/template/src/pages/sample/SampleFormModal.tsx

@@ -1,9 +1,19 @@
-import { useEffect } from "react";
+import { useEffect, useRef } from "react";
 import { useFormContext } from "react-hook-form";
-import { Button, Modal, ModalBody, ModalFooter, ModalIconHeader, SubmitForm } from "@farmzone/fz-react-ui";
+import {
+  Button,
+  FileUploader,
+  Modal,
+  ModalBody,
+  ModalFooter,
+  ModalIconHeader,
+  SubmitForm,
+} from "@farmzone/fz-react-ui";
+import { Paperclip, X } from "lucide-react";
 import { z } from "zod";
 
 import { checkSampleNameAvailable } from "@/app/api/queries";
+import type { FileResponse } from "@/types";
 
 export const sampleFormSchema = z.object({
   name: z.string().min(1, "이름을 입력해 주세요."),
@@ -34,25 +44,34 @@ const PRIORITY_OPTIONS = Array.from({ length: 10 }, (_, i) => ({
 }));
 
 function SampleNameChecker({ originalName }: { originalName?: string }) {
-  const { watch, setError, clearErrors } = useFormContext();
+  const { watch, setError, clearErrors, formState } = useFormContext();
   const name = watch("name") as string;
+  const isDuplicateRef = useRef(false);
 
   useEffect(() => {
     if (!name || name === originalName) {
+      isDuplicateRef.current = false;
       clearErrors("name");
       return;
     }
     const timer = setTimeout(async () => {
-      const available = await checkSampleNameAvailable(name);
-      if (available) {
-        clearErrors("name");
-      } else {
+      const isDuplicate = await checkSampleNameAvailable(name);
+      isDuplicateRef.current = isDuplicate;
+      if (isDuplicate) {
         setError("name", { type: "manual", message: "이미 사용 중인 샘플명입니다." });
+      } else {
+        clearErrors("name");
       }
     }, 500);
     return () => clearTimeout(timer);
   }, [name, originalName, setError, clearErrors]);
 
+  useEffect(() => {
+    if (isDuplicateRef.current && !formState.errors.name) {
+      setError("name", { type: "manual", message: "이미 사용 중인 샘플명입니다." });
+    }
+  }, [formState.errors.name, setError]);
+
   return null;
 }
 
@@ -65,6 +84,10 @@ interface SampleFormModalProps {
   isPending: boolean;
   formKey?: string | number;
   originalName?: string;
+  pendingFiles: Array<File>;
+  onPendingFilesChange: (files: Array<File>) => void;
+  existingFiles?: Array<FileResponse>;
+  onDeleteExistingFile?: (id: number) => void;
 }
 
 export function SampleFormModal({
@@ -76,6 +99,10 @@ export function SampleFormModal({
   isPending,
   formKey,
   originalName,
+  pendingFiles,
+  onPendingFilesChange,
+  existingFiles,
+  onDeleteExistingFile,
 }: SampleFormModalProps) {
   const formId = mode === "create" ? "sample-create-form" : "sample-edit-form";
   const title = mode === "create" ? "샘플 등록" : "샘플 수정";
@@ -85,21 +112,67 @@ export function SampleFormModal({
     <Modal isOpen={isOpen} onClose={onClose} contentClassName="max-w-3xl rounded-xl bg-white">
       <ModalIconHeader type={mode} title={title} onClose={onClose} />
       <ModalBody className="px-6 py-5">
-        <div className="overflow-hidden rounded-lg border border-gray-200">
-          <SubmitForm
-            key={formKey}
-            formId={formId}
-            schema={sampleFormSchema}
-            defaultValues={defaultValues ?? SAMPLE_FORM_DEFAULT_VALUES}
-            onSubmit={onSubmit}
-          >
-            <SampleNameChecker originalName={originalName} />
-            <SubmitForm.Row formKey="name" label="이름" required maxLength={100} />
-            <SubmitForm.Row formKey="description" formType="textarea" label="설명" required maxLength={500} />
-            <SubmitForm.Row formKey="category" formType="radio" label="카테고리" options={CATEGORY_OPTIONS} />
-            <SubmitForm.Row formKey="priority" formType="select" label="우선순위" options={PRIORITY_OPTIONS} />
-            <SubmitForm.Row formKey="active" formType="switch" label="사용 여부" />
-          </SubmitForm>
+        <div className="space-y-4">
+          <div className="overflow-hidden rounded-lg border border-gray-200">
+            <SubmitForm
+              key={formKey}
+              formId={formId}
+              schema={sampleFormSchema}
+              defaultValues={defaultValues ?? SAMPLE_FORM_DEFAULT_VALUES}
+              onSubmit={onSubmit}
+            >
+              <SampleNameChecker originalName={originalName} />
+              <SubmitForm.Row formKey="name" label="이름" required maxLength={100} />
+              <SubmitForm.Row
+                formKey="description"
+                formType="textarea"
+                label="설명"
+                required
+                maxLength={500}
+              />
+              <SubmitForm.Row
+                formKey="category"
+                formType="radio"
+                label="카테고리"
+                options={CATEGORY_OPTIONS}
+              />
+              <SubmitForm.Row
+                formKey="priority"
+                formType="select"
+                label="우선순위"
+                options={PRIORITY_OPTIONS}
+              />
+              <SubmitForm.Row formKey="active" formType="switch" label="사용 여부" />
+            </SubmitForm>
+          </div>
+
+          <div>
+            <p className="mb-1.5 text-sm font-medium text-gray-700">첨부파일</p>
+            {existingFiles && existingFiles.length > 0 && (
+              <ul className="mb-3 space-y-1.5">
+                {existingFiles.map((file) => (
+                  <li
+                    key={file.id}
+                    className="flex items-center justify-between rounded-md border border-gray-200 bg-gray-50 px-3 py-2"
+                  >
+                    <span className="flex items-center gap-1.5 truncate text-sm text-gray-700">
+                      <Paperclip size={13} className="shrink-0 text-gray-400" />
+                      {file.fileName}
+                    </span>
+                    <button
+                      type="button"
+                      onClick={() => onDeleteExistingFile?.(file.id)}
+                      className="ml-2 shrink-0 rounded p-0.5 text-gray-400 hover:bg-red-50 hover:text-red-500"
+                      aria-label="파일 삭제"
+                    >
+                      <X size={14} />
+                    </button>
+                  </li>
+                ))}
+              </ul>
+            )}
+            <FileUploader files={pendingFiles} onChange={onPendingFilesChange} multiple />
+          </div>
         </div>
       </ModalBody>
       <ModalFooter className="flex justify-end gap-2 border-t border-gray-200 bg-neutral-50 px-5 py-3">

package/template/src/pages/sample/detail/index.tsx

@@ -1,6 +1,13 @@
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { useNavigate, useParams } from "react-router";
-import { Badge, Button, confirmModal, toast } from "@farmzone/fz-react-ui";
+import {
+  Badge,
+  Button,
+  confirmModal,
+  FilePreviewViewer,
+  toast,
+  useFilePreviewViewer,
+} from "@farmzone/fz-react-ui";
 import { CornerDownRight, Pencil, Trash2 } from "lucide-react";
 
 import {
@@ -12,14 +19,22 @@ import {
   usePutSample,
 } from "@/app/api/queries";
 import { useUserStore } from "@/app/store";
-import type { Comment } from "@/types";
+import type { Comment, FileResponse } from "@/types";
+import { apiFileInstance } from "@/app/api/api";
 import ListHeader from "@/app/layout/ListHeader";
 import CommentInput from "@/shared/components/CommentInput";
 import { formatDateTime } from "@/shared/utils/format";
 import ListContents from "@/app/layout/ListContents";
+import FilePreviewCard from "@/shared/components/FilePreviewCard";
 import { SampleFormModal } from "../SampleFormModal";
 import type { SampleFormData } from "../SampleFormModal";
 
+function toPreviewFileType(mimeType: string): "image" | "pdf" | "unsupported" {
+  if (mimeType?.startsWith("image/")) return "image";
+  if (mimeType === "application/pdf") return "pdf";
+  return "unsupported";
+}
+
 function countComments(list: Array<Comment>): number {
   return list.reduce((sum, c) => {
     const depth2 = c.replies ?? [];
@@ -37,6 +52,13 @@ export default function SampleDetailPage() {
   const [isEditOpen, setIsEditOpen] = useState(false);
   const [replyingToId, setReplyingToId] = useState<number | null>(null);
   const [editingCommentId, setEditingCommentId] = useState<number | null>(null);
+  const [pendingFiles, setPendingFiles] = useState<Array<File>>([]);
+  const [existingFiles, setExistingFiles] = useState<Array<FileResponse>>([]);
+  const [deleteFileIds, setDeleteFileIds] = useState<Array<number>>([]);
+  const [isUploading, setIsUploading] = useState(false);
+  const [blobUrls, setBlobUrls] = useState<Array<string>>([]);
+  const [previewFileNames, setPreviewFileNames] = useState<Array<string>>([]);
+  const [previewFileTypes, setPreviewFileTypes] = useState<Array<"image" | "pdf" | "unsupported">>([]);
 
   const { data: sample, isLoading } = useGetSample(sampleId);
   const { data: comments = [] } = useGetComments("SAMPLE", sampleId);
@@ -45,24 +67,88 @@ export default function SampleDetailPage() {
   const { mutateAsync: deleteComment } = useDeleteComment();
   const { mutateAsync: putComment, isPending: isCommentUpdating } = usePutComment();
 
+  const sampleFiles = sample?.files ?? [];
   const topComments = comments.filter((c) => c.parentCommentId === null);
   const totalCommentCount = countComments(topComments);
 
-  const openEditModal = () => setIsEditOpen(true);
-  const closeEditModal = () => setIsEditOpen(false);
+  useEffect(() => {
+    if (sampleFiles.length === 0) {
+      setBlobUrls([]);
+      setPreviewFileNames([]);
+      setPreviewFileTypes([]);
+      return;
+    }
+
+    let cancelled = false;
+    const createdUrls: Array<string> = [];
+
+    (async () => {
+      const results = await Promise.all(
+        sampleFiles.map(async (file) => {
+          try {
+            const { data: blob } = await apiFileInstance.get(file.filePath, { responseType: "blob" });
+            const url = URL.createObjectURL(blob);
+            createdUrls.push(url);
+            return { url, name: file.fileName, type: toPreviewFileType(file.fileType) };
+          } catch {
+            return { url: "", name: file.fileName, type: "unsupported" as const };
+          }
+        }),
+      );
+      if (!cancelled) {
+        setBlobUrls(results.map((r) => r.url));
+        setPreviewFileNames(results.map((r) => r.name));
+        setPreviewFileTypes(results.map((r) => r.type));
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+      createdUrls.forEach((url) => url && URL.revokeObjectURL(url));
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sampleFiles.length, sampleFiles[0]?.id]);
+
+  const filePreview = useFilePreviewViewer(blobUrls);
+
+  const openEditModal = () => {
+    setPendingFiles([]);
+    setExistingFiles(sample?.files ?? []);
+    setDeleteFileIds([]);
+    setIsEditOpen(true);
+  };
+
+  const closeEditModal = () => {
+    setIsEditOpen(false);
+    setPendingFiles([]);
+    setExistingFiles([]);
+    setDeleteFileIds([]);
+  };
+
+  const handleDeleteExistingFile = (fileId: number) => {
+    setExistingFiles((prev) => prev.filter((f) => f.id !== fileId));
+    setDeleteFileIds((prev) => [...prev, fileId]);
+  };
 
   const handleEdit = async (data: SampleFormData) => {
-    await putSample({
-      id: sampleId,
-      data: {
-        name: data.name,
-        description: data.description,
-        category: data.category as "BASIC" | "ADVANCED",
-        priority: data.priority,
-        active: data.active,
-      },
-    });
-    closeEditModal();
+    setIsUploading(true);
+    try {
+      await putSample({
+        id: sampleId,
+        data: {
+          name: data.name,
+          description: data.description,
+          category: data.category as "BASIC" | "ADVANCED",
+          priority: data.priority,
+          active: data.active,
+          deleteFileIds: deleteFileIds.length > 0 ? deleteFileIds : undefined,
+        },
+        files: pendingFiles.length > 0 ? pendingFiles : undefined,
+      });
+      closeEditModal();
+    } finally {
+      setIsUploading(false);
+    }
   };
 
   const handleDelete = () => {
@@ -79,7 +165,7 @@ export default function SampleDetailPage() {
   };
 
   const isCommentOwner = (commentUserId: number | null) =>
-    commentUserId !== null && String(commentUserId) === currentUser?.id;
+    commentUserId !== null && String(commentUserId) === String(currentUser?.id);
 
   const handleCommentEditStart = (comment: Comment) => {
     if (!isCommentOwner(comment.userId)) {
@@ -141,7 +227,13 @@ export default function SampleDetailPage() {
   };
 
   const editDefaultValues: SampleFormData | undefined = sample
-    ? { name: sample.name, description: sample.description, category: sample.category, priority: sample.priority, active: sample.active }
+    ? {
+        name: sample.name,
+        description: sample.description,
+        category: sample.category,
+        priority: sample.priority,
+        active: sample.active,
+      }
     : undefined;
 
   return (
@@ -205,6 +297,27 @@ export default function SampleDetailPage() {
               <div className="min-h-44 px-6 py-6">
                 <p className="whitespace-pre-wrap text-sm leading-7 text-gray-800">{sample.description}</p>
               </div>
+
+              {sampleFiles.length > 0 && (
+                <>
+                  <div className="m-4 grid grid-cols-8 gap-2 w-full">
+                    {sampleFiles.map((_, idx) => (
+                      <FilePreviewCard
+                        key={idx}
+                        src={blobUrls[idx] ?? ""}
+                        fileName={previewFileNames[idx] ?? ""}
+                        fileType={previewFileTypes[idx]}
+                        onClick={() => filePreview.open(idx)}
+                      />
+                    ))}
+                  </div>
+                  <FilePreviewViewer
+                    {...filePreview.viewerProps}
+                    fileNames={previewFileNames}
+                    fileTypes={previewFileTypes}
+                  />
+                </>
+              )}
             </>
           ) : (
             <div className="p-8 text-center text-sm text-gray-400">샘플을 찾을 수 없습니다.</div>
@@ -279,7 +392,7 @@ export default function SampleDetailPage() {
                                 <div className="flex-1 space-y-0.5">
                                   <div className="flex items-center gap-2">
                                     <span className="text-sm font-semibold text-gray-800">
-                                      {reply.userName}
+                                      {reply.userName || "알수없음"}
                                     </span>
                                     <span className="text-xs text-gray-400">
                                       {formatDateTime(reply.createdAt)}
@@ -322,7 +435,7 @@ export default function SampleDetailPage() {
                                         <div className="flex-1 space-y-0.5">
                                           <div className="flex items-center gap-2">
                                             <span className="text-sm font-semibold text-gray-800">
-                                              {deepReply.userName}
+                                              {deepReply.userName || "알수없음"}
                                             </span>
                                             <span className="text-xs text-gray-400">
                                               {formatDateTime(deepReply.createdAt)}
@@ -351,7 +464,6 @@ export default function SampleDetailPage() {
                                   })}
                                 </ul>
                               )}
-
                             </li>
                           );
                         })}
@@ -392,8 +504,13 @@ export default function SampleDetailPage() {
         onClose={closeEditModal}
         defaultValues={editDefaultValues}
         onSubmit={handleEdit}
-        isPending={isUpdating}
+        isPending={isUpdating || isUploading}
         formKey={sampleId}
+        originalName={sample?.name}
+        pendingFiles={pendingFiles}
+        onPendingFilesChange={setPendingFiles}
+        existingFiles={existingFiles}
+        onDeleteExistingFile={handleDeleteExistingFile}
       />
     </div>
   );

package/template/src/pages/sample/index.tsx

@@ -2,7 +2,13 @@ import { useState } from "react";
 import { useNavigate } from "react-router";
 import { Badge, Button, confirmModal, PageFilter, Select, Table } from "@farmzone/fz-react-ui";
 
-import { checkSampleNameAvailable, useDeleteSamples, useGetSamples, usePostSample, usePutSample } from "@/app/api/queries";
+import {
+  checkSampleNameAvailable,
+  useDeleteSamples,
+  useGetSamples,
+  usePostSample,
+  usePutSample,
+} from "@/app/api/queries";
 import type { Sample } from "@/types";
 import ListContents from "@/app/layout/ListContents";
 import ListHeader from "@/app/layout/ListHeader";
@@ -40,6 +46,8 @@ export default function SamplePage() {
   const [selectedSample, setSelectedSample] = useState<Sample | null>(null);
   const [editDefaultValues, setEditDefaultValues] = useState<SampleFormData | undefined>(undefined);
   const [selectedKeys, setSelectedKeys] = useState<Array<string | number>>([]);
+  const [pendingFiles, setPendingFiles] = useState<Array<File>>([]);
+  const [isUploading, setIsUploading] = useState(false);
   const [sortOption, setSortOption] = useState<{ sortKey: string; sortOrder: "asc" | "desc" } | undefined>(
     undefined,
   );
@@ -71,36 +79,46 @@ export default function SamplePage() {
     setModalMode(null);
     setSelectedSample(null);
     setEditDefaultValues(undefined);
+    setPendingFiles([]);
   };
 
   const handleSubmit = async (data: SampleFormData) => {
-    if (modalMode === "create") {
-      const available = await checkSampleNameAvailable(data.name);
-      if (!available) return;
-      await postSample({
-        name: data.name,
-        description: data.description,
-        category: data.category as "BASIC" | "ADVANCED",
-        priority: data.priority,
-        active: data.active,
-      });
-    } else if (modalMode === "edit" && selectedSample) {
-      if (data.name !== selectedSample.name) {
-        const available = await checkSampleNameAvailable(data.name);
-        if (!available) return;
+    setIsUploading(true);
+    try {
+      if (modalMode === "create") {
+        const isDuplicate = await checkSampleNameAvailable(data.name);
+        if (isDuplicate) return;
+        await postSample({
+          data: {
+            name: data.name,
+            description: data.description,
+            category: data.category as "BASIC" | "ADVANCED",
+            priority: data.priority,
+            active: data.active,
+          },
+          files: pendingFiles.length > 0 ? pendingFiles : undefined,
+        });
+      } else if (modalMode === "edit" && selectedSample) {
+        if (data.name !== selectedSample.name) {
+          const isDuplicate = await checkSampleNameAvailable(data.name);
+          if (isDuplicate) return;
+        }
+        await putSample({
+          id: selectedSample.id,
+          data: {
+            name: data.name,
+            description: data.description,
+            category: data.category as "BASIC" | "ADVANCED",
+            priority: data.priority,
+            active: data.active,
+          },
+          files: pendingFiles.length > 0 ? pendingFiles : undefined,
+        });
       }
-      await putSample({
-        id: selectedSample.id,
-        data: {
-          name: data.name,
-          description: data.description,
-          category: data.category as "BASIC" | "ADVANCED",
-          priority: data.priority,
-          active: data.active,
-        },
-      });
+      closeModal();
+    } finally {
+      setIsUploading(false);
     }
-    closeModal();
   };
 
   const columns = [
@@ -141,12 +159,12 @@ export default function SamplePage() {
     },
     {
       key: "active",
-      title: "사용여부",
+      title: "상태",
       align: "center" as const,
       width: "30px",
       render: (_: unknown, record: Sample) => (
         <Badge
-          text={record.active ? "O" : "X"}
+          text={record.active ? "활성" : "비활성"}
           className={`scale-90 ${record.active ? "bg-green-100 text-green-700 border-green-100" : "bg-red-100 text-red-500 border-red-100"}`}
         />
       ),
@@ -269,9 +287,11 @@ export default function SamplePage() {
         onClose={closeModal}
         defaultValues={editDefaultValues ?? SAMPLE_FORM_DEFAULT_VALUES}
         onSubmit={handleSubmit}
-        isPending={isCreating || isUpdating}
+        isPending={isCreating || isUpdating || isUploading}
         formKey={selectedSample?.id}
         originalName={selectedSample?.name}
+        pendingFiles={pendingFiles}
+        onPendingFilesChange={setPendingFiles}
       />
     </div>
   );

package/template/src/pages/sample/modal/index.tsx

@@ -244,14 +244,22 @@ export default function SampleModalPage() {
       const res = await apiInstance.get<Blob>(`/excel/template?menuCode=${menuCode}`, {
         responseType: "blob",
       });
+
+      const blob = new Blob([res.data], {
+        type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      });
+
       const disposition = (res.headers as Record<string, string>)["content-disposition"] ?? "";
       const fileNameMatch = /filename\*?=['"]?(?:UTF-8'')?([^;'"]+)['"]?/i.exec(disposition);
-      const fileName = fileNameMatch ? decodeURIComponent(fileNameMatch[1]) : "엑셀_업로드_양식.xlsx";
-      const url = URL.createObjectURL(res.data);
+      const fileName = fileNameMatch ? decodeURIComponent(fileNameMatch[1]) : "샘플 일괄등록 업로딩양식.xlsx";
+
+      const url = URL.createObjectURL(blob);
       const anchor = document.createElement("a");
       anchor.href = url;
       anchor.download = fileName;
+      document.body.appendChild(anchor);
       anchor.click();
+      document.body.removeChild(anchor);
       URL.revokeObjectURL(url);
     } finally {
       setIsDownloading(false);

package/template/src/pages/user/index.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { useFormContext } from "react-hook-form";
 import { X } from "lucide-react";
 import {
@@ -199,16 +199,19 @@ const USER_EDIT_FIELDS: Array<FormFieldConfig<UserEditFormData>> = [
 type ModalMode = "detail" | "create";
 
 function UserIdChecker() {
-  const { watch, setError, clearErrors } = useFormContext();
+  const { watch, setError, clearErrors, formState } = useFormContext();
   const userId = watch("userId") as string;
+  const isDuplicateRef = useRef(false);
 
   useEffect(() => {
     if (!userId) {
+      isDuplicateRef.current = false;
       clearErrors("userId");
       return;
     }
     const timer = setTimeout(async () => {
       const available = await checkUserIdAvailable(userId);
+      isDuplicateRef.current = !available;
       if (available) {
         clearErrors("userId");
       } else {
@@ -218,6 +221,12 @@ function UserIdChecker() {
     return () => clearTimeout(timer);
   }, [userId, setError, clearErrors]);
 
+  useEffect(() => {
+    if (isDuplicateRef.current && !formState.errors.userId) {
+      setError("userId", { type: "manual", message: "이미 사용 중인 아이디입니다." });
+    }
+  }, [formState.errors.userId, setError]);
+
   return null;
 }
 

package/template/src/shared/components/FilePreviewCard.tsx

@@ -8,13 +8,14 @@ interface FilePreviewCardProps {
   fileSize?: string;
   onClick?: () => void;
   className?: string;
+  fileType?: "image" | "pdf" | "unsupported";
 }
 
 /** 예시용 파일 카드 UI — FilePreviewViewer와 분리, 사용처에서 자유롭게 커스터마이징 */
 export default function FilePreviewCard(props: FilePreviewCardProps) {
-  const { src, fileName, fileSize, onClick, className } = props;
+  const { src, fileName, fileSize, onClick, className, fileType: fileTypeProp } = props;
 
-  const fileType = getPreviewFileType(src);
+  const fileType = fileTypeProp ?? getPreviewFileType(src);
   const isImage = fileType === "image";
   const imageSrc = useStableImageSrc(isImage ? src : undefined);
 
@@ -26,7 +27,7 @@ export default function FilePreviewCard(props: FilePreviewCardProps) {
         type="button"
         onClick={onClick}
         className={cn(
-          "group flex flex-col w-full h-40 rounded-lg border border-gray-200 overflow-hidden bg-white hover:border-gray-300 hover:shadow-md transition-all duration-200 text-left cursor-pointer",
+          "group flex flex-col w-full h-30 rounded-lg border border-gray-200 overflow-hidden bg-white hover:border-gray-300 hover:shadow-md transition-all duration-200 text-left cursor-pointer",
           className,
         )}
       >
@@ -50,7 +51,7 @@ export default function FilePreviewCard(props: FilePreviewCardProps) {
       type="button"
       onClick={onClick}
       className={cn(
-        "group flex flex-col w-full h-40 rounded-lg border border-gray-200 overflow-hidden bg-white hover:border-gray-300 hover:shadow-md transition-all duration-200 text-left cursor-pointer",
+        "group flex flex-col w-full h-30 rounded-lg border border-gray-200 overflow-hidden bg-white hover:border-gray-300 hover:shadow-md transition-all duration-200 text-left cursor-pointer",
         className,
       )}
     >

package/template/src/types/sample.ts

@@ -1,3 +1,5 @@
+import type { FileResponse } from "./common";
+
 export type SampleCategory = "BASIC" | "ADVANCED";
 
 export interface Sample {
@@ -9,6 +11,7 @@ export interface Sample {
   active: boolean;
   createdAt: string;
   updatedAt: string;
+  files?: Array<FileResponse>;
 }
 
 export interface GetSamplesParams {
@@ -26,4 +29,5 @@ export interface SampleForm {
   category: SampleCategory;
   priority: number;
   active: boolean;
+  deleteFileIds?: Array<number>;
 }