# 화면관리 검증 시스템 사용 가이드
## 📋 개요
이 문서는 화면관리에서 입력 폼 저장 시 발생하던 타입 불일치와 컬럼 오류 문제를 해결하기 위해 개발된 **개선된 검증 시스템**의 사용 방법을 안내합니다.
## 🚀 주요 개선 사항
### ✅ 해결된 문제점
- **타입 불일치 오류**: 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` 컴포넌트에 검증 기능을 추가할 수 있습니다:
```tsx
```
### 3. 새로운 Enhanced 컴포넌트 사용
완전히 새로운 검증 기능을 위해서는 `EnhancedInteractiveScreenViewer`를 사용하세요:
```tsx
import { EnhancedInteractiveScreenViewer } from "@/components/screen/EnhancedInteractiveScreenViewer";
;
```
## ⚙️ 설정 옵션
### 검증 옵션 (`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/unified-web-types.ts`):
```typescript
export type BaseWebType =
| "text"
| "number"
// ... 기존 타입들
| "new-type"; // 새 타입 추가
```
**백엔드** (`backend-node/src/types/unified-web-types.ts`):
```typescript
export type BaseWebType =
| "text"
| "number"
// ... 기존 타입들
| "new-type"; // 동일하게 추가
```
### 2. 커스텀 검증 규칙 추가
`formValidation.ts`에서 새로운 검증 로직을 추가할 수 있습니다:
```typescript
const validateCustomField = (
fieldName: string,
value: any,
config?: Record
): 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단계: 기존 코드 유지하면서 검증만 추가
// 2단계: 검증 패널 추가
// 3단계: 완전 마이그레이션
```
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**: 실시간 협업 기능
---
이 가이드는 화면관리 검증 시스템의 핵심 기능과 사용법을 다룹니다. 추가 질문이나 개선 제안은 개발팀에 문의해주세요! 🚀