@farmzone/fz-template-react 1.0.4 → 1.0.6

package/README.md

@@ -24,68 +24,58 @@ npx @farmzone/fz-template-react
 # 프로젝트 이름을 입력하세요: my-app
 ```
 
-## 생성되는 프로젝트 구조
-
-```
-my-app/
-├── src/
-│   ├── app/
-│   │   ├── layout/
-│   │   │   ├── Layout.tsx       # 사이드바 + Outlet 레이아웃
-│   │   │   ├── Sidebar.tsx      # 사이드바 컴포넌트
-│   │   │   └── menu.ts          # 메뉴 설정
-│   │   ├── router/
-│   │   │   └── Router.tsx
-│   │   └── App.tsx              # QueryClientProvider 루트
-│   ├── pages/
-│   │   ├── dashboard/
-│   │   │   └── index.tsx
-│   │   └── error/
-│   │       ├── Error.tsx
-│   │       └── NotFound.tsx
-│   └── index.tsx
-├── .gitignore
-├── index.html
-├── index.css
-├── vite.config.ts
-├── tsconfig.json
-└── package.json
-```
-
 ## 포함된 기술 스택
 
-| 항목                  | 버전   |
-| --------------------- | ------ |
-| React                 | ^19    |
-| Vite                  | ^7     |
-| TypeScript            | ~5.9   |
-| Tailwind CSS          | v4     |
-| React Router          | ^7     |
-| TanStack Query        | ^5     |
-| @farmzone/fz-react-ui | latest |
-| react-hook-form + zod | 최신   |
+| 항목                  | 버전    |
+| --------------------- | ------- |
+| React                 | ^19     |
+| Vite                  | ^7      |
+| TypeScript            | ~5.9    |
+| Tailwind CSS          | ^4      |
+| React Router          | ^7      |
+| TanStack Query        | ^5      |
+| @farmzone/fz-react-ui | ^0.0.6  |
+| react-hook-form       | ^7      |
+| zod                   | ^3      |
+| Zustand               | ^5      |
+| axios                 | ^1      |
+| dayjs                 | ^1      |
+| MSW                   | ^2      |
+| lucide-react          | ^1      |
 
 ## 메뉴 추가
 
-`src/app/layout/menu.ts` 수정:
+`src/app/layout/menu.ts`의 `MENU_SECTIONS` 배열에 추가:
 
 ```ts
-import { LayoutDashboard, Users, ScrollText } from "lucide-react";
+import type { MenuSection } from "@farmzone/fz-react-ui";
+import { LayoutDashboard, Users, FileText, ScrollText } from "lucide-react";
 
-export const MENU_SECTIONS: MenuSection[] = [
-  {
-    items: [{ icon: LayoutDashboard, label: "대시보드", path: "/" }],
-  },
+export const MENU_SECTIONS: Array<MenuSection> = [
   {
-    title: "관리",
     items: [
-      { icon: Users, label: "사용자 관리", path: "/user" },
-      { icon: ScrollText, label: "로그", path: "/log" },
+      { icon: LayoutDashboard, label: "대시보드", path: "/" },
+      {
+        icon: FileText,
+        label: "게시글 관리",
+        children: [{ label: "게시글 관리", path: "/post" }],
+      },
+      {
+        icon: Users,
+        label: "사용자 관리",
+        children: [{ label: "사용자 관리", path: "/user" }],
+      },
     ],
   },
+  {
+    title: "시스템",
+    items: [{ icon: ScrollText, label: "로그 관리", path: "/system/log" }],
+  },
 ];
 ```
 
+`children` 배열을 사용하면 아코디언 서브메뉴로 렌더링됩니다.
+
 ## 라우트 추가
 
 `src/app/router/Router.tsx`의 `children` 배열에 추가:
@@ -93,12 +83,18 @@ export const MENU_SECTIONS: MenuSection[] = [
 ```tsx
 children: [
   { index: true, element: <DashboardPage /> },
-  { path: "user", element: <UserListPage /> },
-  { path: "user/:id", element: <UserDetailPage /> },
-  { path: "log", element: <LogPage /> },
+  { path: "sample", element: <SamplePage /> },
+  { path: "sample/modal", element: <SampleModalPage /> },
+  { path: "sample/:id", element: <SampleDetailPage /> },
+  { path: "post", element: <PostPage /> },
+  { path: "post/:id", element: <PostDetailPage /> },
+  { path: "user", element: <UserPage /> },
+  { path: "system/log", element: <LogPage /> },
 ],
 ```
 
+`/login` 경로와 `authLoader`(토큰 미존재 시 `/login` 리다이렉트)는 Router.tsx에 이미 포함되어 있습니다.
+
 ## npm 배포
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farmzone/fz-template-react",
-  "version": "1.0.4",
+  "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.4",
+  "version": "1.0.6",
   "type": "module",
   "scripts": {
     "dev": "vite --host 0.0.0.0 --port 5000",
@@ -10,7 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@farmzone/fz-react-ui": "^0.0.6",
+    "@farmzone/fz-react-ui": "^0.0.8",
     "@hookform/resolvers": "^5.2.2",
     "@tanstack/react-query": "^5.90.0",
     "axios": "^1.13.0",

package/template/pnpm-lock.yaml

@@ -9,8 +9,8 @@ importers:
   .:
     dependencies:
       '@farmzone/fz-react-ui':
-        specifier: ^0.0.6
-        version: 0.0.6(@hookform/resolvers@5.4.0(react-hook-form@7.78.0(react@19.2.7)))(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-daum-postcode@4.0.0(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react-hook-form@7.78.0(react@19.2.7))(react-router@7.17.0(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)(zod@3.25.76)
+        specifier: ^0.0.8
+        version: 0.0.8(@hookform/resolvers@5.4.0(react-hook-form@7.78.0(react@19.2.7)))(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-daum-postcode@4.0.0(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react-hook-form@7.78.0(react@19.2.7))(react-router@7.17.0(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)(zod@3.25.76)
       '@hookform/resolvers':
         specifier: ^5.2.2
         version: 5.4.0(react-hook-form@7.78.0(react@19.2.7))
@@ -391,8 +391,8 @@ packages:
     resolution: {integrity: sha512-43/qtrDUokr7LJqoF2c3+RInu/t4zfrpYdoSDfYyhg52rwLV6TnOvdG4fXm7IkSB3wErkcmJS9iEhjVtOSEjjA==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
 
-  '@farmzone/fz-react-ui@0.0.6':
-    resolution: {integrity: sha512-4BwWCXQBtjZf9Aj1CmnbulJQHMtUVX5EmjhRpNCYbnovD4o+hz/TUTuv3y+JmNqZFnq5TYNgB6zzytBhBpIZ5g==}
+  '@farmzone/fz-react-ui@0.0.8':
+    resolution: {integrity: sha512-atqHgWVSy0sy15P30i1jN3BMtZJQbfyoMwUk1K5Xpgrk4xXtN8lC8AK+LMV8ZHfq0hV0EX+SHJGVpee0PLeHNQ==}
     peerDependencies:
       '@hookform/resolvers': ^5.2.2
       react: '>=18'
@@ -2501,7 +2501,7 @@ snapshots:
       '@eslint/core': 0.17.0
       levn: 0.4.1
 
-  '@farmzone/fz-react-ui@0.0.6(@hookform/resolvers@5.4.0(react-hook-form@7.78.0(react@19.2.7)))(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-daum-postcode@4.0.0(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react-hook-form@7.78.0(react@19.2.7))(react-router@7.17.0(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)(zod@3.25.76)':
+  '@farmzone/fz-react-ui@0.0.8(@hookform/resolvers@5.4.0(react-hook-form@7.78.0(react@19.2.7)))(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-daum-postcode@4.0.0(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react-hook-form@7.78.0(react@19.2.7))(react-router@7.17.0(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)(zod@3.25.76)':
     dependencies:
       '@radix-ui/react-popover': 1.1.16(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       '@radix-ui/react-radio-group': 1.4.0(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)

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);
@@ -221,6 +230,11 @@ export const useDeleteComment = () => {
   });
 };
 
+// --- Sample check ---
+
+export const checkSampleNameAvailable = (name: string): Promise<boolean> =>
+  apiInstance.get<boolean>("/samples/check/name", { params: { name } }).then((r) => r.data);
+
 // --- User ---
 
 export const checkUserIdAvailable = (userId: string): Promise<boolean> =>

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/post/index.tsx

@@ -209,7 +209,6 @@ export default function PostPage() {
           data={content}
           isLoading={isLoading}
           rowKey="id"
-          sortVisibleType={"hovered"}
           sortOption={sortOption}
           onSortChange={(sortKey: string, sortOrder: "asc" | "desc") => {
             setSortOption({ sortKey, sortOrder });

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

@@ -1,10 +1,25 @@
-import { Button, Modal, ModalBody, ModalFooter, ModalIconHeader, SubmitForm } from "@farmzone/fz-react-ui";
+import { useEffect, useRef } from "react";
+import { useFormContext } from "react-hook-form";
+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, "이름을 입력해 주세요."),
   description: z.string().min(1, "설명을 입력해 주세요."),
   category: z.string(),
+  priority: z.coerce.number().min(1).max(10),
   active: z.boolean(),
 });
 
@@ -14,6 +29,7 @@ export const SAMPLE_FORM_DEFAULT_VALUES: SampleFormData = {
   name: "",
   description: "",
   category: "BASIC",
+  priority: 1,
   active: true,
 };
 
@@ -22,6 +38,43 @@ const CATEGORY_OPTIONS = [
   { label: "고급", value: "ADVANCED" },
 ];
 
+const PRIORITY_OPTIONS = Array.from({ length: 10 }, (_, i) => ({
+  label: String(i + 1),
+  value: String(i + 1),
+}));
+
+function SampleNameChecker({ originalName }: { originalName?: string }) {
+  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 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;
+}
+
 interface SampleFormModalProps {
   mode: "create" | "edit";
   isOpen: boolean;
@@ -30,6 +83,11 @@ interface SampleFormModalProps {
   onSubmit: (data: SampleFormData) => Promise<void>;
   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({
@@ -40,6 +98,11 @@ export function SampleFormModal({
   onSubmit,
   isPending,
   formKey,
+  originalName,
+  pendingFiles,
+  onPendingFilesChange,
+  existingFiles,
+  onDeleteExistingFile,
 }: SampleFormModalProps) {
   const formId = mode === "create" ? "sample-create-form" : "sample-edit-form";
   const title = mode === "create" ? "샘플 등록" : "샘플 수정";
@@ -49,19 +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}
-          >
-            <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="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,23 +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",
-        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 = () => {
@@ -78,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)) {
@@ -140,7 +227,13 @@ export default function SampleDetailPage() {
   };
 
   const editDefaultValues: SampleFormData | undefined = sample
-    ? { name: sample.name, description: sample.description, category: sample.category, active: sample.active }
+    ? {
+        name: sample.name,
+        description: sample.description,
+        category: sample.category,
+        priority: sample.priority,
+        active: sample.active,
+      }
     : undefined;
 
   return (
@@ -204,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>
@@ -269,7 +383,6 @@ export default function SampleDetailPage() {
                       <ul className="border-t border-gray-50 bg-gray-50/60">
                         {depth2Replies.map((reply) => {
                           const depth3Replies = reply.replies ?? [];
-                          const isReplyingToReply = replyingToId === reply.id;
                           const isEditingReply = editingCommentId === reply.id;
 
                           return (
@@ -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)}
@@ -297,21 +410,9 @@ export default function SampleDetailPage() {
                                       onCancel={() => setEditingCommentId(null)}
                                     />
                                   ) : (
-                                    <>
-                                      <p className="whitespace-pre-wrap text-sm text-gray-600">
-                                        {reply.content}
-                                      </p>
-                                      {reply.content !== "삭제된 댓글입니다." && (
-                                        <button
-                                          type="button"
-                                          onClick={() => setReplyingToId(isReplyingToReply ? null : reply.id)}
-                                          className="mt-0.5 flex items-center gap-1 text-xs text-gray-400 transition-colors hover:text-blue-500"
-                                        >
-                                          <CornerDownRight size={11} />
-                                          {isReplyingToReply ? "취소" : "답글"}
-                                        </button>
-                                      )}
-                                    </>
+                                    <p className="whitespace-pre-wrap text-sm text-gray-600">
+                                      {reply.content}
+                                    </p>
                                   )}
                                 </div>
                                 {!isEditingReply && renderCommentActions(reply)}
@@ -334,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)}
@@ -363,19 +464,6 @@ export default function SampleDetailPage() {
                                   })}
                                 </ul>
                               )}
-
-                              {/* depth 2 답글 입력창 */}
-                              {isReplyingToReply && !isEditingReply && (
-                                <div className="border-t border-blue-50 bg-blue-50/30 py-3 pl-10 pr-5">
-                                  <CommentInput
-                                    targetType="SAMPLE"
-                                    targetId={sampleId}
-                                    parentCommentId={reply.id}
-                                    placeholder="답글을 입력하세요. @를 입력하면 사용자를 멘션할 수 있습니다."
-                                    onSuccess={() => setReplyingToId(null)}
-                                  />
-                                </div>
-                              )}
                             </li>
                           );
                         })}
@@ -416,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 { 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,28 +79,46 @@ export default function SamplePage() {
     setModalMode(null);
     setSelectedSample(null);
     setEditDefaultValues(undefined);
+    setPendingFiles([]);
   };
 
   const handleSubmit = async (data: SampleFormData) => {
-    if (modalMode === "create") {
-      await postSample({
-        name: data.name,
-        description: data.description,
-        category: data.category as "BASIC" | "ADVANCED",
-        active: data.active,
-      });
-    } else if (modalMode === "edit" && selectedSample) {
-      await putSample({
-        id: selectedSample.id,
-        data: {
-          name: data.name,
-          description: data.description,
-          category: data.category as "BASIC" | "ADVANCED",
-          active: data.active,
-        },
-      });
+    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,
+        });
+      }
+      closeModal();
+    } finally {
+      setIsUploading(false);
     }
-    closeModal();
   };
 
   const columns = [
@@ -133,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"}`}
         />
       ),
@@ -261,8 +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

@@ -1,6 +1,7 @@
 import { useState, type ReactNode } from "react";
 import { Button, Modal, Tab } from "@farmzone/fz-react-ui";
-import { ArrowRight, Clock, Maximize2, Minimize2, X } from "lucide-react";
+import { ArrowRight, Clock, Download, Maximize2, Minimize2, X } from "lucide-react";
+import { apiInstance } from "@/app/api/api";
 import ListHeader from "@/app/layout/ListHeader";
 
 const CATTLE = {
@@ -235,6 +236,35 @@ function CattleDetailModal({ isOpen, onClose }: { isOpen: boolean; onClose: () =
 
 export default function SampleModalPage() {
   const [isOpen, setIsOpen] = useState(false);
+  const [isDownloading, setIsDownloading] = useState(false);
+
+  const handleExcelTemplateDownload = async (menuCode: string) => {
+    setIsDownloading(true);
+    try {
+      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(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);
+    }
+  };
 
   return (
     <div className="p-6">
@@ -247,6 +277,31 @@ export default function SampleModalPage() {
           </Button>
         </div>
       </div>
+      <div className="mt-6 flex items-center justify-center rounded-xl border border-dashed border-gray-300 bg-white p-16">
+        <div className="text-center">
+          <p className="mb-4 text-sm text-gray-500">
+            아래 버튼을 클릭하여 템플릿 다운로드 기능을 확인하세요.
+          </p>
+          <div className="flex flex-col gap-4">
+            <Button
+              variant="outline"
+              onClick={() => handleExcelTemplateDownload("SAMPLE")}
+              disabled={isDownloading}
+            >
+              <Download className="mr-1.5 h-4 w-4" />
+              엑셀 업로드 양식 다운로드 (SAMPLE)
+            </Button>
+            {/* <Button
+              variant="outline"
+              onClick={() => handleExcelTemplateDownload("POST")}
+              disabled={isDownloading}
+            >
+              <Download className="mr-1.5 h-4 w-4" />
+              엑셀 업로드 양식 다운로드 (POST)
+            </Button> */}
+          </div>
+        </div>
+      </div>
       <CattleDetailModal isOpen={isOpen} onClose={() => setIsOpen(false)} />
     </div>
   );

package/template/src/pages/user/config/columns.tsx

@@ -1,5 +1,4 @@
-import { Badge, Button, type Column } from "@farmzone/fz-react-ui";
-import { Pencil, Trash2 } from "lucide-react";
+import { Badge, type Column } from "@farmzone/fz-react-ui";
 
 import type { User } from "@/types";
 import { formatDateTime } from "@/shared/utils/format";
@@ -17,13 +16,7 @@ interface ActionHandlers {
   pageSize: number;
 }
 
-export const getUserColumns = ({
-  onEdit,
-  onDelete,
-  totalElements,
-  page,
-  pageSize,
-}: ActionHandlers): Array<Column<User>> => [
+export const getUserColumns = ({ totalElements, page, pageSize }: ActionHandlers): Array<Column<User>> => [
   {
     key: "index",
     title: "No",

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 {
@@ -140,25 +140,25 @@ const USER_READ_FIELDS: Array<DetailField<UserViewData>> = [
   {
     key: "role",
     label: "구분",
-    render: ({ value }: { value: string }) => (
-      <span className="text-sm text-gray-900">{value === "ADMIN" ? "관리자" : "일반"}</span>
+    render: ({ value }) => (
+      <span className="text-sm text-gray-900">{(value as string) === "ADMIN" ? "관리자" : "일반"}</span>
     ),
   },
   {
     key: "active",
     label: "사용여부",
-    render: ({ value }: { value: boolean }) => (
+    render: ({ value }) => (
       <Badge
-        text={value ? "활성" : "비활성"}
-        className={`scale-90 ${value ? "bg-green-100 text-green-700 border-green-100" : "bg-gray-100 text-gray-500 border-gray-200"}`}
+        text={(value as boolean) ? "활성" : "비활성"}
+        className={`scale-90 ${(value as boolean) ? "bg-green-100 text-green-700 border-green-100" : "bg-gray-100 text-gray-500 border-gray-200"}`}
       />
     ),
   },
   {
     key: "gender",
     label: "성별",
-    render: ({ value }: { value: string }) => (
-      <span className="text-sm text-gray-900">{value === "M" ? "남" : value === "F" ? "여" : "-"}</span>
+    render: ({ value }) => (
+      <span className="text-sm text-gray-900">{(value as string) === "M" ? "남" : (value as string) === "F" ? "여" : "-"}</span>
     ),
   },
   { key: "birthday", label: "생년월일" },
@@ -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 {
@@ -24,5 +27,7 @@ export interface SampleForm {
   name: string;
   description: string;
   category: SampleCategory;
+  priority: number;
   active: boolean;
+  deleteFileIds?: Array<number>;
 }