333 lines
9.2 KiB
Markdown
333 lines
9.2 KiB
Markdown
# 화면관리 검증 시스템 사용 가이드
|
|
|
|
## 📋 개요
|
|
|
|
이 문서는 화면관리에서 입력 폼 저장 시 발생하던 타입 불일치와 컬럼 오류 문제를 해결하기 위해 개발된 **개선된 검증 시스템**의 사용 방법을 안내합니다.
|
|
|
|
## 🚀 주요 개선 사항
|
|
|
|
### ✅ 해결된 문제점
|
|
|
|
- **타입 불일치 오류**: 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
|
|
<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/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<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**: 실시간 협업 기능
|
|
|
|
---
|
|
|
|
이 가이드는 화면관리 검증 시스템의 핵심 기능과 사용법을 다룹니다. 추가 질문이나 개선 제안은 개발팀에 문의해주세요! 🚀
|