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

## 📋 개요

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

## 🚀 주요 개선 사항

### ✅ 해결된 문제점

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

### 🎯 새로운 기능

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

## 🛠️ 기술 스택

### 프론트엔드

- **TypeScript**: 통합 타입 정의 (`v2-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**: 통합 웹타입 정의 (`v2-web-types.ts`)

## 🎮 사용 방법

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

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

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

#### 데모 기능

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

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

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

```tsx
<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`를 사용하세요:

```tsx
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`)

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

### 표시 옵션

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

## 🔧 개발자 가이드

### 1. 새로운 WebType 추가

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

**프론트엔드** (`frontend/types/v2-web-types.ts`):

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

**백엔드** (`backend-node/src/types/v2-web-types.ts`):

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

### 2. 커스텀 검증 규칙 추가

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

```typescript
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이 있는지 확인
```

### 로그 분석

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

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

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

## 📊 성능 모니터링

### 성능 지표

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

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

### 성능 최적화 팁

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

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

2. **검증 지연 시간 조정**:

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

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

3. **불필요한 실시간 검증 비활성화**:
   ```typescript
   // 단순한 폼의 경우
   validationOptions={{ enableRealTimeValidation: false }}
   ```

## 🔄 마이그레이션 가이드

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

1. **단계별 마이그레이션**:

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

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

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

2. **API 호출 변경**:

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

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

## 📞 지원 및 문의

### 개발 지원

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

### 추가 개발 계획

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

---

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