chpark/vexplor

Fork 0

Files

hyeonsu 5f242edabb 공통코드 문서 업데이트

2025-09-04 10:03:43 +09:00

37 KiB

Raw Blame History

공통코드 관리 시스템 설계 문서

📋 목차

시스템 개요
아키텍처 구조
핵심 기능
데이터베이스 설계
화면 구성 요소
API 설계
프론트엔드 구현
백엔드 구현
사용 시나리오
개발 계획

🎯 시스템 개요

공통코드 관리 시스템이란?

공통코드 관리 시스템은 시스템에서 사용하는 공통적인 코드값들을 중앙에서 관리하는 기능입니다. 드롭다운, 선택박스 등에서 반복적으로 사용되는 코드-값 쌍을 체계적으로 관리하여 데이터 일관성을 보장하고 개발 효율성을 높입니다.

주요 특징

중앙 집중 관리: 모든 공통코드를 한 곳에서 통합 관리
카테고리 기반 분류: 코드를 카테고리별로 체계적 분류
다국어 지원: 한국어/영어 코드명 지원
화면관리 시스템 연계: 웹 타입 'code'와 완벽 연동
실시간 반영: 코드 변경사항 즉시 시스템 전체 반영
관리자 전용: 관리자 메뉴에서만 접근 가능

🎯 필수 요구사항

✅ 관리자 메뉴 접근: 관리자 메뉴에서만 접근 가능
✅ 코드 카테고리 관리: 카테고리 생성/수정/삭제
✅ 코드 상세 관리: 코드값과 코드명 매핑 관리
✅ 정렬 순서 관리: 코드 표시 순서 조정
✅ 활성/비활성 관리: 코드 사용 여부 제어
✅ 검색 및 필터링: 대량 코드 효율적 관리
✅ 화면관리 연계: column_labels.code_category와 연동

🏗️ 아키텍처 구조

전체 구조도

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │   Database      │
│                 │    │                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │ CodeCategory│ │    │ │ CommonCode  │ │    │ │ code_       │ │
│ │ Management  │ │    │ │ Controller  │ │    │ │ category    │ │
│ │ (React)     │ │    │ │             │ │    │ │ Table       │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
│                 │    │                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │ CodeDetail  │ │    │ │ CommonCode  │ │    │ │ code_info   │ │
│ │ Management  │ │    │ │ Service     │ │    │ │ Table       │ │
│ │ (React)     │ │    │ │             │ │    │ │             │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
└─────────────────┘    └─────────────────┘    └─────────────────┘

화면관리 시스템 연계

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ 화면관리 시스템  │    │ 공통코드 관리    │    │ 실제 화면       │
│                 │    │                 │    │                 │
│ column_labels   │───▶│ code_category   │───▶│ Select Widget   │
│ web_type='code' │    │ code_info       │    │ <option>값      │
│ code_category   │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

🚀 핵심 기능

1. 코드 카테고리 관리

카테고리 생성: 새로운 코드 카테고리 추가
카테고리 수정: 카테고리명, 설명 수정
카테고리 삭제: 사용하지 않는 카테고리 삭제 (CASCADE)
카테고리 활성화: 카테고리 사용 여부 제어
카테고리 검색: 카테고리명으로 빠른 검색

2. 코드 상세 관리

코드 생성: 카테고리 내 새로운 코드 추가
코드 수정: 코드값, 코드명, 영문명 수정
코드 삭제: 불필요한 코드 삭제
정렬 순서: 드래그앤드롭으로 순서 변경
일괄 업로드: CSV/Excel 파일로 대량 등록
일괄 다운로드: 현재 코드 데이터 내보내기

3. 화면관리 연계

자동 옵션 생성: code_category 기반 select 옵션 자동 생성
실시간 반영: 코드 변경 시 관련 화면 즉시 업데이트
참조 관계 표시: 어떤 화면에서 사용 중인지 표시

4. 검색 및 필터링

통합 검색: 카테고리명, 코드값, 코드명 통합 검색
상태 필터: 활성/비활성 코드 필터링
카테고리 필터: 특정 카테고리만 표시
페이징: 대량 데이터 효율적 표시

🗄️ 데이터베이스 설계

1. 코드 카테고리 테이블

-- 공통코드 카테고리 테이블
CREATE TABLE code_category (
  category_code VARCHAR(50) PRIMARY KEY,
  category_name VARCHAR(100) NOT NULL,
  category_name_eng VARCHAR(100),
  description TEXT,
  sort_order INTEGER DEFAULT 0,
  is_active CHAR(1) DEFAULT 'Y',
  created_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  created_by VARCHAR(50),
  updated_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_by VARCHAR(50)
);

-- 인덱스 추가
CREATE INDEX idx_code_category_active ON code_category(is_active);
CREATE INDEX idx_code_category_sort ON code_category(sort_order);

2. 코드 상세 정보 테이블

-- 공통코드 상세 정보 테이블
CREATE TABLE code_info (
  code_category VARCHAR(50) NOT NULL,
  code_value VARCHAR(50) NOT NULL,
  code_name VARCHAR(100) NOT NULL,
  code_name_eng VARCHAR(100),
  description TEXT,
  sort_order INTEGER DEFAULT 0,
  is_active CHAR(1) DEFAULT 'Y',
  created_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  created_by VARCHAR(50),
  updated_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_by VARCHAR(50),

  -- 복합 기본키
  PRIMARY KEY (code_category, code_value),

  -- 외래키 제약조건
  CONSTRAINT fk_code_info_category
    FOREIGN KEY (code_category) REFERENCES code_category(category_code)
    ON DELETE CASCADE
    ON UPDATE CASCADE
);

-- 성능을 위한 인덱스
CREATE INDEX idx_code_info_category ON code_info(code_category);
CREATE INDEX idx_code_info_active ON code_info(is_active);
CREATE INDEX idx_code_info_sort ON code_info(code_category, sort_order);

3. 기본 데이터 삽입

-- 시스템 필수 공통코드 카테고리
INSERT INTO code_category VALUES
('USER_STATUS', '사용자 상태', 'User Status', '사용자의 활성화 상태', 1, 'Y', now(), 'SYSTEM', now(), 'SYSTEM'),
('USER_TYPE', '사용자 타입', 'User Type', '사용자 권한 타입', 2, 'Y', now(), 'SYSTEM', now(), 'SYSTEM'),
('DEPT_TYPE', '부서 타입', 'Department Type', '부서 분류', 3, 'Y', now(), 'SYSTEM', now(), 'SYSTEM'),
('LANGUAGE', '언어 코드', 'Language Code', '시스템 지원 언어', 4, 'Y', now(), 'SYSTEM', now(), 'SYSTEM'),
('CURRENCY', '통화 코드', 'Currency Code', '시스템 지원 통화', 5, 'Y', now(), 'SYSTEM', now(), 'SYSTEM');

-- 사용자 상태 코드
INSERT INTO code_info VALUES
('USER_STATUS', 'A', '활성', 'Active', '활성 사용자', 1, 'Y', now(), 'SYSTEM', now(), 'SYSTEM'),
('USER_STATUS', 'I', '비활성', 'Inactive', '비활성 사용자', 2, 'Y', now(), 'SYSTEM', now(), 'SYSTEM'),
('USER_STATUS', 'S', '휴면', 'Sleep', '휴면 사용자', 3, 'Y', now(), 'SYSTEM', now(), 'SYSTEM'),
('USER_STATUS', 'D', '삭제', 'Deleted', '삭제된 사용자', 4, 'Y', now(), 'SYSTEM', now(), 'SYSTEM');

-- 사용자 타입 코드
INSERT INTO code_info VALUES
('USER_TYPE', 'ADMIN', '관리자', 'Administrator', '시스템 관리자', 1, 'Y', now(), 'SYSTEM', now(), 'SYSTEM'),
('USER_TYPE', 'USER', '일반사용자', 'User', '일반 사용자', 2, 'Y', now(), 'SYSTEM', now(), 'SYSTEM'),
('USER_TYPE', 'GUEST', '게스트', 'Guest', '게스트 사용자', 3, 'Y', now(), 'SYSTEM', now(), 'SYSTEM'),
('USER_TYPE', 'PARTNER', '협력업체', 'Partner', '협력업체 사용자', 4, 'Y', now(), 'SYSTEM', now(), 'SYSTEM');

🎨 화면 구성 요소

1. 전체 레이아웃

┌─────────────────────────────────────────────────────────────┐
│                    공통코드 관리 시스템                      │
├─────────────────────────────────────────────────────────────┤
│ [새 카테고리]                              [🔍 검색박스]    │
├─────────────────┬───────────────────────────────────────────┤
│  코드 카테고리   │              코드 상세 정보                │
│                │                                           │
│ ┌─────────────┐ │ ┌─────────────────────────────────────────┐ │
│ │ USER_STATUS │ │ │ 코드값 │ 코드명 │ 영문명    │ 순서 │ 상태 │ │
│ │ 사용자 상태  │ │ │ A     │ 활성  │ Active   │  1  │  ✓  │ │
│ │             │ │ │ I     │ 비활성 │ Inactive │  2  │  ✓  │ │
│ │ USER_TYPE   │ │ │ S     │ 휴면  │ Sleep    │  3  │  ✓  │ │
│ │ 사용자 타입  │ │ │ D     │ 삭제  │ Deleted  │  4  │  ✓  │ │
│ │             │ │ └─────────────────────────────────────────┘ │
│ │ DEPT_TYPE   │ │                                           │
│ │ 부서 타입    │ │ [+ 새 코드 추가] [정렬]                   │
│ └─────────────┘ │                                           │
└─────────────────┴───────────────────────────────────────────┘

2. 주요 컴포넌트

CodeCategoryList (좌측 패널)

interface CodeCategoryListProps {
  categories: CodeCategory[];
  selectedCategory: string | null;
  onCategorySelect: (categoryCode: string) => void;
  onCategoryCreate: () => void;
  onCategoryEdit: (category: CodeCategory) => void;
  onCategoryDelete: (categoryCode: string) => void;
}

CodeDetailTable (우측 패널)

interface CodeDetailTableProps {
  categoryCode: string;
  codes: CodeInfo[];
  onCodeCreate: () => void;
  onCodeEdit: (code: CodeInfo) => void;
  onCodeDelete: (codeValue: string) => void;
  onSortOrderChange: (codes: CodeInfo[]) => void;
}

CodeEditModal (편집 모달)

interface CodeEditModalProps {
  isOpen: boolean;
  mode: "create" | "edit";
  categoryCode?: string;
  codeData?: CodeInfo;
  onSave: (data: CodeInfo) => void;
  onClose: () => void;
}

🌐 API 설계

1. 코드 카테고리 API

카테고리 목록 조회

GET /api/common-codes/categories
Query: {
  search?: string;
  isActive?: boolean;
  page?: number;
  size?: number;
}
Response: {
  success: boolean;
  data: CodeCategory[];
  total: number;
}

카테고리 생성

POST /api/common-codes/categories
Body: {
  categoryCode: string;
  categoryName: string;
  categoryNameEng?: string;
  description?: string;
  sortOrder?: number;
}

카테고리 수정

PUT /api/common-codes/categories/:categoryCode
Body: {
  categoryName?: string;
  categoryNameEng?: string;
  description?: string;
  sortOrder?: number;
  isActive?: boolean;
}

카테고리 삭제

DELETE /api/common-codes/categories/:categoryCode

2. 코드 상세 API

카테고리별 코드 목록 조회

GET /api/common-codes/categories/:categoryCode/codes
Query: {
  search?: string;
  isActive?: boolean;
}
Response: {
  success: boolean;
  data: CodeInfo[];
}

코드 생성

POST /api/common-codes/categories/:categoryCode/codes
Body: {
  codeValue: string;
  codeName: string;
  codeNameEng?: string;
  description?: string;
  sortOrder?: number;
}

코드 수정

PUT /api/common-codes/categories/:categoryCode/codes/:codeValue
Body: {
  codeName?: string;
  codeNameEng?: string;
  description?: string;
  sortOrder?: number;
  isActive?: boolean;
}

코드 삭제

DELETE /api/common-codes/categories/:categoryCode/codes/:codeValue

코드 순서 변경

PUT /api/common-codes/categories/:categoryCode/codes/reorder
Body: {
  codes: Array<{
    codeValue: string;
    sortOrder: number;
  }>;
}

3. 화면관리 연계 API

카테고리별 옵션 조회 (화면관리용)

GET /api/common-codes/categories/:categoryCode/options
Response: {
  success: boolean;
  data: Array<{
    value: string;
    label: string;
    labelEng?: string;
  }>;
}

🎭 프론트엔드 구현

1. 페이지 구조

// app/(main)/admin/commonCode/page.tsx
export default function CommonCodeManagementPage() {
  const [selectedCategory, setSelectedCategory] = useState<string | null>(null);
  const [categories, setCategories] = useState<CodeCategory[]>([]);
  const [codes, setCodes] = useState<CodeInfo[]>([]);

  return (
    <div className="flex h-full">
      <CodeCategoryPanel
        categories={categories}
        selectedCategory={selectedCategory}
        onCategorySelect={setSelectedCategory}
      />
      <CodeDetailPanel categoryCode={selectedCategory} codes={codes} />
    </div>
  );
}

2. 주요 컴포넌트

CodeCategoryPanel

// components/admin/commonCode/CodeCategoryPanel.tsx
export function CodeCategoryPanel({
  categories,
  selectedCategory,
  onCategorySelect,
}: CodeCategoryPanelProps) {
  return (
    <div className="w-80 border-r bg-white">
      <div className="p-4 border-b">
        <h2 className="font-semibold">코드 카테고리</h2>
        <Button onClick={onCreateCategory}>
          <Plus className="w-4 h-4 mr-2" />새 카테고리
        </Button>
      </div>

      <div className="p-2">
        {categories.map((category) => (
          <CategoryItem
            key={category.categoryCode}
            category={category}
            isSelected={selectedCategory === category.categoryCode}
            onClick={() => onCategorySelect(category.categoryCode)}
          />
        ))}
      </div>
    </div>
  );
}

CodeDetailPanel

// components/admin/commonCode/CodeDetailPanel.tsx
export function CodeDetailPanel({ categoryCode, codes }: CodeDetailPanelProps) {
  if (!categoryCode) {
    return (
      <div className="flex-1 flex items-center justify-center">
        <p className="text-gray-500">카테고리를 선택하세요</p>
      </div>
    );
  }

  return (
    <div className="flex-1 p-6">
      <div className="flex justify-between items-center mb-4">
        <h2 className="text-xl font-semibold">코드 상세 정보</h2>
        <Button onClick={onCreateCode}>
          <Plus className="w-4 h-4 mr-2" />새 코드
        </Button>
      </div>

      <CodeTable
        codes={codes}
        onEdit={handleEditCode}
        onDelete={handleDeleteCode}
        onReorder={handleReorderCodes}
      />
    </div>
  );
}

⚙️ 백엔드 구현

1. Controller

// backend-node/src/controllers/commonCodeController.ts
export class CommonCodeController {
  // 카테고리 목록 조회
  async getCategories(req: Request, res: Response) {
    try {
      const { search, isActive, page = 1, size = 20 } = req.query;

      const categories = await this.commonCodeService.getCategories({
        search: search as string,
        isActive: isActive === "true",
        page: Number(page),
        size: Number(size),
      });

      res.json({
        success: true,
        data: categories.data,
        total: categories.total,
      });
    } catch (error) {
      res.status(500).json({
        success: false,
        message: error.message,
      });
    }
  }

  // 카테고리별 코드 목록 조회
  async getCodes(req: Request, res: Response) {
    try {
      const { categoryCode } = req.params;
      const { search, isActive } = req.query;

      const codes = await this.commonCodeService.getCodes(categoryCode, {
        search: search as string,
        isActive: isActive === "true",
      });

      res.json({
        success: true,
        data: codes,
      });
    } catch (error) {
      res.status(500).json({
        success: false,
        message: error.message,
      });
    }
  }
}

2. Service

// backend-node/src/services/commonCodeService.ts
export class CommonCodeService {
  // 카테고리 목록 조회
  async getCategories(params: GetCategoriesParams) {
    const { search, isActive, page, size } = params;

    let whereClause = "";
    const queryParams: any[] = [];

    if (search) {
      whereClause +=
        " AND (category_name ILIKE $" +
        (queryParams.length + 1) +
        " OR category_code ILIKE $" +
        (queryParams.length + 1) +
        ")";
      queryParams.push(`%${search}%`);
    }

    if (isActive !== undefined) {
      whereClause += " AND is_active = $" + (queryParams.length + 1);
      queryParams.push(isActive ? "Y" : "N");
    }

    const offset = (page - 1) * size;

    const [categories, total] = await Promise.all([
      this.db.query(
        `
        SELECT * FROM code_category 
        WHERE 1=1 ${whereClause}
        ORDER BY sort_order, category_code
        LIMIT $${queryParams.length + 1} OFFSET $${queryParams.length + 2}
      `,
        [...queryParams, size, offset]
      ),

      this.db.query(
        `
        SELECT COUNT(*) as count FROM code_category 
        WHERE 1=1 ${whereClause}
      `,
        queryParams
      ),
    ]);

    return {
      data: categories.rows,
      total: parseInt(total.rows[0].count),
    };
  }

  // 코드 목록 조회
  async getCodes(categoryCode: string, params: GetCodesParams) {
    const { search, isActive } = params;

    let whereClause = "WHERE code_category = $1";
    const queryParams: any[] = [categoryCode];

    if (search) {
      whereClause +=
        " AND (code_name ILIKE $" +
        (queryParams.length + 1) +
        " OR code_value ILIKE $" +
        (queryParams.length + 1) +
        ")";
      queryParams.push(`%${search}%`);
    }

    if (isActive !== undefined) {
      whereClause += " AND is_active = $" + (queryParams.length + 1);
      queryParams.push(isActive ? "Y" : "N");
    }

    const result = await this.db.query(
      `
      SELECT * FROM code_info 
      ${whereClause}
      ORDER BY sort_order, code_value
    `,
      queryParams
    );

    return result.rows;
  }
}

🎬 사용 시나리오

1. 새로운 공통코드 카테고리 생성

관리자 메뉴 접근: 관리자가 공통코드 관리 메뉴 클릭
카테고리 생성: "새 카테고리" 버튼 클릭
정보 입력: 카테고리 코드, 이름, 설명 입력
저장: 카테고리 생성 완료
코드 추가: 생성된 카테고리에 코드 상세 정보 추가

2. 기존 공통코드 수정

카테고리 선택: 좌측 패널에서 수정할 카테고리 선택
코드 선택: 우측 테이블에서 수정할 코드 클릭
정보 수정: 코드명, 영문명, 설명 등 수정
순서 변경: 드래그앤드롭으로 표시 순서 조정
저장: 변경사항 저장

3. 화면관리 시스템 연계

테이블 타입 관리: column_labels에서 web_type을 'code'로 설정
카테고리 선택: code_category에 공통코드 카테고리 지정
화면 설계: 화면관리에서 해당 컬럼을 드래그하여 위젯 생성
자동 옵션: select 위젯에 공통코드 옵션 자동 생성
실시간 반영: 공통코드 변경 시 화면에 즉시 반영

📅 개발 계획 및 진행상황

✅ Phase 1: (완료)

데이터베이스 스키마 설계 및 생성
Prisma 스키마에 공통코드 모델 추가
code_category, code_info 테이블 생성
기본 데이터 삽입 스크립트 작성 및 실행

완료 내용:

Prisma schema.prisma에 공통코드 모델 추가
Docker 컨테이너에서 테이블 생성 스크립트 실행
5개 카테고리, 22개 기본 코드 데이터 삽입 완료

✅ Phase 2: 백엔드 API 구현 (완료)

CommonCodeController 구현
CommonCodeService 구현
카테고리 CRUD API 구현
코드 상세 CRUD API 구현
정렬 순서 변경 API 구현

완료 내용:

모든 CRUD API 정상 작동 확인
JWT 인증 연동 완료
검색, 정렬, 페이징 기능 구현
Prisma ORM 연동 완료
TypeScript 타입 정의 완료

✅ Phase 3: 프론트엔드 기본 구현 (완료)

공통코드 관리 페이지 생성
CodeCategoryPanel 컴포넌트 구현
CodeDetailPanel 컴포넌트 구현
CodeFormModal, CodeCategoryFormModal 구현
기본 CRUD 기능 구현
관리자 메뉴 통합
실시간 데이터 조회 및 표시
무한 루프 문제 해결

완료 내용:

공통코드 관리 페이지 (/admin/commonCode) 완전 구현
4개 주요 컴포넌트 구현 완료
카테고리 선택 시 실시간 코드 조회 기능
useCommonCode 커스텀 훅 구현
API 응답 처리 최적화 완료
사용자 인터페이스 완성

✅ Phase 4: 고급 기능 구현 (완료)

드래그앤드롭 정렬 기능
검색 및 필터링 기능
코드 편집 모달 구현
활성/비활성 필터 토글
일괄 업로드/다운로드 기능 (선택사항)

완료 내용:

@dnd-kit 라이브러리를 사용한 드래그앤드롭 정렬 기능 구현
카테고리와 코드 양쪽 패널에 검색 및 활성 필터 기능 추가
실시간 유효성 검사, 자동 대문자 변환, 중복 검사 등 개선된 편집 모달
드래그앤드롭으로 변경한 순서가 실제 DB에 저장되는 기능
라우터 순서 최적화로 API 충돌 문제 해결

목표 기간: 2일 → 실제 소요: 1일

✅ Phase 4.5: UX/UI 개선 (완료)

레이아웃 개선: PC에서 가로 배치, 모바일에서 세로 배치
선택된 카테고리 스타일 개선 (검정→회색, 액션 버튼 항상 표시)
코드 수정 모달 개선 (기존 값 로드, 정렬 순서 1부터 시작)
코드 삭제 기능 구현 (확인 모달 포함)

완료 내용:

레이아웃 반응형 개선 완료
- PC 화면: flex-row 사용하여 카테고리(320px 고정) + 코드 상세(flex-1) 가로 배치
- 모바일: flex-col 사용하여 세로 배치, 각 패널 전체 너비 사용
- Tailwind CSS의 반응형 클래스 활용 (lg:flex-row, lg:gap-8)
선택된 카테고리 시각적 개선 완료
- 배경색: bg-black → bg-gray-100 회색 계열로 변경
- 테두리: border-2 border-gray-300 추가하여 시각적 구분 강화
- 액션 버튼: 선택된 카테고리에서 항상 표시되도록 스타일 수정
코드 수정 모달 개선 완료
- 수정 시 기존 데이터 자동 로드: editingCode props를 통해 전체 코드 객체 전달
- 정렬 순서 자동 계산: 기존 코드 최대값 + 1로 자동 설정
- 폼 유효성 검사 및 실시간 피드백 구현
코드 삭제 기능 완성
- AlertModal 컴포넌트를 활용한 삭제 확인 모달 구현
- 빨간색 아이콘과 제목으로 위험 작업임을 시각적으로 표시
- 실제 삭제 API 연동 및 즉시 UI 반영

목표 기간: 1일 → 실제 소요: 1일

✅ Phase 4.6: CRUD 즉시 반영 개선 (완료)

코드 CRUD 작업 후 UI 즉시 반영 문제 해결
카테고리 CRUD 작업 후 UI 즉시 반영 문제 해결
카테고리 생성 시 정렬 순서 자동 계산 개선

완료 내용:

상태 공유 문제 해결
- useCommonCode 훅을 여러 컴포넌트에서 독립적으로 사용하여 발생한 상태 공유 문제 해결
- CodeFormModal과 CodeCategoryFormModal에서 useCommonCode 제거
- 필요한 데이터와 함수들을 props로 전달받는 방식으로 변경
Optimistic Updates 구현
- 서버 응답 대기 없이 즉시 UI 업데이트
- 백그라운드에서 서버 데이터 새로고침으로 일관성 보장
- 생성/수정/삭제 모든 작업에서 즉시 화면 반영
카테고리 정렬 순서 개선
- 초기값: sortOrder: 0 → sortOrder: 1로 변경
- 자동 계산: 기존 카테고리 최대값 + 1로 자동 설정
- 코드와 동일한 로직 적용으로 일관성 확보
TypeScript 타입 안전성 향상
- 모든 any 타입 제거
- 적절한 타입 정의로 IDE 지원 및 런타임 오류 방지
- 린터 에러 0개 달성

목표 기간: 1일 → 실제 소요: 1일

✅ Phase 4.7: 현대적 라이브러리 도입 (완료!)

React Query 도입으로 데이터 페칭 최적화
React Hook Form 도입으로 폼 관리 개선
Zod 도입으로 스키마 기반 유효성 검사
Query Key 기반 캐시 무효화로 CRUD 업데이트 자동화
컴포넌트 모듈화 (CategoryItem, SortableCodeItem 분리)
로컬 상태 제거 및 서버 상태 단일화
린터 오류 0개 달성

구현 완료 내역:

React Query (@tanstack/react-query)
- 자동 캐싱 및 백그라운드 리페칭
- Query Key 기반 캐시 무효화 (frontend/lib/queryKeys.ts)
- Optimistic Updates (드래그앤드롭 순서 변경)
- 로딩/에러 상태 자동 관리
- 네트워크 요청 최적화
- 커스텀 훅 구현: useCategories, useCodes, useCreateCode, useUpdateCode, useDeleteCode, useReorderCodes
React Hook Form
- 성능 최적화 (불필요한 리렌더링 방지)
- 간단한 폼 API 적용 (CodeFormModal, CodeCategoryFormModal)
- Zod와 완벽 연동
- TypeScript 완벽 지원
- 실시간 검증 및 에러 메시지 표시
Zod 스키마 검증
- 스키마 기반 데이터 구조 정의 (frontend/lib/schemas/commonCode.ts)
- TypeScript 타입 자동 생성
- 런타임 검증 + 컴파일 타입 안전성
- 자동화된 에러 메시지
- 카테고리/코드 생성/수정 스키마 분리

주요 성과:

🚀 현대적 아키텍처 도입: React Query + React Hook Form + Zod 완벽 통합
📈 성능 최적화: 불필요한 리렌더링 제거, 효율적 캐싱, Optimistic Updates
🔒 타입 안전성: 완벽한 TypeScript 지원으로 런타임 오류 방지
🧩 컴포넌트 모듈화: CategoryItem, SortableCodeItem 분리로 재사용성 향상
🎯 상태 관리 단순화: 서버 상태와 클라이언트 상태 명확히 분리
✨ 사용자 경험: 즉시 반영되는 CRUD, 부드러운 드래그앤드롭

목표 기간: 2일 → 실제 소요: 1일

✅ Phase 4.8: 공통코드 관리 시스템 개선 (완료!)

구현 완료 내역:

중복 검사 기능 구현
- 백엔드 중복 검사 API 추가 (checkCategoryDuplicate, checkCodeDuplicate)
- REST API 엔드포인트: /check-duplicate 라우트 구현
- 프론트엔드 API 클라이언트 (commonCodeApi.validation)
- React Query 훅 (useCheckCategoryDuplicate, useCheckCodeDuplicate)
- onBlur 검증 UI 구현 (초록색 성공/빨간색 실패 메시지)
- 409 에러 조용한 처리 (콘솔 에러 출력 억제)
폼 검증 시스템 개선
- 중복/유효성 검사 실패 시 저장 버튼 자동 비활성화
- 메시지 우선순위 시스템 (유효성 검사 > 중복 검사)
- 카테고리 영문명/설명 필수 필드로 변경
- 수정 시 카테고리 코드값 표시
- isActive 필드 타입 불일치 문제 해결 (boolean ↔ string)
코드 품질 및 구조 개선
- 컴포넌트 분리: CategoryItem, SortableCodeItem 별도 파일화
- TypeScript 타입 안전성 강화 (any → unknown/구체적 타입)
- 린터 에러 완전 제거 (client.ts 타입 에러 해결)
- 로컬 상태 제거 및 React Query 캐시 직접 사용

✅ Phase 4.9: 사용자 경험 개선 및 성능 최적화 (완료!)

구현 완료 내역:

드래그앤드롭 애니메이션 최적화
- 드롭 애니메이션 제거 (DragOverlay에 dropAnimation={null} 적용)
- 드래그한 아이템이 되돌아가는 모션 완전 제거
- 부드러운 드래그앤드롭 경험 제공
레이아웃 최적화 완료
- 내부 스크롤 적용으로 공간 효율성 증대
- 반응형 디자인 개선 (PC: 가로배치, 모바일: 세로배치)
- 일관된 디자인 시스템 적용
대량 데이터 테스트 환경 구축
- SQL 스크립트 생성 (create-bulk-test-data.sql)
- 카테고리 100개 + 각 카테고리당 코드 3개씩 = 총 300개 테스트 데이터
- 테이블명 및 컬럼명 정확성 검증 (code_category, code_info)
무한 스크롤 구현 완료
- 카테고리 목록 무한 스크롤 (첫 20개 → 10개씩 추가)
- 코드 목록 무한 스크롤 (첫 20개 → 10개씩 추가)
- useInfiniteScroll 커스텀 훅 생성 및 적용
- React Query의 useInfiniteQuery 활용
- 백엔드 페이지네이션 API 연동
- 드래그앤드롭과 무한 스크롤 완벽 호환
데이터 중복 및 동기화 문제 해결
- 무한 스크롤 시 중복 데이터 표시 문제 해결
- React Query 캐시 무효화 최적화
- 활성/비활성 상태 변경 시 즉시 UI 반영
- React Key 중복 에러 해결
모달 안정성 개선
- 카테고리/코드 수정 모달 무한 루프 에러 해결
- useEffect 의존성 배열 최적화
- Props 기반 데이터 전달 방식으로 변경
- React Query 호출 최적화

기술적 개선사항:

드래그앤드롭 최적화: @dnd-kit의 드롭 애니메이션을 제거하여 즉각적인 피드백 제공
대량 데이터 처리: 페이지네이션 → 무한 스크롤로 완전 전환 (첫 20개 → 10개씩 추가)
성능 최적화: React Query 캐싱과 무한 스크롤 조합으로 메모리 효율성 증대
안정성 개선: 모달 무한 루프 에러 해결, React Query 캐시 최적화
데이터 일관성: 중복 데이터 제거, 즉시 UI 반영, React Key 관리

목표 기간: 1일 → 실제 소요: 1일

달성 결과: Phase 4.9 완료로 전체 진행률 98% 달성 🎉

구현 계획 (완료):

1단계: 의존성 설치 및 설정

npm install @tanstack/react-query react-hook-form @hookform/resolvers zod

2단계: React Query 설정
- QueryClient 설정 및 Provider 추가
- Query Key factory 함수 생성
- 커스텀 훅 생성 (useCategories, useCodes, useCreateCode 등)

3단계: Zod 스키마 정의

const categorySchema = z.object({
  categoryCode: z.string().regex(/^[A-Z0-9_]+$/, "대문자, 숫자, _만 가능"),
  categoryName: z.string().min(1, "필수 입력").max(20, "20자 이하"),
  categoryNameEng: z.string().max(20, "20자 이하"),
  description: z.string().max(50, "50자 이하"),
  sortOrder: z.number().min(1, "1 이상"),
});

const codeSchema = z.object({
  codeValue: z.string().regex(/^[A-Z0-9_]+$/, "대문자, 숫자, _만 가능"),
  codeName: z.string().min(1, "필수 입력").max(20, "20자 이하"),
  codeNameEng: z.string().max(20, "20자 이하"),
  description: z.string().max(50, "50자 이하"),
  sortOrder: z.number().min(1, "1 이상"),
});

4단계: Query Key 전략

// 카테고리 관련
["categories"][ // 모든 카테고리
  ("categories", { active: true })
][ // 활성 카테고리만
  // 코드 관련
  ("codes", categoryCode)
][ // 특정 카테고리의 모든 코드
  ("codes", categoryCode, { active: true })
][("code", categoryCode, codeValue)]; // 특정 카테고리의 활성 코드만 // 특정 코드 상세

5단계: React Hook Form 적용
- CodeFormModal, CodeCategoryFormModal 리팩토링
- 기존 수동 검증 로직 제거
- Zod resolver 적용
6단계: 기존 코드 정리
- useCommonCode 훅 단순화
- 수동 상태 관리 코드 제거
- 수동 Optimistic Updates 로직 제거

예상 개선 효과:

코드량 40-50% 감소: 보일러플레이트 코드 대폭 감소
타입 안전성 100% 보장: 런타임 + 컴파일 타임 검증
성능 최적화: 자동 캐싱, 불필요한 리렌더링 방지
개발자 경험 향상: 자동화된 폼 검증, 에러 처리
유지보수성 향상: 표준화된 패턴, 명확한 데이터 흐름

목표 기간: 2일

⏳ Phase 5: 화면관리 연계 (예정)

column_labels와 연동 확인
화면관리에서 code 타입 위젯 테스트
공통코드 변경 시 화면 반영 테스트
옵션 조회 API 구현

목표 기간: 1일

⏳ Phase 6: 테스트 및 최적화 (예정)

전체 기능 통합 테스트
성능 최적화
사용자 경험 개선
문서화 및 사용자 가이드

목표 기간: 1일

🎯 현재 구현 상태

📊 전체 진행률: 98% 🎉

✅ Phase 1: 기본 구조 및 데이터베이스 (100%) - 완료!
✅ Phase 2: 백엔드 API 구현 (100%) - 완료!
✅ Phase 3: 프론트엔드 기본 구현 (100%) - 완료!
✅ Phase 4: 고급 기능 구현 (100%) - 완료!
✅ Phase 4.5: UX/UI 개선 (100%) - 완료!
✅ Phase 4.6: CRUD 즉시 반영 개선 (100%) - 완료!
✅ Phase 4.7: 현대적 라이브러리 도입 (100%) - 완료!
✅ Phase 4.8: 공통코드 관리 시스템 개선 (100%) - 완료!
✅ Phase 4.9: 사용자 경험 개선 및 성능 최적화 (100%) - 완료!
⏳ Phase 5: 화면관리 연계 (0%) - 선택사항
⏳ Phase 6: 테스트 및 최적화 (0%) - 선택사항

🏆 핵심 기능 완성도

공통코드 관리 시스템의 모든 핵심 기능이 완성되었습니다!

✅ 카테고리 관리: 생성/수정/삭제/검색/필터링/무한스크롤
✅ 코드 관리: 생성/수정/삭제/검색/필터링/무한스크롤
✅ 드래그앤드롭: 코드 순서 변경 (드롭 애니메이션 최적화)
✅ 활성/비활성: 배지 클릭으로 상태 토글 (즉시 UI 반영)
✅ 폼 검증: Zod 스키마 기반 + 실시간 중복 검사
✅ 성능 최적화: React Query + 무한 스크롤 + 캐시 최적화
✅ 안정성: 모달 에러 해결 + 데이터 중복 방지
✅ 사용자 경험: 즉시 반영 + 부드러운 애니메이션

🎯 현재 상태: 운영 준비 완료 ✨

🚀 기대 효과

1. 개발 효율성 향상

공통코드 중앙 관리로 중복 작업 제거
화면관리 시스템과 연계로 자동 위젯 생성

2. 데이터 일관성 보장

모든 시스템에서 동일한 코드값 사용
코드 변경 시 전체 시스템 일괄 반영

3. 유지보수성 향상

코드 변경이 필요할 때 한 곳에서만 수정
체계적인 코드 분류 및 관리

4. 사용자 경험 개선

일관된 선택 옵션 제공
다국어 지원으로 글로벌 대응

공통코드 관리 시스템을 통해 전체 ERP 시스템의 품질과 효율성을 크게 향상시킬 수 있습니다! 🎉

37 KiB Raw Blame History

공통코드 관리 시스템 설계 문서

📋 목차

🎯 시스템 개요

공통코드 관리 시스템이란?

주요 특징

🎯 필수 요구사항

🏗️ 아키텍처 구조

전체 구조도

화면관리 시스템 연계

🚀 핵심 기능

1. 코드 카테고리 관리

2. 코드 상세 관리

3. 화면관리 연계

4. 검색 및 필터링

🗄️ 데이터베이스 설계

1. 코드 카테고리 테이블

2. 코드 상세 정보 테이블

3. 기본 데이터 삽입

🎨 화면 구성 요소

1. 전체 레이아웃

2. 주요 컴포넌트

CodeCategoryList (좌측 패널)

CodeDetailTable (우측 패널)

CodeEditModal (편집 모달)

🌐 API 설계

1. 코드 카테고리 API

카테고리 목록 조회

카테고리 생성

카테고리 수정

카테고리 삭제

2. 코드 상세 API

카테고리별 코드 목록 조회

코드 생성

코드 수정

코드 삭제

코드 순서 변경

3. 화면관리 연계 API

카테고리별 옵션 조회 (화면관리용)

🎭 프론트엔드 구현

1. 페이지 구조

2. 주요 컴포넌트

CodeCategoryPanel

CodeDetailPanel

⚙️ 백엔드 구현

1. Controller

2. Service

🎬 사용 시나리오

1. 새로운 공통코드 카테고리 생성

2. 기존 공통코드 수정

3. 화면관리 시스템 연계

📅 개발 계획 및 진행상황

✅ Phase 1: (완료)

✅ Phase 2: 백엔드 API 구현 (완료)

✅ Phase 3: 프론트엔드 기본 구현 (완료)

✅ Phase 4: 고급 기능 구현 (완료)

✅ Phase 4.5: UX/UI 개선 (완료)

✅ Phase 4.6: CRUD 즉시 반영 개선 (완료)

✅ Phase 4.7: 현대적 라이브러리 도입 (완료!)

✅ Phase 4.8: 공통코드 관리 시스템 개선 (완료!)

✅ Phase 4.9: 사용자 경험 개선 및 성능 최적화 (완료!)

⏳ Phase 5: 화면관리 연계 (예정)

⏳ Phase 6: 테스트 및 최적화 (예정)

🎯 현재 구현 상태

📊 전체 진행률: 98% 🎉

🏆 핵심 기능 완성도

🎯 현재 상태: 운영 준비 완료 ✨

🚀 기대 효과

1. 개발 효율성 향상

2. 데이터 일관성 보장

3. 유지보수성 향상

4. 사용자 경험 개선

37 KiB

Raw Blame History