chpark/vexplor

Fork 0

Files

kjs 4b28530fec 타입 관리 개선 및 화면 비율조정 중간커밋

2025-09-19 18:43:55 +09:00

9.2 KiB

Raw Blame History

화면관리 검증 시스템 사용 가이드

📋 개요

이 문서는 화면관리에서 입력 폼 저장 시 발생하던 타입 불일치와 컬럼 오류 문제를 해결하기 위해 개발된 개선된 검증 시스템의 사용 방법을 안내합니다.

🚀 주요 개선 사항

✅ 해결된 문제점

타입 불일치 오류: WebType 정의 통합으로 프론트엔드-백엔드 타입 일관성 확보
없는 컬럼 참조: 클라이언트 사전 검증으로 존재하지 않는 컬럼 접근 방지
불명확한 오류 메시지: 사용자 친화적인 상세 오류 메시지 제공
느린 저장 성능: 캐싱 및 사전 검증으로 불필요한 서버 호출 최소화

🎯 새로운 기능

실시간 폼 검증: 입력과 동시에 유효성 검사
스마트 오류 제안: 오타나 잘못된 컬럼명에 대한 추천
향상된 타입 변환: PostgreSQL 타입에 맞는 안전한 데이터 변환
성능 최적화: 테이블 컬럼 정보 캐싱으로 빠른 응답

🛠️ 기술 스택

프론트엔드

TypeScript: 통합 타입 정의 (unified-web-types.ts)
React Hooks: 실시간 검증 (useFormValidation)
Validation Utils: 클라이언트 검증 로직 (formValidation.ts)
Enhanced Service: 통합 폼 서비스 (enhancedFormService.ts)

백엔드

Enhanced Service: 개선된 동적 폼 서비스 (enhancedDynamicFormService.ts)
Table Management API: 테이블 관리 API (tableManagementController.ts)
Type Safety: 통합 웹타입 정의 (unified-web-types.ts)

🎮 사용 방법

1. 데모 페이지에서 테스트

개선된 검증 시스템을 직접 체험할 수 있는 데모 페이지가 제공됩니다:

http://localhost:9771/admin/validation-demo

데모 기능

유효한 데이터 입력: 모든 검증을 통과하는 테스트 데이터
잘못된 데이터 입력: 다양한 검증 오류를 확인할 수 있는 데이터
실시간 검증: 입력과 동시에 검증 결과 확인
상세 검증 상태: 필드별 검증 상태 및 오류 메시지

2. 기존 화면에서 검증 기능 활성화

기존 InteractiveScreenViewer 컴포넌트에 검증 기능을 추가할 수 있습니다:

<InteractiveScreenViewer
  component={component}
  allComponents={allComponents}
  formData={formData}
  onFormDataChange={handleFormDataChange}
  screenInfo={screenInfo}
  // 검증 기능 활성화
  enableEnhancedValidation={true}
  tableColumns={tableColumns}
  showValidationPanel={true}
  validationOptions={{
    enableRealTimeValidation: true,
    validationDelay: 300,
    enableAutoSave: false,
    showToastMessages: true,
  }}
/>

3. 새로운 Enhanced 컴포넌트 사용

완전히 새로운 검증 기능을 위해서는 EnhancedInteractiveScreenViewer를 사용하세요:

import { EnhancedInteractiveScreenViewer } from "@/components/screen/EnhancedInteractiveScreenViewer";

<EnhancedInteractiveScreenViewer
  component={component}
  allComponents={allComponents}
  formData={formData}
  onFormDataChange={handleFormDataChange}
  screenInfo={screenInfo}
  tableColumns={tableColumns}
  showValidationPanel={true}
  showDeveloperInfo={false} // 개발 모드에서만 true
/>;

⚙️ 설정 옵션

검증 옵션 (`validationOptions`)

interface ValidationOptions {
  enableRealTimeValidation?: boolean; // 실시간 검증 활성화 (기본: true)
  validationDelay?: number; // 검증 지연 시간 ms (기본: 300)
  enableAutoSave?: boolean; // 자동 저장 (기본: false)
  autoSaveDelay?: number; // 자동 저장 지연 시간 ms (기본: 2000)
  showToastMessages?: boolean; // 토스트 메시지 표시 (기본: true)
  validateOnMount?: boolean; // 마운트 시 검증 (기본: false)
}

표시 옵션

interface DisplayOptions {
  showValidationPanel?: boolean; // 검증 패널 표시 (기본: false)
  compactValidation?: boolean; // 간소화된 검증 UI (기본: false)
  showDeveloperInfo?: boolean; // 개발자 정보 표시 (기본: false)
}

🔧 개발자 가이드

1. 새로운 WebType 추가

새로운 웹타입을 추가하려면 양쪽 모두 업데이트해야 합니다:

프론트엔드 (frontend/types/unified-web-types.ts):

export type BaseWebType =
  | "text"
  | "number"
  // ... 기존 타입들
  | "new-type"; // 새 타입 추가

백엔드 (backend-node/src/types/unified-web-types.ts):

export type BaseWebType =
  | "text"
  | "number"
  // ... 기존 타입들
  | "new-type"; // 동일하게 추가

2. 커스텀 검증 규칙 추가

formValidation.ts에서 새로운 검증 로직을 추가할 수 있습니다:

const validateCustomField = (
  fieldName: string,
  value: any,
  config?: Record<string, any>
): FieldValidationResult => {
  // 커스텀 검증 로직
  if (customValidationFails) {
    return {
      isValid: false,
      error: {
        field: fieldName,
        code: "CUSTOM_ERROR",
        message: "커스텀 오류 메시지",
        severity: "error",
        value,
      },
    };
  }

  return { isValid: true };
};

3. 테이블 컬럼 정보 캐싱

시스템은 자동으로 테이블 컬럼 정보를 캐싱합니다:

클라이언트: 10분간 캐싱
서버: 10분간 캐싱
수동 캐시 클리어: enhancedFormService.clearTableCache(tableName)

🚨 트러블슈팅

자주 발생하는 문제

1. "테이블 정보를 찾을 수 없습니다"

해결책:
1. 테이블명이 정확한지 확인
2. table_type_columns 테이블에 해당 테이블 정보가 있는지 확인
3. 데이터베이스 연결 상태 확인 (http://localhost:8080/api/table-management/health)

2. "컬럼이 존재하지 않습니다"

해결책:
1. WidgetComponent의 columnName 속성 확인
2. 데이터베이스 스키마와 일치하는지 확인
3. 제안된 유사한 컬럼명 사용 고려

3. "타입 변환 오류"

해결책:
1. webType과 PostgreSQL 데이터 타입 호환성 확인
2. detailSettings의 제약조건 검토
3. 입력값 형식 확인 (예: 날짜는 YYYY-MM-DD)

4. 검증이 작동하지 않음

해결책:
1. enableEnhancedValidation={true} 설정 확인
2. tableColumns 배열이 올바르게 전달되었는지 확인
3. screenInfo에 id와 tableName이 있는지 확인

로그 분석

개발 모드에서는 상세한 로그가 제공됩니다:

// 클라이언트 로그
console.log("🔍 개선된 검증 시스템 사용");
console.log("💾 폼 데이터 저장 요청:", formData);

// 서버 로그
logger.info("개선된 폼 저장 시작: tableName");
logger.debug("Data after validation:", transformedData);

📊 성능 모니터링

성능 지표

시스템은 다음 성능 지표를 추적합니다:

검증 시간: 클라이언트 검증 수행 시간
저장 시간: 서버 저장 처리 시간
전체 시간: 요청부터 응답까지 총 시간
캐시 히트율: 테이블 컬럼 정보 캐시 사용률

성능 최적화 팁

테이블 컬럼 정보 사전 로드:

// 화면 로드 시 테이블 정보 미리 캐싱
await enhancedFormService.getTableColumns(tableName);

검증 지연 시간 조정:

// 빠른 응답이 필요한 경우
validationOptions={{ validationDelay: 100 }}

// 서버 부하를 줄이려는 경우
validationOptions={{ validationDelay: 1000 }}

불필요한 실시간 검증 비활성화:

// 단순한 폼의 경우
validationOptions={{ enableRealTimeValidation: false }}

🔄 마이그레이션 가이드

기존 코드에서 새 시스템으로

단계별 마이그레이션:

// 1단계: 기존 코드 유지하면서 검증만 추가
<InteractiveScreenViewer
  {...existingProps}
  enableEnhancedValidation={true}
  tableColumns={tableColumns}
/>

// 2단계: 검증 패널 추가
<InteractiveScreenViewer
  {...existingProps}
  enableEnhancedValidation={true}
  tableColumns={tableColumns}
  showValidationPanel={true}
/>

// 3단계: 완전 마이그레이션
<EnhancedInteractiveScreenViewer
  {...existingProps}
  tableColumns={tableColumns}
  showValidationPanel={true}
/>

API 호출 변경:

// 기존 방식
await dynamicFormApi.saveFormData(formData);

// 새로운 방식 (권장)
await dynamicFormApi.saveData(formData);

📞 지원 및 문의

개발 지원

데모 페이지: /admin/validation-demo
API 상태 확인: /api/table-management/health
로그 레벨: 개발 환경에서 DEBUG 로그 활성화

추가 개발 계획

Phase 2: 웹타입별 상세 설정 UI
Phase 3: 고급 검증 규칙 (정규식, 범위 등)
Phase 4: 조건부 필드 및 계산 필드
Phase 5: 실시간 협업 기능

이 가이드는 화면관리 검증 시스템의 핵심 기능과 사용법을 다룹니다. 추가 질문이나 개선 제안은 개발팀에 문의해주세요! 🚀

9.2 KiB Raw Blame History