437 lines
15 KiB
Markdown
437 lines
15 KiB
Markdown
# 방안 1: 컴포넌트 URL 참조 + Zod 스키마 관리
|
|
|
|
## 1. 현재 문제점 정리
|
|
|
|
### 1.1 JSON 구조 불일치
|
|
|
|
```
|
|
현재 상태:
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ v2-table-list 컴포넌트 │
|
|
│ 화면 A: { pageSize: 20, showCheckbox: true } │
|
|
│ 화면 B: { pagination: { size: 20 }, checkbox: true } │
|
|
│ 화면 C: { paging: { pageSize: 20 }, hasCheckbox: true } │
|
|
│ │
|
|
│ → 같은 설정인데 키 이름이 다름 │
|
|
│ → 타입 검증 없음 (런타임 에러 발생) │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 1.2 컴포넌트 수정 시 마이그레이션 필요
|
|
|
|
```
|
|
컴포넌트 구조 변경:
|
|
pageSize → pagination.pageSize 로 변경하면?
|
|
|
|
→ 100개 화면의 JSON 전부 마이그레이션 필요
|
|
→ 테스트 공수 발생
|
|
→ 누락 시 런타임 에러
|
|
```
|
|
|
|
---
|
|
|
|
## 2. 방안 1 + Zod 아키텍처
|
|
|
|
### 2.1 전체 구조
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 1. 컴포넌트 코드 + Zod 스키마 (프론트엔드) │
|
|
│ │
|
|
│ @/lib/registry/components/v2-table-list/ │
|
|
│ ├── index.ts # 컴포넌트 등록 │
|
|
│ ├── TableListRenderer.tsx # 렌더링 로직 │
|
|
│ ├── schema.ts # ⭐ Zod 스키마 정의 │
|
|
│ └── defaults.ts # ⭐ 기본값 정의 │
|
|
│ │
|
|
│ 코드 수정 → 빌드 → 전 회사 즉시 적용 │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
│ URL로 참조
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 2. DB (최소한의 차이점만 저장) │
|
|
│ │
|
|
│ screen_layouts.properties = { │
|
|
│ "componentUrl": "@/registry/v2-table-list", │
|
|
│ "config": { │
|
|
│ "pageSize": 50 ← 기본값(20)과 다른 것만 │
|
|
│ } │
|
|
│ } │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
│ 설정 병합
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 3. 런타임: 기본값 + 오버라이드 병합 + Zod 검증 │
|
|
│ │
|
|
│ 최종 설정 = deepMerge(기본값, 오버라이드) │
|
|
│ 검증된 설정 = schema.parse(최종 설정) │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 2.2 Zod 스키마 예시
|
|
|
|
```typescript
|
|
// @/lib/registry/components/v2-table-list/schema.ts
|
|
import { z } from "zod";
|
|
|
|
// 컬럼 설정 스키마
|
|
const columnSchema = z.object({
|
|
columnName: z.string(),
|
|
displayName: z.string(),
|
|
visible: z.boolean().default(true),
|
|
sortable: z.boolean().default(true),
|
|
width: z.number().optional(),
|
|
align: z.enum(["left", "center", "right"]).default("left"),
|
|
format: z.enum(["text", "number", "date", "currency"]).default("text"),
|
|
order: z.number().default(0),
|
|
});
|
|
|
|
// 페이지네이션 스키마
|
|
const paginationSchema = z.object({
|
|
enabled: z.boolean().default(true),
|
|
pageSize: z.number().default(20),
|
|
showSizeSelector: z.boolean().default(true),
|
|
pageSizeOptions: z.array(z.number()).default([10, 20, 50, 100]),
|
|
});
|
|
|
|
// 체크박스 스키마
|
|
const checkboxSchema = z.object({
|
|
enabled: z.boolean().default(true),
|
|
multiple: z.boolean().default(true),
|
|
position: z.enum(["left", "right"]).default("left"),
|
|
});
|
|
|
|
// 테이블 리스트 전체 스키마
|
|
export const tableListSchema = z.object({
|
|
tableName: z.string(),
|
|
columns: z.array(columnSchema).default([]),
|
|
pagination: paginationSchema.default({}),
|
|
checkbox: checkboxSchema.default({}),
|
|
showHeader: z.boolean().default(true),
|
|
autoLoad: z.boolean().default(true),
|
|
});
|
|
|
|
// 타입 자동 추론
|
|
export type TableListConfig = z.infer<typeof tableListSchema>;
|
|
```
|
|
|
|
### 2.3 기본값 정의
|
|
|
|
```typescript
|
|
// @/lib/registry/components/v2-table-list/defaults.ts
|
|
import { TableListConfig } from "./schema";
|
|
|
|
export const defaultConfig: Partial<TableListConfig> = {
|
|
pagination: {
|
|
enabled: true,
|
|
pageSize: 20,
|
|
showSizeSelector: true,
|
|
pageSizeOptions: [10, 20, 50, 100],
|
|
},
|
|
checkbox: {
|
|
enabled: true,
|
|
multiple: true,
|
|
position: "left",
|
|
},
|
|
showHeader: true,
|
|
autoLoad: true,
|
|
};
|
|
```
|
|
|
|
### 2.4 설정 로드 로직
|
|
|
|
```typescript
|
|
// @/lib/registry/utils/configLoader.ts
|
|
import { deepMerge } from "@/lib/utils";
|
|
|
|
export function loadComponentConfig<T>(
|
|
componentUrl: string,
|
|
overrideConfig: Partial<T>
|
|
): T {
|
|
// 1. 컴포넌트 모듈에서 스키마와 기본값 가져오기
|
|
const { schema, defaultConfig } = getComponentModule(componentUrl);
|
|
|
|
// 2. 기본값 + 오버라이드 병합
|
|
const mergedConfig = deepMerge(defaultConfig, overrideConfig);
|
|
|
|
// 3. Zod 스키마로 검증 + 기본값 자동 적용
|
|
const validatedConfig = schema.parse(mergedConfig);
|
|
|
|
return validatedConfig;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 현재 시스템 적응도 분석
|
|
|
|
### 3.1 변경이 필요한 부분
|
|
|
|
| 영역 | 현재 | 변경 후 | 공수 |
|
|
|-----|-----|--------|-----|
|
|
| **컴포넌트 폴더 구조** | types.ts만 있음 | schema.ts, defaults.ts 추가 | 중간 |
|
|
| **screen_layouts** | 모든 설정 저장 | URL + 차이점만 저장 | 중간 |
|
|
| **화면 저장 로직** | JSON 통째로 저장 | 차이점 추출 후 저장 | 중간 |
|
|
| **화면 로드 로직** | JSON 그대로 사용 | 기본값 병합 + Zod 검증 | 낮음 |
|
|
| **기존 데이터** | - | 마이그레이션 필요 | 높음 |
|
|
|
|
### 3.2 기존 코드와의 호환성
|
|
|
|
```
|
|
현재 Zod 사용 현황:
|
|
✅ zod v4.1.5 이미 설치됨
|
|
✅ @hookform/resolvers 설치됨 (react-hook-form + Zod 연동)
|
|
✅ 공통코드 관리에 Zod 스키마 사용 중 (lib/schemas/commonCode.ts)
|
|
|
|
→ Zod 패턴이 이미 프로젝트에 존재함
|
|
→ 동일한 패턴으로 컴포넌트 스키마 추가 가능
|
|
```
|
|
|
|
### 3.3 점진적 마이그레이션 가능 여부
|
|
|
|
```
|
|
Phase 1: 새 컴포넌트만 적용
|
|
- 신규 컴포넌트는 schema.ts + defaults.ts 구조로 생성
|
|
- 기존 컴포넌트는 그대로 유지
|
|
|
|
Phase 2: 핵심 컴포넌트 마이그레이션
|
|
- v2-table-list, v2-button-primary 등 자주 사용하는 것 먼저
|
|
- 기존 JSON 데이터 → 차이점만 남기고 정리
|
|
|
|
Phase 3: 전체 마이그레이션
|
|
- 나머지 컴포넌트 순차 적용
|
|
|
|
→ 점진적 적용 가능 ✅
|
|
```
|
|
|
|
---
|
|
|
|
## 4. 향후 장점
|
|
|
|
### 4.1 컴포넌트 수정 시
|
|
|
|
```
|
|
변경 전:
|
|
컴포넌트 수정 → 100개 화면 JSON 마이그레이션 → 테스트 → 배포
|
|
|
|
변경 후:
|
|
컴포넌트 수정 → 빌드 → 배포 → 끝
|
|
|
|
왜?
|
|
- 기본값/로직은 코드에 있음
|
|
- DB에는 "다른 것만" 저장되어 있음
|
|
- 코드 변경이 자동으로 모든 화면에 적용됨
|
|
```
|
|
|
|
### 4.2 새 설정 추가 시
|
|
|
|
```
|
|
변경 전:
|
|
1. types.ts 수정
|
|
2. 100개 화면 JSON에 새 필드 추가 (마이그레이션)
|
|
3. 기본값 없으면 에러 발생
|
|
|
|
변경 후:
|
|
1. schema.ts에 필드 추가 + .default() 설정
|
|
2. 끝. 기존 데이터는 자동으로 기본값 적용됨
|
|
|
|
// 예시
|
|
const schema = z.object({
|
|
// 기존 필드
|
|
pageSize: z.number().default(20),
|
|
|
|
// 🆕 새 필드 추가 - 기본값 있으면 마이그레이션 불필요
|
|
showRowNumber: z.boolean().default(false),
|
|
});
|
|
```
|
|
|
|
### 4.3 타입 안정성
|
|
|
|
```typescript
|
|
// 현재: 타입 검증 없음
|
|
const config = component.componentConfig; // any 타입
|
|
config.pageSize; // 있을 수도, 없을 수도...
|
|
config.pagination.pageSize; // 구조가 다를 수도...
|
|
|
|
// 변경 후: Zod로 검증 + TypeScript 타입 추론
|
|
const config = tableListSchema.parse(rawConfig);
|
|
config.pagination.pageSize; // ✅ 타입 보장
|
|
config.unknownField; // ❌ 컴파일 에러
|
|
```
|
|
|
|
### 4.4 런타임 에러 방지
|
|
|
|
```typescript
|
|
// Zod 검증 실패 시 명확한 에러 메시지
|
|
try {
|
|
const config = tableListSchema.parse(rawConfig);
|
|
} catch (error) {
|
|
if (error instanceof z.ZodError) {
|
|
console.error("설정 오류:", error.errors);
|
|
// [
|
|
// { path: ["pagination", "pageSize"], message: "Expected number, received string" },
|
|
// { path: ["columns", 0, "align"], message: "Invalid enum value" }
|
|
// ]
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4.5 문서화 자동화
|
|
|
|
```typescript
|
|
// Zod 스키마에서 자동으로 문서 생성 가능
|
|
import { zodToJsonSchema } from "zod-to-json-schema";
|
|
|
|
const jsonSchema = zodToJsonSchema(tableListSchema);
|
|
// → JSON Schema 형식으로 변환 → 문서화 도구에서 사용
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 유지보수 측면
|
|
|
|
### 5.1 컴포넌트 개발자 입장
|
|
|
|
| 작업 | 현재 | 변경 후 |
|
|
|-----|-----|--------|
|
|
| 새 컴포넌트 생성 | types.ts 작성 (선택) | schema.ts + defaults.ts 작성 (필수) |
|
|
| 설정 구조 변경 | 마이그레이션 스크립트 작성 | schema 수정 + 기본값 설정 |
|
|
| 타입 체크 | 수동 검증 | Zod가 자동 검증 |
|
|
| 디버깅 | console.log로 추적 | Zod 에러 메시지로 바로 파악 |
|
|
|
|
### 5.2 화면 개발자 입장
|
|
|
|
| 작업 | 현재 | 변경 후 |
|
|
|-----|-----|--------|
|
|
| 화면 생성 | 모든 설정 직접 지정 | 필요한 것만 오버라이드 |
|
|
| 설정 실수 | 런타임 에러 | 저장 시 Zod 검증 에러 |
|
|
| 기본값 확인 | 코드 뒤져보기 | defaults.ts 확인 |
|
|
|
|
### 5.3 운영자 입장
|
|
|
|
| 작업 | 현재 | 변경 후 |
|
|
|-----|-----|--------|
|
|
| 일괄 설정 변경 | 100개 JSON 수정 | defaults.ts 수정 → 전체 적용 |
|
|
| 회사별 기본값 | 불가능 | 회사별 defaults 테이블 추가 가능 |
|
|
| 오류 추적 | 어려움 | Zod 검증 로그 확인 |
|
|
|
|
---
|
|
|
|
## 6. 데이터 마이그레이션 계획
|
|
|
|
### 6.1 차이점 추출 스크립트
|
|
|
|
```typescript
|
|
// 기존 JSON에서 기본값과 다른 것만 추출
|
|
async function extractDiff(componentUrl: string, fullConfig: any): Promise<any> {
|
|
const { defaultConfig } = getComponentModule(componentUrl);
|
|
|
|
function getDiff(defaults: any, current: any): any {
|
|
const diff: any = {};
|
|
|
|
for (const key of Object.keys(current)) {
|
|
if (defaults[key] === undefined) {
|
|
// 기본값에 없는 키 = 그대로 유지
|
|
diff[key] = current[key];
|
|
} else if (typeof current[key] === 'object' && !Array.isArray(current[key])) {
|
|
// 중첩 객체 = 재귀 비교
|
|
const nestedDiff = getDiff(defaults[key], current[key]);
|
|
if (Object.keys(nestedDiff).length > 0) {
|
|
diff[key] = nestedDiff;
|
|
}
|
|
} else if (JSON.stringify(defaults[key]) !== JSON.stringify(current[key])) {
|
|
// 값이 다름 = 저장
|
|
diff[key] = current[key];
|
|
}
|
|
// 값이 같음 = 저장 안 함 (기본값 사용)
|
|
}
|
|
|
|
return diff;
|
|
}
|
|
|
|
return getDiff(defaultConfig, fullConfig);
|
|
}
|
|
```
|
|
|
|
### 6.2 마이그레이션 순서
|
|
|
|
```
|
|
1. 컴포넌트별 schema.ts, defaults.ts 작성
|
|
2. 기존 데이터 분석 (어떤 설정이 자주 사용되는지)
|
|
3. 가장 많이 사용되는 값을 기본값으로 설정
|
|
4. 차이점 추출 스크립트 실행
|
|
5. 새 구조로 데이터 업데이트
|
|
6. 테스트
|
|
```
|
|
|
|
---
|
|
|
|
## 7. 예상 공수
|
|
|
|
| 단계 | 작업 | 예상 공수 |
|
|
|-----|-----|---------|
|
|
| **Phase 1** | 아키텍처 설계 + 유틸리티 함수 | 1주 |
|
|
| **Phase 2** | 핵심 컴포넌트 5개 스키마 작성 | 1주 |
|
|
| **Phase 3** | 데이터 마이그레이션 스크립트 | 1주 |
|
|
| **Phase 4** | 테스트 + 버그 수정 | 1주 |
|
|
| **Phase 5** | 나머지 컴포넌트 순차 적용 | 2-3주 |
|
|
| **총계** | | **6-7주** |
|
|
|
|
---
|
|
|
|
## 8. 위험 요소 및 대응
|
|
|
|
### 8.1 위험 요소
|
|
|
|
| 위험 | 영향 | 대응 |
|
|
|-----|-----|-----|
|
|
| 기존 데이터 손실 | 높음 | 마이그레이션 전 백업 필수 |
|
|
| 스키마 설계 실수 | 중간 | 충분한 리뷰 + 테스트 |
|
|
| 런타임 성능 저하 | 낮음 | Zod는 충분히 빠름 |
|
|
| 개발자 학습 비용 | 낮음 | Zod는 직관적, 이미 사용 중 |
|
|
|
|
### 8.2 롤백 계획
|
|
|
|
```
|
|
문제 발생 시:
|
|
1. 기존 JSON 구조로 데이터 복원 (백업에서)
|
|
2. 새 로직 비활성화 (feature flag)
|
|
3. 원인 분석 후 재시도
|
|
```
|
|
|
|
---
|
|
|
|
## 9. 결론
|
|
|
|
### 9.1 방안 1 + Zod 조합의 평가
|
|
|
|
| 항목 | 점수 | 이유 |
|
|
|-----|-----|-----|
|
|
| **현재 시스템 적응도** | ★★★★☆ | Zod 이미 사용 중, 점진적 적용 가능 |
|
|
| **향후 확장성** | ★★★★★ | 새 설정 추가 용이, 타입 안정성 |
|
|
| **유지보수성** | ★★★★★ | 코드 수정 → 전 회사 적용, 명확한 에러 |
|
|
| **마이그레이션 공수** | ★★★☆☆ | 6-7주 소요, 점진적 적용으로 리스크 분산 |
|
|
| **안정성** | ★★★★☆ | Zod 검증으로 런타임 에러 방지 |
|
|
|
|
### 9.2 최종 권장
|
|
|
|
```
|
|
✅ 방안 1 (URL 참조 + Zod 스키마) 적용 권장
|
|
|
|
이유:
|
|
1. 컴포넌트 수정 → 코드만 변경 → 전 회사 자동 적용
|
|
2. Zod로 JSON 구조 일관성 보장
|
|
3. 타입 안정성 + 런타임 검증
|
|
4. 기존 시스템과 호환 (Zod 이미 사용 중)
|
|
5. 점진적 마이그레이션 가능
|
|
```
|
|
|
|
### 9.3 다음 단계
|
|
|
|
1. 핵심 컴포넌트 1개로 PoC (Proof of Concept)
|
|
2. 팀 리뷰 및 피드백
|
|
3. 표준 패턴 확정
|
|
4. 순차적 적용
|