vexplor/카테고리_타입_구현_완료.md

카테고리 타입 구현 완료 보고서

개요

테이블 타입 관리에 새로운 입력 타입 **"category"**를 추가하여, 메뉴별로 독립적으로 관리되는 카테고리 값 시스템을 구현했습니다.

구현 내용

1. 데이터베이스

생성된 테이블

• table_column_category_values: 카테고리 값 저장 테이블
  • value_id: 기본키 (SERIAL)
  • table_name, column_name: 테이블.컬럼 식별
  • value_code, value_name_kor, value_name_eng, value_name_cn: 카테고리 값
  • parent_value_id: 계층 구조 지원 (최대 3단계)
  • display_order: 표시 순서
  • is_active, is_default: 활성/기본값 플래그
  • color_code, icon_name: 시각적 표현
  • company_code: 멀티테넌시 지원

마이그레이션 파일

• db/migrations/036_create_table_column_category_values.sql
• 외래키: company_mng(company_code) (DB 호환성 확인 완료)
• 인덱스: (table_name, column_name, company_code), (parent_value_id)

2. 백엔드 (Node.js)

생성된 파일

1. 타입 정의: backend-node/src/types/tableCategoryValue.ts

   • CategoryColumn: 카테고리 타입 컬럼 정보
   • TableCategoryValue: 카테고리 값 정보

2. 서비스: backend-node/src/services/tableCategoryValueService.ts

   • getCategoryColumns(): 테이블의 카테고리 컬럼 목록 조회
   • getCategoryValues(): 특정 컬럼의 카테고리 값 목록 조회
   • addCategoryValue(): 카테고리 값 추가
   • updateCategoryValue(): 카테고리 값 수정
   • deleteCategoryValue(): 카테고리 값 삭제 (단일)
   • bulkDeleteCategoryValues(): 카테고리 값 대량 삭제

3. 컨트롤러: backend-node/src/controllers/tableCategoryValueController.ts

   • HTTP 요청 처리
   • 에러 핸들링

4. 라우트: backend-node/src/routes/tableCategoryValueRoutes.ts

   • GET /:tableName/columns: 카테고리 컬럼 목록
   • GET /:tableName/:columnName/values: 카테고리 값 목록
   • POST /:tableName/:columnName/values: 카테고리 값 추가
   • PUT /:tableName/:columnName/values/:valueId: 카테고리 값 수정
   • DELETE /:tableName/:columnName/values/:valueId: 카테고리 값 삭제
   • DELETE /:tableName/:columnName/values/bulk: 대량 삭제

5. 앱 통합: backend-node/src/app.ts

   • /api/table-categories 라우트 등록
   • 인증 미들웨어 적용 (authenticateToken)

수정된 import 경로 (호환성 수정)

• ❌ ../config/database → ✅ ../database/db
• ❌ logger default import → ✅ { logger } named import
• ❌ authenticate → ✅ authenticateToken

백엔드 DB 호환성 수정

• ❌ table_columns → ✅ table_type_columns
• ❌ web_type → ✅ input_type
• ❌ column_order → ✅ display_order
• ❌ column_label → ✅ column_name (라벨용으로 사용)

3. 프론트엔드 (Next.js + React)

생성된 파일

1. 타입 정의: frontend/types/tableCategoryValue.ts

   • CategoryColumn, TableCategoryValue 인터페이스

2. API 클라이언트: frontend/lib/api/tableCategoryValue.ts

   • 백엔드 API 호출 함수들
   • ApiResponse 타입 사용

3. 컴포넌트:

   • CategoryValueManager.tsx: 카테고리 값 관리 메인 컴포넌트
   • CategoryValueAddDialog.tsx: 카테고리 값 추가 Dialog
   • CategoryValueEditDialog.tsx: 카테고리 값 편집 Dialog
   • CategoryValueManagerDialog.tsx: ✅ Dialog 래퍼 (새로 추가)

수정된 파일

1. constants/tableManagement.ts

   • WEB_TYPE_CATEGORY: "table.management.web.type.category"
   • WEB_TYPE_CATEGORY_DESC: 다국어 키 추가
   • WEB_TYPE_OPTIONS_WITH_KEYS에 category 옵션 추가

2. types/input-types.ts

   • InputType에 "category" 추가 (9개 핵심 타입)
   • INPUT_TYPE_OPTIONS에 category 옵션 추가:

     {
       value: "category",
       label: "카테고리",
       description: "메뉴별 카테고리 값 선택",
       category: "reference",
       icon: "FolderTree",
     }
     

   • INPUT_TYPE_DEFAULT_CONFIGS, WEB_TYPE_TO_INPUT_TYPE, INPUT_TYPE_TO_WEB_TYPE, INPUT_TYPE_VALIDATION_RULES에 category 추가

3. app/(main)/admin/tableMng/page.tsx (테이블 타입 관리 페이지)

   • ✅ CategoryValueManagerDialog import
   • ✅ 상태 관리 추가:

     const [categoryDialogOpen, setCategoryDialogOpen] = useState(false);
     const [categoryDialogData, setCategoryDialogData] = useState<{
       tableName: string;
       columnName: string;
       columnLabel: string;
     } | null>(null);
     

   • ✅ 입력 타입이 "category"일 때 "카테고리 값 관리" 버튼 표시
   • ✅ 버튼 클릭 시 Dialog 오픈
   • ✅ Dialog 렌더링 (페이지 하단)

삭제된 파일 (불필요)

• ❌ app/table-categories/page.tsx (독립 페이지)
• ❌ components/table-category/TableCategoryManager.tsx (좌우 분할 패널)
• ❌ components/table-category/CategoryColumnList.tsx (좌측 컬럼 리스트)

사용 방법

1. 테이블 타입 관리 페이지 접속

http://localhost:9771/admin/tableMng

2. 테이블 선택 후 컬럼의 입력 타입을 "카테고리"로 설정

드롭다운에서 "카테고리" 옵션 선택

3. "카테고리 값 관리" 버튼 클릭

입력 타입을 "카테고리"로 설정하면, 해당 컬럼 옆에 "카테고리 값 관리" 버튼이 표시됩니다.

4. Dialog에서 카테고리 값 관리

• 검색: 카테고리 코드/라벨 검색
• 추가: "추가" 버튼으로 새 카테고리 값 생성
• 수정: 편집 아이콘 클릭
• 삭제: 체크박스 선택 후 "선택 삭제" 버튼
• 정렬: display_order로 자동 정렬
• 기본값 설정: 체크박스로 기본값 지정

주요 특징

1. 메뉴별 독립 관리

• 각 테이블.컬럼마다 독립적인 카테고리 값
• 채번 규칙처럼 메뉴(테이블)별로 다른 카테고리 사용 가능

2. 멀티테넌시 지원

• company_code로 회사별 데이터 격리
• 최고 관리자(company_code = "*")는 모든 회사 데이터 조회 가능

3. 계층 구조 지원

• parent_value_id를 통한 최대 3단계 계층
• 추후 트리 UI 구현 가능

4. 시각적 표현

• color_code: 색상 태그
• icon_name: 아이콘 표시
• 추후 UI에 반영 가능

5. 다국어 지원

• value_name_kor, value_name_eng, value_name_cn
• 사용자 언어에 따라 표시

기술적 의사결정

왜 독립 페이지를 제거했나?

• ❌ 독립 페이지: 테이블 선택 → 컬럼 선택 (2단계)
• ✅ 통합 UI: 테이블 타입 관리에서 바로 버튼 클릭 (1단계)
• 사용자 경험 개선: 입력 타입 설정과 카테고리 값 관리를 한 화면에서 처리

왜 Dialog 형태로 구현했나?

• 테이블 타입 관리 페이지를 벗어나지 않고 작업 가능
• 모달 방식으로 집중된 UX 제공
• 반응형 디자인 (모바일 max-w-[90vw], 데스크톱 max-w-[900px])

왜 CategoryColumnList를 제거했나?

• 좌우 분할 패널은 독립 페이지에서만 의미가 있음
• Dialog에서는 단일 컬럼만 다루므로 불필요
• 코드 복잡도 감소

다음 단계 (선택적 구현)

1. 화면관리 시스템 통합

• RealtimePreview에서 category 타입 렌더링
• Select 박스로 카테고리 값 표시

2. 계층 구조 UI

• 트리 형태로 부모-자식 관계 표시
• 드래그앤드롭으로 순서 변경

3. 색상/아이콘 UI

• 카테고리 값에 색상 태그 표시
• 아이콘 선택기 추가

4. 데이터 검증

• 화면에서 입력 시 카테고리 값 검증
• 존재하지 않는 카테고리 값 입력 방지

5. 통계 및 분석

• 카테고리별 데이터 집계
• 사용 빈도 분석

파일 목록

백엔드

db/migrations/036_create_table_column_category_values.sql
backend-node/src/types/tableCategoryValue.ts
backend-node/src/services/tableCategoryValueService.ts
backend-node/src/controllers/tableCategoryValueController.ts
backend-node/src/routes/tableCategoryValueRoutes.ts
backend-node/src/app.ts (수정)

프론트엔드

frontend/types/tableCategoryValue.ts
frontend/lib/api/tableCategoryValue.ts
frontend/components/table-category/CategoryValueManager.tsx
frontend/components/table-category/CategoryValueAddDialog.tsx
frontend/components/table-category/CategoryValueEditDialog.tsx
frontend/components/table-category/CategoryValueManagerDialog.tsx (신규)
frontend/constants/tableManagement.ts (수정)
frontend/types/input-types.ts (수정)
frontend/app/(main)/admin/tableMng/page.tsx (수정)

삭제된 파일

frontend/app/table-categories/page.tsx
frontend/components/table-category/TableCategoryManager.tsx
frontend/components/table-category/CategoryColumnList.tsx

테스트 시나리오

1. 테이블 타입 관리 페이지 접속

   • URL: http://localhost:9771/admin/tableMng

2. 테이블 선택

   • 테이블 목록에서 원하는 테이블 선택

3. 입력 타입 설정

   • 컬럼의 "입력 타입" 드롭다운에서 "카테고리" 선택

4. 카테고리 값 관리 버튼 확인

   • "카테고리 값 관리" 버튼이 표시되는지 확인

5. Dialog 열기

   • 버튼 클릭 → Dialog가 열리는지 확인

6. 카테고리 값 추가

   • "추가" 버튼 클릭
   • 코드, 라벨, 설명 입력
   • "저장" 버튼 클릭

7. 카테고리 값 편집

   • 편집 아이콘 클릭
   • 정보 수정 후 "저장"

8. 카테고리 값 삭제

   • 체크박스 선택
   • "선택 삭제" 버튼 클릭

9. 검색 기능

   • 검색창에 코드/라벨 입력
   • 필터링 결과 확인

10. 저장 및 재로드

    • 테이블 타입 관리 페이지에서 "저장" 버튼 클릭
    • 페이지 새로고침 후 카테고리 값이 유지되는지 확인

참고 문서

• 카테고리_시스템_구현_계획서.md
• 카테고리_관리_컴포넌트_구현_계획서.md
• 카테고리_컴포넌트_DB_호환성_분석.md
• 카테고리_컴포넌트_구현_완료.md (이전 버전)

완료 일시

2025-11-05 09:40 KST

구현자

AI Assistant (Claude Sonnet 4.5)