vexplor/docs/채번규칙_컴포넌트_구현_완료.md

채번규칙 컴포넌트 구현 완료

작성일: 2025-11-04
상태: 백엔드 및 프론트엔드 핵심 구현 완료 (화면관리 통합 대기)

---

구현 개요

채번규칙(Numbering Rule) 컴포넌트는 시스템에서 자동으로 코드를 생성하는 규칙을 설정하고 관리하는 관리자 전용 컴포넌트입니다.

생성 코드 예시:

• 제품 코드: PROD-20251104-0001
• 프로젝트 코드: PRJ-2025-001
• 거래처 코드: CUST-A-0001

---

완료된 구현 항목

1. 데이터베이스 레이어 ✅

파일: db/migrations/034_create_numbering_rules.sql

• numbering_rules 마스터 테이블 생성
• numbering_rule_parts 파트 테이블 생성
• 멀티테넌시 지원 (company_code 필드)
• 인덱스 생성 (성능 최적화)
• 샘플 데이터 삽입

주요 기능:

• 규칙 ID, 규칙명, 구분자, 초기화 주기
• 현재 시퀀스 번호 관리
• 적용 대상 테이블/컬럼 지정
• 최대 6개 파트 지원

---

2. 백엔드 레이어 ✅

2.1 서비스 레이어

파일: backend-node/src/services/numberingRuleService.ts

구현된 메서드:

• getRuleList(companyCode) - 규칙 목록 조회
• getRuleById(ruleId, companyCode) - 특정 규칙 조회
• createRule(config, companyCode, userId) - 규칙 생성
• updateRule(ruleId, updates, companyCode) - 규칙 수정
• deleteRule(ruleId, companyCode) - 규칙 삭제
• generateCode(ruleId, companyCode) - 코드 생성
• resetSequence(ruleId, companyCode) - 시퀀스 초기화

핵심 로직:

• 트랜잭션 관리 (BEGIN/COMMIT/ROLLBACK)
• 멀티테넌시 필터링 (company_code 기반)
• JSON 설정 직렬화/역직렬화
• 날짜 형식 변환 (YYYY, YYYYMMDD 등)
• 순번 자동 증가 및 제로 패딩

2.2 컨트롤러 레이어

파일: backend-node/src/controllers/numberingRuleController.ts

구현된 엔드포인트:

• GET /api/numbering-rules - 규칙 목록 조회
• GET /api/numbering-rules/:ruleId - 특정 규칙 조회
• POST /api/numbering-rules - 규칙 생성
• PUT /api/numbering-rules/:ruleId - 규칙 수정
• DELETE /api/numbering-rules/:ruleId - 규칙 삭제
• POST /api/numbering-rules/:ruleId/generate - 코드 생성
• POST /api/numbering-rules/:ruleId/reset - 시퀀스 초기화

보안 및 검증:

• authenticateToken 미들웨어로 인증 확인
• 입력값 검증 (필수 필드, 파트 최소 개수)
• 에러 핸들링 및 적절한 HTTP 상태 코드 반환

2.3 라우터 등록

파일: backend-node/src/app.ts

import numberingRuleController from "./controllers/numberingRuleController";
app.use("/api/numbering-rules", numberingRuleController);

---

3. 프론트엔드 레이어 ✅

3.1 타입 정의

파일: frontend/types/numbering-rule.ts

정의된 타입:

• CodePartType - 파트 유형 (prefix/sequence/date/year/month/custom)
• GenerationMethod - 생성 방식 (auto/manual)
• DateFormat - 날짜 형식 (YYYY/YYYYMMDD 등)
• NumberingRulePart - 단일 파트 인터페이스
• NumberingRuleConfig - 전체 규칙 인터페이스
• 상수 옵션 배열 (UI용)

3.2 API 클라이언트

파일: frontend/lib/api/numberingRule.ts

구현된 함수:

• getNumberingRules() - 규칙 목록 조회
• getNumberingRuleById(ruleId) - 특정 규칙 조회
• createNumberingRule(config) - 규칙 생성
• updateNumberingRule(ruleId, config) - 규칙 수정
• deleteNumberingRule(ruleId) - 규칙 삭제
• generateCode(ruleId) - 코드 생성
• resetSequence(ruleId) - 시퀀스 초기화

기술 스택:

• Axios 기반 API 클라이언트
• 에러 핸들링 및 응답 타입 정의

3.3 컴포넌트 구조

frontend/components/numbering-rule/
├── NumberingRuleDesigner.tsx      # 메인 디자이너 (좌우 분할)
├── NumberingRulePreview.tsx       # 실시간 미리보기
├── NumberingRuleCard.tsx          # 단일 파트 카드
├── AutoConfigPanel.tsx            # 자동 생성 설정
└── ManualConfigPanel.tsx          # 직접 입력 설정

3.4 주요 컴포넌트 기능

NumberingRuleDesigner (메인 컴포넌트):

• 좌측: 저장된 규칙 목록 (카드 리스트)
• 우측: 규칙 편집 영역 (파트 추가/수정/삭제)
• 실시간 미리보기
• 규칙 저장/불러오기/삭제
• 타이틀 편집 기능
• 로딩 상태 관리

NumberingRulePreview:

• 설정된 규칙에 따라 실시간 코드 생성
• 컴팩트 모드 지원
• useMemo로 성능 최적화

NumberingRuleCard:

• 파트 유형 선택 (Select)
• 생성 방식 선택 (자동/수동)
• 동적 설정 패널 표시
• 삭제 버튼

AutoConfigPanel:

• 파트 유형별 설정 UI
• 접두사, 순번, 날짜, 연도, 월, 커스텀
• 입력값 검증 및 가이드 텍스트

ManualConfigPanel:

• 직접 입력값 설정
• 플레이스홀더 설정

---

기술적 특징

Shadcn/ui 스타일 가이드 준수

• 반응형 크기: h-8 sm:h-10, text-xs sm:text-sm
• 색상 토큰: bg-muted, text-muted-foreground, border-border
• 간격: space-y-3 sm:space-y-4, gap-4
• 상태: hover:bg-accent, disabled:opacity-50

실시간 속성 편집 패턴

const [currentRule, setCurrentRule] = useState<NumberingRuleConfig | null>(null);

useEffect(() => {
  if (currentRule) {
    onChange?.(currentRule); // 상위 컴포넌트로 실시간 전파
  }
}, [currentRule, onChange]);

const handleUpdatePart = useCallback((partId: string, updates: Partial<NumberingRulePart>) => {
  setCurrentRule((prev) => {
    if (!prev) return null;
    return {
      ...prev,
      parts: prev.parts.map((part) => (part.id === partId ? { ...part, ...updates } : part)),
    };
  });
}, []);

멀티테넌시 지원

// 백엔드 쿼리
WHERE company_code = $1 OR company_code = '*'

// 일반 회사는 자신의 데이터만 조회
// company_code = "*"는 최고 관리자 전용 데이터

에러 처리 및 사용자 피드백

try {
  const response = await createNumberingRule(config);
  if (response.success) {
    toast.success("채번 규칙이 저장되었습니다");
  } else {
    toast.error(response.error || "저장 실패");
  }
} catch (error: any) {
  toast.error(`저장 실패: ${error.message}`);
}

---

남은 작업

화면관리 시스템 통합 (TODO)

다음 파일들을 생성하여 화면관리 시스템에 컴포넌트를 등록해야 합니다:

frontend/lib/registry/components/numbering-rule/
├── index.ts                      # 컴포넌트 정의 및 등록
├── NumberingRuleComponent.tsx   # 래퍼 컴포넌트
├── NumberingRuleConfigPanel.tsx # 속성 설정 패널
└── types.ts                      # 컴포넌트 설정 타입

등록 예시:

export const NumberingRuleDefinition = createComponentDefinition({
  id: "numbering-rule",
  name: "코드 채번 규칙",
  category: ComponentCategory.ADMIN,
  component: NumberingRuleWrapper,
  configPanel: NumberingRuleConfigPanel,
  defaultSize: { width: 1200, height: 800 },
  icon: "Hash",
  tags: ["코드", "채번", "규칙", "관리자"],
});

---

테스트 가이드

백엔드 API 테스트 (Postman/Thunder Client)

1. 규칙 목록 조회

GET http://localhost:8080/api/numbering-rules
Authorization: Bearer {token}

2. 규칙 생성

POST http://localhost:8080/api/numbering-rules
Content-Type: application/json
Authorization: Bearer {token}

{
  "ruleId": "PROD_CODE",
  "ruleName": "제품 코드 규칙",
  "separator": "-",
  "parts": [
    {
      "order": 1,
      "partType": "prefix",
      "generationMethod": "auto",
      "autoConfig": { "prefix": "PROD" }
    },
    {
      "order": 2,
      "partType": "date",
      "generationMethod": "auto",
      "autoConfig": { "dateFormat": "YYYYMMDD" }
    },
    {
      "order": 3,
      "partType": "sequence",
      "generationMethod": "auto",
      "autoConfig": { "sequenceLength": 4, "startFrom": 1 }
    }
  ]
}

3. 코드 생성

POST http://localhost:8080/api/numbering-rules/PROD_CODE/generate
Authorization: Bearer {token}

Response:
{
  "success": true,
  "data": {
    "code": "PROD-20251104-0001"
  }
}

프론트엔드 테스트

1. 새 규칙 생성:

   • "새 규칙 생성" 버튼 클릭
   • 규칙명 입력
   • "규칙 추가" 버튼으로 파트 추가
   • 각 파트의 설정 변경
   • "저장" 버튼 클릭

2. 미리보기 확인:

   • 파트 추가/수정 시 실시간으로 코드 미리보기 업데이트 확인
   • 구분자 변경 시 반영 확인

3. 규칙 편집:

   • 좌측 목록에서 규칙 선택
   • 우측 편집 영역에서 수정
   • 저장 후 목록에 반영 확인

4. 규칙 삭제:

   • 목록 카드의 삭제 버튼 클릭
   • 목록에서 제거 확인

---

파일 목록

백엔드

• db/migrations/034_create_numbering_rules.sql (마이그레이션)
• backend-node/src/services/numberingRuleService.ts (서비스)
• backend-node/src/controllers/numberingRuleController.ts (컨트롤러)
• backend-node/src/app.ts (라우터 등록)

프론트엔드

• frontend/types/numbering-rule.ts (타입 정의)
• frontend/lib/api/numberingRule.ts (API 클라이언트)
• frontend/components/numbering-rule/NumberingRuleDesigner.tsx
• frontend/components/numbering-rule/NumberingRulePreview.tsx
• frontend/components/numbering-rule/NumberingRuleCard.tsx
• frontend/components/numbering-rule/AutoConfigPanel.tsx
• frontend/components/numbering-rule/ManualConfigPanel.tsx

---

다음 단계

1. 마이그레이션 실행:

   psql -U postgres -d ilshin -f db/migrations/034_create_numbering_rules.sql
   

2. 백엔드 서버 확인 (이미 실행 중이면 자동 반영)

3. 화면관리 통합:

   • 레지스트리 컴포넌트 파일 생성
   • 컴포넌트 등록 및 화면 디자이너에서 사용 가능하도록 설정

4. 테스트:

   • API 테스트 (Postman)
   • UI 테스트 (브라우저)
   • 멀티테넌시 검증

---

작성 완료: 2025-11-04
문의: 백엔드 및 프론트엔드 핵심 기능 완료, 화면관리 통합만 남음