@farmzone/fz-template-react 1.0.5 → 1.0.7

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

@@ -1,641 +1,704 @@
-import { useEffect, useState } from "react";
-import { useFormContext } from "react-hook-form";
-import { X } from "lucide-react";
-import {
-  Badge,
-  FileUploader,
-  Button,
-  confirmModal,
-  DetailContent,
-  Modal,
-  ModalBody,
-  ModalFooter,
-  ModalIconHeader,
-  PageFilter,
-  Select,
-  SubmitForm,
-  Table,
-  useDetailController,
-  type DetailField,
-  type FormFieldConfig,
-} from "@farmzone/fz-react-ui";
-
-import {
-  useGetUsers,
-  useGetUser,
-  usePostUser,
-  usePutUser,
-  useDeleteUser,
-  useDeleteUsers,
-  checkUserIdAvailable,
-} from "@/app/api/queries";
-import type { User, UserRole } from "@/types";
-import ListContents from "@/app/layout/ListContents";
-import ListHeader from "@/app/layout/ListHeader";
-import { formatDateTime } from "@/shared/utils/format";
-import { getUserColumns } from "./config/columns";
-import {
-  userCreateSchema,
-  userEditSchema,
-  type UserCreateFormData,
-  type UserEditFormData,
-} from "./config/schema";
-
-const PAGE_SIZE_OPTIONS = [
-  { label: "15", value: "15" },
-  { label: "30", value: "30" },
-  { label: "60", value: "60" },
-  { label: "100", value: "100" },
-];
-
-// --- 필터 ---
-
-interface UserFilterParams {
-  role: string;
-  keywordType: string;
-  keyword: string;
-  dateType: string;
-  startDate: string;
-  endDate: string;
-}
-
-const EMPTY_USER_FILTER: UserFilterParams = {
-  role: "",
-  keywordType: "name",
-  keyword: "",
-  dateType: "createdAt",
-  startDate: "",
-  endDate: "",
-};
-
-const ROLE_OPTIONS = [
-  { label: "관리자", value: "ADMIN" },
-  { label: "일반", value: "USER" },
-];
-
-const KEYWORD_TYPE_OPTIONS = [
-  { label: "성명", value: "name" },
-  { label: "아이디", value: "userId" },
-];
-
-const DATE_TYPE_OPTIONS = [
-  { label: "생성일", value: "createdAt" },
-  { label: "최근접속일", value: "lastLoginAt" },
-];
-
-// --- 폼 옵션 ---
-
-const ROLE_SUBMIT_OPTIONS = [
-  { label: "관리자", value: "ADMIN" },
-  { label: "일반", value: "USER" },
-];
-
-const GENDER_OPTIONS = [
-  { label: "남", value: "M" },
-  { label: "여", value: "F" },
-];
-
-const CREATE_DEFAULT_VALUES: UserCreateFormData = {
-  userId: "",
-  name: "",
-  password: "",
-  passwordCheck: "",
-  role: "USER",
-  gender: "",
-  birthday: "",
-  phone: "",
-};
-
-// --- 상세 뷰 타입 ---
-
-interface UserViewData {
-  userId: string;
-  name: string;
-  role: string;
-  gender: string;
-  birthday: string;
-  phone: string;
-  active: boolean;
-  createdAt: string;
-  lastLoginAt: string;
-}
-
-function toViewData(user: User): UserViewData {
-  return {
-    userId: user.userId,
-    name: user.name,
-    role: user.role,
-    gender: user.gender ?? "",
-    birthday: user.birthday ?? "",
-    phone: user.phone ?? "",
-    active: user.active,
-    createdAt: formatDateTime(user.createdAt),
-    lastLoginAt: formatDateTime(user.lastLoginAt),
-  };
-}
-
-const USER_READ_FIELDS: Array<DetailField<UserViewData>> = [
-  { key: "userId", label: "아이디" },
-  { key: "name", label: "성명" },
-  {
-    key: "role",
-    label: "구분",
-    render: ({ value }) => (
-      <span className="text-sm text-gray-900">{(value as string) === "ADMIN" ? "관리자" : "일반"}</span>
-    ),
-  },
-  {
-    key: "active",
-    label: "사용여부",
-    render: ({ value }) => (
-      <Badge
-        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 }) => (
-      <span className="text-sm text-gray-900">{(value as string) === "M" ? "남" : (value as string) === "F" ? "여" : "-"}</span>
-    ),
-  },
-  { key: "birthday", label: "생년월일" },
-  { key: "phone", label: "연락처" },
-  { key: "createdAt", label: "등록일시" },
-  { key: "lastLoginAt", label: "최근접속일" },
-];
-
-const USER_EDIT_FIELDS: Array<FormFieldConfig<UserEditFormData>> = [
-  { name: "userId", label: "아이디", readOnly: true, colspan: 4 },
-  { name: "name", label: "성명", required: true, maxLength: 50, colspan: 4 },
-  {
-    name: "password",
-    type: "password",
-    label: "비밀번호 변경",
-    placeholder: "변경 시에만 입력하세요",
-    maxLength: 100,
-    revalidateFields: ["passwordCheck"],
-    colspan: 4,
-  },
-  {
-    name: "passwordCheck",
-    type: "password",
-    label: "비밀번호 확인",
-    placeholder: "변경 시에만 입력하세요",
-    maxLength: 100,
-    colspan: 4,
-  },
-  { name: "active", type: "switch", label: "사용여부", colspan: 4 },
-  { name: "role", type: "radio", label: "구분", options: ROLE_SUBMIT_OPTIONS, colspan: 4 },
-  { name: "gender", type: "radio", label: "성별", options: GENDER_OPTIONS, colspan: 4 },
-  { name: "birthday", type: "date", label: "생년월일", colspan: 4 },
-  { name: "phone", label: "연락처", colspan: 4, maxLength: 20 },
-];
-
-// --- 모달 모드 ---
-
-type ModalMode = "detail" | "create";
-
-function UserIdChecker() {
-  const { watch, setError, clearErrors } = useFormContext();
-  const userId = watch("userId") as string;
-
-  useEffect(() => {
-    if (!userId) {
-      clearErrors("userId");
-      return;
-    }
-    const timer = setTimeout(async () => {
-      const available = await checkUserIdAvailable(userId);
-      if (available) {
-        clearErrors("userId");
-      } else {
-        setError("userId", { type: "manual", message: "이미 사용 중인 아이디입니다." });
-      }
-    }, 500);
-    return () => clearTimeout(timer);
-  }, [userId, setError, clearErrors]);
-
-  return null;
-}
-
-export default function UserPage() {
-  const [page, setPage] = useState(0);
-  const [pageSize, setPageSize] = useState(15);
-  const [filterParams, setFilterParams] = useState<UserFilterParams>(EMPTY_USER_FILTER);
-  const [submittedFilter, setSubmittedFilter] = useState<UserFilterParams>(EMPTY_USER_FILTER);
-
-  const [modalMode, setModalMode] = useState<ModalMode | null>(null);
-  const [selectedUserId, setSelectedUserId] = useState<number | null>(null);
-  const [selectedKeys, setSelectedKeys] = useState<Array<string | number>>([]);
-  const [profilePhoto, setProfilePhoto] = useState<Array<File>>([]);
-  const [editProfilePhoto, setEditProfilePhoto] = useState<Array<File>>([]);
-  const [deleteFileIds, setDeleteFileIds] = useState<Array<number>>([]);
-
-  const controller = useDetailController();
-
-  const { data, isLoading } = useGetUsers({
-    page,
-    size: pageSize,
-    role: submittedFilter.role || undefined,
-    keywordType: submittedFilter.keyword ? submittedFilter.keywordType : undefined,
-    keyword: submittedFilter.keyword || undefined,
-    dateType: submittedFilter.startDate || submittedFilter.endDate ? submittedFilter.dateType : undefined,
-    startDate: submittedFilter.startDate || undefined,
-    endDate: submittedFilter.endDate || undefined,
-  });
-
-  const { data: detailUser } = useGetUser(modalMode === "detail" ? selectedUserId : null);
-  const { mutateAsync: postUser, isPending: isCreating } = usePostUser();
-  const { mutateAsync: putUser } = usePutUser();
-  const { mutateAsync: deleteUser } = useDeleteUser();
-  const { mutateAsync: deleteUsers } = useDeleteUsers();
-
-  const totalElements = data?.totalElements ?? 0;
-  const totalPages = data?.totalPages ?? 0;
-  const content = data?.content ?? [];
-
-  const openCreate = () => {
-    setModalMode("create");
-  };
-
-  const openDetail = (user: User) => {
-    setSelectedUserId(user.id);
-    controller.toRead();
-    setModalMode("detail");
-  };
-
-  const openDetailInEditMode = (user: User) => {
-    setSelectedUserId(user.id);
-    controller.toEdit();
-    setModalMode("detail");
-  };
-
-  const closeModal = () => {
-    controller.toRead();
-    setModalMode(null);
-    setSelectedUserId(null);
-    setProfilePhoto([]);
-    setEditProfilePhoto([]);
-    setDeleteFileIds([]);
-  };
-
-  // TODO FormFieldConfig에 autoComplete="off" prop 추가하여 적용 뒤 삭제 필요
-  useEffect(() => {
-    if (modalMode !== "create") return;
-    const timer = setTimeout(() => {
-      const form = document.getElementById("user-create-form");
-      if (!form) return;
-      form.setAttribute("autocomplete", "off");
-      form.querySelectorAll("input").forEach((input) => {
-        input.setAttribute("autocomplete", input.type === "password" ? "new-password" : "off");
-      });
-    }, 0);
-    return () => clearTimeout(timer);
-  }, [modalMode]);
-
-  const handleCreateFormSubmit = async (formData: UserCreateFormData) => {
-    const available = await checkUserIdAvailable(formData.userId);
-    if (!available) return;
-    await postUser({
-      data: {
-        userId: formData.userId,
-        name: formData.name,
-        password: formData.password,
-        role: formData.role as UserRole,
-        gender: formData.gender || undefined,
-        birthday: formData.birthday || undefined,
-        phone: formData.phone || undefined,
-      },
-      file: profilePhoto[0],
-    });
-    closeModal();
-  };
-
-  const handleDetailEditSave = async (formData: UserEditFormData) => {
-    if (!selectedUserId) return;
-    await putUser({
-      id: selectedUserId,
-      data: {
-        name: formData.name,
-        role: formData.role as UserRole,
-        active: formData.active,
-        gender: formData.gender || undefined,
-        birthday: formData.birthday || undefined,
-        phone: formData.phone || undefined,
-        ...(formData.password ? { password: formData.password } : {}),
-        ...(deleteFileIds.length > 0 ? { deleteFileIds } : {}),
-      },
-      file: editProfilePhoto[0],
-    });
-  };
-
-  const handleDelete = (user: User) => {
-    confirmModal({
-      content: `"${user.name}" 사용자를 삭제하시겠습니까?`,
-      onOk: async () => {
-        await deleteUser(user.id);
-        closeModal();
-      },
-      onCancel: () => {},
-      className: "max-w-100",
-    });
-  };
-
-  const displayUser = detailUser ?? content.find((u) => u.id === selectedUserId);
-  const viewData = displayUser ? toViewData(displayUser) : undefined;
-
-  const columns = getUserColumns({
-    onEdit: openDetailInEditMode,
-    onDelete: handleDelete,
-    totalElements,
-    page,
-    pageSize,
-  });
-
-  return (
-    <div className="p-6">
-      <ListHeader
-        title="사용자 관리"
-        rightArea={
-          <div className="flex items-center gap-2">
-            <Button variant="save" onClick={openCreate}>
-              등록
-            </Button>
-            <Button
-              variant="delete"
-              disabled={selectedKeys.length === 0}
-              onClick={() => {
-                confirmModal({
-                  content: `선택한 ${selectedKeys.length}개 항목을 삭제하시겠습니까?`,
-                  onOk: async () => {
-                    await deleteUsers(selectedKeys.map(Number));
-                    setSelectedKeys([]);
-                  },
-                  onCancel: () => {},
-                  className: "max-w-100",
-                });
-              }}
-            >
-              삭제
-            </Button>
-          </div>
-        }
-      />
-      <ListContents>
-        <PageFilter
-          values={filterParams}
-          onChange={(updates: Partial<UserFilterParams>) =>
-            setFilterParams((prev) => ({ ...prev, ...updates }))
-          }
-          onSubmit={() => {
-            setPage(0);
-            setSelectedKeys([]);
-            setSubmittedFilter(filterParams);
-          }}
-          onReset={() => {
-            setFilterParams(EMPTY_USER_FILTER);
-            setSubmittedFilter(EMPTY_USER_FILTER);
-            setPage(0);
-            setPageSize(15);
-            setSelectedKeys([]);
-          }}
-          rows={[
-            {
-              options: [
-                { type: "select", key: "role", label: "구분", placeholder: "전체", options: ROLE_OPTIONS },
-                { type: "select", key: "dateType", label: "기간", options: DATE_TYPE_OPTIONS },
-                { type: "date-range", key: "startDate", endKey: "endDate" },
-              ],
-            },
-            {
-              options: [
-                { type: "select", key: "keywordType", label: "검색", options: KEYWORD_TYPE_OPTIONS },
-                { type: "input", key: "keyword", placeholder: "검색어 입력" },
-              ],
-            },
-          ]}
-        />
-        <Table
-          columns={columns}
-          data={content}
-          isLoading={isLoading}
-          rowKey="id"
-          onRowClick={openDetail}
-          paginationInfo={{
-            page,
-            totalPages,
-            onPageChange: (newPage: number) => {
-              setPage(newPage);
-              setSelectedKeys([]);
-            },
-          }}
-          checkboxInfo={{
-            selectedKeys,
-            onSelectionChange: setSelectedKeys,
-          }}
-          renderFooter={{
-            renderLeft: (
-              <p className="text-sm text-gray-600">
-                총 <span className="font-semibold text-gray-900">{totalElements}</span>건
-              </p>
-            ),
-            renderRight: (
-              <div className="flex items-center gap-2.5 pr-5">
-                <p className="text-sm font-medium text-gray-700">페이지 개수</p>
-                <Select
-                  value={String(pageSize)}
-                  options={PAGE_SIZE_OPTIONS}
-                  onChange={(val: string) => {
-                    setPageSize(Number(val));
-                    setPage(0);
-                    setSelectedKeys([]);
-                  }}
-                />
-              </div>
-            ),
-          }}
-        />
-      </ListContents>
-
-      {/* 상세/수정 모달 */}
-      <Modal
-        isOpen={modalMode === "detail"}
-        onClose={closeModal}
-        contentClassName="max-w-3xl rounded-xl bg-white"
-      >
-        <ModalIconHeader
-          type={controller.mode === "edit" ? "edit" : "detail"}
-          title={controller.mode === "edit" ? "사용자 수정" : "사용자 상세"}
-          onClose={closeModal}
-        />
-        <ModalBody className="px-6 py-5">
-          <div className="overflow-hidden border border-gray-200">
-            <DetailContent
-              key={selectedUserId}
-              controller={controller}
-              data={viewData}
-              readFields={USER_READ_FIELDS}
-              editSchema={userEditSchema}
-              editFields={USER_EDIT_FIELDS}
-              onSave={handleDetailEditSave}
-              layout="compact"
-            />
-          </div>
-          {(controller.mode === "edit" || !!displayUser?.files?.length) && (
-            <div className="mt-4 overflow-hidden rounded-lg border border-gray-200">
-              <div className="border-b border-gray-200 bg-gray-50 px-4 py-2 text-sm font-medium text-gray-700">
-                프로필 사진
-              </div>
-              <div className="p-4">
-                {controller.mode === "edit" ? (
-                  <>
-                    {displayUser?.files?.[0] && !deleteFileIds.includes(displayUser.files[0].id) && (
-                      <div className="mb-3">
-                        <p className="mb-1 text-xs text-gray-500">현재 사진</p>
-                        <div className="relative inline-block">
-                          <img
-                            src={`${import.meta.env.VITE_APP_API_HOST}${displayUser.files[0].filePath}`}
-                            alt="현재 프로필 사진"
-                            className="h-20 w-20 rounded-lg object-cover"
-                          />
-                          <button
-                            type="button"
-                            onClick={() => setDeleteFileIds((prev) => [...prev, displayUser.files![0].id])}
-                            className="absolute -right-1.5 -top-1.5 flex h-5 w-5 items-center justify-center rounded-full bg-red-500 text-white hover:bg-red-600"
-                            aria-label="현재 사진 삭제"
-                          >
-                            <X size={11} />
-                          </button>
-                        </div>
-                      </div>
-                    )}
-                    <FileUploader files={editProfilePhoto} onChange={setEditProfilePhoto} />
-                  </>
-                ) : (
-                  <img
-                    src={`${import.meta.env.VITE_APP_API_HOST}${displayUser!.files![0].filePath}`}
-                    alt="프로필 사진"
-                    className="h-32 w-32 rounded-lg object-cover"
-                  />
-                )}
-              </div>
-            </div>
-          )}
-        </ModalBody>
-        <ModalFooter className="flex justify-end gap-2 border-t border-gray-200 bg-neutral-50 px-5 py-3">
-          {controller.mode === "edit" ? (
-            <>
-              <Button
-                variant="outline"
-                onClick={() => {
-                  controller.toRead();
-                  setEditProfilePhoto([]);
-                  setDeleteFileIds([]);
-                }}
-                disabled={controller.isSaving}
-              >
-                취소
-              </Button>
-              <Button type="submit" form={controller.formId} variant="save" disabled={controller.isSaving}>
-                {controller.isSaving ? "저장 중..." : "저장"}
-              </Button>
-            </>
-          ) : (
-            <>
-              {displayUser && (
-                <Button variant="save" onClick={() => controller.toEdit()}>
-                  수정
-                </Button>
-              )}
-              {displayUser && (
-                <Button variant="delete" onClick={() => handleDelete(displayUser)}>
-                  삭제
-                </Button>
-              )}
-              <Button variant="outline" onClick={closeModal}>
-                닫기
-              </Button>
-            </>
-          )}
-        </ModalFooter>
-      </Modal>
-
-      {/* 등록 모달 */}
-      <Modal
-        isOpen={modalMode === "create"}
-        onClose={closeModal}
-        contentClassName="max-w-3xl rounded-xl bg-white"
-      >
-        <ModalIconHeader type="create" title="사용자 등록" onClose={closeModal} />
-        <ModalBody className="px-6 py-5">
-          <div className="overflow-hidden border border-gray-200">
-            <div className="overflow-y-auto max-h-[80vh]">
-              <SubmitForm
-                formId="user-create-form"
-                schema={userCreateSchema}
-                defaultValues={CREATE_DEFAULT_VALUES}
-                onSubmit={handleCreateFormSubmit}
-              >
-                <UserIdChecker />
-                <SubmitForm.Row formKey="userId" label="아이디" required maxLength={50} colspan={4} />
-                <SubmitForm.Row formKey="name" label="성명" required maxLength={50} colspan={4} />
-                <SubmitForm.Row
-                  formKey="password"
-                  formType="password"
-                  label="비밀번호"
-                  required
-                  maxLength={100}
-                  revalidateFields={["passwordCheck"]}
-                  colspan={4}
-                />
-                <SubmitForm.Row
-                  formKey="passwordCheck"
-                  formType="password"
-                  label="비밀번호 확인"
-                  required
-                  maxLength={100}
-                  colspan={4}
-                />
-                <SubmitForm.Row
-                  formKey="role"
-                  formType="radio"
-                  label="구분"
-                  options={ROLE_SUBMIT_OPTIONS}
-                  colspan={4}
-                />
-                <SubmitForm.Row
-                  formKey="gender"
-                  formType="radio"
-                  label="성별"
-                  options={GENDER_OPTIONS}
-                  colspan={4}
-                />
-                <SubmitForm.Row formKey="birthday" formType="date" label="생년월일" colspan={4} />
-                <SubmitForm.Row formKey="phone" label="연락처" colspan={4} maxLength={20} />
-              </SubmitForm>
-            </div>
-          </div>
-          <div className="mt-4 overflow-hidden rounded-lg border border-gray-200">
-            <div className="border-b border-gray-200 bg-gray-50 px-4 py-2 text-sm font-medium text-gray-700">
-              프로필 사진
-            </div>
-            <div className="p-4">
-              <FileUploader files={profilePhoto} onChange={setProfilePhoto} />
-            </div>
-          </div>
-        </ModalBody>
-        <ModalFooter className="flex justify-end gap-2 border-t border-gray-200 bg-neutral-50 px-5 py-3">
-          <Button type="submit" form="user-create-form" variant="save" disabled={isCreating}>
-            등록
-          </Button>
-          <Button variant="outline" onClick={closeModal}>
-            취소
-          </Button>
-        </ModalFooter>
-      </Modal>
-    </div>
-  );
-}
+import { useCallback, useEffect, useState } from "react";
+import { useFormContext } from "react-hook-form";
+import { useSearchParams } from "react-router";
+import { X } from "lucide-react";
+import {
+  Badge,
+  Button,
+  confirmModal,
+  DetailModalFrame,
+  FileUploader,
+  Modal,
+  ModalBody,
+  ModalFooter,
+  ModalIconHeader,
+  PageFilter,
+  Select,
+  SubmitForm,
+  Table,
+  useBlockModalConfirm,
+  useCustomBlocker,
+  useDetailController,
+  type DetailField,
+  type DetailMode,
+  type FormFieldConfig,
+} from "@farmzone/fz-react-ui";
+
+import {
+  checkUserIdAvailable,
+  useDeleteUser,
+  useDeleteUsers,
+  useGetUser,
+  useGetUsers,
+  usePostUser,
+  usePutUser,
+} from "@/app/api/queries";
+import type { User, UserRole } from "@/types";
+import ListContents from "@/app/layout/ListContents";
+import ListHeader from "@/app/layout/ListHeader";
+import { formatDateTime } from "@/shared/utils/format";
+import { getUserColumns } from "./config/columns";
+import {
+  userCreateSchema,
+  userEditSchema,
+  type UserCreateFormData,
+  type UserEditFormData,
+} from "./config/schema";
+
+const PAGE_SIZE_OPTIONS = [
+  { label: "15", value: "15" },
+  { label: "30", value: "30" },
+  { label: "60", value: "60" },
+  { label: "100", value: "100" },
+];
+
+// --- 필터 ---
+
+interface UserFilterParams {
+  role: string;
+  keywordType: string;
+  keyword: string;
+  dateType: string;
+  startDate: string;
+  endDate: string;
+}
+
+const EMPTY_USER_FILTER: UserFilterParams = {
+  role: "",
+  keywordType: "name",
+  keyword: "",
+  dateType: "createdAt",
+  startDate: "",
+  endDate: "",
+};
+
+const ROLE_OPTIONS = [
+  { label: "관리자", value: "ADMIN" },
+  { label: "일반", value: "USER" },
+];
+
+const KEYWORD_TYPE_OPTIONS = [
+  { label: "성명", value: "name" },
+  { label: "아이디", value: "userId" },
+];
+
+const DATE_TYPE_OPTIONS = [
+  { label: "생성일", value: "createdAt" },
+  { label: "최근접속일", value: "lastLoginAt" },
+];
+
+// --- 폼 옵션 ---
+
+const ROLE_SUBMIT_OPTIONS = [
+  { label: "관리자", value: "ADMIN" },
+  { label: "일반", value: "USER" },
+];
+
+const GENDER_OPTIONS = [
+  { label: "남", value: "M" },
+  { label: "여", value: "F" },
+];
+
+const CREATE_DEFAULT_VALUES: UserCreateFormData = {
+  userId: "",
+  name: "",
+  password: "",
+  passwordCheck: "",
+  role: "USER",
+  gender: "",
+  birthday: "",
+  phone: "",
+};
+
+// --- 상세 뷰 타입 ---
+
+interface UserViewData {
+  userId: string;
+  name: string;
+  role: string;
+  gender: string;
+  birthday: string;
+  phone: string;
+  active: boolean;
+  createdAt: string;
+  lastLoginAt: string;
+}
+
+function toViewData(user: User): UserViewData {
+  return {
+    userId: user.userId,
+    name: user.name,
+    role: user.role,
+    gender: user.gender ?? "",
+    birthday: user.birthday ?? "",
+    phone: user.phone ?? "",
+    active: user.active,
+    createdAt: formatDateTime(user.createdAt),
+    lastLoginAt: formatDateTime(user.lastLoginAt),
+  };
+}
+
+const USER_READ_FIELDS: Array<DetailField<UserViewData>> = [
+  { key: "userId", label: "아이디" },
+  { key: "name", label: "성명" },
+  {
+    key: "role",
+    label: "구분",
+    render: ({ value }) => {
+      const role = typeof value === "string" ? value : "";
+      return <span className="text-sm text-gray-900">{role === "ADMIN" ? "관리자" : "일반"}</span>;
+    },
+  },
+  {
+    key: "active",
+    label: "사용여부",
+    render: ({ value }) => {
+      const isActive = typeof value === "boolean" ? value : false;
+      return (
+        <Badge
+          text={isActive ? "활성" : "비활성"}
+          className={`scale-90 ${
+            isActive
+              ? "bg-green-100 text-green-700 border-green-100"
+              : "bg-gray-100 text-gray-500 border-gray-200"
+          }`}
+        />
+      );
+    },
+  },
+  {
+    key: "gender",
+    label: "성별",
+    render: ({ value }) => {
+      const gender = typeof value === "string" ? value : "";
+      return (
+        <span className="text-sm text-gray-900">{gender === "M" ? "남" : gender === "F" ? "여" : "-"}</span>
+      );
+    },
+  },
+  { key: "birthday", label: "생년월일" },
+  { key: "phone", label: "연락처" },
+  { key: "createdAt", label: "등록일시" },
+  { key: "lastLoginAt", label: "최근접속일" },
+];
+
+const USER_EDIT_FIELDS: Array<FormFieldConfig<UserEditFormData>> = [
+  { name: "userId", label: "아이디", readOnly: true, colspan: 4 },
+  { name: "name", label: "성명", required: true, maxLength: 50, colspan: 4 },
+  {
+    name: "password",
+    type: "password",
+    label: "비밀번호 변경",
+    placeholder: "변경 시에만 입력하세요",
+    maxLength: 100,
+    revalidateFields: ["passwordCheck"],
+    colspan: 4,
+  },
+  {
+    name: "passwordCheck",
+    type: "password",
+    label: "비밀번호 확인",
+    placeholder: "변경 시에만 입력하세요",
+    maxLength: 100,
+    colspan: 4,
+  },
+  { name: "active", type: "switch", label: "사용여부", colspan: 4 },
+  { name: "role", type: "radio", label: "구분", options: ROLE_SUBMIT_OPTIONS, colspan: 4 },
+  { name: "gender", type: "radio", label: "성별", options: GENDER_OPTIONS, colspan: 4 },
+  { name: "birthday", type: "date", label: "생년월일", colspan: 4 },
+  { name: "phone", label: "연락처", colspan: 4, maxLength: 20 },
+];
+
+function UserIdChecker() {
+  const { watch, setError, clearErrors } = useFormContext();
+  const rawUserId = watch("userId");
+  const userId = typeof rawUserId === "string" ? rawUserId : "";
+
+  useEffect(() => {
+    if (!userId) {
+      clearErrors("userId");
+      return;
+    }
+    const timer = setTimeout(async () => {
+      const available = await checkUserIdAvailable(userId);
+      if (available) {
+        clearErrors("userId");
+      } else {
+        setError("userId", { type: "manual", message: "이미 사용 중인 아이디입니다." });
+      }
+    }, 500);
+    return () => clearTimeout(timer);
+  }, [userId, setError, clearErrors]);
+
+  return null;
+}
+
+export default function UserPage() {
+  const [page, setPage] = useState(0);
+  const [pageSize, setPageSize] = useState(15);
+  const [filterParams, setFilterParams] = useState<UserFilterParams>(EMPTY_USER_FILTER);
+  const [submittedFilter, setSubmittedFilter] = useState<UserFilterParams>(EMPTY_USER_FILTER);
+  const [selectedKeys, setSelectedKeys] = useState<Array<string | number>>([]);
+  const [profilePhoto, setProfilePhoto] = useState<Array<File>>([]);
+  const [editProfilePhoto, setEditProfilePhoto] = useState<Array<File>>([]);
+  const [deleteFileIds, setDeleteFileIds] = useState<Array<number>>([]);
+  const [isDirty, setIsDirty] = useState(false);
+
+  // URL 기반 모달 상태
+  const [searchParams, setSearchParams] = useSearchParams();
+  const isDetailOpen = searchParams.get("detail") === "true";
+  const isCreateOpen = searchParams.get("create") === "true";
+  const selectedUserId = searchParams.get("userId") ? Number(searchParams.get("userId")) : null;
+  const detailMode = (searchParams.get("detailMode") ?? "read") as DetailMode;
+
+  const { promiseConfirm } = useBlockModalConfirm();
+  const createController = useDetailController();
+
+  // 수정 모드 + dirty 상태일 때 라우터 이탈 방지
+  useCustomBlocker({
+    enabled: isDetailOpen && detailMode === "edit",
+    isDirty,
+    confirm: () =>
+      promiseConfirm({
+        content: "저장하지 않은 변경사항이 있습니다. 페이지를 이동하시겠습니까?",
+      }),
+  });
+
+  const { data, isLoading } = useGetUsers({
+    page,
+    size: pageSize,
+    role: submittedFilter.role || undefined,
+    keywordType: submittedFilter.keyword ? submittedFilter.keywordType : undefined,
+    keyword: submittedFilter.keyword || undefined,
+    dateType: submittedFilter.startDate || submittedFilter.endDate ? submittedFilter.dateType : undefined,
+    startDate: submittedFilter.startDate || undefined,
+    endDate: submittedFilter.endDate || undefined,
+  });
+
+  const { data: detailUser } = useGetUser(isDetailOpen ? selectedUserId : null);
+  const { mutateAsync: postUser } = usePostUser();
+  const { mutateAsync: putUser } = usePutUser();
+  const { mutateAsync: deleteUser } = useDeleteUser();
+  const { mutateAsync: deleteUsers } = useDeleteUsers();
+
+  const totalElements = data?.totalElements ?? 0;
+  const totalPages = data?.totalPages ?? 0;
+  const content = data?.content ?? [];
+
+  const openDetail = useCallback(
+    (user: User) => {
+      setSearchParams((prev) => {
+        const next = new URLSearchParams(prev);
+        next.set("detail", "true");
+        next.set("userId", String(user.id));
+        next.delete("create");
+        return next;
+      });
+    },
+    [setSearchParams],
+  );
+
+  const openDetailInEditMode = useCallback(
+    (user: User) => {
+      setSearchParams((prev) => {
+        const next = new URLSearchParams(prev);
+        next.set("detail", "true");
+        next.set("userId", String(user.id));
+        next.set("detailMode", "edit");
+        next.delete("create");
+        return next;
+      });
+    },
+    [setSearchParams],
+  );
+
+  const openCreate = useCallback(() => {
+    setSearchParams((prev) => {
+      const next = new URLSearchParams(prev);
+      next.set("create", "true");
+      next.delete("detail");
+      next.delete("userId");
+      next.delete("detailMode");
+      return next;
+    });
+  }, [setSearchParams]);
+
+  const handleDetailDone = useCallback(() => {
+    setSearchParams((prev) => {
+      const next = new URLSearchParams(prev);
+      next.delete("detail");
+      next.delete("userId");
+      next.delete("detailMode");
+      return next;
+    });
+    setEditProfilePhoto([]);
+    setDeleteFileIds([]);
+    setIsDirty(false);
+  }, [setSearchParams]);
+
+  const handleDetailModeChange = useCallback(
+    (mode: DetailMode) => {
+      setSearchParams((prev) => {
+        const next = new URLSearchParams(prev);
+        if (mode === "read") {
+          next.delete("detailMode");
+        } else {
+          next.set("detailMode", mode);
+        }
+        return next;
+      });
+    },
+    [setSearchParams],
+  );
+
+  const handleCreateDone = useCallback(() => {
+    setSearchParams((prev) => {
+      const next = new URLSearchParams(prev);
+      next.delete("create");
+      return next;
+    });
+    setProfilePhoto([]);
+  }, [setSearchParams]);
+
+  const createFormId = createController.formId;
+
+  // TODO FormFieldConfig에 autoComplete="off" prop 추가하여 적용 뒤 삭제 필요
+  useEffect(() => {
+    if (!isCreateOpen) return;
+    const timer = setTimeout(() => {
+      const form = document.getElementById(createFormId);
+      if (!form) return;
+      form.setAttribute("autocomplete", "off");
+      form.querySelectorAll("input").forEach((input) => {
+        input.setAttribute("autocomplete", input.type === "password" ? "new-password" : "off");
+      });
+    }, 0);
+    return () => clearTimeout(timer);
+  }, [isCreateOpen, createFormId]);
+
+  const handleCreateFormSubmit = async (formData: UserCreateFormData) => {
+    createController.handleSaveStart();
+    try {
+      const available = await checkUserIdAvailable(formData.userId);
+      if (!available) return;
+      await postUser({
+        data: {
+          userId: formData.userId,
+          name: formData.name,
+          password: formData.password,
+          role: formData.role as UserRole,
+          gender: formData.gender || undefined,
+          birthday: formData.birthday || undefined,
+          phone: formData.phone || undefined,
+        },
+        file: profilePhoto[0],
+      });
+      handleCreateDone();
+    } finally {
+      createController.handleSaveEnd();
+    }
+  };
+
+  const handleDetailEditSave = async (formData: UserEditFormData) => {
+    if (!selectedUserId) return;
+    await putUser({
+      id: selectedUserId,
+      data: {
+        name: formData.name,
+        role: formData.role as UserRole,
+        active: formData.active,
+        gender: formData.gender || undefined,
+        birthday: formData.birthday || undefined,
+        phone: formData.phone || undefined,
+        ...(formData.password ? { password: formData.password } : {}),
+        ...(deleteFileIds.length > 0 ? { deleteFileIds } : {}),
+      },
+      file: editProfilePhoto[0],
+    });
+  };
+
+  const displayUser = detailUser ?? content.find((u) => u.id === selectedUserId);
+  const viewData = displayUser ? toViewData(displayUser) : undefined;
+
+  const handleDelete = useCallback(
+    (user: User) => {
+      confirmModal({
+        content: `"${user.name}" 사용자를 삭제하시겠습니까?`,
+        onOk: async () => {
+          await deleteUser(user.id);
+          handleDetailDone();
+        },
+        onCancel: () => {},
+        className: "max-w-100",
+      });
+    },
+    [deleteUser, handleDetailDone],
+  );
+
+  const handleDeleteDisplayUser = useCallback(() => {
+    if (displayUser) handleDelete(displayUser);
+  }, [displayUser, handleDelete]);
+
+  const renderProfilePhotoSection = useCallback(
+    ({ isEditMode }: { isEditMode: boolean }) => {
+      if (!isEditMode && !displayUser?.files?.length) return null;
+
+      const currentFile = displayUser?.files?.[0];
+      const showCurrentFile = currentFile !== undefined && !deleteFileIds.includes(currentFile.id);
+
+      return (
+        <div className="border-t border-gray-200">
+          <div className="border-b border-gray-200 bg-gray-50 px-4 py-2 text-sm font-medium text-gray-700">
+            프로필 사진
+          </div>
+          <div className="p-4">
+            {isEditMode ? (
+              <>
+                {showCurrentFile && currentFile && (
+                  <div className="mb-3">
+                    <p className="mb-1 text-xs text-gray-500">현재 사진</p>
+                    <div className="relative inline-block">
+                      <img
+                        src={`${import.meta.env.VITE_APP_API_HOST}${currentFile.filePath}`}
+                        alt="현재 프로필 사진"
+                        className="h-20 w-20 rounded-lg object-cover"
+                      />
+                      <button
+                        type="button"
+                        onClick={() => setDeleteFileIds((prev) => [...prev, currentFile.id])}
+                        className="absolute -right-1.5 -top-1.5 flex h-5 w-5 items-center justify-center rounded-full bg-red-500 text-white hover:bg-red-600"
+                        aria-label="현재 사진 삭제"
+                      >
+                        <X size={11} />
+                      </button>
+                    </div>
+                  </div>
+                )}
+                <FileUploader files={editProfilePhoto} onChange={setEditProfilePhoto} />
+              </>
+            ) : (
+              currentFile && (
+                <img
+                  src={`${import.meta.env.VITE_APP_API_HOST}${currentFile.filePath}`}
+                  alt="프로필 사진"
+                  className="h-32 w-32 rounded-lg object-cover"
+                />
+              )
+            )}
+          </div>
+        </div>
+      );
+    },
+    [displayUser, deleteFileIds, editProfilePhoto],
+  );
+
+  const columns = getUserColumns({
+    onEdit: openDetailInEditMode,
+    onDelete: handleDelete,
+    totalElements,
+    page,
+    pageSize,
+  });
+
+  return (
+    <div className="p-6">
+      <ListHeader
+        title="사용자 관리"
+        rightArea={
+          <div className="flex items-center gap-2">
+            <Button variant="save" onClick={openCreate}>
+              등록
+            </Button>
+            <Button
+              variant="delete"
+              disabled={selectedKeys.length === 0}
+              onClick={() => {
+                confirmModal({
+                  content: `선택한 ${selectedKeys.length}개 항목을 삭제하시겠습니까?`,
+                  onOk: async () => {
+                    await deleteUsers(selectedKeys.map(Number));
+                    setSelectedKeys([]);
+                  },
+                  onCancel: () => {},
+                  className: "max-w-100",
+                });
+              }}
+            >
+              삭제
+            </Button>
+          </div>
+        }
+      />
+      <ListContents>
+        <PageFilter
+          values={filterParams}
+          onChange={(updates: Partial<UserFilterParams>) =>
+            setFilterParams((prev) => ({ ...prev, ...updates }))
+          }
+          onSubmit={() => {
+            setPage(0);
+            setSelectedKeys([]);
+            setSubmittedFilter(filterParams);
+          }}
+          onReset={() => {
+            setFilterParams(EMPTY_USER_FILTER);
+            setSubmittedFilter(EMPTY_USER_FILTER);
+            setPage(0);
+            setPageSize(15);
+            setSelectedKeys([]);
+          }}
+          rows={[
+            {
+              options: [
+                { type: "select", key: "role", label: "구분", placeholder: "전체", options: ROLE_OPTIONS },
+                { type: "select", key: "dateType", label: "기간", options: DATE_TYPE_OPTIONS },
+                { type: "date-range", key: "startDate", endKey: "endDate" },
+              ],
+            },
+            {
+              options: [
+                { type: "select", key: "keywordType", label: "검색", options: KEYWORD_TYPE_OPTIONS },
+                { type: "input", key: "keyword", placeholder: "검색어 입력" },
+              ],
+            },
+          ]}
+        />
+        <Table
+          columns={columns}
+          data={content}
+          isLoading={isLoading}
+          rowKey="id"
+          onRowClick={openDetail}
+          paginationInfo={{
+            page,
+            totalPages,
+            onPageChange: (newPage: number) => {
+              setPage(newPage);
+              setSelectedKeys([]);
+            },
+          }}
+          checkboxInfo={{
+            selectedKeys,
+            onSelectionChange: setSelectedKeys,
+          }}
+          renderFooter={{
+            renderLeft: (
+              <p className="text-sm text-gray-600">
+                총 <span className="font-semibold text-gray-900">{totalElements}</span>건
+              </p>
+            ),
+            renderRight: (
+              <div className="flex items-center gap-2.5 pr-5">
+                <p className="text-sm font-medium text-gray-700">페이지 개수</p>
+                <Select
+                  value={String(pageSize)}
+                  options={PAGE_SIZE_OPTIONS}
+                  onChange={(val: string) => {
+                    setPageSize(Number(val));
+                    setPage(0);
+                    setSelectedKeys([]);
+                  }}
+                />
+              </div>
+            ),
+          }}
+        />
+      </ListContents>
+
+      {/* 상세/수정 모달 */}
+      <DetailModalFrame<UserViewData, typeof userEditSchema>
+        key={selectedUserId}
+        open={isDetailOpen}
+        title={detailMode === "edit" ? "사용자 수정" : "사용자 상세"}
+        data={viewData}
+        readFields={USER_READ_FIELDS}
+        editSchema={userEditSchema}
+        editFields={USER_EDIT_FIELDS}
+        onSave={handleDetailEditSave}
+        onDone={handleDetailDone}
+        mode={detailMode}
+        onModeChange={handleDetailModeChange}
+        onDirtyChange={setIsDirty}
+        contentClassName="max-w-3xl"
+        renderExtraContent={renderProfilePhotoSection}
+        renderFooterExtra={
+          displayUser ? (
+            <Button variant="delete" onClick={handleDeleteDisplayUser}>
+              삭제
+            </Button>
+          ) : undefined
+        }
+      />
+
+      {/* 등록 모달 */}
+      <Modal
+        isOpen={isCreateOpen}
+        onClose={handleCreateDone}
+        contentClassName="max-w-3xl rounded-xl bg-white"
+      >
+        <ModalIconHeader type="create" title="사용자 등록" onClose={handleCreateDone} />
+        <ModalBody className="flex-1 min-h-0 p-0">
+          <SubmitForm
+            formId={createFormId}
+            schema={userCreateSchema}
+            defaultValues={CREATE_DEFAULT_VALUES}
+            onSubmit={handleCreateFormSubmit}
+          >
+            <UserIdChecker />
+            <SubmitForm.Row formKey="userId" label="아이디" required maxLength={50} colspan={4} />
+            <SubmitForm.Row formKey="name" label="성명" required maxLength={50} colspan={4} />
+            <SubmitForm.Row
+              formKey="password"
+              formType="password"
+              label="비밀번호"
+              required
+              maxLength={100}
+              revalidateFields={["passwordCheck"]}
+              colspan={4}
+            />
+            <SubmitForm.Row
+              formKey="passwordCheck"
+              formType="password"
+              label="비밀번호 확인"
+              required
+              maxLength={100}
+              colspan={4}
+            />
+            <SubmitForm.Row
+              formKey="role"
+              formType="radio"
+              label="구분"
+              options={ROLE_SUBMIT_OPTIONS}
+              colspan={4}
+            />
+            <SubmitForm.Row
+              formKey="gender"
+              formType="radio"
+              label="성별"
+              options={GENDER_OPTIONS}
+              colspan={4}
+            />
+            <SubmitForm.Row formKey="birthday" formType="date" label="생년월일" colspan={4} />
+            <SubmitForm.Row formKey="phone" label="연락처" colspan={4} maxLength={20} />
+          </SubmitForm>
+          <div className="border-t border-gray-200">
+            <div className="border-b border-gray-200 bg-gray-50 px-4 py-2 text-sm font-medium text-gray-700">
+              프로필 사진
+            </div>
+            <div className="p-4">
+              <FileUploader files={profilePhoto} onChange={setProfilePhoto} />
+            </div>
+          </div>
+        </ModalBody>
+        <ModalFooter className="flex justify-end gap-2 border-t border-gray-200 bg-neutral-50 px-5 py-3">
+          <Button type="submit" form={createFormId} variant="save" disabled={createController.isSaving}>
+            {createController.isSaving ? "저장 중..." : "등록"}
+          </Button>
+          <Button variant="outline" onClick={handleCreateDone}>
+            취소
+          </Button>
+        </ModalFooter>
+      </Modal>
+    </div>
+  );
+}