ERP-node/PHASE3.16_DATA_MANAGEMENT_SERVICES_MIGRATION.md

# 📋 Phase 3.16: Data Management Services Raw Query 전환 계획

## 📋 개요

데이터 관리 관련 서비스들은 총 **18개의 Prisma 호출**이 있으며, 동적 폼, 데이터 매핑, 데이터 서비스, 관리자 기능을 담당합니다.

### 📊 기본 정보

| 항목            | 내용                                                  |
| --------------- | ----------------------------------------------------- |
| 대상 서비스     | 4개 (EnhancedDynamicForm, DataMapping, Data, Admin)   |
| 파일 위치       | `backend-node/src/services/{enhanced,data,admin}*.ts` |
| 총 파일 크기    | 2,062 라인                                            |
| Prisma 호출     | 0개 (전환 완료)                                        |
| **현재 진행률** | **18/18 (100%)** ✅ **전환 완료**                     |
| 복잡도          | 중간 (동적 쿼리, JSON 필드, 관리자 기능)              |
| 우선순위        | 🟡 중간 (Phase 3.16)                                  |
| **상태**        | ✅ **완료**                                           |

---

## ✅ 전환 완료 내역

### 전환된 Prisma 호출 (18개)

#### 1. EnhancedDynamicFormService (6개)
- `validateTableExists()` - $queryRawUnsafe → query
- `getTableColumns()` - $queryRawUnsafe → query
- `getColumnWebTypes()` - $queryRawUnsafe → query  
- `getPrimaryKeys()` - $queryRawUnsafe → query
- `performInsert()` - $queryRawUnsafe → query
- `performUpdate()` - $queryRawUnsafe → query

#### 2. DataMappingService (5개)
- `getSourceData()` - $queryRawUnsafe → query
- `executeInsert()` - $executeRawUnsafe → query
- `executeUpsert()` - $executeRawUnsafe → query
- `executeUpdate()` - $executeRawUnsafe → query
- `disconnect()` - 제거 (Raw Query는 disconnect 불필요)

#### 3. DataService (4개)
- `getTableData()` - $queryRawUnsafe → query
- `checkTableExists()` - $queryRawUnsafe → query
- `getTableColumnsSimple()` - $queryRawUnsafe → query
- `getColumnLabel()` - $queryRawUnsafe → query

#### 4. AdminService (3개)
- `getAdminMenuList()` - $queryRaw → query (WITH RECURSIVE)
- `getUserMenuList()` - $queryRaw → query (WITH RECURSIVE)
- `getMenuInfo()` - findUnique → query (JOIN)

### 주요 기술적 해결 사항

1. **변수명 충돌 해결**
   - `dataService.ts`에서 `query` 변수 → `sql` 변수로 변경
   - `query()` 함수와 로컬 변수 충돌 방지

2. **WITH RECURSIVE 쿼리 전환**
   - Prisma의 `$queryRaw` 템플릿 리터럴 → 일반 문자열
   - `${userLang}` → `$1` 파라미터 바인딩

3. **JOIN 쿼리 전환**
   - Prisma의 `include` 옵션 → `LEFT JOIN` 쿼리
   - 관계 데이터를 단일 쿼리로 조회

4. **동적 쿼리 생성**
   - 동적 WHERE 조건 구성
   - SQL 인젝션 방지 (컬럼명 검증)
   - 동적 ORDER BY 처리

### 컴파일 상태
✅ TypeScript 컴파일 성공  
✅ Linter 오류 없음

---

## 🔍 서비스별 상세 분석

### 1. EnhancedDynamicFormService (6개 호출, 786 라인)

**주요 기능**:

- 고급 동적 폼 관리
- 폼 검증 규칙
- 조건부 필드 표시
- 폼 템플릿 관리

**예상 Prisma 호출**:

- `getEnhancedForms()` - 고급 폼 목록 조회
- `getEnhancedForm()` - 고급 폼 단건 조회
- `createEnhancedForm()` - 고급 폼 생성
- `updateEnhancedForm()` - 고급 폼 수정
- `deleteEnhancedForm()` - 고급 폼 삭제
- `getFormValidationRules()` - 검증 규칙 조회

**기술적 고려사항**:

- JSON 필드 (validation_rules, conditional_logic, field_config)
- 복잡한 검증 규칙
- 동적 필드 생성
- 조건부 표시 로직

---

### 2. DataMappingService (5개 호출, 575 라인)

**주요 기능**:

- 데이터 매핑 설정 관리
- 소스-타겟 필드 매핑
- 데이터 변환 규칙
- 매핑 실행

**예상 Prisma 호출**:

- `getDataMappings()` - 매핑 설정 목록 조회
- `getDataMapping()` - 매핑 설정 단건 조회
- `createDataMapping()` - 매핑 설정 생성
- `updateDataMapping()` - 매핑 설정 수정
- `deleteDataMapping()` - 매핑 설정 삭제

**기술적 고려사항**:

- JSON 필드 (field_mappings, transformation_rules)
- 복잡한 변환 로직
- 매핑 검증
- 실행 이력 추적

---

### 3. DataService (4개 호출, 327 라인)

**주요 기능**:

- 동적 데이터 조회
- 데이터 필터링
- 데이터 정렬
- 데이터 집계

**예상 Prisma 호출**:

- `getDataByTable()` - 테이블별 데이터 조회
- `getDataById()` - 데이터 단건 조회
- `executeCustomQuery()` - 커스텀 쿼리 실행
- `getDataStatistics()` - 데이터 통계 조회

**기술적 고려사항**:

- 동적 테이블 쿼리
- SQL 인젝션 방지
- 동적 WHERE 조건
- 집계 쿼리

---

### 4. AdminService (3개 호출, 374 라인)

**주요 기능**:

- 관리자 메뉴 관리
- 시스템 설정
- 사용자 관리
- 로그 조회

**예상 Prisma 호출**:

- `getAdminMenus()` - 관리자 메뉴 조회
- `getSystemSettings()` - 시스템 설정 조회
- `updateSystemSettings()` - 시스템 설정 업데이트

**기술적 고려사항**:

- 메뉴 계층 구조
- 권한 기반 필터링
- JSON 설정 필드
- 캐싱

---

## 💡 통합 전환 전략

### Phase 1: 단순 CRUD 전환 (12개)

**EnhancedDynamicFormService (6개) + DataMappingService (5개) + AdminService (1개)**

- 기본 CRUD 기능
- JSON 필드 처리

### Phase 2: 동적 쿼리 전환 (4개)

**DataService (4개)**

- 동적 테이블 쿼리
- 보안 검증

### Phase 3: 고급 기능 전환 (2개)

**AdminService (2개)**

- 시스템 설정
- 캐싱

---

## 💻 전환 예시

### 예시 1: 고급 폼 생성 (JSON 필드)

**변경 전**:

```typescript
const form = await prisma.enhanced_forms.create({
  data: {
    form_code: formCode,
    form_name: formName,
    validation_rules: validationRules, // JSON
    conditional_logic: conditionalLogic, // JSON
    field_config: fieldConfig, // JSON
    company_code: companyCode,
  },
});
```

**변경 후**:

```typescript
const form = await queryOne<any>(
  `INSERT INTO enhanced_forms 
   (form_code, form_name, validation_rules, conditional_logic, 
    field_config, company_code, created_at, updated_at)
   VALUES ($1, $2, $3, $4, $5, $6, NOW(), NOW())
   RETURNING *`,
  [
    formCode,
    formName,
    JSON.stringify(validationRules),
    JSON.stringify(conditionalLogic),
    JSON.stringify(fieldConfig),
    companyCode,
  ]
);
```

### 예시 2: 데이터 매핑 조회

**변경 전**:

```typescript
const mappings = await prisma.data_mappings.findMany({
  where: {
    source_table: sourceTable,
    target_table: targetTable,
    is_active: true,
  },
  include: {
    source_columns: true,
    target_columns: true,
  },
});
```

**변경 후**:

```typescript
const mappings = await query<any>(
  `SELECT 
     dm.*,
     json_agg(DISTINCT jsonb_build_object(
       'column_id', sc.column_id,
       'column_name', sc.column_name
     )) FILTER (WHERE sc.column_id IS NOT NULL) as source_columns,
     json_agg(DISTINCT jsonb_build_object(
       'column_id', tc.column_id,
       'column_name', tc.column_name
     )) FILTER (WHERE tc.column_id IS NOT NULL) as target_columns
   FROM data_mappings dm
   LEFT JOIN columns sc ON dm.mapping_id = sc.mapping_id AND sc.type = 'source'
   LEFT JOIN columns tc ON dm.mapping_id = tc.mapping_id AND tc.type = 'target'
   WHERE dm.source_table = $1 
   AND dm.target_table = $2 
   AND dm.is_active = $3
   GROUP BY dm.mapping_id`,
  [sourceTable, targetTable, true]
);
```

### 예시 3: 동적 테이블 쿼리 (DataService)

**변경 전**:

```typescript
// Prisma로는 동적 테이블 쿼리 불가능
// 이미 $queryRawUnsafe 사용 중일 가능성
const data = await prisma.$queryRawUnsafe(
  `SELECT * FROM ${tableName} WHERE ${whereClause}`,
  ...params
);
```

**변경 후**:

```typescript
// SQL 인젝션 방지를 위한 테이블명 검증
const validTableName = validateTableName(tableName);

const data = await query<any>(
  `SELECT * FROM ${validTableName} WHERE ${whereClause}`,
  params
);
```

### 예시 4: 관리자 메뉴 조회 (계층 구조)

**변경 전**:

```typescript
const menus = await prisma.admin_menus.findMany({
  where: { is_active: true },
  orderBy: { sort_order: "asc" },
  include: {
    children: {
      orderBy: { sort_order: "asc" },
    },
  },
});
```

**변경 후**:

```typescript
// 재귀 CTE를 사용한 계층 쿼리
const menus = await query<any>(
  `WITH RECURSIVE menu_tree AS (
     SELECT *, 0 as level, ARRAY[menu_id] as path
     FROM admin_menus
     WHERE parent_id IS NULL AND is_active = $1
     
     UNION ALL
     
     SELECT m.*, mt.level + 1, mt.path || m.menu_id
     FROM admin_menus m
     JOIN menu_tree mt ON m.parent_id = mt.menu_id
     WHERE m.is_active = $1
   )
   SELECT * FROM menu_tree
   ORDER BY path, sort_order`,
  [true]
);
```

---

## 🔧 기술적 고려사항

### 1. JSON 필드 처리

```typescript
// 복잡한 JSON 구조
interface ValidationRules {
  required?: string[];
  min?: Record<string, number>;
  max?: Record<string, number>;
  pattern?: Record<string, string>;
  custom?: Array<{ field: string; rule: string }>;
}

// 저장 시
JSON.stringify(validationRules);

// 조회 후
const parsed =
  typeof row.validation_rules === "string"
    ? JSON.parse(row.validation_rules)
    : row.validation_rules;
```

### 2. 동적 테이블 쿼리 보안

```typescript
// 테이블명 화이트리스트
const ALLOWED_TABLES = ["users", "products", "orders"];

function validateTableName(tableName: string): string {
  if (!ALLOWED_TABLES.includes(tableName)) {
    throw new Error("Invalid table name");
  }
  return tableName;
}

// 컬럼명 검증
function validateColumnName(columnName: string): string {
  if (!/^[a-z_][a-z0-9_]*$/i.test(columnName)) {
    throw new Error("Invalid column name");
  }
  return columnName;
}
```

### 3. 재귀 CTE (계층 구조)

```sql
WITH RECURSIVE hierarchy AS (
  -- 최상위 노드
  SELECT * FROM table WHERE parent_id IS NULL

  UNION ALL

  -- 하위 노드
  SELECT t.* FROM table t
  JOIN hierarchy h ON t.parent_id = h.id
)
SELECT * FROM hierarchy
```

### 4. JSON 집계 (관계 데이터)

```sql
SELECT
  parent.*,
  COALESCE(
    json_agg(
      jsonb_build_object('id', child.id, 'name', child.name)
    ) FILTER (WHERE child.id IS NOT NULL),
    '[]'
  ) as children
FROM parent
LEFT JOIN child ON parent.id = child.parent_id
GROUP BY parent.id
```

---

## 📝 전환 체크리스트

### EnhancedDynamicFormService (6개)

- [ ] `getEnhancedForms()` - 목록 조회
- [ ] `getEnhancedForm()` - 단건 조회
- [ ] `createEnhancedForm()` - 생성 (JSON 필드)
- [ ] `updateEnhancedForm()` - 수정 (JSON 필드)
- [ ] `deleteEnhancedForm()` - 삭제
- [ ] `getFormValidationRules()` - 검증 규칙 조회

### DataMappingService (5개)

- [ ] `getDataMappings()` - 목록 조회
- [ ] `getDataMapping()` - 단건 조회
- [ ] `createDataMapping()` - 생성
- [ ] `updateDataMapping()` - 수정
- [ ] `deleteDataMapping()` - 삭제

### DataService (4개)

- [ ] `getDataByTable()` - 동적 테이블 조회
- [ ] `getDataById()` - 단건 조회
- [ ] `executeCustomQuery()` - 커스텀 쿼리
- [ ] `getDataStatistics()` - 통계 조회

### AdminService (3개)

- [ ] `getAdminMenus()` - 메뉴 조회 (재귀 CTE)
- [ ] `getSystemSettings()` - 시스템 설정 조회
- [ ] `updateSystemSettings()` - 시스템 설정 업데이트

### 공통 작업

- [ ] import 문 수정 (모든 서비스)
- [ ] Prisma import 완전 제거
- [ ] JSON 필드 처리 확인
- [ ] 보안 검증 (SQL 인젝션)

---

## 🧪 테스트 계획

### 단위 테스트 (18개)

- 각 Prisma 호출별 1개씩

### 통합 테스트 (6개)

- EnhancedDynamicFormService: 폼 생성 및 검증 테스트 (2개)
- DataMappingService: 매핑 설정 및 실행 테스트 (2개)
- DataService: 동적 쿼리 및 보안 테스트 (1개)
- AdminService: 메뉴 계층 구조 테스트 (1개)

### 보안 테스트

- SQL 인젝션 방지 테스트
- 테이블명 검증 테스트
- 컬럼명 검증 테스트

---

## 🎯 예상 난이도 및 소요 시간

- **난이도**: ⭐⭐⭐⭐ (높음)
  - JSON 필드 처리
  - 동적 쿼리 보안
  - 재귀 CTE
  - JSON 집계
- **예상 소요 시간**: 2.5~3시간
  - Phase 1 (기본 CRUD): 1시간
  - Phase 2 (동적 쿼리): 1시간
  - Phase 3 (고급 기능): 0.5시간
  - 테스트 및 문서화: 0.5시간

---

## ⚠️ 주의사항

### 보안 필수 체크리스트

1. ✅ 동적 테이블명은 반드시 화이트리스트 검증
2. ✅ 동적 컬럼명은 정규식으로 검증
3. ✅ WHERE 절 파라미터는 반드시 바인딩
4. ✅ JSON 필드는 파싱 에러 처리
5. ✅ 재귀 쿼리는 깊이 제한 설정

### 성능 최적화

- JSON 필드 인덱싱 (GIN 인덱스)
- 재귀 쿼리 깊이 제한
- 집계 쿼리 최적화
- 필요시 캐싱 적용

---

**상태**: ⏳ **대기 중**  
**특이사항**: JSON 필드, 동적 쿼리, 재귀 CTE, 보안 검증 포함  
**⚠️ 주의**: 동적 쿼리는 SQL 인젝션 방지가 매우 중요!