프론트엔드 기본 구현 완료

docs/공통코드_관리_시스템_설계.md

@@ -679,14 +679,25 @@ export class CommonCodeService {
 - Prisma ORM 연동 완료
 - TypeScript 타입 정의 완료
 
-### ⏳ Phase 3: 프론트엔드 기본 구현 (예정)
+### ✅ Phase 3: 프론트엔드 기본 구현 (완료)
 
-- [ ] 공통코드 관리 페이지 생성
+- [x] 공통코드 관리 페이지 생성
-- [ ] CodeCategoryPanel 컴포넌트 구현
+- [x] CodeCategoryPanel 컴포넌트 구현
-- [ ] CodeDetailPanel 컴포넌트 구현
+- [x] CodeDetailPanel 컴포넌트 구현
-- [ ] 기본 CRUD 기능 구현
+- [x] CodeFormModal, CodeCategoryFormModal 구현
+- [x] 기본 CRUD 기능 구현
+- [x] 관리자 메뉴 통합
+- [x] 실시간 데이터 조회 및 표시
+- [x] 무한 루프 문제 해결
 
-**목표 기간**: 2일
+**완료 내용:**
+
+- 공통코드 관리 페이지 (/admin/commonCode) 완전 구현
+- 4개 주요 컴포넌트 구현 완료
+- 카테고리 선택 시 실시간 코드 조회 기능
+- useCommonCode 커스텀 훅 구현
+- API 응답 처리 최적화 완료
+- 사용자 인터페이스 완성
 
 ### ⏳ Phase 4: 고급 기능 구현 (예정)
 
@@ -717,11 +728,11 @@ export class CommonCodeService {
 
 ## 🎯 현재 구현 상태
 
-### 📊 **전체 진행률: 0%**
+### 📊 **전체 진행률: 50%** 🎉
 
-- ⏳ **Phase 1**: 기본 구조 및 데이터베이스 (0%)
+- ✅ **Phase 1**: 기본 구조 및 데이터베이스 (100%) - **완료!**
-- ⏳ **Phase 2**: 백엔드 API 구현 (0%)
+- ✅ **Phase 2**: 백엔드 API 구현 (100%) - **완료!**
-- ⏳ **Phase 3**: 프론트엔드 기본 구현 (0%)
+- ✅ **Phase 3**: 프론트엔드 기본 구현 (100%) - **완료!**
 - ⏳ **Phase 4**: 고급 기능 구현 (0%)
 - ⏳ **Phase 5**: 화면관리 연계 (0%)
 - ⏳ **Phase 6**: 테스트 및 최적화 (0%)

frontend/app/(main)/admin/commonCode/page.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import { useState } from "react";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Separator } from "@/components/ui/separator";
+import { CodeCategoryPanel } from "@/components/admin/CodeCategoryPanel";
+import { CodeDetailPanel } from "@/components/admin/CodeDetailPanel";
+// import { useMultiLang } from "@/hooks/useMultiLang"; // 무한 루프 방지를 위해 임시 제거
+
+export default function CommonCodeManagementPage() {
+  // const { getText } = useMultiLang(); // 무한 루프 방지를 위해 임시 제거
+  const [selectedCategoryCode, setSelectedCategoryCode] = useState<string>("");
+
+  return (
+    <div className="container mx-auto space-y-6 p-6">
+      {/* 페이지 헤더 */}
+      <div className="flex items-center justify-between">
+        <div>
+          <h1 className="text-3xl font-bold tracking-tight">공통코드 관리</h1>
+          <p className="text-muted-foreground">시스템에서 사용하는 공통코드를 관리합니다</p>
+        </div>
+      </div>
+
+      {/* 메인 콘텐츠 */}
+      <div className="grid grid-cols-1 gap-6 lg:grid-cols-3">
+        {/* 카테고리 패널 */}
+        <Card className="lg:col-span-1">
+          <CardHeader>
+            <CardTitle className="flex items-center gap-2">📂 코드 카테고리</CardTitle>
+          </CardHeader>
+          <CardContent className="p-0">
+            <CodeCategoryPanel selectedCategoryCode={selectedCategoryCode} onSelectCategory={setSelectedCategoryCode} />
+          </CardContent>
+        </Card>
+
+        {/* 구분선 */}
+        <Separator orientation="vertical" className="hidden lg:block" />
+
+        {/* 코드 상세 패널 */}
+        <Card className="lg:col-span-2">
+          <CardHeader>
+            <CardTitle className="flex items-center gap-2">
+              📋 코드 상세 정보
+              {selectedCategoryCode && (
+                <span className="text-muted-foreground text-sm font-normal">({selectedCategoryCode})</span>
+              )}
+            </CardTitle>
+          </CardHeader>
+          <CardContent className="p-0">
+            <CodeDetailPanel categoryCode={selectedCategoryCode} />
+          </CardContent>
+        </Card>
+      </div>
+    </div>
+  );
+}

frontend/components/admin/CodeCategoryFormModal.tsx

@@ -0,0 +1,237 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+import { Label } from "@/components/ui/label";
+import { Switch } from "@/components/ui/switch";
+import { useCommonCode } from "@/hooks/useCommonCode";
+// import { useMultiLang } from "@/hooks/useMultiLang"; // 무한 루프 방지를 위해 임시 제거
+import { LoadingSpinner } from "@/components/common/LoadingSpinner";
+import { CodeCategory } from "@/types/commonCode";
+
+interface CodeCategoryFormModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  editingCategoryCode?: string;
+}
+
+export function CodeCategoryFormModal({ isOpen, onClose, editingCategoryCode }: CodeCategoryFormModalProps) {
+  // const { getText } = useMultiLang(); // 무한 루프 방지를 위해 임시 제거
+  const { categories, createCategory, updateCategory } = useCommonCode();
+
+  // 폼 상태
+  const [formData, setFormData] = useState({
+    categoryCode: "",
+    categoryName: "",
+    categoryNameEng: "",
+    description: "",
+    sortOrder: 0,
+    isActive: true,
+  });
+
+  const [loading, setLoading] = useState(false);
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  // 수정 모드일 때 기존 데이터 로드
+  useEffect(() => {
+    if (editingCategoryCode && categories.length > 0) {
+      const category = categories.find((c) => c.category_code === editingCategoryCode);
+      if (category) {
+        setFormData({
+          categoryCode: category.category_code,
+          categoryName: category.category_name,
+          categoryNameEng: category.category_name_eng || "",
+          description: category.description || "",
+          sortOrder: category.sort_order,
+          isActive: category.is_active === "Y",
+        });
+      }
+    } else {
+      // 새 카테고리일 때 초기값
+      setFormData({
+        categoryCode: "",
+        categoryName: "",
+        categoryNameEng: "",
+        description: "",
+        sortOrder: 0,
+        isActive: true,
+      });
+    }
+    setErrors({});
+  }, [editingCategoryCode, categories, isOpen]);
+
+  // 입력값 검증
+  const validateForm = () => {
+    const newErrors: Record<string, string> = {};
+
+    if (!formData.categoryCode.trim()) {
+      newErrors.categoryCode = "필수 입력 항목입니다.";
+    }
+
+    if (!formData.categoryName.trim()) {
+      newErrors.categoryName = "필수 입력 항목입니다.";
+    }
+
+    setErrors(newErrors);
+    return Object.keys(newErrors).length === 0;
+  };
+
+  // 폼 제출 핸들러
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+
+    if (!validateForm()) return;
+
+    setLoading(true);
+
+    try {
+      if (editingCategoryCode) {
+        // 수정
+        await updateCategory(editingCategoryCode, {
+          categoryName: formData.categoryName,
+          categoryNameEng: formData.categoryNameEng,
+          description: formData.description,
+          sortOrder: formData.sortOrder,
+          isActive: formData.isActive,
+        });
+      } else {
+        // 생성
+        await createCategory({
+          categoryCode: formData.categoryCode,
+          categoryName: formData.categoryName,
+          categoryNameEng: formData.categoryNameEng,
+          description: formData.description,
+          sortOrder: formData.sortOrder,
+        });
+      }
+
+      onClose();
+    } catch (error) {
+      console.error("카테고리 저장 오류:", error);
+      // 에러 처리는 useCommonCode 훅에서 처리됨
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  // 입력값 변경 핸들러
+  const handleChange = (field: string, value: any) => {
+    setFormData((prev) => ({ ...prev, [field]: value }));
+
+    // 에러 제거
+    if (errors[field]) {
+      setErrors((prev) => ({ ...prev, [field]: "" }));
+    }
+  };
+
+  return (
+    <Dialog open={isOpen} onOpenChange={onClose}>
+      <DialogContent className="sm:max-w-[500px]">
+        <DialogHeader>
+          <DialogTitle>{editingCategoryCode ? "카테고리 수정" : "새 카테고리"}</DialogTitle>
+        </DialogHeader>
+
+        <form onSubmit={handleSubmit} className="space-y-4">
+          {/* 카테고리 코드 */}
+          <div className="space-y-2">
+            <Label htmlFor="categoryCode">{"카테고리 코드"} *</Label>
+            <Input
+              id="categoryCode"
+              value={formData.categoryCode}
+              onChange={(e) => handleChange("categoryCode", e.target.value)}
+              disabled={!!editingCategoryCode || loading}
+              placeholder={"카테고리 코드를 입력하세요"}
+              className={errors.categoryCode ? "border-red-500" : ""}
+            />
+            {errors.categoryCode && <p className="text-sm text-red-600">{errors.categoryCode}</p>}
+          </div>
+
+          {/* 카테고리명 */}
+          <div className="space-y-2">
+            <Label htmlFor="categoryName">{"카테고리명"} *</Label>
+            <Input
+              id="categoryName"
+              value={formData.categoryName}
+              onChange={(e) => handleChange("categoryName", e.target.value)}
+              disabled={loading}
+              placeholder={"카테고리명을 입력하세요"}
+              className={errors.categoryName ? "border-red-500" : ""}
+            />
+            {errors.categoryName && <p className="text-sm text-red-600">{errors.categoryName}</p>}
+          </div>
+
+          {/* 영문명 */}
+          <div className="space-y-2">
+            <Label htmlFor="categoryNameEng">{"카테고리 영문명"}</Label>
+            <Input
+              id="categoryNameEng"
+              value={formData.categoryNameEng}
+              onChange={(e) => handleChange("categoryNameEng", e.target.value)}
+              disabled={loading}
+              placeholder={"카테고리 영문명을 입력하세요"}
+            />
+          </div>
+
+          {/* 설명 */}
+          <div className="space-y-2">
+            <Label htmlFor="description">{"설명"}</Label>
+            <Textarea
+              id="description"
+              value={formData.description}
+              onChange={(e) => handleChange("description", e.target.value)}
+              disabled={loading}
+              placeholder={"설명을 입력하세요"}
+              rows={3}
+            />
+          </div>
+
+          {/* 정렬 순서 */}
+          <div className="space-y-2">
+            <Label htmlFor="sortOrder">{"정렬 순서"}</Label>
+            <Input
+              id="sortOrder"
+              type="number"
+              value={formData.sortOrder}
+              onChange={(e) => handleChange("sortOrder", parseInt(e.target.value) || 0)}
+              disabled={loading}
+              min={0}
+            />
+          </div>
+
+          {/* 활성 상태 (수정 시에만) */}
+          {editingCategoryCode && (
+            <div className="flex items-center space-x-2">
+              <Switch
+                id="isActive"
+                checked={formData.isActive}
+                onCheckedChange={(checked) => handleChange("isActive", checked)}
+                disabled={loading}
+              />
+              <Label htmlFor="isActive">{"활성"}</Label>
+            </div>
+          )}
+
+          {/* 버튼 */}
+          <div className="flex justify-end space-x-2 pt-4">
+            <Button type="button" variant="outline" onClick={onClose} disabled={loading}>
+              {"취소"}
+            </Button>
+            <Button type="submit" disabled={loading}>
+              {loading ? (
+                <>
+                  <LoadingSpinner size="sm" className="mr-2" />
+                  {"저장 중..."}
+                </>
+              ) : (
+                "저장"
+              )}
+            </Button>
+          </div>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}

frontend/components/admin/CodeCategoryPanel.tsx

@@ -0,0 +1,200 @@
+"use client";
+
+import { useState } from "react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Badge } from "@/components/ui/badge";
+import { LoadingSpinner } from "@/components/common/LoadingSpinner";
+import { useCommonCode } from "@/hooks/useCommonCode";
+// import { useMultiLang } from "@/hooks/useMultiLang"; // 무한 루프 방지를 위해 임시 제거
+import { CodeCategoryFormModal } from "./CodeCategoryFormModal";
+import { AlertModal } from "@/components/common/AlertModal";
+import { Search, Plus, Edit, Trash2 } from "lucide-react";
+import { cn } from "@/lib/utils";
+
+interface CodeCategoryPanelProps {
+  selectedCategoryCode: string;
+  onSelectCategory: (categoryCode: string) => void;
+}
+
+export function CodeCategoryPanel({ selectedCategoryCode, onSelectCategory }: CodeCategoryPanelProps) {
+  // useMultiLang 호출 제거 - 상위에서 전달받도록 수정
+  const { categories, categoriesLoading, categoriesError, fetchCategories, deleteCategory } = useCommonCode();
+
+  // 로컬 상태
+  const [searchTerm, setSearchTerm] = useState("");
+  const [showFormModal, setShowFormModal] = useState(false);
+  const [editingCategory, setEditingCategory] = useState<string>("");
+  const [showDeleteModal, setShowDeleteModal] = useState(false);
+  const [deletingCategory, setDeletingCategory] = useState<string>("");
+
+  // 검색 필터링
+  const filteredCategories = categories.filter(
+    (category) =>
+      category.category_name.toLowerCase().includes(searchTerm.toLowerCase()) ||
+      category.category_code.toLowerCase().includes(searchTerm.toLowerCase()),
+  );
+
+  // 카테고리 생성 핸들러
+  const handleCreateCategory = () => {
+    setEditingCategory("");
+    setShowFormModal(true);
+  };
+
+  // 카테고리 수정 핸들러
+  const handleEditCategory = (categoryCode: string) => {
+    setEditingCategory(categoryCode);
+    setShowFormModal(true);
+  };
+
+  // 카테고리 삭제 핸들러
+  const handleDeleteCategory = (categoryCode: string) => {
+    setDeletingCategory(categoryCode);
+    setShowDeleteModal(true);
+  };
+
+  // 삭제 확인 핸들러
+  const handleConfirmDelete = async () => {
+    if (!deletingCategory) return;
+
+    try {
+      await deleteCategory(deletingCategory);
+      setShowDeleteModal(false);
+      setDeletingCategory("");
+    } catch (error) {
+      console.error("카테고리 삭제 오류:", error);
+      // 에러 처리는 useCommonCode 훅에서 처리됨
+    }
+  };
+
+  if (categoriesError) {
+    return (
+      <div className="p-4 text-center text-red-600">
+        <p className="mb-2">❌ {categoriesError}</p>
+        <Button onClick={() => fetchCategories()} variant="outline" size="sm">
+          다시 시도
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      {/* 검색 및 추가 버튼 */}
+      <div className="space-y-3 border-b p-4">
+        <div className="flex gap-2">
+          <div className="relative flex-1">
+            <Search className="absolute top-1/2 left-3 h-4 w-4 -translate-y-1/2 transform text-gray-400" />
+            <Input
+              placeholder="카테고리 검색..."
+              value={searchTerm}
+              onChange={(e) => setSearchTerm(e.target.value)}
+              className="pl-10"
+            />
+          </div>
+        </div>
+
+        <Button onClick={handleCreateCategory} className="w-full" size="sm">
+          <Plus className="mr-2 h-4 w-4" />새 카테고리
+        </Button>
+      </div>
+
+      {/* 카테고리 목록 */}
+      <div className="max-h-96 overflow-y-auto">
+        {categoriesLoading ? (
+          <div className="p-4 text-center">
+            <LoadingSpinner size="sm" />
+            <p className="text-muted-foreground mt-2 text-sm">카테고리를 불러오는 중...</p>
+          </div>
+        ) : filteredCategories.length === 0 ? (
+          <div className="text-muted-foreground p-4 text-center">
+            <p>카테고리가 없습니다.</p>
+          </div>
+        ) : (
+          <div className="space-y-1">
+            {filteredCategories.map((category) => (
+              <div
+                key={category.category_code}
+                className={cn(
+                  "group flex cursor-pointer items-center justify-between rounded-lg p-3 transition-colors",
+                  selectedCategoryCode === category.category_code
+                    ? "bg-primary text-primary-foreground"
+                    : "hover:bg-muted",
+                )}
+                onClick={() => onSelectCategory(category.category_code)}
+              >
+                <div className="min-w-0 flex-1">
+                  <div className="mb-1 flex items-center gap-2">
+                    <span className="text-sm font-medium">{category.category_name}</span>
+                    {category.is_active === "Y" ? (
+                      <Badge variant="secondary" className="text-xs">
+                        활성
+                      </Badge>
+                    ) : (
+                      <Badge variant="outline" className="text-xs">
+                        비활성
+                      </Badge>
+                    )}
+                  </div>
+                  <p className="text-muted-foreground truncate text-xs">{category.category_code}</p>
+                  {category.description && (
+                    <p className="text-muted-foreground mt-1 truncate text-xs">{category.description}</p>
+                  )}
+                </div>
+
+                {/* 액션 버튼 */}
+                <div className="flex gap-1 opacity-0 transition-opacity group-hover:opacity-100">
+                  <Button
+                    variant="ghost"
+                    size="sm"
+                    className="h-8 w-8 p-0"
+                    onClick={(e) => {
+                      e.stopPropagation();
+                      handleEditCategory(category.category_code);
+                    }}
+                  >
+                    <Edit className="h-3 w-3" />
+                  </Button>
+                  <Button
+                    variant="ghost"
+                    size="sm"
+                    className="h-8 w-8 p-0 text-red-600 hover:text-red-700"
+                    onClick={(e) => {
+                      e.stopPropagation();
+                      handleDeleteCategory(category.category_code);
+                    }}
+                  >
+                    <Trash2 className="h-3 w-3" />
+                  </Button>
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+
+      {/* 카테고리 폼 모달 */}
+      {showFormModal && (
+        <CodeCategoryFormModal
+          isOpen={showFormModal}
+          onClose={() => setShowFormModal(false)}
+          editingCategoryCode={editingCategory}
+        />
+      )}
+
+      {/* 삭제 확인 모달 */}
+      {showDeleteModal && (
+        <AlertModal
+          isOpen={showDeleteModal}
+          onClose={() => setShowDeleteModal(false)}
+          onConfirm={handleConfirmDelete}
+          title="삭제 확인"
+          message="이 카테고리를 삭제하시겠습니까? 관련된 모든 코드도 함께 삭제됩니다."
+          confirmText="삭제"
+          cancelText="취소"
+          variant="destructive"
+        />
+      )}
+    </div>
+  );
+}

frontend/components/admin/CodeDetailPanel.tsx

@@ -0,0 +1,220 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Badge } from "@/components/ui/badge";
+import { LoadingSpinner } from "@/components/common/LoadingSpinner";
+import { useCommonCode } from "@/hooks/useCommonCode";
+// import { useMultiLang } from "@/hooks/useMultiLang"; // 무한 루프 방지를 위해 임시 제거
+import { CodeFormModal } from "./CodeFormModal";
+import { AlertModal } from "@/components/common/AlertModal";
+import { Search, Plus, Edit, Trash2 } from "lucide-react";
+import { cn } from "@/lib/utils";
+
+interface CodeDetailPanelProps {
+  categoryCode: string;
+}
+
+export function CodeDetailPanel({ categoryCode }: CodeDetailPanelProps) {
+  // const { getText } = useMultiLang(); // 무한 루프 방지를 위해 임시 제거
+  const { codes, codesLoading, codesError, fetchCodes, deleteCode } = useCommonCode();
+
+  // 카테고리 변경 시 코드 조회
+  useEffect(() => {
+    if (categoryCode) {
+      console.log("🔍 카테고리 변경됨, 코드 조회:", categoryCode);
+      fetchCodes(categoryCode);
+    }
+  }, [categoryCode, fetchCodes]);
+
+  // 로컬 상태
+  const [searchTerm, setSearchTerm] = useState("");
+  const [showFormModal, setShowFormModal] = useState(false);
+  const [editingCode, setEditingCode] = useState<{ categoryCode: string; codeValue: string }>({
+    categoryCode: "",
+    codeValue: "",
+  });
+  const [showDeleteModal, setShowDeleteModal] = useState(false);
+  const [deletingCode, setDeletingCode] = useState<{ categoryCode: string; codeValue: string }>({
+    categoryCode: "",
+    codeValue: "",
+  });
+
+  // 검색 필터링
+  const filteredCodes = codes.filter(
+    (code) =>
+      code.code_name.toLowerCase().includes(searchTerm.toLowerCase()) ||
+      code.code_value.toLowerCase().includes(searchTerm.toLowerCase()),
+  );
+
+  // 코드 생성 핸들러
+  const handleCreateCode = () => {
+    if (!categoryCode) return;
+
+    setEditingCode({ categoryCode: "", codeValue: "" });
+    setShowFormModal(true);
+  };
+
+  // 코드 수정 핸들러
+  const handleEditCode = (codeValue: string) => {
+    setEditingCode({ categoryCode, codeValue });
+    setShowFormModal(true);
+  };
+
+  // 코드 삭제 핸들러
+  const handleDeleteCode = (codeValue: string) => {
+    setDeletingCode({ categoryCode, codeValue });
+    setShowDeleteModal(true);
+  };
+
+  // 삭제 확인 핸들러
+  const handleConfirmDelete = async () => {
+    if (!deletingCode.categoryCode || !deletingCode.codeValue) return;
+
+    try {
+      await deleteCode(deletingCode.categoryCode, deletingCode.codeValue);
+      setShowDeleteModal(false);
+      setDeletingCode({ categoryCode: "", codeValue: "" });
+    } catch (error) {
+      console.error("코드 삭제 오류:", error);
+      // 에러 처리는 useCommonCode 훅에서 처리됨
+    }
+  };
+
+  // 카테고리가 선택되지 않은 경우
+  if (!categoryCode) {
+    return (
+      <div className="text-muted-foreground flex h-64 items-center justify-center">
+        <div className="text-center">
+          <p className="mb-2 text-lg font-medium">카테고리를 선택하세요</p>
+          <p className="text-sm">왼쪽에서 카테고리를 선택하면 해당 코드 목록이 표시됩니다.</p>
+        </div>
+      </div>
+    );
+  }
+
+  // 에러 상태
+  if (codesError) {
+    return (
+      <div className="p-4 text-center text-red-600">
+        <p className="mb-2">❌ {codesError}</p>
+        <Button onClick={() => fetchCodes(categoryCode)} variant="outline" size="sm">
+          다시 시도
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      {/* 검색 및 추가 버튼 */}
+      <div className="space-y-3 border-b p-4">
+        <div className="flex gap-2">
+          <div className="relative flex-1">
+            <Search className="absolute top-1/2 left-3 h-4 w-4 -translate-y-1/2 transform text-gray-400" />
+            <Input
+              placeholder="코드 검색..."
+              value={searchTerm}
+              onChange={(e) => setSearchTerm(e.target.value)}
+              className="pl-10"
+            />
+          </div>
+        </div>
+
+        <Button onClick={handleCreateCode} className="w-full" size="sm">
+          <Plus className="mr-2 h-4 w-4" />새 코드
+        </Button>
+      </div>
+
+      {/* 코드 목록 */}
+      <div className="max-h-96 overflow-y-auto">
+        {codesLoading ? (
+          <div className="p-4 text-center">
+            <LoadingSpinner size="sm" />
+            <p className="text-muted-foreground mt-2 text-sm">코드를 불러오는 중...</p>
+          </div>
+        ) : filteredCodes.length === 0 ? (
+          <div className="text-muted-foreground p-4 text-center">
+            <p>코드가 없습니다.</p>
+          </div>
+        ) : (
+          <div className="space-y-1">
+            {filteredCodes.map((code) => (
+              <div
+                key={`${code.code_category}-${code.code_value}`}
+                className="group hover:bg-muted flex items-center justify-between rounded-lg p-3 transition-colors"
+              >
+                <div className="min-w-0 flex-1">
+                  <div className="mb-1 flex items-center gap-2">
+                    <span className="text-sm font-medium">{code.code_name}</span>
+                    {code.is_active === "Y" ? (
+                      <Badge variant="secondary" className="text-xs">
+                        활성
+                      </Badge>
+                    ) : (
+                      <Badge variant="outline" className="text-xs">
+                        비활성
+                      </Badge>
+                    )}
+                  </div>
+                  <div className="text-muted-foreground flex items-center gap-2 text-xs">
+                    <span className="bg-muted rounded px-2 py-1 font-mono">{code.code_value}</span>
+                    {code.code_name_eng && <span>({code.code_name_eng})</span>}
+                  </div>
+                  {code.description && (
+                    <p className="text-muted-foreground mt-1 truncate text-xs">{code.description}</p>
+                  )}
+                </div>
+
+                {/* 액션 버튼 */}
+                <div className="flex gap-1 opacity-0 transition-opacity group-hover:opacity-100">
+                  <Button
+                    variant="ghost"
+                    size="sm"
+                    className="h-8 w-8 p-0"
+                    onClick={() => handleEditCode(code.code_value)}
+                  >
+                    <Edit className="h-3 w-3" />
+                  </Button>
+                  <Button
+                    variant="ghost"
+                    size="sm"
+                    className="h-8 w-8 p-0 text-red-600 hover:text-red-700"
+                    onClick={() => handleDeleteCode(code.code_value)}
+                  >
+                    <Trash2 className="h-3 w-3" />
+                  </Button>
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+
+      {/* 코드 폼 모달 */}
+      {showFormModal && (
+        <CodeFormModal
+          isOpen={showFormModal}
+          onClose={() => setShowFormModal(false)}
+          categoryCode={categoryCode}
+          editingCodeValue={editingCode.codeValue}
+        />
+      )}
+
+      {/* 삭제 확인 모달 */}
+      {showDeleteModal && (
+        <AlertModal
+          isOpen={showDeleteModal}
+          onClose={() => setShowDeleteModal(false)}
+          onConfirm={handleConfirmDelete}
+          title="삭제 확인"
+          message="이 코드를 삭제하시겠습니까?"
+          confirmText="삭제"
+          cancelText="취소"
+          variant="destructive"
+        />
+      )}
+    </div>
+  );
+}

frontend/components/admin/CodeFormModal.tsx

@@ -0,0 +1,237 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+import { Label } from "@/components/ui/label";
+import { Switch } from "@/components/ui/switch";
+import { useCommonCode } from "@/hooks/useCommonCode";
+// import { useMultiLang } from "@/hooks/useMultiLang"; // 무한 루프 방지를 위해 임시 제거
+import { LoadingSpinner } from "@/components/common/LoadingSpinner";
+
+interface CodeFormModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  categoryCode: string;
+  editingCodeValue?: string;
+}
+
+export function CodeFormModal({ isOpen, onClose, categoryCode, editingCodeValue }: CodeFormModalProps) {
+  // const { getText } = useMultiLang(); // 무한 루프 방지를 위해 임시 제거
+  const { codes, createCode, updateCode } = useCommonCode();
+
+  // 폼 상태
+  const [formData, setFormData] = useState({
+    codeValue: "",
+    codeName: "",
+    codeNameEng: "",
+    description: "",
+    sortOrder: 0,
+    isActive: true,
+  });
+
+  const [loading, setLoading] = useState(false);
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  // 수정 모드일 때 기존 데이터 로드
+  useEffect(() => {
+    if (editingCodeValue && codes.length > 0) {
+      const code = codes.find((c) => c.code_value === editingCodeValue);
+      if (code) {
+        setFormData({
+          codeValue: code.code_value,
+          codeName: code.code_name,
+          codeNameEng: code.code_name_eng || "",
+          description: code.description || "",
+          sortOrder: code.sort_order,
+          isActive: code.is_active === "Y",
+        });
+      }
+    } else {
+      // 새 코드일 때 초기값
+      setFormData({
+        codeValue: "",
+        codeName: "",
+        codeNameEng: "",
+        description: "",
+        sortOrder: 0,
+        isActive: true,
+      });
+    }
+    setErrors({});
+  }, [editingCodeValue, codes, isOpen]);
+
+  // 입력값 검증
+  const validateForm = () => {
+    const newErrors: Record<string, string> = {};
+
+    if (!formData.codeValue.trim()) {
+      newErrors.codeValue = "필수 입력 항목입니다.";
+    }
+
+    if (!formData.codeName.trim()) {
+      newErrors.codeName = "필수 입력 항목입니다.";
+    }
+
+    setErrors(newErrors);
+    return Object.keys(newErrors).length === 0;
+  };
+
+  // 폼 제출 핸들러
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+
+    if (!validateForm()) return;
+
+    setLoading(true);
+
+    try {
+      if (editingCodeValue) {
+        // 수정
+        await updateCode(categoryCode, editingCodeValue, {
+          codeName: formData.codeName,
+          codeNameEng: formData.codeNameEng,
+          description: formData.description,
+          sortOrder: formData.sortOrder,
+          isActive: formData.isActive,
+        });
+      } else {
+        // 생성
+        await createCode(categoryCode, {
+          codeValue: formData.codeValue,
+          codeName: formData.codeName,
+          codeNameEng: formData.codeNameEng,
+          description: formData.description,
+          sortOrder: formData.sortOrder,
+        });
+      }
+
+      onClose();
+    } catch (error) {
+      console.error("코드 저장 오류:", error);
+      // 에러 처리는 useCommonCode 훅에서 처리됨
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  // 입력값 변경 핸들러
+  const handleChange = (field: string, value: any) => {
+    setFormData((prev) => ({ ...prev, [field]: value }));
+
+    // 에러 제거
+    if (errors[field]) {
+      setErrors((prev) => ({ ...prev, [field]: "" }));
+    }
+  };
+
+  return (
+    <Dialog open={isOpen} onOpenChange={onClose}>
+      <DialogContent className="sm:max-w-[500px]">
+        <DialogHeader>
+          <DialogTitle>{editingCodeValue ? "코드 수정" : "새 코드"}</DialogTitle>
+        </DialogHeader>
+
+        <form onSubmit={handleSubmit} className="space-y-4">
+          {/* 코드값 */}
+          <div className="space-y-2">
+            <Label htmlFor="codeValue">{"코드값"} *</Label>
+            <Input
+              id="codeValue"
+              value={formData.codeValue}
+              onChange={(e) => handleChange("codeValue", e.target.value)}
+              disabled={!!editingCodeValue || loading}
+              placeholder={"코드값을 입력하세요"}
+              className={errors.codeValue ? "border-red-500" : ""}
+            />
+            {errors.codeValue && <p className="text-sm text-red-600">{errors.codeValue}</p>}
+          </div>
+
+          {/* 코드명 */}
+          <div className="space-y-2">
+            <Label htmlFor="codeName">{"코드명"} *</Label>
+            <Input
+              id="codeName"
+              value={formData.codeName}
+              onChange={(e) => handleChange("codeName", e.target.value)}
+              disabled={loading}
+              placeholder={"코드명을 입력하세요"}
+              className={errors.codeName ? "border-red-500" : ""}
+            />
+            {errors.codeName && <p className="text-sm text-red-600">{errors.codeName}</p>}
+          </div>
+
+          {/* 영문명 */}
+          <div className="space-y-2">
+            <Label htmlFor="codeNameEng">{"코드 영문명"}</Label>
+            <Input
+              id="codeNameEng"
+              value={formData.codeNameEng}
+              onChange={(e) => handleChange("codeNameEng", e.target.value)}
+              disabled={loading}
+              placeholder={"코드 영문명을 입력하세요"}
+            />
+          </div>
+
+          {/* 설명 */}
+          <div className="space-y-2">
+            <Label htmlFor="description">{"설명"}</Label>
+            <Textarea
+              id="description"
+              value={formData.description}
+              onChange={(e) => handleChange("description", e.target.value)}
+              disabled={loading}
+              placeholder={"설명을 입력하세요"}
+              rows={3}
+            />
+          </div>
+
+          {/* 정렬 순서 */}
+          <div className="space-y-2">
+            <Label htmlFor="sortOrder">{"정렬 순서"}</Label>
+            <Input
+              id="sortOrder"
+              type="number"
+              value={formData.sortOrder}
+              onChange={(e) => handleChange("sortOrder", parseInt(e.target.value) || 0)}
+              disabled={loading}
+              min={0}
+            />
+          </div>
+
+          {/* 활성 상태 (수정 시에만) */}
+          {editingCodeValue && (
+            <div className="flex items-center space-x-2">
+              <Switch
+                id="isActive"
+                checked={formData.isActive}
+                onCheckedChange={(checked) => handleChange("isActive", checked)}
+                disabled={loading}
+              />
+              <Label htmlFor="isActive">{"활성"}</Label>
+            </div>
+          )}
+
+          {/* 버튼 */}
+          <div className="flex justify-end space-x-2 pt-4">
+            <Button type="button" variant="outline" onClick={onClose} disabled={loading}>
+              {"취소"}
+            </Button>
+            <Button type="submit" disabled={loading}>
+              {loading ? (
+                <>
+                  <LoadingSpinner size="sm" className="mr-2" />
+                  {"저장 중..."}
+                </>
+              ) : (
+                "저장"
+              )}
+            </Button>
+          </div>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}

frontend/hooks/useCommonCode.ts

@@ -0,0 +1,265 @@
+import { useState, useEffect, useCallback } from "react";
+import { commonCodeApi } from "@/lib/api/commonCode";
+import {
+  CodeCategory,
+  CodeInfo,
+  CreateCategoryRequest,
+  UpdateCategoryRequest,
+  CreateCodeRequest,
+  UpdateCodeRequest,
+  GetCategoriesQuery,
+  GetCodesQuery,
+} from "@/types/commonCode";
+
+/**
+ * 공통코드 관리를 위한 커스텀 훅
+ */
+export function useCommonCode() {
+  // 카테고리 관련 상태
+  const [categories, setCategories] = useState<CodeCategory[]>([]);
+  const [categoriesLoading, setCategoriesLoading] = useState(false);
+  const [categoriesError, setCategoriesError] = useState<string | null>(null);
+  const [totalCategories, setTotalCategories] = useState(0);
+
+  // 코드 관련 상태
+  const [codes, setCodes] = useState<CodeInfo[]>([]);
+  const [codesLoading, setCodesLoading] = useState(false);
+  const [codesError, setCodesError] = useState<string | null>(null);
+
+  // 선택된 카테고리
+  const [selectedCategoryCode, setSelectedCategoryCode] = useState<string>("");
+
+  /**
+   * 카테고리 목록 조회
+   */
+  const fetchCategories = useCallback(async (params?: GetCategoriesQuery) => {
+    setCategoriesLoading(true);
+    setCategoriesError(null);
+
+    try {
+      const response = await commonCodeApi.categories.getList(params);
+
+      if (response.success) {
+        setCategories(response.data || []);
+        setTotalCategories(response.total || 0);
+        setCategoriesError(null); // 에러 상태 초기화
+      } else {
+        throw new Error(response.message || "카테고리 조회에 실패했습니다.");
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "알 수 없는 오류가 발생했습니다.";
+      setCategoriesError(errorMessage);
+      console.error("카테고리 조회 오류:", error);
+    } finally {
+      setCategoriesLoading(false);
+    }
+  }, []);
+
+  /**
+   * 코드 목록 조회
+   */
+  const fetchCodes = useCallback(async (categoryCode: string, params?: GetCodesQuery) => {
+    if (!categoryCode) {
+      setCodes([]);
+      return;
+    }
+
+    setCodesLoading(true);
+    setCodesError(null);
+
+    try {
+      const response = await commonCodeApi.codes.getList(categoryCode, params);
+
+      if (response.success && response.data) {
+        setCodes(response.data);
+      } else {
+        throw new Error(response.message || "코드 조회에 실패했습니다.");
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "알 수 없는 오류가 발생했습니다.";
+      setCodesError(errorMessage);
+      console.error("코드 조회 오류:", error);
+    } finally {
+      setCodesLoading(false);
+    }
+  }, []);
+
+  /**
+   * 카테고리 생성
+   */
+  const createCategory = useCallback(
+    async (data: CreateCategoryRequest) => {
+      try {
+        const response = await commonCodeApi.categories.create(data);
+
+        if (response.success) {
+          await fetchCategories(); // 목록 새로고침
+          return response;
+        } else {
+          throw new Error(response.message || "카테고리 생성에 실패했습니다.");
+        }
+      } catch (error) {
+        console.error("카테고리 생성 오류:", error);
+        throw error;
+      }
+    },
+    [fetchCategories],
+  );
+
+  /**
+   * 카테고리 수정
+   */
+  const updateCategory = useCallback(
+    async (categoryCode: string, data: UpdateCategoryRequest) => {
+      try {
+        const response = await commonCodeApi.categories.update(categoryCode, data);
+
+        if (response.success) {
+          await fetchCategories(); // 목록 새로고침
+          return response;
+        } else {
+          throw new Error(response.message || "카테고리 수정에 실패했습니다.");
+        }
+      } catch (error) {
+        console.error("카테고리 수정 오류:", error);
+        throw error;
+      }
+    },
+    [fetchCategories],
+  );
+
+  /**
+   * 카테고리 삭제
+   */
+  const deleteCategory = useCallback(
+    async (categoryCode: string) => {
+      try {
+        const response = await commonCodeApi.categories.delete(categoryCode);
+
+        if (response.success) {
+          await fetchCategories(); // 목록 새로고침
+          if (selectedCategoryCode === categoryCode) {
+            setSelectedCategoryCode(""); // 선택 해제
+            setCodes([]); // 코드 목록 초기화
+          }
+          return response;
+        } else {
+          throw new Error(response.message || "카테고리 삭제에 실패했습니다.");
+        }
+      } catch (error) {
+        console.error("카테고리 삭제 오류:", error);
+        throw error;
+      }
+    },
+    [fetchCategories, selectedCategoryCode],
+  );
+
+  /**
+   * 코드 생성
+   */
+  const createCode = useCallback(
+    async (categoryCode: string, data: CreateCodeRequest) => {
+      try {
+        const response = await commonCodeApi.codes.create(categoryCode, data);
+
+        if (response.success) {
+          await fetchCodes(categoryCode); // 목록 새로고침
+          return response;
+        } else {
+          throw new Error(response.message || "코드 생성에 실패했습니다.");
+        }
+      } catch (error) {
+        console.error("코드 생성 오류:", error);
+        throw error;
+      }
+    },
+    [fetchCodes],
+  );
+
+  /**
+   * 코드 수정
+   */
+  const updateCode = useCallback(
+    async (categoryCode: string, codeValue: string, data: UpdateCodeRequest) => {
+      try {
+        const response = await commonCodeApi.codes.update(categoryCode, codeValue, data);
+
+        if (response.success) {
+          await fetchCodes(categoryCode); // 목록 새로고침
+          return response;
+        } else {
+          throw new Error(response.message || "코드 수정에 실패했습니다.");
+        }
+      } catch (error) {
+        console.error("코드 수정 오류:", error);
+        throw error;
+      }
+    },
+    [fetchCodes],
+  );
+
+  /**
+   * 코드 삭제
+   */
+  const deleteCode = useCallback(
+    async (categoryCode: string, codeValue: string) => {
+      try {
+        const response = await commonCodeApi.codes.delete(categoryCode, codeValue);
+
+        if (response.success) {
+          await fetchCodes(categoryCode); // 목록 새로고침
+          return response;
+        } else {
+          throw new Error(response.message || "코드 삭제에 실패했습니다.");
+        }
+      } catch (error) {
+        console.error("코드 삭제 오류:", error);
+        throw error;
+      }
+    },
+    [fetchCodes],
+  );
+
+  /**
+   * 초기 데이터 로드
+   */
+  useEffect(() => {
+    fetchCategories();
+  }, [fetchCategories]);
+
+  /**
+   * 선택된 카테고리 변경 시 코드 목록 로드
+   */
+  useEffect(() => {
+    if (selectedCategoryCode) {
+      fetchCodes(selectedCategoryCode);
+    } else {
+      setCodes([]);
+    }
+  }, [selectedCategoryCode, fetchCodes]);
+
+  return {
+    // 카테고리 관련
+    categories,
+    categoriesLoading,
+    categoriesError,
+    totalCategories,
+    fetchCategories,
+    createCategory,
+    updateCategory,
+    deleteCategory,
+
+    // 코드 관련
+    codes,
+    codesLoading,
+    codesError,
+    fetchCodes,
+    createCode,
+    updateCode,
+    deleteCode,
+
+    // 선택된 카테고리
+    selectedCategoryCode,
+    setSelectedCategoryCode,
+  };
+}

frontend/lib/api/commonCode.ts

@@ -0,0 +1,126 @@
+import { apiClient } from "./client";
+import {
+  CodeCategory,
+  CodeInfo,
+  CodeOption,
+  CreateCategoryRequest,
+  UpdateCategoryRequest,
+  CreateCodeRequest,
+  UpdateCodeRequest,
+  ReorderCodesRequest,
+  GetCategoriesQuery,
+  GetCodesQuery,
+  ApiResponse,
+} from "@/types/commonCode";
+
+/**
+ * 공통코드 관리 API 클라이언트
+ */
+export const commonCodeApi = {
+  // 카테고리 관련 API
+  categories: {
+    /**
+     * 카테고리 목록 조회
+     */
+    async getList(params?: GetCategoriesQuery): Promise<ApiResponse<CodeCategory[]>> {
+      const searchParams = new URLSearchParams();
+
+      if (params?.search) searchParams.append("search", params.search);
+      if (params?.isActive !== undefined) searchParams.append("isActive", params.isActive.toString());
+      if (params?.page) searchParams.append("page", params.page.toString());
+      if (params?.size) searchParams.append("size", params.size.toString());
+
+      const queryString = searchParams.toString();
+      const url = `/common-codes/categories${queryString ? `?${queryString}` : ""}`;
+
+      const response = await apiClient.get(url);
+      return response.data;
+    },
+
+    /**
+     * 카테고리 생성
+     */
+    async create(data: CreateCategoryRequest): Promise<ApiResponse<CodeCategory>> {
+      const response = await apiClient.post("/common-codes/categories", data);
+      return response.data;
+    },
+
+    /**
+     * 카테고리 수정
+     */
+    async update(categoryCode: string, data: UpdateCategoryRequest): Promise<ApiResponse<CodeCategory>> {
+      const response = await apiClient.put(`/common-codes/categories/${categoryCode}`, data);
+      return response.data;
+    },
+
+    /**
+     * 카테고리 삭제
+     */
+    async delete(categoryCode: string): Promise<ApiResponse> {
+      const response = await apiClient.delete(`/common-codes/categories/${categoryCode}`);
+      return response.data;
+    },
+  },
+
+  // 코드 관련 API
+  codes: {
+    /**
+     * 카테고리별 코드 목록 조회
+     */
+    async getList(categoryCode: string, params?: GetCodesQuery): Promise<ApiResponse<CodeInfo[]>> {
+      const searchParams = new URLSearchParams();
+
+      if (params?.search) searchParams.append("search", params.search);
+      if (params?.isActive !== undefined) searchParams.append("isActive", params.isActive.toString());
+
+      const queryString = searchParams.toString();
+      const url = `/common-codes/categories/${categoryCode}/codes${queryString ? `?${queryString}` : ""}`;
+
+      const response = await apiClient.get(url);
+      return response.data;
+    },
+
+    /**
+     * 코드 생성
+     */
+    async create(categoryCode: string, data: CreateCodeRequest): Promise<ApiResponse<CodeInfo>> {
+      const response = await apiClient.post(`/common-codes/categories/${categoryCode}/codes`, data);
+      return response.data;
+    },
+
+    /**
+     * 코드 수정
+     */
+    async update(categoryCode: string, codeValue: string, data: UpdateCodeRequest): Promise<ApiResponse<CodeInfo>> {
+      const response = await apiClient.put(`/common-codes/categories/${categoryCode}/codes/${codeValue}`, data);
+      return response.data;
+    },
+
+    /**
+     * 코드 삭제
+     */
+    async delete(categoryCode: string, codeValue: string): Promise<ApiResponse> {
+      const response = await apiClient.delete(`/common-codes/categories/${categoryCode}/codes/${codeValue}`);
+      return response.data;
+    },
+
+    /**
+     * 코드 순서 변경
+     */
+    async reorder(categoryCode: string, data: ReorderCodesRequest): Promise<ApiResponse> {
+      const response = await apiClient.put(`/common-codes/categories/${categoryCode}/codes/reorder`, data);
+      return response.data;
+    },
+  },
+
+  // 옵션 조회 API (화면관리용)
+  options: {
+    /**
+     * 카테고리별 옵션 조회
+     */
+    async getOptions(categoryCode: string): Promise<ApiResponse<CodeOption[]>> {
+      const response = await apiClient.get(`/common-codes/categories/${categoryCode}/options`);
+      return response.data;
+    },
+  },
+};

frontend/types/commonCode.ts

@@ -0,0 +1,94 @@
+// 공통코드 관련 타입 정의
+
+export interface CodeCategory {
+  category_code: string;
+  category_name: string;
+  category_name_eng?: string | null;
+  description?: string | null;
+  sort_order: number;
+  is_active: string;
+  created_date?: string | null;
+  created_by?: string | null;
+  updated_date?: string | null;
+  updated_by?: string | null;
+}
+
+export interface CodeInfo {
+  code_category: string;
+  code_value: string;
+  code_name: string;
+  code_name_eng?: string | null;
+  description?: string | null;
+  sort_order: number;
+  is_active: string;
+  created_date?: string | null;
+  created_by?: string | null;
+  updated_date?: string | null;
+  updated_by?: string | null;
+}
+
+export interface CreateCategoryRequest {
+  categoryCode: string;
+  categoryName: string;
+  categoryNameEng?: string;
+  description?: string;
+  sortOrder?: number;
+}
+
+export interface UpdateCategoryRequest {
+  categoryName?: string;
+  categoryNameEng?: string;
+  description?: string;
+  sortOrder?: number;
+  isActive?: boolean;
+}
+
+export interface CreateCodeRequest {
+  codeValue: string;
+  codeName: string;
+  codeNameEng?: string;
+  description?: string;
+  sortOrder?: number;
+}
+
+export interface UpdateCodeRequest {
+  codeName?: string;
+  codeNameEng?: string;
+  description?: string;
+  sortOrder?: number;
+  isActive?: boolean;
+}
+
+export interface CodeOption {
+  value: string;
+  label: string;
+  labelEng?: string | null;
+}
+
+export interface ReorderCodesRequest {
+  codes: Array<{
+    codeValue: string;
+    sortOrder: number;
+  }>;
+}
+
+export interface GetCategoriesQuery {
+  search?: string;
+  isActive?: boolean;
+  page?: number;
+  size?: number;
+}
+
+export interface GetCodesQuery {
+  search?: string;
+  isActive?: boolean;
+}
+
+export interface ApiResponse<T = any> {
+  success: boolean;
+  data?: T;
+  message: string;
+  error?: string;
+  total?: number;
+}
+