kjs
/
ERP-node
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge branch 'main' into feature/screen-management

This commit is contained in:
kjs 2025-11-10 14:37:50 +09:00
parent 7ab3781372 873addb96a
commit 7dc420a1a2
40 changed files with 561 additions and 17359 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

312
CARD_COMPONENT_ENHANCEMENT_PLAN.md
View File

@ -1,312 +0,0 @@
# 카드 컴포넌트 기능 확장 계획
## 📋 프로젝트 개요
테이블 리스트 컴포넌트의 고급 기능들(Entity 조인, 필터, 검색, 페이지네이션)을 카드 컴포넌트에도 적용하여 일관된 사용자 경험을 제공합니다.
## 🔍 현재 상태 분석
### ✅ 기존 기능
- 테이블 데이터를 카드 형태로 표시
- 기본적인 컬럼 매핑 (제목, 부제목, 설명, 이미지)
- 카드 레이아웃 설정 (행당 카드 수, 간격)
- 설정 패널 존재
### ❌ 부족한 기능
- Entity 조인 기능
- 필터 및 검색 기능
- 페이지네이션
- 코드 변환 기능
- 정렬 기능
## 🎯 개발 단계
### Phase 1: 타입 및 인터페이스 확장 ⚡
#### 1.1 새로운 타입 정의 추가
```typescript
// CardDisplayConfig 확장
interface CardFilterConfig {
enabled: boolean;
quickSearch: boolean;
showColumnSelector?: boolean;
advancedFilter: boolean;
filterableColumns: string[];
}
interface CardPaginationConfig {
enabled: boolean;
pageSize: number;
showSizeSelector: boolean;
showPageInfo: boolean;
pageSizeOptions: number[];
}
interface CardSortConfig {
enabled: boolean;
defaultSort?: {
column: string;
direction: "asc" | "desc";
};
sortableColumns: string[];
}
```
#### 1.2 CardDisplayConfig 확장
- filter, pagination, sort 설정 추가
- Entity 조인 관련 설정 추가
- 코드 변환 관련 설정 추가
### Phase 2: 핵심 기능 구현 🚀
#### 2.1 Entity 조인 기능
- `useEntityJoinOptimization` 훅 적용
- 조인된 컬럼 데이터 매핑
- 코드 변환 기능 (`optimizedConvertCode`)
- 컬럼 메타정보 관리
#### 2.2 데이터 관리 로직
- 검색/필터/정렬이 적용된 데이터 로딩
- 페이지네이션 처리
- 실시간 검색 기능
- 캐시 최적화
#### 2.3 상태 관리
```typescript
// 새로운 상태 추가
const [searchTerm, setSearchTerm] = useState("");
const [selectedSearchColumn, setSelectedSearchColumn] = useState("");
const [sortColumn, setSortColumn] = useState<string | null>(null);
const [sortDirection, setSortDirection] = useState<"asc" | "desc">("asc");
const [currentPage, setCurrentPage] = useState(1);
const [totalPages, setTotalPages] = useState(0);
const [totalItems, setTotalItems] = useState(0);
```
### Phase 3: UI 컴포넌트 구현 🎨
#### 3.1 헤더 영역
```jsx
<div className="card-header">
<h3>{tableConfig.title || tableLabel}</h3>
<div className="search-controls">
{/* 검색바 */}
<Input placeholder="검색..." />
{/* 검색 컬럼 선택기 */}
<select>...</select>
{/* 새로고침 버튼 */}
<Button>↻</Button>
</div>
</div>
```
#### 3.2 카드 그리드 영역
```jsx
<div
className="card-grid"
style={{
display: "grid",
gridTemplateColumns: `repeat(${cardsPerRow}, 1fr)`,
gap: `${cardSpacing}px`,
}}
>
{displayData.map((item, index) => (
<Card key={index}>{/* 카드 내용 렌더링 */}</Card>
))}
</div>
```
#### 3.3 페이지네이션 영역
```jsx
<div className="card-pagination">
<div>
전체 {totalItems}건 중 {startItem}-{endItem} 표시
</div>
<div>
<select>페이지 크기</select>
<Button>◀◀</Button>
<Button>◀</Button>
<span>
{currentPage} / {totalPages}
</span>
<Button>▶</Button>
<Button>▶▶</Button>
</div>
</div>
```
### Phase 4: 설정 패널 확장 ⚙️
#### 4.1 새 탭 추가
- **필터 탭**: 검색 및 필터 설정
- **페이지네이션 탭**: 페이지 관련 설정
- **정렬 탭**: 정렬 기본값 설정
#### 4.2 설정 옵션
```jsx
// 필터 탭
<TabsContent value="filter">
<Checkbox>필터 기능 사용</Checkbox>
<Checkbox>빠른 검색</Checkbox>
<Checkbox>검색 컬럼 선택기 표시</Checkbox>
<Checkbox>고급 필터</Checkbox>
</TabsContent>
// 페이지네이션 탭
<TabsContent value="pagination">
<Checkbox>페이지네이션 사용</Checkbox>
<Input label="페이지 크기" />
<Checkbox>페이지 크기 선택기 표시</Checkbox>
<Checkbox>페이지 정보 표시</Checkbox>
</TabsContent>
```
## 🛠️ 구현 우선순위
### 🟢 High Priority (1-2주)
1. **Entity 조인 기능**: 테이블 리스트의 로직 재사용
2. **기본 검색 기능**: 검색바 및 실시간 검색
3. **페이지네이션**: 카드 개수 제한 및 페이지 이동
### 🟡 Medium Priority (2-3주)
4. **고급 필터**: 컬럼별 필터 옵션
5. **정렬 기능**: 컬럼별 정렬 및 상태 표시
6. **검색 컬럼 선택기**: 특정 컬럼 검색 기능
### 🔵 Low Priority (3-4주)
7. **카드 뷰 옵션**: 그리드/리스트 전환
8. **카드 크기 조절**: 동적 크기 조정
9. **즐겨찾기 필터**: 자주 사용하는 필터 저장
## 📝 기술적 고려사항
### 재사용 가능한 코드
- `useEntityJoinOptimization` 훅
- 필터 및 검색 로직
- 페이지네이션 컴포넌트
- 코드 캐시 시스템
### 성능 최적화
- 가상화 스크롤 (대량 데이터)
- 이미지 지연 로딩
- 메모리 효율적인 렌더링
- 디바운스된 검색
### 일관성 유지
- 테이블 리스트와 동일한 API
- 동일한 설정 구조
- 일관된 스타일링
- 동일한 이벤트 핸들링
## 🗂️ 파일 구조
```
frontend/lib/registry/components/card-display/
├── CardDisplayComponent.tsx # 메인 컴포넌트 (수정)
├── CardDisplayConfigPanel.tsx # 설정 패널 (수정)
├── types.ts # 타입 정의 (수정)
├── index.ts # 기본 설정 (수정)
├── hooks/
│ └── useCardDataManagement.ts # 데이터 관리 훅 (신규)
├── components/
│ ├── CardHeader.tsx # 헤더 컴포넌트 (신규)
│ ├── CardGrid.tsx # 그리드 컴포넌트 (신규)
│ ├── CardPagination.tsx # 페이지네이션 (신규)
│ └── CardFilter.tsx # 필터 컴포넌트 (신규)
└── utils/
└── cardHelpers.ts # 유틸리티 함수 (신규)
```
## ✅ 완료된 단계
### Phase 1: 타입 및 인터페이스 확장 ✅
- ✅ `CardFilterConfig`, `CardPaginationConfig`, `CardSortConfig` 타입 정의
- ✅ `CardColumnConfig` 인터페이스 추가 (Entity 조인 지원)
- ✅ `CardDisplayConfig` 확장 (새로운 기능들 포함)
- ✅ 기본 설정 업데이트 (filter, pagination, sort 기본값)
### Phase 2: Entity 조인 기능 구현 ✅
- ✅ `useEntityJoinOptimization` 훅 적용
- ✅ 컬럼 메타정보 관리 (`columnMeta` 상태)
- ✅ 코드 변환 기능 (`optimizedConvertCode`)
- ✅ Entity 조인을 고려한 데이터 로딩 로직
### Phase 3: 새로운 UI 구조 구현 ✅
- ✅ 헤더 영역 (제목, 검색바, 컬럼 선택기, 새로고침)
- ✅ 카드 그리드 영역 (반응형 그리드, 로딩/오류 상태)
- ✅ 개별 카드 렌더링 (제목, 부제목, 설명, 추가 필드)
- ✅ 푸터/페이지네이션 영역 (페이지 정보, 크기 선택, 네비게이션)
- ✅ 검색 기능 (디바운스, 컬럼 선택)
- ✅ 코드 값 포맷팅 (`formatCellValue`)
### Phase 4: 설정 패널 확장 ✅
- ✅ **탭 기반 UI 구조** - 5개 탭으로 체계적 분류
- ✅ **일반 탭** - 기본 설정, 카드 레이아웃, 스타일 옵션
- ✅ **매핑 탭** - 컬럼 매핑, 동적 표시 컬럼 관리
- ✅ **필터 탭** - 검색 및 필터 설정 옵션
- ✅ **페이징 탭** - 페이지 관련 설정 및 크기 옵션
- ✅ **정렬 탭** - 정렬 기본값 설정
- ✅ **Shadcn/ui 컴포넌트 적용** - 일관된 UI/UX
## 🎉 프로젝트 완료!
### 📊 최종 달성 결과
**🚀 100% 완료** - 모든 계획된 기능이 성공적으로 구현되었습니다!
#### ✅ 구현된 주요 기능들
1. **완전한 데이터 관리**: 테이블 리스트와 동일한 수준의 데이터 로딩, 검색, 필터링, 페이지네이션
2. **Entity 조인 지원**: 관계형 데이터 조인 및 코드 변환 자동화
3. **고급 검색**: 실시간 검색, 컬럼별 검색, 자동 컬럼 선택
4. **완전한 설정 UI**: 5개 탭으로 분류된 직관적인 설정 패널
5. **반응형 카드 그리드**: 설정 가능한 레이아웃과 스타일
#### 🎯 성능 및 사용성
- **성능 최적화**: 디바운스 검색, 배치 코드 로딩, 캐시 활용
- **사용자 경험**: 로딩 상태, 오류 처리, 직관적인 UI
- **일관성**: 테이블 리스트와 완전히 동일한 API 및 기능
#### 📁 완성된 파일 구조
```
frontend/lib/registry/components/card-display/
├── CardDisplayComponent.tsx ✅ 완전 재구현 (Entity 조인, 검색, 페이징)
├── CardDisplayConfigPanel.tsx ✅ 5개 탭 기반 설정 패널
├── types.ts ✅ 확장된 타입 시스템
└── index.ts ✅ 업데이트된 기본 설정
```
---
**🏆 최종 상태**: **완료** (100%)
**🎯 목표 달성**: 테이블 리스트와 동일한 수준의 강력한 카드 컴포넌트 완성
**⚡ 개발 기간**: 계획 대비 빠른 완료 (예상 3-4주 → 실제 1일)
**✨ 품질**: 테이블 리스트 대비 동등하거나 우수한 기능 수준
### 🔥 주요 성과
이제 사용자들은 **테이블 리스트**와 **카드 디스플레이** 중에서 자유롭게 선택하여 동일한 데이터를 서로 다른 형태로 시각화할 수 있습니다. 두 컴포넌트 모두 완전히 동일한 고급 기능을 제공합니다!

304
DEPLOYMENT_GUIDE_KPSLP.md Normal file
View File

@ -0,0 +1,304 @@
# vexplor 프로젝트 NCP Kubernetes 배포 가이드
## 배포 환경
- **Kubernetes 클러스터**: NCP Kubernetes
- **네임스페이스**: apps
- **GitOps 도구**: Argo CD (https://argocd.kpslp.kr)
- **CI/CD**: Jenkins (Kaniko 빌드)
- **컨테이너 레지스트리**: registry.kpslp.kr
## 전제 조건
### 1. GitLab 레포지토리
- [x] 프로젝트 코드 레포: 이미 생성됨 (현재 레포)
- [ ] Helm Charts 레포: `https://gitlab.kpslp.kr/root/helm-charts` 접근 권한 필요
### 2. 필요한 권한
- [ ] GitLab 계정 및 레포지토리 접근 권한
- [ ] Jenkins 프로젝트 생성 권한 또는 담당자 요청
- [ ] Argo CD 접속 계정
- [ ] Container Registry 푸시 권한
---
## 배포 단계
### Step 1: Helm Charts 레포지토리 설정
김욱동 책임님께 다음 사항을 요청하세요:
```
안녕하세요.
vexplor 프로젝트 배포를 위해 다음 작업이 필요합니다:
1. helm-charts 레포지토리 접근 권한 부여
- 레포지토리: https://gitlab.kpslp.kr/root/helm-charts
- 현재 404 오류로 접근 불가
- 계정: [본인 GitLab 사용자명]
2. values 파일 업로드
- 첨부된 values_vexplor.yaml 파일을
- kpslp/values_vexplor.yaml 경로에 업로드해주시거나
- 업로드 방법을 안내해주세요
3. Jenkins 프로젝트 생성
- 프로젝트명: vexplor
- Git 레포지토리: [현재 프로젝트 GitLab URL]
- Jenkinsfile: 프로젝트 루트에 이미 준비됨
감사합니다.
```
**첨부 파일**: `values_vexplor.yaml` (프로젝트 루트에 생성됨)
---
### Step 2: Jenkins 프로젝트 등록
Jenkins에서 새 파이프라인 프로젝트를 생성합니다:
1. **Jenkins 접속** (URL은 담당자에게 문의)
2. **New Item** 클릭
3. **프로젝트명**: `vexplor`
4. **Pipeline** 선택
5. **Pipeline 설정**:
- Definition: `Pipeline script from SCM`
- SCM: `Git`
- Repository URL: `[현재 프로젝트 GitLab URL]`
- Credentials: `gitlab_userpass_root` (또는 담당자가 안내한 credential)
- Branch: `*/main`
- Script Path: `Jenkinsfile`
---
### Step 3: Argo CD 애플리케이션 등록
1. **Argo CD 접속**: https://argocd.kpslp.kr
2. **New App 생성**:
- **Application Name**: `vexplor`
- **Project**: `default`
- **Sync Policy**: `Automatic` (자동 배포) 또는 `Manual` (수동 배포)
- **Auto-Create Namespace**: ✓ (체크)
3. **Source 설정**:
- **Repository URL**: `https://gitlab.kpslp.kr/root/helm-charts`
- **Revision**: `HEAD` 또는 `main`
- **Path**: `kpslp`
- **Helm Values**: `values_vexplor.yaml`
4. **Destination 설정**:
- **Cluster URL**: `https://kubernetes.default.svc` (기본값)
- **Namespace**: `apps`
5. **Create** 클릭
---
### Step 4: 첫 배포 실행
#### 4-1. Git Push로 Jenkins 빌드 트리거
```bash
git add .
git commit -m "feat: NCP Kubernetes 배포 설정 완료"
git push origin main
```
#### 4-2. Jenkins 빌드 모니터링
1. Jenkins에서 `vexplor` 프로젝트 열기
2. 빌드 시작 확인 (자동 트리거 또는 수동 빌드)
3. 로그 확인:
- **Checkout**: Git 소스 다운로드
- **Build**: Docker 이미지 빌드 (`registry.kpslp.kr/slp/vexplor:xxxxx`)
- **Update Image Tag**: helm-charts 레포의 values 파일 업데이트
#### 4-3. Argo CD 배포 확인
1. Argo CD 대시보드에서 `vexplor` 앱 열기
2. **Sync Status**: `OutOfSync` → `Synced` 변경 확인
3. **Health Status**: `Progressing` → `Healthy` 변경 확인
4. Pod 상태 확인 (Running 상태여야 함)
---
## 배포 후 확인사항
### 1. Pod 상태 확인
```bash
kubectl get pods -n apps | grep vexplor
```
**예상 출력**:
```
vexplor-xxxxxxxxxx-xxxxx 1/1 Running 0 2m
```
### 2. 서비스 확인
```bash
kubectl get svc -n apps | grep vexplor
```
### 3. Ingress 확인
```bash
kubectl get ingress -n apps | grep vexplor
```
### 4. 로그 확인
```bash
# 전체 로그
kubectl logs -n apps -l app=vexplor
# 최근 50줄
kubectl logs -n apps -l app=vexplor --tail=50
# 실시간 로그 (스트리밍)
kubectl logs -n apps -l app=vexplor -f
```
### 5. 애플리케이션 접속
- **URL**: `https://vexplor.kpslp.kr` (values 파일에 설정한 도메인)
- **헬스체크**: `https://vexplor.kpslp.kr/api/health`
---
## 트러블슈팅
### 문제 1: Jenkins 빌드 실패
**증상**: Build 단계에서 에러 발생
**확인사항**:
- Docker 이미지 빌드 로그 확인
- `Dockerfile`이 프로젝트 루트에 있는지 확인
- 빌드 컨텍스트에 필요한 파일들이 있는지 확인
**해결**:
```bash
# 로컬에서 Docker 빌드 테스트
docker build -f Dockerfile -t vexplor:test .
```
### 문제 2: helm-charts 레포 푸시 실패
**증상**: Update Image Tag 단계에서 실패
**원인**: `gitlab_userpass_root` credential 문제 또는 권한 부족
**해결**: 김욱동 책임님께 credential 확인 요청
### 문제 3: Argo CD Sync 실패
**증상**: `OutOfSync` 상태에서 변경 없음
**확인사항**:
- values 파일이 올바른 경로에 있는지 (`kpslp/values_vexplor.yaml`)
- Argo CD가 helm-charts 레포를 읽을 수 있는지
**해결**: Argo CD에서 수동 Sync 시도 또는 담당자에게 문의
### 문제 4: Pod가 CrashLoopBackOff 상태
**증상**: Pod가 계속 재시작됨
**확인**:
```bash
kubectl describe pod -n apps [pod-name]
kubectl logs -n apps [pod-name] --previous
```
**일반적인 원인**:
- 환경 변수 누락 (DATABASE_HOST 등)
- 데이터베이스 연결 실패
- 포트 바인딩 문제
**해결**:
1. `values_vexplor.yaml`의 `env` 섹션 확인
2. 데이터베이스 서비스명 확인 (`postgres-service.apps.svc.cluster.local`)
3. Secret 설정 확인 (DB 비밀번호 등)
---
## 업데이트 배포 프로세스
코드 수정 후 배포 절차:
```bash
# 1. 코드 수정
git add .
git commit -m "feat: 새로운 기능 추가"
git push origin main
# 2. Jenkins 자동 빌드 (자동 트리거)
# - Git push 감지
# - Docker 이미지 빌드
# - 새 이미지 태그로 values 파일 업데이트
# 3. Argo CD 자동 배포 (Sync Policy가 Automatic인 경우)
# - helm-charts 레포 변경 감지
# - Kubernetes에 새 이미지 배포
# - Rolling Update 수행
```
**수동 배포**: Argo CD 대시보드에서 `Sync` 버튼 클릭
---
## 체크리스트
배포 전 확인사항:
- [ ] Jenkinsfile 수정 완료 (단일 이미지 빌드)
- [ ] Dockerfile 확인 (멀티스테이지 빌드)
- [ ] values_vexplor.yaml 작성 및 업로드
- [ ] Jenkins 프로젝트 생성
- [ ] Argo CD 애플리케이션 등록
- [ ] 환경 변수 설정 (DATABASE_HOST 등)
- [ ] Secret 생성 (DB 비밀번호 등)
- [ ] Ingress 도메인 설정
- [ ] 헬스체크 엔드포인트 확인 (`/api/health`)
---
## 참고 자료
- **Kaniko**: 컨테이너 내에서 Docker 이미지를 빌드하는 도구
- **GitOps**: Git을 Single Source of Truth로 사용하는 배포 방식
- **Argo CD**: GitOps를 위한 Kubernetes CD 도구
- **Helm**: Kubernetes 패키지 매니저
---
## 담당자 연락처
- **NCP 클러스터 관리**: 김욱동 책임 (엘에스티라유텍)
- **Bastion 서버**: 223.130.135.25:22 (Docker 직접 배포용 아님)
- **Argo CD**: https://argocd.kpslp.kr
- **Kubernetes 네임스페이스**: apps
---
## 추가 설정 (선택사항)
### PostgreSQL 데이터베이스 설정
클러스터 내부에 PostgreSQL이 없다면:
```yaml
# values_vexplor.yaml 에 추가
postgresql:
enabled: true
auth:
username: vexplor
password: changeme123 # Secret으로 관리 권장
database: vexplor
primary:
persistence:
enabled: true
size: 10Gi
```
### Secret 생성 (민감 정보)
```bash
kubectl create secret generic vexplor-secrets \
--from-literal=db-password='your-secure-password' \
--from-literal=jwt-secret='your-jwt-secret' \
-n apps
```
### 모니터링 (Prometheus + Grafana)
담당자에게 메트릭 수집 설정 요청

106
Dockerfile Normal file
View File

@ -0,0 +1,106 @@
# ==========================
# 멀티 스테이지 Dockerfile
# - 백엔드: Node.js + Express + TypeScript
# - 프론트엔드: Next.js (프로덕션 빌드)
# ==========================
# ------------------------------
# Stage 1: 백엔드 빌드
# ------------------------------
FROM node:20.10-alpine AS backend-builder
WORKDIR /app/backend
# 백엔드 의존성 설치
COPY backend-node/package*.json ./
RUN npm ci --only=production && \
npm cache clean --force
# 백엔드 소스 복사 및 빌드
COPY backend-node/tsconfig.json ./
COPY backend-node/src ./src
RUN npm install -D typescript @types/node && \
npm run build && \
npm prune --production
# ------------------------------
# Stage 2: 프론트엔드 빌드
# ------------------------------
FROM node:20.10-alpine AS frontend-builder
WORKDIR /app/frontend
# 프론트엔드 의존성 설치
COPY frontend/package*.json ./
RUN npm ci && \
npm cache clean --force
# 프론트엔드 소스 복사
COPY frontend/ ./
# Next.js 프로덕션 빌드 (린트 비활성화)
ENV NEXT_TELEMETRY_DISABLED=1
ENV NODE_ENV=production
RUN npm run build:no-lint
# ------------------------------
# Stage 3: 최종 런타임 이미지
# ------------------------------
FROM node:20.10-alpine AS runtime
# 보안 강화: 비특권 사용자 생성
RUN addgroup -g 1001 -S nodejs && \
adduser -S nodejs -u 1001
WORKDIR /app
# 백엔드 런타임 파일 복사
COPY --from=backend-builder --chown=nodejs:nodejs /app/backend/dist ./backend/dist
COPY --from=backend-builder --chown=nodejs:nodejs /app/backend/node_modules ./backend/node_modules
COPY --from=backend-builder --chown=nodejs:nodejs /app/backend/package.json ./backend/package.json
# 프론트엔드 런타임 파일 복사
COPY --from=frontend-builder --chown=nodejs:nodejs /app/frontend/.next ./frontend/.next
COPY --from=frontend-builder --chown=nodejs:nodejs /app/frontend/node_modules ./frontend/node_modules
COPY --from=frontend-builder --chown=nodejs:nodejs /app/frontend/package.json ./frontend/package.json
COPY --from=frontend-builder --chown=nodejs:nodejs /app/frontend/public ./frontend/public
COPY --from=frontend-builder --chown=nodejs:nodejs /app/frontend/next.config.mjs ./frontend/next.config.mjs
# 업로드 디렉토리 생성 (백엔드용)
RUN mkdir -p /app/backend/uploads && \
chown -R nodejs:nodejs /app/backend/uploads
# 시작 스크립트 생성
RUN echo '#!/bin/sh' > /app/start.sh && \
echo 'set -e' >> /app/start.sh && \
echo '' >> /app/start.sh && \
echo '# 백엔드 시작 (백그라운드)' >> /app/start.sh && \
echo 'cd /app/backend' >> /app/start.sh && \
echo 'echo "Starting backend on port 8080..."' >> /app/start.sh && \
echo 'node dist/app.js &' >> /app/start.sh && \
echo 'BACKEND_PID=$!' >> /app/start.sh && \
echo '' >> /app/start.sh && \
echo '# 프론트엔드 시작 (포그라운드)' >> /app/start.sh && \
echo 'cd /app/frontend' >> /app/start.sh && \
echo 'echo "Starting frontend on port 3000..."' >> /app/start.sh && \
echo 'npm start &' >> /app/start.sh && \
echo 'FRONTEND_PID=$!' >> /app/start.sh && \
echo '' >> /app/start.sh && \
echo '# 프로세스 모니터링' >> /app/start.sh && \
echo 'wait $BACKEND_PID $FRONTEND_PID' >> /app/start.sh && \
chmod +x /app/start.sh && \
chown nodejs:nodejs /app/start.sh
# 비특권 사용자로 전환
USER nodejs
# 포트 노출
EXPOSE 3000 8080
# 헬스체크
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
CMD wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1
# 컨테이너 시작
CMD ["/app/start.sh"]

399
EXTERNAL_REST_API_IMPLEMENTATION_COMPLETE.md
View File

@ -1,399 +0,0 @@
# 외부 커넥션 관리 REST API 지원 구현 완료 보고서
## 📋 구현 개요
`/admin/external-connections` 페이지에 REST API 연결 관리 기능을 성공적으로 추가했습니다.
이제 외부 데이터베이스 연결과 REST API 연결을 탭을 통해 통합 관리할 수 있습니다.
---
## ✅ 구현 완료 사항
### 1. 데이터베이스 구조
**파일**: `/Users/dohyeonsu/Documents/ERP-node/db/create_external_rest_api_connections.sql`
- ✅ `external_rest_api_connections` 테이블 생성
- ✅ 인증 타입 (none, api-key, bearer, basic, oauth2) 지원
- ✅ 헤더 정보 JSONB 저장
- ✅ 테스트 결과 저장 (last_test_date, last_test_result, last_test_message)
- ✅ 샘플 데이터 포함 (기상청 API, JSONPlaceholder)
### 2. 백엔드 구현
#### 타입 정의
**파일**: `backend-node/src/types/externalRestApiTypes.ts`
- ✅ ExternalRestApiConnection 인터페이스
- ✅ ExternalRestApiConnectionFilter 인터페이스
- ✅ RestApiTestRequest 인터페이스
- ✅ RestApiTestResult 인터페이스
- ✅ AuthType 타입 정의
#### 서비스 계층
**파일**: `backend-node/src/services/externalRestApiConnectionService.ts`
- ✅ CRUD 메서드 (getConnections, getConnectionById, createConnection, updateConnection, deleteConnection)
- ✅ 연결 테스트 메서드 (testConnection, testConnectionById)
- ✅ 민감 정보 암호화/복호화 (AES-256-GCM)
- ✅ 유효성 검증
- ✅ 인증 타입별 헤더 구성
#### API 라우트
**파일**: `backend-node/src/routes/externalRestApiConnectionRoutes.ts`
- ✅ GET `/api/external-rest-api-connections` - 목록 조회
- ✅ GET `/api/external-rest-api-connections/:id` - 상세 조회
- ✅ POST `/api/external-rest-api-connections` - 연결 생성
- ✅ PUT `/api/external-rest-api-connections/:id` - 연결 수정
- ✅ DELETE `/api/external-rest-api-connections/:id` - 연결 삭제
- ✅ POST `/api/external-rest-api-connections/test` - 연결 테스트 (데이터 기반)
- ✅ POST `/api/external-rest-api-connections/:id/test` - 연결 테스트 (ID 기반)
#### 라우트 등록
**파일**: `backend-node/src/app.ts`
- ✅ externalRestApiConnectionRoutes import
- ✅ `/api/external-rest-api-connections` 경로 등록
### 3. 프론트엔드 구현
#### API 클라이언트
**파일**: `frontend/lib/api/externalRestApiConnection.ts`
- ✅ ExternalRestApiConnectionAPI 클래스
- ✅ CRUD 메서드
- ✅ 연결 테스트 메서드
- ✅ 지원되는 인증 타입 조회
#### 헤더 관리 컴포넌트
**파일**: `frontend/components/admin/HeadersManager.tsx`
- ✅ 동적 키-값 추가/삭제
- ✅ 테이블 형식 UI
- ✅ 실시간 업데이트
#### 인증 설정 컴포넌트
**파일**: `frontend/components/admin/AuthenticationConfig.tsx`
- ✅ 인증 타입 선택
- ✅ API Key 설정 (header/query 선택)
- ✅ Bearer Token 설정
- ✅ Basic Auth 설정
- ✅ OAuth 2.0 설정
- ✅ 타입별 동적 UI 표시
#### REST API 연결 모달
**파일**: `frontend/components/admin/RestApiConnectionModal.tsx`
- ✅ 기본 정보 입력 (연결명, 설명, URL)
- ✅ 헤더 관리 통합
- ✅ 인증 설정 통합
- ✅ 고급 설정 (타임아웃, 재시도)
- ✅ 연결 테스트 기능
- ✅ 테스트 결과 표시
- ✅ 유효성 검증
#### REST API 연결 목록 컴포넌트
**파일**: `frontend/components/admin/RestApiConnectionList.tsx`
- ✅ 연결 목록 테이블
- ✅ 검색 기능 (연결명, URL)
- ✅ 필터링 (인증 타입, 활성 상태)
- ✅ 연결 테스트 버튼 및 결과 표시
- ✅ 편집/삭제 기능
- ✅ 마지막 테스트 정보 표시
#### 메인 페이지 탭 구조
**파일**: `frontend/app/(main)/admin/external-connections/page.tsx`
- ✅ 탭 UI 추가 (Database / REST API)
- ✅ 데이터베이스 연결 탭 (기존 기능)
- ✅ REST API 연결 탭 (신규 기능)
- ✅ 탭 전환 상태 관리
---
## 🎯 주요 기능
### 1. 탭 전환
- 데이터베이스 연결 관리 ↔ REST API 연결 관리 간 탭으로 전환
- 각 탭은 독립적으로 동작
### 2. REST API 연결 관리
- **연결명**: 고유한 이름으로 연결 식별
- **기본 URL**: API의 베이스 URL
- **헤더 설정**: 키-값 쌍으로 HTTP 헤더 관리
- **인증 설정**: 5가지 인증 타입 지원
- 인증 없음 (none)
- API Key (header 또는 query parameter)
- Bearer Token
- Basic Auth
- OAuth 2.0
### 3. 연결 테스트
- 저장 전 연결 테스트 가능
- 테스트 엔드포인트 지정 가능 (선택)
- 응답 시간, 상태 코드 표시
- 테스트 결과 데이터베이스 저장
### 4. 보안
- 민감 정보 암호화 (API 키, 토큰, 비밀번호)
- AES-256-GCM 알고리즘 사용
- 환경 변수로 암호화 키 관리
---
## 📁 생성된 파일 목록
### 데이터베이스
- `db/create_external_rest_api_connections.sql`
### 백엔드
- `backend-node/src/types/externalRestApiTypes.ts`
- `backend-node/src/services/externalRestApiConnectionService.ts`
- `backend-node/src/routes/externalRestApiConnectionRoutes.ts`
### 프론트엔드
- `frontend/lib/api/externalRestApiConnection.ts`
- `frontend/components/admin/HeadersManager.tsx`
- `frontend/components/admin/AuthenticationConfig.tsx`
- `frontend/components/admin/RestApiConnectionModal.tsx`
- `frontend/components/admin/RestApiConnectionList.tsx`
### 수정된 파일
- `backend-node/src/app.ts` (라우트 등록)
- `frontend/app/(main)/admin/external-connections/page.tsx` (탭 구조)
---
## 🚀 사용 방법
### 1. 데이터베이스 테이블 생성
SQL 스크립트를 실행하세요:
```bash
psql -U postgres -d your_database -f db/create_external_rest_api_connections.sql
```
### 2. 백엔드 재시작
암호화 키 환경 변수 설정 (선택):
```bash
export DB_PASSWORD_SECRET="your-secret-key-32-characters-long"
```
백엔드 재시작:
```bash
cd backend-node
npm run dev
```
### 3. 프론트엔드 접속
브라우저에서 다음 URL로 접속:
```
http://localhost:3000/admin/external-connections
```
### 4. REST API 연결 추가
1. "REST API 연결" 탭 클릭
2. "새 연결 추가" 버튼 클릭
3. 연결 정보 입력:
- 연결명 (필수)
- 기본 URL (필수)
- 헤더 설정
- 인증 설정
4. 연결 테스트 (선택)
5. 저장
---
## 🧪 테스트 시나리오
### 테스트 1: 인증 없는 공개 API
```
연결명: JSONPlaceholder
기본 URL: https://jsonplaceholder.typicode.com
인증 타입: 인증 없음
테스트 엔드포인트: /posts/1
```
### 테스트 2: API Key (Query Parameter)
```
연결명: 기상청 API
기본 URL: https://apis.data.go.kr/1360000/VilageFcstInfoService_2.0
인증 타입: API Key
키 위치: Query Parameter
키 이름: serviceKey
키 값: [your-api-key]
테스트 엔드포인트: /getUltraSrtNcst
```
### 테스트 3: Bearer Token
```
연결명: GitHub API
기본 URL: https://api.github.com
인증 타입: Bearer Token
토큰: ghp_your_token_here
헤더:
- Accept: application/vnd.github.v3+json
- User-Agent: YourApp
테스트 엔드포인트: /user
```
---
## 🔧 고급 설정
### 타임아웃 설정
- 기본값: 30000ms (30초)
- 범위: 1000ms ~ 120000ms
### 재시도 설정
- 재시도 횟수: 0~5회
- 재시도 간격: 100ms ~ 10000ms
### 헤더 관리
- 동적 추가/삭제
- 일반적인 헤더:
- `Content-Type: application/json`
- `Accept: application/json`
- `User-Agent: YourApp/1.0`
---
## 🔒 보안 고려사항
### 암호화
- API 키, 토큰, 비밀번호는 자동 암호화
- AES-256-GCM 알고리즘 사용
- 환경 변수 `DB_PASSWORD_SECRET`로 키 관리
### 권한
- 관리자 권한만 접근 가능
- 회사별 데이터 분리 (`company_code`)
### 테스트 제한
- 동시 테스트 실행 제한
- 타임아웃 강제 적용
---
## 📊 데이터베이스 스키마
```sql
external_rest_api_connections
├── id (SERIAL PRIMARY KEY)
├── connection_name (VARCHAR(100) UNIQUE) -- 연결명
├── description (TEXT) -- 설명
├── base_url (VARCHAR(500)) -- 기본 URL
├── default_headers (JSONB) -- 헤더 (키-값)
├── auth_type (VARCHAR(20)) -- 인증 타입
├── auth_config (JSONB) -- 인증 설정
├── timeout (INTEGER) -- 타임아웃
├── retry_count (INTEGER) -- 재시도 횟수
├── retry_delay (INTEGER) -- 재시도 간격
├── company_code (VARCHAR(20)) -- 회사 코드
├── is_active (CHAR(1)) -- 활성 상태
├── created_date (TIMESTAMP) -- 생성일
├── created_by (VARCHAR(50)) -- 생성자
├── updated_date (TIMESTAMP) -- 수정일
├── updated_by (VARCHAR(50)) -- 수정자
├── last_test_date (TIMESTAMP) -- 마지막 테스트 일시
├── last_test_result (CHAR(1)) -- 마지막 테스트 결과
└── last_test_message (TEXT) -- 마지막 테스트 메시지
```
---
## 🎉 완료 요약
### 구현 완료
- ✅ 데이터베이스 테이블 생성
- ✅ 백엔드 API (CRUD + 테스트)
- ✅ 프론트엔드 UI (탭 + 모달 + 목록)
- ✅ 헤더 관리 기능
- ✅ 5가지 인증 타입 지원
- ✅ 연결 테스트 기능
- ✅ 민감 정보 암호화
### 테스트 완료
- ✅ API 엔드포인트 테스트
- ✅ UI 컴포넌트 통합
- ✅ 탭 전환 기능
- ✅ CRUD 작업
- ✅ 연결 테스트
### 문서 완료
- ✅ 계획서 (PHASE_EXTERNAL_CONNECTION_REST_API_ENHANCEMENT.md)
- ✅ 완료 보고서 (본 문서)
- ✅ SQL 스크립트 (주석 포함)
---
## 🚀 다음 단계 (선택 사항)
### 향후 확장 가능성
1. **엔드포인트 프리셋 관리**
- 자주 사용하는 엔드포인트 저장
- 빠른 호출 지원
2. **요청 템플릿**
- HTTP 메서드별 요청 바디 템플릿
- 변수 치환 기능
3. **응답 매핑**
- API 응답을 내부 데이터 구조로 변환
- 매핑 룰 설정
4. **로그 및 모니터링**
- API 호출 이력 기록
- 응답 시간 모니터링
- 오류율 추적
---
**구현 완료일**: 2025-10-21
**버전**: 1.0
**개발자**: AI Assistant
**상태**: 완료 ✅

56
Jenkinsfile vendored Normal file
View File

@ -0,0 +1,56 @@
pipeline {
agent {
label "kaniko"
}
stages {
stage("Checkout") {
steps {
checkout scm
script {
env.GIT_COMMIT_SHORT = sh(script: 'git rev-parse --short HEAD', returnStdout: true).trim()
env.GIT_AUTHOR_NAME = sh(script: "git log -1 --pretty=format:'%an'", returnStdout: true)
env.GIT_AUTHOR_EMAIL = sh(script: "git log -1 --pretty=format:'%ae'", returnStdout: true)
env.GIT_COMMIT_MESSAGE = sh (script: 'git log -1 --pretty=%B ${GIT_COMMIT}', returnStdout: true).trim()
env.GIT_PROJECT_NAME = GIT_URL.replaceAll('.git$', '').tokenize('/')[-2]
env.GIT_REPO_NAME = GIT_URL.replaceAll('.git$', '').tokenize('/')[-1]
}
}
}
stage("Build") {
steps {
container("kaniko") {
script {
sh "/kaniko/executor --context . --destination registry.kpslp.kr/${GIT_PROJECT_NAME}/${GIT_REPO_NAME}:${GIT_COMMIT_SHORT}"
}
}
}
}
stage("Update Image Tag") {
steps {
deleteDir()
checkout([
$class: 'GitSCM',
branches: [[name: '*/main']],
extensions: [],
userRemoteConfigs: [[credentialsId: 'gitlab_userpass_root', url: "https://gitlab.kpslp.kr/root/helm-charts"]]
])
script {
def valuesYaml = "kpslp/values_${GIT_REPO_NAME}.yaml"
def values = readYaml file: "${valuesYaml}"
values.image.tag = env.GIT_COMMIT_SHORT
writeYaml file: "${valuesYaml}", data: values, overwrite: true
sh "git config user.name '${GIT_AUTHOR_NAME}'"
sh "git config user.email '${GIT_AUTHOR_EMAIL}'"
withCredentials([usernameColonPassword(credentialsId: 'gitlab_userpass_root', variable: 'USERPASS')]) {
sh '''
git add . && \
git commit -m "${GIT_REPO_NAME}: ${GIT_COMMIT_MESSAGE}" && \
git push https://${USERPASS}@gitlab.kpslp.kr/root/helm-charts HEAD:main || true
'''
}
}
}
}
}
}

733
PHASE1.5_AUTH_MIGRATION_PLAN.md
View File

@ -1,733 +0,0 @@
# 🔐 Phase 1.5: 인증 및 관리자 서비스 Raw Query 전환 계획
## 📋 개요
Phase 2의 핵심 서비스 전환 전에 **인증 및 관리자 시스템**을 먼저 Raw Query로 전환하여 전체 시스템의 안정적인 기반을 구축합니다.
### 🎯 목표
- AuthService의 5개 Prisma 호출 제거
- AdminService의 3개 Prisma 호출 제거 (이미 Raw Query 사용 중)
- AdminController의 28개 Prisma 호출 제거
- 로그인 → 인증 → API 호출 전체 플로우 검증
### 📊 전환 대상
| 서비스 | Prisma 호출 수 | 복잡도 | 우선순위 |
|--------|----------------|--------|----------|
| AuthService | 5개 | 중간 | 🔴 최우선 |
| AdminService | 3개 | 낮음 (이미 Raw Query) | 🟢 확인만 필요 |
| AdminController | 28개 | 중간 | 🟡 2순위 |
---
## 🔍 AuthService 분석
### Prisma 사용 현황 (5개)
```typescript
// Line 21: loginPwdCheck() - 사용자 비밀번호 조회
const userInfo = await prisma.user_info.findUnique({
where: { user_id: userId },
select: { user_password: true },
});
// Line 82: insertLoginAccessLog() - 로그인 로그 기록
await prisma.$executeRaw`INSERT INTO LOGIN_ACCESS_LOG(...)`;
// Line 126: getUserInfo() - 사용자 정보 조회
const userInfo = await prisma.user_info.findUnique({
where: { user_id: userId },
select: { /* 20개 필드 */ },
});
// Line 157: getUserInfo() - 권한 정보 조회
const authInfo = await prisma.authority_sub_user.findMany({
where: { user_id: userId },
include: { authority_master: { select: { auth_name: true } } },
});
// Line 177: getUserInfo() - 회사 정보 조회
const companyInfo = await prisma.company_mng.findFirst({
where: { company_code: userInfo.company_code || "ILSHIN" },
select: { company_name: true },
});
```
### 핵심 메서드
1. **loginPwdCheck()** - 로그인 비밀번호 검증
- user_info 테이블 조회
- 비밀번호 암호화 비교
- 마스터 패스워드 체크
2. **insertLoginAccessLog()** - 로그인 이력 기록
- LOGIN_ACCESS_LOG 테이블 INSERT
- Raw Query 이미 사용 중 (유지)
3. **getUserInfo()** - 사용자 상세 정보 조회
- user_info 테이블 조회 (20개 필드)
- authority_sub_user + authority_master 조인 (권한)
- company_mng 테이블 조회 (회사명)
- PersonBean 타입 변환
4. **processLogin()** - 로그인 전체 프로세스
- 위 3개 메서드 조합
- JWT 토큰 생성
---
## 🛠️ 전환 계획
### Step 1: loginPwdCheck() 전환
**기존 Prisma 코드:**
```typescript
const userInfo = await prisma.user_info.findUnique({
where: { user_id: userId },
select: { user_password: true },
});
```
**새로운 Raw Query 코드:**
```typescript
import { query } from "../database/db";
const result = await query<{ user_password: string }>(
"SELECT user_password FROM user_info WHERE user_id = $1",
[userId]
);
const userInfo = result.length > 0 ? result[0] : null;
```
### Step 2: getUserInfo() 전환 (사용자 정보)
**기존 Prisma 코드:**
```typescript
const userInfo = await prisma.user_info.findUnique({
where: { user_id: userId },
select: {
sabun: true,
user_id: true,
user_name: true,
// ... 20개 필드
},
});
```
**새로운 Raw Query 코드:**
```typescript
const result = await query<{
sabun: string | null;
user_id: string;
user_name: string;
user_name_eng: string | null;
user_name_cn: string | null;
dept_code: string | null;
dept_name: string | null;
position_code: string | null;
position_name: string | null;
email: string | null;
tel: string | null;
cell_phone: string | null;
user_type: string | null;
user_type_name: string | null;
partner_objid: string | null;
company_code: string | null;
locale: string | null;
photo: Buffer | null;
}>(
`SELECT
sabun, user_id, user_name, user_name_eng, user_name_cn,
dept_code, dept_name, position_code, position_name,
email, tel, cell_phone, user_type, user_type_name,
partner_objid, company_code, locale, photo
FROM user_info
WHERE user_id = $1`,
[userId]
);
const userInfo = result.length > 0 ? result[0] : null;
```
### Step 3: getUserInfo() 전환 (권한 정보)
**기존 Prisma 코드:**
```typescript
const authInfo = await prisma.authority_sub_user.findMany({
where: { user_id: userId },
include: {
authority_master: {
select: { auth_name: true },
},
},
});
const authNames = authInfo
.filter((auth: any) => auth.authority_master?.auth_name)
.map((auth: any) => auth.authority_master!.auth_name!)
.join(",");
```
**새로운 Raw Query 코드:**
```typescript
const authResult = await query<{ auth_name: string }>(
`SELECT am.auth_name
FROM authority_sub_user asu
INNER JOIN authority_master am ON asu.auth_code = am.auth_code
WHERE asu.user_id = $1`,
[userId]
);
const authNames = authResult.map(row => row.auth_name).join(",");
```
### Step 4: getUserInfo() 전환 (회사 정보)
**기존 Prisma 코드:**
```typescript
const companyInfo = await prisma.company_mng.findFirst({
where: { company_code: userInfo.company_code || "ILSHIN" },
select: { company_name: true },
});
```
**새로운 Raw Query 코드:**
```typescript
const companyResult = await query<{ company_name: string }>(
"SELECT company_name FROM company_mng WHERE company_code = $1",
[userInfo.company_code || "ILSHIN"]
);
const companyInfo = companyResult.length > 0 ? companyResult[0] : null;
```
---
## 📝 완전 전환된 AuthService 코드
```typescript
import { query } from "../database/db";
import { JwtUtils } from "../utils/jwtUtils";
import { EncryptUtil } from "../utils/encryptUtil";
import { PersonBean, LoginResult, LoginLogData } from "../types/auth";
import { logger } from "../utils/logger";
export class AuthService {
/**
* 로그인 비밀번호 검증 (Raw Query 전환)
*/
static async loginPwdCheck(
userId: string,
password: string
): Promise<LoginResult> {
try {
// Raw Query로 사용자 비밀번호 조회
const result = await query<{ user_password: string }>(
"SELECT user_password FROM user_info WHERE user_id = $1",
[userId]
);
const userInfo = result.length > 0 ? result[0] : null;
if (userInfo && userInfo.user_password) {
const dbPassword = userInfo.user_password;
logger.info(`로그인 시도: ${userId}`);
logger.debug(`DB 비밀번호: ${dbPassword}, 입력 비밀번호: ${password}`);
// 마스터 패스워드 체크
if (password === "qlalfqjsgh11") {
logger.info(`마스터 패스워드로 로그인 성공: ${userId}`);
return { loginResult: true };
}
// 비밀번호 검증
if (EncryptUtil.matches(password, dbPassword)) {
logger.info(`비밀번호 일치로 로그인 성공: ${userId}`);
return { loginResult: true };
} else {
logger.warn(`비밀번호 불일치로 로그인 실패: ${userId}`);
return {
loginResult: false,
errorReason: "패스워드가 일치하지 않습니다.",
};
}
} else {
logger.warn(`사용자가 존재하지 않음: ${userId}`);
return {
loginResult: false,
errorReason: "사용자가 존재하지 않습니다.",
};
}
} catch (error) {
logger.error(
`로그인 검증 중 오류 발생: ${error instanceof Error ? error.message : error}`
);
return {
loginResult: false,
errorReason: "로그인 처리 중 오류가 발생했습니다.",
};
}
}
/**
* 로그인 로그 기록 (이미 Raw Query 사용 - 유지)
*/
static async insertLoginAccessLog(logData: LoginLogData): Promise<void> {
try {
await query(
`INSERT INTO LOGIN_ACCESS_LOG(
LOG_TIME, SYSTEM_NAME, USER_ID, LOGIN_RESULT, ERROR_MESSAGE,
REMOTE_ADDR, RECPTN_DT, RECPTN_RSLT_DTL, RECPTN_RSLT, RECPTN_RSLT_CD
) VALUES (
now(), $1, UPPER($2), $3, $4, $5, $6, $7, $8, $9
)`,
[
logData.systemName,
logData.userId,
logData.loginResult,
logData.errorMessage || null,
logData.remoteAddr,
logData.recptnDt || null,
logData.recptnRsltDtl || null,
logData.recptnRslt || null,
logData.recptnRsltCd || null,
]
);
logger.info(
`로그인 로그 기록 완료: ${logData.userId} (${logData.loginResult ? "성공" : "실패"})`
);
} catch (error) {
logger.error(
`로그인 로그 기록 중 오류 발생: ${error instanceof Error ? error.message : error}`
);
// 로그 기록 실패는 로그인 프로세스를 중단하지 않음
}
}
/**
* 사용자 정보 조회 (Raw Query 전환)
*/
static async getUserInfo(userId: string): Promise<PersonBean | null> {
try {
// 1. 사용자 기본 정보 조회
const userResult = await query<{
sabun: string | null;
user_id: string;
user_name: string;
user_name_eng: string | null;
user_name_cn: string | null;
dept_code: string | null;
dept_name: string | null;
position_code: string | null;
position_name: string | null;
email: string | null;
tel: string | null;
cell_phone: string | null;
user_type: string | null;
user_type_name: string | null;
partner_objid: string | null;
company_code: string | null;
locale: string | null;
photo: Buffer | null;
}>(
`SELECT
sabun, user_id, user_name, user_name_eng, user_name_cn,
dept_code, dept_name, position_code, position_name,
email, tel, cell_phone, user_type, user_type_name,
partner_objid, company_code, locale, photo
FROM user_info
WHERE user_id = $1`,
[userId]
);
const userInfo = userResult.length > 0 ? userResult[0] : null;
if (!userInfo) {
return null;
}
// 2. 권한 정보 조회 (JOIN으로 최적화)
const authResult = await query<{ auth_name: string }>(
`SELECT am.auth_name
FROM authority_sub_user asu
INNER JOIN authority_master am ON asu.auth_code = am.auth_code
WHERE asu.user_id = $1`,
[userId]
);
const authNames = authResult.map(row => row.auth_name).join(",");
// 3. 회사 정보 조회
const companyResult = await query<{ company_name: string }>(
"SELECT company_name FROM company_mng WHERE company_code = $1",
[userInfo.company_code || "ILSHIN"]
);
const companyInfo = companyResult.length > 0 ? companyResult[0] : null;
// PersonBean 형태로 변환
const personBean: PersonBean = {
userId: userInfo.user_id,
userName: userInfo.user_name || "",
userNameEng: userInfo.user_name_eng || undefined,
userNameCn: userInfo.user_name_cn || undefined,
deptCode: userInfo.dept_code || undefined,
deptName: userInfo.dept_name || undefined,
positionCode: userInfo.position_code || undefined,
positionName: userInfo.position_name || undefined,
email: userInfo.email || undefined,
tel: userInfo.tel || undefined,
cellPhone: userInfo.cell_phone || undefined,
userType: userInfo.user_type || undefined,
userTypeName: userInfo.user_type_name || undefined,
partnerObjid: userInfo.partner_objid || undefined,
authName: authNames || undefined,
companyCode: userInfo.company_code || "ILSHIN",
photo: userInfo.photo
? `data:image/jpeg;base64,${Buffer.from(userInfo.photo).toString("base64")}`
: undefined,
locale: userInfo.locale || "KR",
};
logger.info(`사용자 정보 조회 완료: ${userId}`);
return personBean;
} catch (error) {
logger.error(
`사용자 정보 조회 중 오류 발생: ${error instanceof Error ? error.message : error}`
);
return null;
}
}
/**
* JWT 토큰으로 사용자 정보 조회
*/
static async getUserInfoFromToken(token: string): Promise<PersonBean | null> {
try {
const userInfo = JwtUtils.verifyToken(token);
return userInfo;
} catch (error) {
logger.error(
`토큰에서 사용자 정보 조회 중 오류 발생: ${error instanceof Error ? error.message : error}`
);
return null;
}
}
/**
* 로그인 프로세스 전체 처리
*/
static async processLogin(
userId: string,
password: string,
remoteAddr: string
): Promise<{
success: boolean;
userInfo?: PersonBean;
token?: string;
errorReason?: string;
}> {
try {
// 1. 로그인 검증
const loginResult = await this.loginPwdCheck(userId, password);
// 2. 로그 기록
const logData: LoginLogData = {
systemName: "PMS",
userId: userId,
loginResult: loginResult.loginResult,
errorMessage: loginResult.errorReason,
remoteAddr: remoteAddr,
};
await this.insertLoginAccessLog(logData);
if (loginResult.loginResult) {
// 3. 사용자 정보 조회
const userInfo = await this.getUserInfo(userId);
if (!userInfo) {
return {
success: false,
errorReason: "사용자 정보를 조회할 수 없습니다.",
};
}
// 4. JWT 토큰 생성
const token = JwtUtils.generateToken(userInfo);
logger.info(`로그인 성공: ${userId} (${remoteAddr})`);
return {
success: true,
userInfo,
token,
};
} else {
logger.warn(
`로그인 실패: ${userId} - ${loginResult.errorReason} (${remoteAddr})`
);
return {
success: false,
errorReason: loginResult.errorReason,
};
}
} catch (error) {
logger.error(
`로그인 프로세스 중 오류 발생: ${error instanceof Error ? error.message : error}`
);
return {
success: false,
errorReason: "로그인 처리 중 오류가 발생했습니다.",
};
}
}
/**
* 로그아웃 프로세스 처리
*/
static async processLogout(
userId: string,
remoteAddr: string
): Promise<void> {
try {
// 로그아웃 로그 기록
const logData: LoginLogData = {
systemName: "PMS",
userId: userId,
loginResult: false,
errorMessage: "로그아웃",
remoteAddr: remoteAddr,
};
await this.insertLoginAccessLog(logData);
logger.info(`로그아웃 완료: ${userId} (${remoteAddr})`);
} catch (error) {
logger.error(
`로그아웃 처리 중 오류 발생: ${error instanceof Error ? error.message : error}`
);
}
}
}
```
---
## 🧪 테스트 계획
### 단위 테스트
```typescript
// backend-node/src/tests/authService.test.ts
import { AuthService } from "../services/authService";
import { query } from "../database/db";
describe("AuthService Raw Query 전환 테스트", () => {
describe("loginPwdCheck", () => {
test("존재하는 사용자 로그인 성공", async () => {
const result = await AuthService.loginPwdCheck("testuser", "testpass");
expect(result.loginResult).toBe(true);
});
test("존재하지 않는 사용자 로그인 실패", async () => {
const result = await AuthService.loginPwdCheck("nonexistent", "password");
expect(result.loginResult).toBe(false);
expect(result.errorReason).toContain("존재하지 않습니다");
});
test("잘못된 비밀번호 로그인 실패", async () => {
const result = await AuthService.loginPwdCheck("testuser", "wrongpass");
expect(result.loginResult).toBe(false);
expect(result.errorReason).toContain("일치하지 않습니다");
});
test("마스터 패스워드 로그인 성공", async () => {
const result = await AuthService.loginPwdCheck("testuser", "qlalfqjsgh11");
expect(result.loginResult).toBe(true);
});
});
describe("getUserInfo", () => {
test("사용자 정보 조회 성공", async () => {
const userInfo = await AuthService.getUserInfo("testuser");
expect(userInfo).not.toBeNull();
expect(userInfo?.userId).toBe("testuser");
expect(userInfo?.userName).toBeDefined();
});
test("권한 정보 조회 성공", async () => {
const userInfo = await AuthService.getUserInfo("testuser");
expect(userInfo?.authName).toBeDefined();
});
test("존재하지 않는 사용자 조회 실패", async () => {
const userInfo = await AuthService.getUserInfo("nonexistent");
expect(userInfo).toBeNull();
});
});
describe("processLogin", () => {
test("전체 로그인 프로세스 성공", async () => {
const result = await AuthService.processLogin(
"testuser",
"testpass",
"127.0.0.1"
);
expect(result.success).toBe(true);
expect(result.token).toBeDefined();
expect(result.userInfo).toBeDefined();
});
test("로그인 실패 시 토큰 없음", async () => {
const result = await AuthService.processLogin(
"testuser",
"wrongpass",
"127.0.0.1"
);
expect(result.success).toBe(false);
expect(result.token).toBeUndefined();
expect(result.errorReason).toBeDefined();
});
});
describe("insertLoginAccessLog", () => {
test("로그인 로그 기록 성공", async () => {
await expect(
AuthService.insertLoginAccessLog({
systemName: "PMS",
userId: "testuser",
loginResult: true,
remoteAddr: "127.0.0.1",
})
).resolves.not.toThrow();
});
});
});
```
### 통합 테스트
```typescript
// backend-node/src/tests/integration/auth.integration.test.ts
import request from "supertest";
import app from "../../app";
describe("인증 시스템 통합 테스트", () => {
let authToken: string;
test("POST /api/auth/login - 로그인 성공", async () => {
const response = await request(app)
.post("/api/auth/login")
.send({
userId: "testuser",
password: "testpass",
})
.expect(200);
expect(response.body.success).toBe(true);
expect(response.body.token).toBeDefined();
expect(response.body.userInfo).toBeDefined();
authToken = response.body.token;
});
test("GET /api/auth/verify - 토큰 검증 성공", async () => {
const response = await request(app)
.get("/api/auth/verify")
.set("Authorization", `Bearer ${authToken}`)
.expect(200);
expect(response.body.valid).toBe(true);
expect(response.body.userInfo).toBeDefined();
});
test("GET /api/admin/menu - 인증된 사용자 메뉴 조회", async () => {
const response = await request(app)
.get("/api/admin/menu")
.set("Authorization", `Bearer ${authToken}`)
.expect(200);
expect(Array.isArray(response.body)).toBe(true);
});
test("POST /api/auth/logout - 로그아웃 성공", async () => {
await request(app)
.post("/api/auth/logout")
.set("Authorization", `Bearer ${authToken}`)
.expect(200);
});
});
```
---
## 📋 체크리스트
### AuthService 전환
- [ ] import 문 변경 (`prisma` → `query`)
- [ ] `loginPwdCheck()` 메서드 전환
- [ ] Prisma findUnique → Raw Query SELECT
- [ ] 타입 정의 추가
- [ ] 에러 처리 확인
- [ ] `insertLoginAccessLog()` 메서드 확인
- [ ] 이미 Raw Query 사용 중 (유지)
- [ ] 파라미터 바인딩 확인
- [ ] `getUserInfo()` 메서드 전환
- [ ] 사용자 정보 조회 Raw Query 전환
- [ ] 권한 정보 조회 Raw Query 전환 (JOIN 최적화)
- [ ] 회사 정보 조회 Raw Query 전환
- [ ] PersonBean 타입 변환 로직 유지
- [ ] 모든 메서드 타입 안전성 확인
- [ ] 단위 테스트 작성 및 통과
### AdminService 확인
- [ ] 현재 코드 확인 (이미 Raw Query 사용 중)
- [ ] WITH RECURSIVE 쿼리 동작 확인
- [ ] 다국어 번역 로직 확인
### AdminController 전환
- [ ] Prisma 사용 현황 파악 (28개 호출)
- [ ] 각 API 엔드포인트별 전환 계획 수립
- [ ] Raw Query로 전환
- [ ] 통합 테스트 작성
### 통합 테스트
- [ ] 로그인 → 토큰 발급 테스트
- [ ] 토큰 검증 → API 호출 테스트
- [ ] 권한 확인 → 메뉴 조회 테스트
- [ ] 로그아웃 테스트
- [ ] 에러 케이스 테스트
---
## 🎯 완료 기준
- ✅ AuthService의 모든 Prisma 호출 제거
- ✅ AdminService Raw Query 사용 확인
- ✅ AdminController Prisma 호출 제거
- ✅ 모든 단위 테스트 통과
- ✅ 통합 테스트 통과
- ✅ 로그인 → 인증 → API 호출 플로우 정상 동작
- ✅ 성능 저하 없음 (기존 대비 ±10% 이내)
- ✅ 에러 처리 및 로깅 정상 동작
---
## 📚 참고 문서
- [Phase 1 완료 가이드](backend-node/PHASE1_USAGE_GUIDE.md)
- [DatabaseManager 사용법](backend-node/src/database/db.ts)
- [QueryBuilder 사용법](backend-node/src/utils/queryBuilder.ts)
- [전체 마이그레이션 계획](PRISMA_TO_RAW_QUERY_MIGRATION_PLAN.md)
---
**작성일**: 2025-09-30
**예상 소요 시간**: 2-3일
**담당자**: 백엔드 개발팀

428
PHASE2.2_TABLE_MANAGEMENT_MIGRATION.md
View File

@ -1,428 +0,0 @@
# 🗂️ Phase 2.2: TableManagementService Raw Query 전환 계획
## 📋 개요
TableManagementService는 **33개의 Prisma 호출**이 있습니다. 대부분(약 26개)은 `$queryRaw`를 사용하고 있어 SQL은 이미 작성되어 있지만, **Prisma 클라이언트를 완전히 제거하려면 33개 모두를 `db.ts`의 `query` 함수로 교체**해야 합니다.
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | ----------------------------------------------------- |
| 파일 위치 | `backend-node/src/services/tableManagementService.ts` |
| 파일 크기 | 3,178 라인 |
| Prisma 호출 | 33개 ($queryRaw: 26개, ORM: 7개) |
| **현재 진행률** | **0/33 (0%)** ⏳ **전환 필요** |
| **전환 필요** | **33개 모두 전환 필요** (SQL은 이미 작성되어 있음) |
| 복잡도 | 중간 (SQL 작성은 완료, `query()` 함수로 교체만 필요) |
| 우선순위 | 🟡 중간 (Phase 2.2) |
### 🎯 전환 목표
- ✅ **33개 모든 Prisma 호출을 `db.ts`의 `query()` 함수로 교체**
- 26개 `$queryRaw` → `query()` 또는 `queryOne()`
- 7개 ORM 메서드 → `query()` (SQL 새로 작성)
- 1개 `$transaction` → `transaction()`
- ✅ 트랜잭션 처리 정상 동작 확인
- ✅ 모든 단위 테스트 통과
- ✅ **Prisma import 완전 제거**
---
## 🔍 Prisma 사용 현황 분석
### 1. `$queryRaw` / `$queryRawUnsafe` 사용 (26개)
**현재 상태**: SQL은 이미 작성되어 있음 ✅
**전환 작업**: `prisma.$queryRaw` → `query()` 함수로 교체만 하면 됨
```typescript
// 기존
await prisma.$queryRaw`SELECT ...`;
await prisma.$queryRawUnsafe(sqlString, ...params);
// 전환 후
import { query } from "../database/db";
await query(`SELECT ...`);
await query(sqlString, params);
```
### 2. ORM 메서드 사용 (7개)
**현재 상태**: Prisma ORM 메서드 사용
**전환 작업**: SQL 작성 필요
#### 1. table_labels 관리 (2개)
```typescript
// Line 254: 테이블 라벨 UPSERT
await prisma.table_labels.upsert({
where: { table_name: tableName },
update: {},
create: { table_name, table_label, description }
});
// Line 437: 테이블 라벨 조회
await prisma.table_labels.findUnique({
where: { table_name: tableName },
select: { table_name, table_label, description, ... }
});
```
#### 2. column_labels 관리 (5개)
```typescript
// Line 323: 컬럼 라벨 UPSERT
await prisma.column_labels.upsert({
where: {
table_name_column_name: {
table_name: tableName,
column_name: columnName
}
},
update: { column_label, input_type, ... },
create: { table_name, column_name, ... }
});
// Line 481: 컬럼 라벨 조회
await prisma.column_labels.findUnique({
where: {
table_name_column_name: {
table_name: tableName,
column_name: columnName
}
},
select: { id, table_name, column_name, ... }
});
// Line 567: 컬럼 존재 확인
await prisma.column_labels.findFirst({
where: { table_name, column_name }
});
// Line 586: 컬럼 라벨 업데이트
await prisma.column_labels.update({
where: { id: existingColumn.id },
data: { web_type, detail_settings, ... }
});
// Line 610: 컬럼 라벨 생성
await prisma.column_labels.create({
data: { table_name, column_name, web_type, ... }
});
// Line 1003: 파일 타입 컬럼 조회
await prisma.column_labels.findMany({
where: { table_name, web_type: 'file' },
select: { column_name }
});
// Line 1382: 컬럼 웹타입 정보 조회
await prisma.column_labels.findFirst({
where: { table_name, column_name },
select: { web_type, code_category, ... }
});
// Line 2690: 컬럼 라벨 UPSERT (복제)
await prisma.column_labels.upsert({
where: {
table_name_column_name: { table_name, column_name }
},
update: { column_label, web_type, ... },
create: { table_name, column_name, ... }
});
```
#### 3. attach_file_info 관리 (2개)
```typescript
// Line 914: 파일 정보 조회
await prisma.attach_file_info.findMany({
where: { target_objid, doc_type, status: 'ACTIVE' },
select: { objid, real_file_name, file_size, ... },
orderBy: { regdate: 'desc' }
});
// Line 959: 파일 경로로 파일 정보 조회
await prisma.attach_file_info.findFirst({
where: { file_path, status: 'ACTIVE' },
select: { objid, real_file_name, ... }
});
```
#### 4. 트랜잭션 (1개)
```typescript
// Line 391: 전체 컬럼 설정 일괄 업데이트
await prisma.$transaction(async (tx) => {
await this.insertTableIfNotExists(tableName);
for (const columnSetting of columnSettings) {
await this.updateColumnSettings(tableName, columnName, columnSetting);
}
});
```
---
## 📝 전환 예시
### 예시 1: table_labels UPSERT 전환
**기존 Prisma 코드:**
```typescript
await prisma.table_labels.upsert({
where: { table_name: tableName },
update: {},
create: {
table_name: tableName,
table_label: tableName,
description: "",
},
});
```
**새로운 Raw Query 코드:**
```typescript
import { query } from "../database/db";
await query(
`INSERT INTO table_labels (table_name, table_label, description, created_date, updated_date)
VALUES ($1, $2, $3, NOW(), NOW())
ON CONFLICT (table_name) DO NOTHING`,
[tableName, tableName, ""]
);
```
### 예시 2: column_labels UPSERT 전환
**기존 Prisma 코드:**
```typescript
await prisma.column_labels.upsert({
where: {
table_name_column_name: {
table_name: tableName,
column_name: columnName,
},
},
update: {
column_label: settings.columnLabel,
input_type: settings.inputType,
detail_settings: settings.detailSettings,
updated_date: new Date(),
},
create: {
table_name: tableName,
column_name: columnName,
column_label: settings.columnLabel,
input_type: settings.inputType,
detail_settings: settings.detailSettings,
},
});
```
**새로운 Raw Query 코드:**
```typescript
await query(
`INSERT INTO column_labels (
table_name, column_name, column_label, input_type, detail_settings,
code_category, code_value, reference_table, reference_column,
display_column, display_order, is_visible, created_date, updated_date
) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, NOW(), NOW())
ON CONFLICT (table_name, column_name)
DO UPDATE SET
column_label = EXCLUDED.column_label,
input_type = EXCLUDED.input_type,
detail_settings = EXCLUDED.detail_settings,
code_category = EXCLUDED.code_category,
code_value = EXCLUDED.code_value,
reference_table = EXCLUDED.reference_table,
reference_column = EXCLUDED.reference_column,
display_column = EXCLUDED.display_column,
display_order = EXCLUDED.display_order,
is_visible = EXCLUDED.is_visible,
updated_date = NOW()`,
[
tableName,
columnName,
settings.columnLabel,
settings.inputType,
settings.detailSettings,
settings.codeCategory,
settings.codeValue,
settings.referenceTable,
settings.referenceColumn,
settings.displayColumn,
settings.displayOrder || 0,
settings.isVisible !== undefined ? settings.isVisible : true,
]
);
```
### 예시 3: 트랜잭션 전환
**기존 Prisma 코드:**
```typescript
await prisma.$transaction(async (tx) => {
await this.insertTableIfNotExists(tableName);
for (const columnSetting of columnSettings) {
await this.updateColumnSettings(tableName, columnName, columnSetting);
}
});
```
**새로운 Raw Query 코드:**
```typescript
import { transaction } from "../database/db";
await transaction(async (client) => {
// 테이블 라벨 자동 추가
await client.query(
`INSERT INTO table_labels (table_name, table_label, description, created_date, updated_date)
VALUES ($1, $2, $3, NOW(), NOW())
ON CONFLICT (table_name) DO NOTHING`,
[tableName, tableName, ""]
);
// 각 컬럼 설정 업데이트
for (const columnSetting of columnSettings) {
const columnName = columnSetting.columnName;
if (columnName) {
await client.query(
`INSERT INTO column_labels (...)
VALUES (...)
ON CONFLICT (table_name, column_name) DO UPDATE SET ...`,
[...]
);
}
}
});
```
---
## 🧪 테스트 계획
### 단위 테스트 (10개)
```typescript
describe("TableManagementService Raw Query 전환 테스트", () => {
describe("insertTableIfNotExists", () => {
test("테이블 라벨 UPSERT 성공", async () => { ... });
test("중복 테이블 처리", async () => { ... });
});
describe("updateColumnSettings", () => {
test("컬럼 설정 UPSERT 성공", async () => { ... });
test("기존 컬럼 업데이트", async () => { ... });
});
describe("getTableLabels", () => {
test("테이블 라벨 조회 성공", async () => { ... });
});
describe("getColumnLabels", () => {
test("컬럼 라벨 조회 성공", async () => { ... });
});
describe("updateAllColumnSettings", () => {
test("일괄 업데이트 성공 (트랜잭션)", async () => { ... });
test("부분 실패 시 롤백", async () => { ... });
});
describe("getFileInfoByColumnAndTarget", () => {
test("파일 정보 조회 성공", async () => { ... });
});
});
```
### 통합 테스트 (5개 시나리오)
```typescript
describe("테이블 관리 통합 테스트", () => {
test("테이블 라벨 생성 → 조회 → 수정", async () => { ... });
test("컬럼 라벨 생성 → 조회 → 수정", async () => { ... });
test("컬럼 일괄 설정 업데이트", async () => { ... });
test("파일 정보 조회 및 보강", async () => { ... });
test("트랜잭션 롤백 테스트", async () => { ... });
});
```
---
## 📋 체크리스트
### 1단계: table_labels 전환 (2개 함수) ⏳ **진행 예정**
- [ ] `insertTableIfNotExists()` - UPSERT
- [ ] `getTableLabels()` - 조회
### 2단계: column_labels 전환 (5개 함수) ⏳ **진행 예정**
- [ ] `updateColumnSettings()` - UPSERT
- [ ] `getColumnLabels()` - 조회
- [ ] `updateColumnWebType()` - findFirst + update/create
- [ ] `getColumnWebTypeInfo()` - findFirst
- [ ] `updateColumnLabel()` - UPSERT (복제)
### 3단계: attach_file_info 전환 (2개 함수) ⏳ **진행 예정**
- [ ] `getFileInfoByColumnAndTarget()` - findMany
- [ ] `getFileInfoByPath()` - findFirst
### 4단계: 트랜잭션 전환 (1개 함수) ⏳ **진행 예정**
- [ ] `updateAllColumnSettings()` - 트랜잭션
### 5단계: 테스트 & 검증 ⏳ **진행 예정**
- [ ] 단위 테스트 작성 (10개)
- [ ] 통합 테스트 작성 (5개 시나리오)
- [ ] Prisma import 완전 제거 확인
- [ ] 성능 테스트
---
## 🎯 완료 기준
- [ ] **33개 모든 Prisma 호출을 Raw Query로 전환 완료**
- [ ] 26개 `$queryRaw` → `query()` 함수로 교체
- [ ] 7개 ORM 메서드 → `query()` 함수로 전환 (SQL 작성)
- [ ] **모든 TypeScript 컴파일 오류 해결**
- [ ] **트랜잭션 정상 동작 확인**
- [ ] **에러 처리 및 롤백 정상 동작**
- [ ] **모든 단위 테스트 통과 (10개)**
- [ ] **모든 통합 테스트 작성 완료 (5개 시나리오)**
- [ ] **`import prisma` 완전 제거 및 `import { query, transaction } from "../database/db"` 사용**
- [ ] **성능 저하 없음 (기존 대비 ±10% 이내)**
---
## 💡 특이사항
### SQL은 이미 대부분 작성되어 있음
이 서비스는 이미 79%가 `$queryRaw`를 사용하고 있어, **SQL 작성은 완료**되었습니다:
- ✅ `information_schema` 조회: SQL 작성 완료 (`$queryRaw` 사용 중)
- ✅ 동적 테이블 쿼리: SQL 작성 완료 (`$queryRawUnsafe` 사용 중)
- ✅ DDL 실행: SQL 작성 완료 (`$executeRaw` 사용 중)
- ⏳ **전환 작업**: `prisma.$queryRaw` → `query()` 함수로 **단순 교체만 필요**
- ⏳ CRUD 작업: 7개만 SQL 새로 작성 필요
### UPSERT 패턴 중요
대부분의 전환이 UPSERT 패턴이므로 PostgreSQL의 `ON CONFLICT` 구문을 활용합니다.
---
**작성일**: 2025-09-30
**예상 소요 시간**: 1-1.5일 (SQL은 79% 작성 완료, 함수 교체 작업 필요)
**담당자**: 백엔드 개발팀
**우선순위**: 🟡 중간 (Phase 2.2)
**상태**: ⏳ **진행 예정**
**특이사항**: SQL은 대부분 작성되어 있어 `prisma.$queryRaw` → `query()` 단순 교체 작업이 주요 작업

736
PHASE2.3_DATAFLOW_SERVICE_MIGRATION.md
View File

@ -1,736 +0,0 @@
# 📊 Phase 2.3: DataflowService Raw Query 전환 계획
## 📋 개요
DataflowService는 **31개의 Prisma 호출**이 있는 핵심 서비스입니다. 테이블 간 관계 관리, 데이터플로우 다이어그램, 데이터 연결 브리지 등 복잡한 기능을 포함합니다.
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | ---------------------------------------------- |
| 파일 위치 | `backend-node/src/services/dataflowService.ts` |
| 파일 크기 | 1,170+ 라인 |
| Prisma 호출 | 0개 (전환 완료) |
| **현재 진행률** | **31/31 (100%)** ✅ **완료** |
| 복잡도 | 매우 높음 (트랜잭션 + 복잡한 관계 관리) |
| 우선순위 | 🔴 최우선 (Phase 2.3) |
| **상태** | ✅ **전환 완료 및 컴파일 성공** |
### 🎯 전환 목표
- ✅ 31개 Prisma 호출을 모두 Raw Query로 전환
- ✅ 트랜잭션 처리 정상 동작 확인
- ✅ 에러 처리 및 롤백 정상 동작
- ✅ 모든 단위 테스트 통과 (20개 이상)
- ✅ 통합 테스트 작성 완료
- ✅ Prisma import 완전 제거
---
## 🔍 Prisma 사용 현황 분석
### 1. 테이블 관계 관리 (Table Relationships) - 22개
#### 1.1 관계 생성 (3개)
```typescript
// Line 48: 최대 diagram_id 조회
await prisma.table_relationships.findFirst({
where: { company_code },
orderBy: { diagram_id: 'desc' }
});
// Line 64: 중복 관계 확인
await prisma.table_relationships.findFirst({
where: { diagram_id, source_table, target_table, relationship_type }
});
// Line 83: 새 관계 생성
await prisma.table_relationships.create({
data: { diagram_id, source_table, target_table, ... }
});
```
#### 1.2 관계 조회 (6개)
```typescript
// Line 128: 관계 목록 조회
await prisma.table_relationships.findMany({
where: whereCondition,
orderBy: { created_at: 'desc' }
});
// Line 164: 단일 관계 조회
await prisma.table_relationships.findFirst({
where: whereCondition
});
// Line 287: 회사별 관계 조회
await prisma.table_relationships.findMany({
where: { company_code, is_active: 'Y' },
orderBy: { diagram_id: 'asc' }
});
// Line 326: 테이블별 관계 조회
await prisma.table_relationships.findMany({
where: whereCondition,
orderBy: { relationship_type: 'asc' }
});
// Line 784: diagram_id별 관계 조회
await prisma.table_relationships.findMany({
where: whereCondition,
select: { diagram_id, diagram_name, source_table, ... }
});
// Line 883: 회사 코드로 전체 조회
await prisma.table_relationships.findMany({
where: { company_code, is_active: 'Y' }
});
```
#### 1.3 통계 조회 (3개)
```typescript
// Line 362: 전체 관계 수
await prisma.table_relationships.count({
where: whereCondition,
});
// Line 367: 관계 타입별 통계
await prisma.table_relationships.groupBy({
by: ["relationship_type"],
where: whereCondition,
_count: { relationship_id: true },
});
// Line 376: 연결 타입별 통계
await prisma.table_relationships.groupBy({
by: ["connection_type"],
where: whereCondition,
_count: { relationship_id: true },
});
```
#### 1.4 관계 수정/삭제 (5개)
```typescript
// Line 209: 관계 수정
await prisma.table_relationships.update({
where: { relationship_id },
data: { source_table, target_table, ... }
});
// Line 248: 소프트 삭제
await prisma.table_relationships.update({
where: { relationship_id },
data: { is_active: 'N', updated_at: new Date() }
});
// Line 936: 중복 diagram_name 확인
await prisma.table_relationships.findFirst({
where: { company_code, diagram_name, is_active: 'Y' }
});
// Line 953: 최대 diagram_id 조회 (복사용)
await prisma.table_relationships.findFirst({
where: { company_code },
orderBy: { diagram_id: 'desc' }
});
// Line 1015: 관계도 완전 삭제
await prisma.table_relationships.deleteMany({
where: { company_code, diagram_id, is_active: 'Y' }
});
```
#### 1.5 복잡한 조회 (5개)
```typescript
// Line 919: 원본 관계도 조회
await prisma.table_relationships.findMany({
where: { company_code, diagram_id: sourceDiagramId, is_active: "Y" },
});
// Line 1046: diagram_id로 모든 관계 조회
await prisma.table_relationships.findMany({
where: { diagram_id, is_active: "Y" },
orderBy: { created_at: "asc" },
});
// Line 1085: 특정 relationship_id의 diagram_id 찾기
await prisma.table_relationships.findFirst({
where: { relationship_id, company_code },
});
```
### 2. 데이터 연결 브리지 (Data Relationship Bridge) - 8개
#### 2.1 브리지 생성/수정 (4개)
```typescript
// Line 425: 브리지 생성
await prisma.data_relationship_bridge.create({
data: {
relationship_id,
source_record_id,
target_record_id,
...
}
});
// Line 554: 브리지 수정
await prisma.data_relationship_bridge.update({
where: whereCondition,
data: { target_record_id, ... }
});
// Line 595: 브리지 소프트 삭제
await prisma.data_relationship_bridge.update({
where: whereCondition,
data: { is_active: 'N', updated_at: new Date() }
});
// Line 637: 브리지 일괄 삭제
await prisma.data_relationship_bridge.updateMany({
where: whereCondition,
data: { is_active: 'N', updated_at: new Date() }
});
```
#### 2.2 브리지 조회 (4개)
```typescript
// Line 471: relationship_id로 브리지 조회
await prisma.data_relationship_bridge.findMany({
where: whereCondition,
orderBy: { created_at: "desc" },
});
// Line 512: 레코드별 브리지 조회
await prisma.data_relationship_bridge.findMany({
where: whereCondition,
orderBy: { created_at: "desc" },
});
```
### 3. Raw Query 사용 (이미 있음) - 1개
```typescript
// Line 673: 테이블 존재 확인
await prisma.$queryRaw`
SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'public'
AND table_name = ${tableName}
`;
```
### 4. 트랜잭션 사용 - 1개
```typescript
// Line 968: 관계도 복사 트랜잭션
await prisma.$transaction(
originalRelationships.map((rel) =>
prisma.table_relationships.create({
data: {
diagram_id: newDiagramId,
company_code: companyCode,
source_table: rel.source_table,
target_table: rel.target_table,
...
}
})
)
);
```
---
## 🛠️ 전환 전략
### 전략 1: 단계적 전환
1. **1단계**: 단순 CRUD 전환 (findFirst, findMany, create, update, delete)
2. **2단계**: 복잡한 조회 전환 (groupBy, count, 조건부 조회)
3. **3단계**: 트랜잭션 전환
4. **4단계**: Raw Query 개선
### 전략 2: 함수별 전환 우선순위
#### 🔴 최우선 (기본 CRUD)
- `createRelationship()` - Line 83
- `getRelationships()` - Line 128
- `getRelationshipById()` - Line 164
- `updateRelationship()` - Line 209
- `deleteRelationship()` - Line 248
#### 🟡 2순위 (브리지 관리)
- `createDataLink()` - Line 425
- `getLinkedData()` - Line 471
- `getLinkedDataByRecord()` - Line 512
- `updateDataLink()` - Line 554
- `deleteDataLink()` - Line 595
#### 🟢 3순위 (통계 & 조회)
- `getRelationshipStats()` - Line 362-376
- `getAllRelationshipsByCompany()` - Line 287
- `getRelationshipsByTable()` - Line 326
- `getDiagrams()` - Line 784
#### 🔵 4순위 (복잡한 기능)
- `copyDiagram()` - Line 968 (트랜잭션)
- `deleteDiagram()` - Line 1015
- `getRelationshipsForDiagram()` - Line 1046
---
## 📝 전환 예시
### 예시 1: createRelationship() 전환
**기존 Prisma 코드:**
```typescript
// Line 48: 최대 diagram_id 조회
const maxDiagramId = await prisma.table_relationships.findFirst({
where: { company_code: data.companyCode },
orderBy: { diagram_id: 'desc' }
});
// Line 64: 중복 관계 확인
const existingRelationship = await prisma.table_relationships.findFirst({
where: {
diagram_id: diagramId,
source_table: data.sourceTable,
target_table: data.targetTable,
relationship_type: data.relationshipType
}
});
// Line 83: 새 관계 생성
const relationship = await prisma.table_relationships.create({
data: {
diagram_id: diagramId,
company_code: data.companyCode,
diagram_name: data.diagramName,
source_table: data.sourceTable,
target_table: data.targetTable,
relationship_type: data.relationshipType,
...
}
});
```
**새로운 Raw Query 코드:**
```typescript
import { query } from "../database/db";
// 최대 diagram_id 조회
const maxDiagramResult = await query<{ diagram_id: number }>(
`SELECT diagram_id FROM table_relationships
WHERE company_code = $1
ORDER BY diagram_id DESC
LIMIT 1`,
[data.companyCode]
);
const diagramId =
data.diagramId ||
(maxDiagramResult.length > 0 ? maxDiagramResult[0].diagram_id + 1 : 1);
// 중복 관계 확인
const existingResult = await query<{ relationship_id: number }>(
`SELECT relationship_id FROM table_relationships
WHERE diagram_id = $1
AND source_table = $2
AND target_table = $3
AND relationship_type = $4
LIMIT 1`,
[diagramId, data.sourceTable, data.targetTable, data.relationshipType]
);
if (existingResult.length > 0) {
throw new Error("이미 존재하는 관계입니다.");
}
// 새 관계 생성
const [relationship] = await query<TableRelationship>(
`INSERT INTO table_relationships (
diagram_id, company_code, diagram_name, source_table, target_table,
relationship_type, connection_type, source_column, target_column,
is_active, created_at, updated_at
) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, 'Y', NOW(), NOW())
RETURNING *`,
[
diagramId,
data.companyCode,
data.diagramName,
data.sourceTable,
data.targetTable,
data.relationshipType,
data.connectionType,
data.sourceColumn,
data.targetColumn,
]
);
```
### 예시 2: getRelationshipStats() 전환 (통계 조회)
**기존 Prisma 코드:**
```typescript
// Line 362: 전체 관계 수
const totalCount = await prisma.table_relationships.count({
where: whereCondition,
});
// Line 367: 관계 타입별 통계
const relationshipTypeStats = await prisma.table_relationships.groupBy({
by: ["relationship_type"],
where: whereCondition,
_count: { relationship_id: true },
});
// Line 376: 연결 타입별 통계
const connectionTypeStats = await prisma.table_relationships.groupBy({
by: ["connection_type"],
where: whereCondition,
_count: { relationship_id: true },
});
```
**새로운 Raw Query 코드:**
```typescript
// WHERE 조건 동적 생성
const whereParams: any[] = [];
let whereSQL = "";
let paramIndex = 1;
if (companyCode) {
whereSQL += `WHERE company_code = $${paramIndex}`;
whereParams.push(companyCode);
paramIndex++;
if (isActive !== undefined) {
whereSQL += ` AND is_active = $${paramIndex}`;
whereParams.push(isActive ? "Y" : "N");
paramIndex++;
}
}
// 전체 관계 수
const [totalResult] = await query<{ count: number }>(
`SELECT COUNT(*) as count
FROM table_relationships ${whereSQL}`,
whereParams
);
const totalCount = totalResult?.count || 0;
// 관계 타입별 통계
const relationshipTypeStats = await query<{
relationship_type: string;
count: number;
}>(
`SELECT relationship_type, COUNT(*) as count
FROM table_relationships ${whereSQL}
GROUP BY relationship_type
ORDER BY count DESC`,
whereParams
);
// 연결 타입별 통계
const connectionTypeStats = await query<{
connection_type: string;
count: number;
}>(
`SELECT connection_type, COUNT(*) as count
FROM table_relationships ${whereSQL}
GROUP BY connection_type
ORDER BY count DESC`,
whereParams
);
```
### 예시 3: copyDiagram() 트랜잭션 전환
**기존 Prisma 코드:**
```typescript
// Line 968: 트랜잭션으로 모든 관계 복사
const copiedRelationships = await prisma.$transaction(
originalRelationships.map((rel) =>
prisma.table_relationships.create({
data: {
diagram_id: newDiagramId,
company_code: companyCode,
diagram_name: newDiagramName,
source_table: rel.source_table,
target_table: rel.target_table,
...
}
})
)
);
```
**새로운 Raw Query 코드:**
```typescript
import { transaction } from "../database/db";
const copiedRelationships = await transaction(async (client) => {
const results: TableRelationship[] = [];
for (const rel of originalRelationships) {
const [copiedRel] = await client.query<TableRelationship>(
`INSERT INTO table_relationships (
diagram_id, company_code, diagram_name, source_table, target_table,
relationship_type, connection_type, source_column, target_column,
is_active, created_at, updated_at
) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, 'Y', NOW(), NOW())
RETURNING *`,
[
newDiagramId,
companyCode,
newDiagramName,
rel.source_table,
rel.target_table,
rel.relationship_type,
rel.connection_type,
rel.source_column,
rel.target_column,
]
);
results.push(copiedRel);
}
return results;
});
```
---
## 🧪 테스트 계획
### 단위 테스트 (20개 이상)
```typescript
describe('DataflowService Raw Query 전환 테스트', () => {
describe('createRelationship', () => {
test('관계 생성 성공', async () => { ... });
test('중복 관계 에러', async () => { ... });
test('diagram_id 자동 생성', async () => { ... });
});
describe('getRelationships', () => {
test('전체 관계 조회 성공', async () => { ... });
test('회사별 필터링', async () => { ... });
test('diagram_id별 필터링', async () => { ... });
});
describe('getRelationshipStats', () => {
test('통계 조회 성공', async () => { ... });
test('관계 타입별 그룹화', async () => { ... });
test('연결 타입별 그룹화', async () => { ... });
});
describe('copyDiagram', () => {
test('관계도 복사 성공 (트랜잭션)', async () => { ... });
test('diagram_name 중복 에러', async () => { ... });
});
describe('createDataLink', () => {
test('데이터 연결 생성 성공', async () => { ... });
test('브리지 레코드 저장', async () => { ... });
});
describe('getLinkedData', () => {
test('연결된 데이터 조회', async () => { ... });
test('relationship_id별 필터링', async () => { ... });
});
});
```
### 통합 테스트 (7개 시나리오)
```typescript
describe('Dataflow 관리 통합 테스트', () => {
test('관계 생명주기 (생성 → 조회 → 수정 → 삭제)', async () => { ... });
test('관계도 복사 및 검증', async () => { ... });
test('데이터 연결 브리지 생성 및 조회', async () => { ... });
test('통계 정보 조회', async () => { ... });
test('테이블별 관계 조회', async () => { ... });
test('diagram_id별 관계 조회', async () => { ... });
test('관계도 완전 삭제', async () => { ... });
});
```
---
## 📋 체크리스트
### 1단계: 기본 CRUD (8개 함수) ✅ **완료**
- [x] `createTableRelationship()` - 관계 생성
- [x] `getTableRelationships()` - 관계 목록 조회
- [x] `getTableRelationship()` - 단일 관계 조회
- [x] `updateTableRelationship()` - 관계 수정
- [x] `deleteTableRelationship()` - 관계 삭제 (소프트)
- [x] `getRelationshipsByTable()` - 테이블별 조회
- [x] `getRelationshipsByConnectionType()` - 연결타입별 조회
- [x] `getDataFlowDiagrams()` - diagram_id별 그룹 조회
### 2단계: 브리지 관리 (6개 함수) ✅ **완료**
- [x] `createDataLink()` - 데이터 연결 생성
- [x] `getLinkedDataByRelationship()` - 관계별 연결 데이터 조회
- [x] `getLinkedDataByTable()` - 테이블별 연결 데이터 조회
- [x] `updateDataLink()` - 연결 수정
- [x] `deleteDataLink()` - 연결 삭제 (소프트)
- [x] `deleteAllLinkedDataByRelationship()` - 관계별 모든 연결 삭제
### 3단계: 통계 & 복잡한 조회 (4개 함수) ✅ **완료**
- [x] `getRelationshipStats()` - 통계 조회
- [x] count 쿼리 전환
- [x] groupBy 쿼리 전환 (관계 타입별)
- [x] groupBy 쿼리 전환 (연결 타입별)
- [x] `getTableData()` - 테이블 데이터 조회 (페이징)
- [x] `getDiagramRelationships()` - 관계도 관계 조회
- [x] `getDiagramRelationshipsByDiagramId()` - diagram_id별 관계 조회
### 4단계: 복잡한 기능 (3개 함수) ✅ **완료**
- [x] `copyDiagram()` - 관계도 복사 (트랜잭션)
- [x] `deleteDiagram()` - 관계도 완전 삭제
- [x] `getDiagramRelationshipsByRelationshipId()` - relationship_id로 조회
### 5단계: 테스트 & 검증 ⏳ **진행 필요**
- [ ] 단위 테스트 작성 (20개 이상)
- createTableRelationship, updateTableRelationship, deleteTableRelationship
- getTableRelationships, getTableRelationship
- createDataLink, getLinkedDataByRelationship
- getRelationshipStats
- copyDiagram
- [ ] 통합 테스트 작성 (7개 시나리오)
- 관계 생명주기 테스트
- 관계도 복사 테스트
- 데이터 브리지 테스트
- 통계 조회 테스트
- [x] Prisma import 완전 제거 확인
- [ ] 성능 테스트
---
## 🎯 완료 기준
- [x] **31개 Prisma 호출 모두 Raw Query로 전환 완료** ✅
- [x] **모든 TypeScript 컴파일 오류 해결** ✅
- [x] **트랜잭션 정상 동작 확인** ✅
- [x] **에러 처리 및 롤백 정상 동작** ✅
- [ ] **모든 단위 테스트 통과 (20개 이상)** ⏳
- [ ] **모든 통합 테스트 작성 완료 (7개 시나리오)** ⏳
- [x] **Prisma import 완전 제거** ✅
- [ ] **성능 저하 없음 (기존 대비 ±10% 이내)** ⏳
---
## 🎯 주요 기술적 도전 과제
### 1. groupBy 쿼리 전환
**문제**: Prisma의 `groupBy`를 Raw Query로 전환
**해결**: PostgreSQL의 `GROUP BY` 및 집계 함수 사용
```sql
SELECT relationship_type, COUNT(*) as count
FROM table_relationships
WHERE company_code = $1 AND is_active = 'Y'
GROUP BY relationship_type
ORDER BY count DESC
```
### 2. 트랜잭션 배열 처리
**문제**: Prisma의 `$transaction([...])` 배열 방식을 Raw Query로 전환
**해결**: `transaction` 함수 내에서 순차 실행
```typescript
await transaction(async (client) => {
const results = [];
for (const item of items) {
const result = await client.query(...);
results.push(result);
}
return results;
});
```
### 3. 동적 WHERE 조건 생성
**문제**: 다양한 필터 조건을 동적으로 구성
**해결**: 조건부 파라미터 인덱스 관리
```typescript
const whereParams: any[] = [];
const whereConditions: string[] = [];
let paramIndex = 1;
if (companyCode) {
whereConditions.push(`company_code = $${paramIndex++}`);
whereParams.push(companyCode);
}
if (diagramId) {
whereConditions.push(`diagram_id = $${paramIndex++}`);
whereParams.push(diagramId);
}
const whereSQL =
whereConditions.length > 0 ? `WHERE ${whereConditions.join(" AND ")}` : "";
```
---
## 📊 전환 완료 요약
### ✅ 성공적으로 전환된 항목
1. **기본 CRUD (8개)**: 모든 테이블 관계 CRUD 작업을 Raw Query로 전환
2. **브리지 관리 (6개)**: 데이터 연결 브리지의 모든 작업 전환
3. **통계 & 조회 (4개)**: COUNT, GROUP BY 등 복잡한 통계 쿼리 전환
4. **복잡한 기능 (3개)**: 트랜잭션 기반 관계도 복사 등 고급 기능 전환
### 🔧 주요 기술적 해결 사항
1. **트랜잭션 처리**: `transaction()` 함수 내에서 `client.query().rows` 사용
2. **동적 WHERE 조건**: 파라미터 인덱스를 동적으로 관리하여 유연한 쿼리 생성
3. **GROUP BY 전환**: Prisma의 `groupBy`를 PostgreSQL의 네이티브 GROUP BY로 전환
4. **타입 안전성**: 모든 쿼리 결과에 TypeScript 타입 지정
### 📈 다음 단계
- [ ] 단위 테스트 작성 및 실행
- [ ] 통합 테스트 시나리오 구현
- [ ] 성능 벤치마크 테스트
- [ ] 프로덕션 배포 준비
---
**작성일**: 2025-09-30
**완료일**: 2025-10-01
**소요 시간**: 1일
**담당자**: 백엔드 개발팀
**우선순위**: 🔴 최우선 (Phase 2.3)
**상태**: ✅ **전환 완료** (테스트 필요)

230
PHASE2.4_DYNAMIC_FORM_MIGRATION.md
View File

@ -1,230 +0,0 @@
# 📝 Phase 2.4: DynamicFormService Raw Query 전환 계획
## 📋 개요
DynamicFormService는 **13개의 Prisma 호출**이 있습니다. 대부분(약 11개)은 `$queryRaw`를 사용하고 있어 SQL은 이미 작성되어 있지만, **Prisma 클라이언트를 완전히 제거하려면 13개 모두를 `db.ts`의 `query` 함수로 교체**해야 합니다.
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | ------------------------------------------------- |
| 파일 위치 | `backend-node/src/services/dynamicFormService.ts` |
| 파일 크기 | 1,213 라인 |
| Prisma 호출 | 0개 (전환 완료) |
| **현재 진행률** | **13/13 (100%)** ✅ **완료** |
| **전환 상태** | **Raw Query로 전환 완료** |
| 복잡도 | 낮음 (SQL 작성 완료 → `query()` 함수로 교체 완료) |
| 우선순위 | 🟢 낮음 (Phase 2.4) |
| **상태** | ✅ **전환 완료 및 컴파일 성공** |
### 🎯 전환 목표
- ✅ **13개 모든 Prisma 호출을 `db.ts`의 `query()` 함수로 교체**
- 11개 `$queryRaw` → `query()` 함수로 교체
- 2개 ORM 메서드 → `query()` (SQL 새로 작성)
- ✅ 모든 단위 테스트 통과
- ✅ **Prisma import 완전 제거**
---
## 🔍 Prisma 사용 현황 분석
### 1. `$queryRaw` / `$queryRawUnsafe` 사용 (11개)
**현재 상태**: SQL은 이미 작성되어 있음 ✅
**전환 작업**: `prisma.$queryRaw` → `query()` 함수로 교체만 하면 됨
```typescript
// 기존
await prisma.$queryRaw<Array<{ column_name; data_type }>>`...`;
await prisma.$queryRawUnsafe(upsertQuery, ...values);
// 전환 후
import { query } from "../database/db";
await query<Array<{ column_name: string; data_type: string }>>(`...`);
await query(upsertQuery, values);
```
### 2. ORM 메서드 사용 (2개)
**현재 상태**: Prisma ORM 메서드 사용
**전환 작업**: SQL 작성 필요
#### 1. dynamic_form_data 조회 (1개)
```typescript
// Line 867: 폼 데이터 조회
const result = await prisma.dynamic_form_data.findUnique({
where: { id },
select: { data: true },
});
```
#### 2. screen_layouts 조회 (1개)
```typescript
// Line 1101: 화면 레이아웃 조회
const screenLayouts = await prisma.screen_layouts.findMany({
where: {
screen_id: screenId,
component_type: "widget",
},
select: {
component_id: true,
properties: true,
},
});
```
---
## 📝 전환 예시
### 예시 1: dynamic_form_data 조회 전환
**기존 Prisma 코드:**
```typescript
const result = await prisma.dynamic_form_data.findUnique({
where: { id },
select: { data: true },
});
```
**새로운 Raw Query 코드:**
```typescript
import { queryOne } from "../database/db";
const result = await queryOne<{ data: any }>(
`SELECT data FROM dynamic_form_data WHERE id = $1`,
[id]
);
```
### 예시 2: screen_layouts 조회 전환
**기존 Prisma 코드:**
```typescript
const screenLayouts = await prisma.screen_layouts.findMany({
where: {
screen_id: screenId,
component_type: "widget",
},
select: {
component_id: true,
properties: true,
},
});
```
**새로운 Raw Query 코드:**
```typescript
import { query } from "../database/db";
const screenLayouts = await query<{
component_id: string;
properties: any;
}>(
`SELECT component_id, properties
FROM screen_layouts
WHERE screen_id = $1 AND component_type = $2`,
[screenId, "widget"]
);
```
---
## 🧪 테스트 계획
### 단위 테스트 (5개)
```typescript
describe("DynamicFormService Raw Query 전환 테스트", () => {
describe("getFormDataById", () => {
test("폼 데이터 조회 성공", async () => { ... });
test("존재하지 않는 데이터", async () => { ... });
});
describe("getScreenLayoutsForControl", () => {
test("화면 레이아웃 조회 성공", async () => { ... });
test("widget 타입만 필터링", async () => { ... });
test("빈 결과 처리", async () => { ... });
});
});
```
### 통합 테스트 (3개 시나리오)
```typescript
describe("동적 폼 통합 테스트", () => {
test("폼 데이터 UPSERT → 조회", async () => { ... });
test("폼 데이터 업데이트 → 조회", async () => { ... });
test("화면 레이아웃 조회 → 제어 설정 확인", async () => { ... });
});
```
---
## 📋 전환 완료 내역
### ✅ 전환된 함수들 (13개 Raw Query 호출)
1. **getTableColumnInfo()** - 컬럼 정보 조회
2. **getPrimaryKeyColumns()** - 기본 키 조회
3. **getNotNullColumns()** - NOT NULL 컬럼 조회
4. **upsertFormData()** - UPSERT 실행
5. **partialUpdateFormData()** - 부분 업데이트
6. **updateFormData()** - 전체 업데이트
7. **deleteFormData()** - 데이터 삭제
8. **getFormDataById()** - 폼 데이터 조회
9. **getTableColumns()** - 테이블 컬럼 조회
10. **getTablePrimaryKeys()** - 기본 키 조회
11. **getScreenLayoutsForControl()** - 화면 레이아웃 조회
### 🔧 주요 기술적 해결 사항
1. **Prisma import 완전 제거**: `import { query, queryOne } from "../database/db"`
2. **동적 UPSERT 쿼리**: PostgreSQL ON CONFLICT 구문 사용
3. **부분 업데이트**: 동적 SET 절 생성
4. **타입 변환**: PostgreSQL 타입 자동 변환 로직 유지
## 📋 체크리스트
### 1단계: ORM 호출 전환 ✅ **완료**
- [x] `getFormDataById()` - queryOne 전환
- [x] `getScreenLayoutsForControl()` - query 전환
- [x] 모든 Raw Query 함수 전환
### 2단계: 테스트 & 검증 ⏳ **진행 예정**
- [ ] 단위 테스트 작성 (5개)
- [ ] 통합 테스트 작성 (3개 시나리오)
- [x] Prisma import 완전 제거 확인 ✅
- [ ] 성능 테스트
---
## 🎯 완료 기준
- [x] **13개 모든 Prisma 호출을 Raw Query로 전환 완료** ✅
- [x] 11개 `$queryRaw` → `query()` 함수로 교체 ✅
- [x] 2개 ORM 메서드 → `query()` 함수로 전환 ✅
- [x] **모든 TypeScript 컴파일 오류 해결** ✅
- [x] **`import prisma` 완전 제거** ✅
- [ ] **모든 단위 테스트 통과 (5개)** ⏳
- [ ] **모든 통합 테스트 작성 완료 (3개 시나리오)** ⏳
- [ ] **성능 저하 없음** ⏳
---
**작성일**: 2025-09-30
**완료일**: 2025-10-01
**소요 시간**: 완료됨 (이전에 전환)
**담당자**: 백엔드 개발팀
**우선순위**: 🟢 낮음 (Phase 2.4)
**상태**: ✅ **전환 완료** (테스트 필요)
**특이사항**: SQL은 이미 작성되어 있었고, `query()` 함수로 교체 완료

125
PHASE2.5_EXTERNAL_DB_CONNECTION_MIGRATION.md
View File

@ -1,125 +0,0 @@
# 🔌 Phase 2.5: ExternalDbConnectionService Raw Query 전환 계획
## 📋 개요
ExternalDbConnectionService는 **15개의 Prisma 호출**이 있으며, 외부 데이터베이스 연결 정보를 관리하는 서비스입니다.
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | ---------------------------------------------------------- |
| 파일 위치 | `backend-node/src/services/externalDbConnectionService.ts` |
| 파일 크기 | 1,100+ 라인 |
| Prisma 호출 | 0개 (전환 완료) |
| **현재 진행률** | **15/15 (100%)** ✅ **완료** |
| 복잡도 | 중간 (CRUD + 연결 테스트) |
| 우선순위 | 🟡 중간 (Phase 2.5) |
| **상태** | ✅ **전환 완료 및 컴파일 성공** |
### 🎯 전환 목표
- ✅ 15개 Prisma 호출을 모두 Raw Query로 전환
- ✅ 민감 정보 암호화 처리 유지
- ✅ 연결 테스트 로직 정상 동작
- ✅ 모든 단위 테스트 통과
---
## 🔍 주요 기능
### 1. 외부 DB 연결 정보 CRUD
- 생성, 조회, 수정, 삭제
- 연결 정보 암호화/복호화
### 2. 연결 테스트
- MySQL, PostgreSQL, MSSQL, Oracle 연결 테스트
### 3. 연결 정보 관리
- 회사별 연결 정보 조회
- 활성/비활성 상태 관리
---
## 📝 예상 전환 패턴
### CRUD 작업
```typescript
// 생성
await query(
`INSERT INTO external_db_connections
(connection_name, db_type, host, port, database_name, username, password, company_code)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
RETURNING *`,
[...]
);
// 조회
await query(
`SELECT * FROM external_db_connections
WHERE company_code = $1 AND is_active = 'Y'`,
[companyCode]
);
// 수정
await query(
`UPDATE external_db_connections
SET connection_name = $1, host = $2, ...
WHERE connection_id = $2`,
[...]
);
// 삭제 (소프트)
await query(
`UPDATE external_db_connections
SET is_active = 'N'
WHERE connection_id = $1`,
[connectionId]
);
```
---
## 📋 전환 완료 내역
### ✅ 전환된 함수들 (15개 Prisma 호출)
1. **getConnections()** - 동적 WHERE 조건 생성으로 전환
2. **getConnectionsGroupedByType()** - DB 타입 카테고리 조회
3. **getConnectionById()** - 단일 연결 조회 (비밀번호 마스킹)
4. **getConnectionByIdWithPassword()** - 비밀번호 포함 조회
5. **createConnection()** - 새 연결 생성 + 중복 확인
6. **updateConnection()** - 동적 필드 업데이트
7. **deleteConnection()** - 물리 삭제
8. **testConnectionById()** - 연결 테스트용 조회
9. **getDecryptedPassword()** - 비밀번호 복호화용 조회
10. **executeQuery()** - 쿼리 실행용 조회
11. **getTables()** - 테이블 목록 조회용
### 🔧 주요 기술적 해결 사항
1. **동적 WHERE 조건 생성**: 필터 조건에 따라 동적으로 SQL 생성
2. **동적 UPDATE 쿼리**: 변경된 필드만 업데이트하도록 구현
3. **ILIKE 검색**: 대소문자 구분 없는 검색 지원
4. **암호화 로직 유지**: PasswordEncryption 클래스와 통합 유지
## 🎯 완료 기준
- [x] **15개 Prisma 호출 모두 Raw Query로 전환** ✅
- [x] **암호화/복호화 로직 정상 동작** ✅
- [x] **연결 테스트 정상 동작** ✅
- [ ] **모든 단위 테스트 통과 (10개 이상)** ⏳
- [x] **Prisma import 완전 제거** ✅
- [x] **TypeScript 컴파일 성공** ✅
---
**작성일**: 2025-09-30
**완료일**: 2025-10-01
**소요 시간**: 1시간
**담당자**: 백엔드 개발팀
**우선순위**: 🟡 중간 (Phase 2.5)
**상태**: ✅ **전환 완료** (테스트 필요)

225
PHASE2.6_DATAFLOW_CONTROL_MIGRATION.md
View File

@ -1,225 +0,0 @@
# 🎮 Phase 2.6: DataflowControlService Raw Query 전환 계획
## 📋 개요
DataflowControlService는 **6개의 Prisma 호출**이 있으며, 데이터플로우 제어 및 실행을 담당하는 서비스입니다.
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | ----------------------------------------------------- |
| 파일 위치 | `backend-node/src/services/dataflowControlService.ts` |
| 파일 크기 | 1,100+ 라인 |
| Prisma 호출 | 0개 (전환 완료) |
| **현재 진행률** | **6/6 (100%)** ✅ **완료** |
| 복잡도 | 높음 (복잡한 비즈니스 로직) |
| 우선순위 | 🟡 중간 (Phase 2.6) |
| **상태** | ✅ **전환 완료 및 컴파일 성공** |
### 🎯 전환 목표
- ✅ **6개 모든 Prisma 호출을 `db.ts`의 `query()` 함수로 교체**
- ✅ 복잡한 비즈니스 로직 정상 동작 확인
- ✅ 모든 단위 테스트 통과
- ✅ **Prisma import 완전 제거**
---
## 🔍 Prisma 사용 현황 분석
### 주요 기능
1. **데이터플로우 실행 관리**
- 관계 기반 데이터 조회 및 저장
- 조건부 실행 로직
2. **트랜잭션 처리**
- 여러 테이블에 걸친 데이터 처리
3. **데이터 변환 및 매핑**
- 소스-타겟 데이터 변환
---
## 📝 전환 계획
### 1단계: 기본 조회 전환 (2개 함수)
**함수 목록**:
- `getRelationshipById()` - 관계 정보 조회
- `getDataflowConfig()` - 데이터플로우 설정 조회
### 2단계: 데이터 실행 로직 전환 (2개 함수)
**함수 목록**:
- `executeDataflow()` - 데이터플로우 실행
- `validateDataflow()` - 데이터플로우 검증
### 3단계: 복잡한 기능 - 트랜잭션 (2개 함수)
**함수 목록**:
- `executeWithTransaction()` - 트랜잭션 내 실행
- `rollbackOnError()` - 에러 시 롤백
---
## 💻 전환 예시
### 예시 1: 관계 정보 조회
```typescript
// 기존 Prisma
const relationship = await prisma.table_relationship.findUnique({
where: { relationship_id: relationshipId },
include: {
source_table: true,
target_table: true,
},
});
// 전환 후
import { query } from "../database/db";
const relationship = await query<TableRelationship>(
`SELECT
tr.*,
st.table_name as source_table_name,
tt.table_name as target_table_name
FROM table_relationship tr
LEFT JOIN table_labels st ON tr.source_table_id = st.table_id
LEFT JOIN table_labels tt ON tr.target_table_id = tt.table_id
WHERE tr.relationship_id = $1`,
[relationshipId]
);
```
### 예시 2: 트랜잭션 내 실행
```typescript
// 기존 Prisma
await prisma.$transaction(async (tx) => {
// 소스 데이터 조회
const sourceData = await tx.dynamic_form_data.findMany(...);
// 타겟 데이터 저장
await tx.dynamic_form_data.createMany(...);
// 실행 로그 저장
await tx.dataflow_execution_log.create(...);
});
// 전환 후
import { transaction } from "../database/db";
await transaction(async (client) => {
// 소스 데이터 조회
const sourceData = await client.query(
`SELECT * FROM dynamic_form_data WHERE ...`,
[...]
);
// 타겟 데이터 저장
await client.query(
`INSERT INTO dynamic_form_data (...) VALUES (...)`,
[...]
);
// 실행 로그 저장
await client.query(
`INSERT INTO dataflow_execution_log (...) VALUES (...)`,
[...]
);
});
```
---
## ✅ 5단계: 테스트 & 검증
### 단위 테스트 (10개)
- [ ] getRelationshipById - 관계 정보 조회
- [ ] getDataflowConfig - 설정 조회
- [ ] executeDataflow - 데이터플로우 실행
- [ ] validateDataflow - 검증
- [ ] executeWithTransaction - 트랜잭션 실행
- [ ] rollbackOnError - 에러 처리
- [ ] transformData - 데이터 변환
- [ ] mapSourceToTarget - 필드 매핑
- [ ] applyConditions - 조건 적용
- [ ] logExecution - 실행 로그
### 통합 테스트 (4개 시나리오)
1. **데이터플로우 실행 시나리오**
- 관계 조회 → 데이터 실행 → 로그 저장
2. **트랜잭션 테스트**
- 여러 테이블 동시 처리
- 에러 발생 시 롤백
3. **조건부 실행 테스트**
- 조건에 따른 데이터 처리
4. **데이터 변환 테스트**
- 소스-타겟 데이터 매핑
---
## 📋 전환 완료 내역
### ✅ 전환된 함수들 (6개 Prisma 호출)
1. **executeDataflowControl()** - 관계도 정보 조회 (findUnique → queryOne)
2. **evaluateActionConditions()** - 대상 테이블 조건 확인 ($queryRawUnsafe → query)
3. **executeInsertAction()** - INSERT 실행 ($executeRawUnsafe → query)
4. **executeUpdateAction()** - UPDATE 실행 ($executeRawUnsafe → query)
5. **executeDeleteAction()** - DELETE 실행 ($executeRawUnsafe → query)
6. **checkColumnExists()** - 컬럼 존재 확인 ($queryRawUnsafe → query)
### 🔧 주요 기술적 해결 사항
1. **Prisma import 완전 제거**: `import { query, queryOne } from "../database/db"`
2. **동적 테이블 쿼리 전환**: `$queryRawUnsafe` / `$executeRawUnsafe` → `query()`
3. **파라미터 바인딩 수정**: MySQL `?` → PostgreSQL `$1, $2...`
4. **복잡한 비즈니스 로직 유지**: 조건부 실행, 다중 커넥션, 에러 처리
## 🎯 완료 기준
- [x] **6개 모든 Prisma 호출을 Raw Query로 전환 완료** ✅
- [x] **모든 TypeScript 컴파일 오류 해결** ✅
- [x] **`import prisma` 완전 제거** ✅
- [ ] **트랜잭션 정상 동작 확인** ⏳
- [ ] **복잡한 비즈니스 로직 정상 동작** ⏳
- [ ] **모든 단위 테스트 통과 (10개)** ⏳
- [ ] **모든 통합 테스트 작성 완료 (4개 시나리오)** ⏳
- [ ] **성능 저하 없음** ⏳
---
## 💡 특이사항
### 복잡한 비즈니스 로직
이 서비스는 데이터플로우 제어라는 복잡한 비즈니스 로직을 처리합니다:
- 조건부 실행 로직
- 데이터 변환 및 매핑
- 트랜잭션 관리
- 에러 처리 및 롤백
### 성능 최적화 중요
데이터플로우 실행은 대량의 데이터를 처리할 수 있으므로:
- 배치 처리 고려
- 인덱스 활용
- 쿼리 최적화
---
**작성일**: 2025-09-30
**완료일**: 2025-10-01
**소요 시간**: 30분
**담당자**: 백엔드 개발팀
**우선순위**: 🟡 중간 (Phase 2.6)
**상태**: ✅ **전환 완료** (테스트 필요)
**특이사항**: 복잡한 비즈니스 로직이 포함되어 있어 신중한 테스트 필요

175
PHASE2.7_DDL_EXECUTION_MIGRATION.md
View File

@ -1,175 +0,0 @@
# 🔧 Phase 2.7: DDLExecutionService Raw Query 전환 계획
## 📋 개요
DDLExecutionService는 **4개의 Prisma 호출**이 있으며, DDL(Data Definition Language) 실행 및 관리를 담당하는 서비스입니다.
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | -------------------------------------------------- |
| 파일 위치 | `backend-node/src/services/ddlExecutionService.ts` |
| 파일 크기 | 400+ 라인 |
| Prisma 호출 | 4개 |
| **현재 진행률** | **6/6 (100%)** ✅ **완료** |
| 복잡도 | 중간 (DDL 실행 + 로그 관리) |
| 우선순위 | 🔴 최우선 (테이블 추가 기능 - Phase 2.3으로 변경) |
### 🎯 전환 목표
- ✅ **4개 모든 Prisma 호출을 `db.ts`의 `query()` 함수로 교체**
- ✅ DDL 실행 정상 동작 확인
- ✅ 모든 단위 테스트 통과
- ✅ **Prisma import 완전 제거**
---
## 🔍 Prisma 사용 현황 분석
### 주요 기능
1. **DDL 실행**
- CREATE TABLE, ALTER TABLE, DROP TABLE
- CREATE INDEX, DROP INDEX
2. **실행 로그 관리**
- DDL 실행 이력 저장
- 에러 로그 관리
3. **롤백 지원**
- DDL 롤백 SQL 생성 및 실행
---
## 📝 전환 계획
### 1단계: DDL 실행 전환 (2개 함수)
**함수 목록**:
- `executeDDL()` - DDL 실행
- `validateDDL()` - DDL 문법 검증
### 2단계: 로그 관리 전환 (2개 함수)
**함수 목록**:
- `saveDDLLog()` - 실행 로그 저장
- `getDDLHistory()` - 실행 이력 조회
---
## 💻 전환 예시
### 예시 1: DDL 실행 및 로그 저장
```typescript
// 기존 Prisma
await prisma.$executeRawUnsafe(ddlQuery);
await prisma.ddl_execution_log.create({
data: {
ddl_statement: ddlQuery,
execution_status: "SUCCESS",
executed_by: userId,
},
});
// 전환 후
import { query } from "../database/db";
await query(ddlQuery);
await query(
`INSERT INTO ddl_execution_log
(ddl_statement, execution_status, executed_by, executed_date)
VALUES ($1, $2, $3, $4)`,
[ddlQuery, "SUCCESS", userId, new Date()]
);
```
### 예시 2: DDL 실행 이력 조회
```typescript
// 기존 Prisma
const history = await prisma.ddl_execution_log.findMany({
where: {
company_code: companyCode,
execution_status: "SUCCESS",
},
orderBy: { executed_date: "desc" },
take: 50,
});
// 전환 후
import { query } from "../database/db";
const history = await query<DDLLog[]>(
`SELECT * FROM ddl_execution_log
WHERE company_code = $1
AND execution_status = $2
ORDER BY executed_date DESC
LIMIT $3`,
[companyCode, "SUCCESS", 50]
);
```
---
## ✅ 3단계: 테스트 & 검증
### 단위 테스트 (8개)
- [ ] executeDDL - CREATE TABLE
- [ ] executeDDL - ALTER TABLE
- [ ] executeDDL - DROP TABLE
- [ ] executeDDL - CREATE INDEX
- [ ] validateDDL - 문법 검증
- [ ] saveDDLLog - 로그 저장
- [ ] getDDLHistory - 이력 조회
- [ ] rollbackDDL - DDL 롤백
### 통합 테스트 (3개 시나리오)
1. **테이블 생성 → 로그 저장 → 이력 조회**
2. **DDL 실행 실패 → 에러 로그 저장**
3. **DDL 롤백 테스트**
---
## 🎯 완료 기준
- [ ] **4개 모든 Prisma 호출을 Raw Query로 전환 완료**
- [ ] **모든 TypeScript 컴파일 오류 해결**
- [ ] **DDL 실행 정상 동작 확인**
- [ ] **모든 단위 테스트 통과 (8개)**
- [ ] **모든 통합 테스트 작성 완료 (3개 시나리오)**
- [ ] **`import prisma` 완전 제거 및 `import { query } from "../database/db"` 사용**
- [ ] **성능 저하 없음**
---
## 💡 특이사항
### DDL 실행의 위험성
DDL은 데이터베이스 스키마를 변경하므로 매우 신중하게 처리해야 합니다:
- 실행 전 검증 필수
- 롤백 SQL 자동 생성
- 실행 이력 철저히 관리
### 트랜잭션 지원 제한
PostgreSQL에서 일부 DDL은 트랜잭션을 지원하지만, 일부는 자동 커밋됩니다:
- CREATE TABLE: 트랜잭션 지원 ✅
- DROP TABLE: 트랜잭션 지원 ✅
- CREATE INDEX CONCURRENTLY: 트랜잭션 미지원 ❌
---
**작성일**: 2025-09-30
**예상 소요 시간**: 0.5일
**담당자**: 백엔드 개발팀
**우선순위**: 🟢 낮음 (Phase 2.7)
**상태**: ⏳ **진행 예정**
**특이사항**: DDL 실행의 특성상 신중한 테스트 필요

566
PHASE2_SCREEN_MANAGEMENT_MIGRATION.md
View File

@ -1,566 +0,0 @@
# 🖥️ Phase 2.1: ScreenManagementService Raw Query 전환 계획
## 📋 개요
ScreenManagementService는 **46개의 Prisma 호출**이 있는 가장 복잡한 서비스입니다. 화면 정의, 레이아웃, 메뉴 할당, 템플릿 등 다양한 기능을 포함합니다.
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | ------------------------------------------------------ |
| 파일 위치 | `backend-node/src/services/screenManagementService.ts` |
| 파일 크기 | 1,700+ 라인 |
| Prisma 호출 | 46개 |
| **현재 진행률** | **46/46 (100%)** ✅ **완료** |
| 복잡도 | 매우 높음 |
| 우선순위 | 🔴 최우선 |
### 🎯 전환 현황 (2025-09-30 업데이트)
- ✅ **Stage 1 완료**: 기본 CRUD (8개 함수) - Commit: 13c1bc4, 0e8d1d4
- ✅ **Stage 2 완료**: 레이아웃 관리 (2개 함수, 4 Prisma 호출) - Commit: 67dced7
- ✅ **Stage 3 완료**: 템플릿 & 메뉴 관리 (5개 함수) - Commit: 74351e8
- ✅ **Stage 4 완료**: 복잡한 기능 (트랜잭션) - **모든 46개 Prisma 호출 전환 완료**
---
## 🔍 Prisma 사용 현황 분석
### 1. 화면 정의 관리 (Screen Definitions) - 18개
```typescript
// Line 53: 화면 코드 중복 확인
await prisma.screen_definitions.findFirst({ where: { screen_code, is_active: { not: "D" } } })
// Line 70: 화면 생성
await prisma.screen_definitions.create({ data: { ... } })
// Line 99: 화면 목록 조회 (페이징)
await prisma.screen_definitions.findMany({ where, skip, take, orderBy })
// Line 105: 화면 총 개수
await prisma.screen_definitions.count({ where })
// Line 166: 전체 화면 목록
await prisma.screen_definitions.findMany({ where })
// Line 178: 화면 코드로 조회
await prisma.screen_definitions.findFirst({ where: { screen_code } })
// Line 205: 화면 ID로 조회
await prisma.screen_definitions.findFirst({ where: { screen_id } })
// Line 221: 화면 존재 확인
await prisma.screen_definitions.findUnique({ where: { screen_id } })
// Line 236: 화면 업데이트
await prisma.screen_definitions.update({ where, data })
// Line 268: 화면 복사 - 원본 조회
await prisma.screen_definitions.findUnique({ where, include: { screen_layouts } })
// Line 292: 화면 순서 변경 - 전체 조회
await prisma.screen_definitions.findMany({ where })
// Line 486: 화면 템플릿 적용 - 존재 확인
await prisma.screen_definitions.findUnique({ where })
// Line 557: 화면 복사 - 존재 확인
await prisma.screen_definitions.findUnique({ where })
// Line 578: 화면 복사 - 중복 확인
await prisma.screen_definitions.findFirst({ where })
// Line 651: 화면 삭제 - 존재 확인
await prisma.screen_definitions.findUnique({ where })
// Line 672: 화면 삭제 (물리 삭제)
await prisma.screen_definitions.delete({ where })
// Line 700: 삭제된 화면 조회
await prisma.screen_definitions.findMany({ where: { is_active: "D" } })
// Line 706: 삭제된 화면 개수
await prisma.screen_definitions.count({ where })
// Line 763: 일괄 삭제 - 화면 조회
await prisma.screen_definitions.findMany({ where })
// Line 1083: 레이아웃 저장 - 화면 확인
await prisma.screen_definitions.findUnique({ where })
// Line 1181: 레이아웃 조회 - 화면 확인
await prisma.screen_definitions.findUnique({ where })
// Line 1655: 위젯 데이터 저장 - 화면 존재 확인
await prisma.screen_definitions.findMany({ where })
```
### 2. 레이아웃 관리 (Screen Layouts) - 4개
```typescript
// Line 1096: 레이아웃 삭제
await prisma.screen_layouts.deleteMany({ where: { screen_id } });
// Line 1107: 레이아웃 생성 (단일)
await prisma.screen_layouts.create({ data });
// Line 1152: 레이아웃 생성 (다중)
await prisma.screen_layouts.create({ data });
// Line 1193: 레이아웃 조회
await prisma.screen_layouts.findMany({ where });
```
### 3. 템플릿 관리 (Screen Templates) - 2개
```typescript
// Line 1303: 템플릿 목록 조회
await prisma.screen_templates.findMany({ where });
// Line 1317: 템플릿 생성
await prisma.screen_templates.create({ data });
```
### 4. 메뉴 할당 (Screen Menu Assignments) - 5개
```typescript
// Line 446: 메뉴 할당 조회
await prisma.screen_menu_assignments.findMany({ where });
// Line 1346: 메뉴 할당 중복 확인
await prisma.screen_menu_assignments.findFirst({ where });
// Line 1358: 메뉴 할당 생성
await prisma.screen_menu_assignments.create({ data });
// Line 1376: 화면별 메뉴 할당 조회
await prisma.screen_menu_assignments.findMany({ where });
// Line 1401: 메뉴 할당 삭제
await prisma.screen_menu_assignments.deleteMany({ where });
```
### 5. 테이블 레이블 (Table Labels) - 3개
```typescript
// Line 117: 테이블 레이블 조회 (페이징)
await prisma.table_labels.findMany({ where, skip, take });
// Line 713: 테이블 레이블 조회 (전체)
await prisma.table_labels.findMany({ where });
```
### 6. 컬럼 레이블 (Column Labels) - 2개
```typescript
// Line 948: 웹타입 정보 조회
await prisma.column_labels.findMany({ where, select });
// Line 1456: 컬럼 레이블 UPSERT
await prisma.column_labels.upsert({ where, create, update });
```
### 7. Raw Query 사용 (이미 있음) - 6개
```typescript
// Line 627: 화면 순서 변경 (일괄 업데이트)
await prisma.$executeRaw`UPDATE screen_definitions SET display_order = ...`;
// Line 833: 테이블 목록 조회
await prisma.$queryRaw<Array<{ table_name: string }>>`SELECT tablename ...`;
// Line 876: 테이블 존재 확인
await prisma.$queryRaw<Array<{ table_name: string }>>`SELECT tablename ...`;
// Line 922: 테이블 컬럼 정보 조회
await prisma.$queryRaw<Array<ColumnInfo>>`SELECT column_name, data_type ...`;
// Line 1418: 컬럼 정보 조회 (상세)
await prisma.$queryRaw`SELECT column_name, data_type ...`;
```
### 8. 트랜잭션 사용 - 3개
```typescript
// Line 521: 화면 템플릿 적용 트랜잭션
await prisma.$transaction(async (tx) => { ... })
// Line 593: 화면 복사 트랜잭션
await prisma.$transaction(async (tx) => { ... })
// Line 788: 일괄 삭제 트랜잭션
await prisma.$transaction(async (tx) => { ... })
// Line 1697: 위젯 데이터 저장 트랜잭션
await prisma.$transaction(async (tx) => { ... })
```
---
## 🛠️ 전환 전략
### 전략 1: 단계적 전환
1. **1단계**: 단순 CRUD 전환 (findFirst, findMany, create, update, delete)
2. **2단계**: 복잡한 조회 전환 (include, join)
3. **3단계**: 트랜잭션 전환
4. **4단계**: Raw Query 개선
### 전략 2: 함수별 전환 우선순위
#### 🔴 최우선 (기본 CRUD)
- `createScreen()` - Line 70
- `getScreensByCompany()` - Line 99-105
- `getScreenByCode()` - Line 178
- `getScreenById()` - Line 205
- `updateScreen()` - Line 236
- `deleteScreen()` - Line 672
#### 🟡 2순위 (레이아웃)
- `saveLayout()` - Line 1096-1152
- `getLayout()` - Line 1193
- `deleteLayout()` - Line 1096
#### 🟢 3순위 (템플릿 & 메뉴)
- `getTemplates()` - Line 1303
- `createTemplate()` - Line 1317
- `assignToMenu()` - Line 1358
- `getMenuAssignments()` - Line 1376
- `removeMenuAssignment()` - Line 1401
#### 🔵 4순위 (복잡한 기능)
- `copyScreen()` - Line 593 (트랜잭션)
- `applyTemplate()` - Line 521 (트랜잭션)
- `bulkDelete()` - Line 788 (트랜잭션)
- `reorderScreens()` - Line 627 (Raw Query)
---
## 📝 전환 예시
### 예시 1: createScreen() 전환
**기존 Prisma 코드:**
```typescript
// Line 53: 중복 확인
const existingScreen = await prisma.screen_definitions.findFirst({
where: {
screen_code: screenData.screenCode,
is_active: { not: "D" },
},
});
// Line 70: 생성
const screen = await prisma.screen_definitions.create({
data: {
screen_name: screenData.screenName,
screen_code: screenData.screenCode,
table_name: screenData.tableName,
company_code: screenData.companyCode,
description: screenData.description,
created_by: screenData.createdBy,
},
});
```
**새로운 Raw Query 코드:**
```typescript
import { query } from "../database/db";
// 중복 확인
const existingResult = await query<{ screen_id: number }>(
`SELECT screen_id FROM screen_definitions
WHERE screen_code = $1 AND is_active != 'D'
LIMIT 1`,
[screenData.screenCode]
);
if (existingResult.length > 0) {
throw new Error("이미 존재하는 화면 코드입니다.");
}
// 생성
const [screen] = await query<ScreenDefinition>(
`INSERT INTO screen_definitions (
screen_name, screen_code, table_name, company_code, description, created_by
) VALUES ($1, $2, $3, $4, $5, $6)
RETURNING *`,
[
screenData.screenName,
screenData.screenCode,
screenData.tableName,
screenData.companyCode,
screenData.description,
screenData.createdBy,
]
);
```
### 예시 2: getScreensByCompany() 전환 (페이징)
**기존 Prisma 코드:**
```typescript
const [screens, total] = await Promise.all([
prisma.screen_definitions.findMany({
where: whereClause,
skip: (page - 1) * size,
take: size,
orderBy: { created_at: "desc" },
}),
prisma.screen_definitions.count({ where: whereClause }),
]);
```
**새로운 Raw Query 코드:**
```typescript
const offset = (page - 1) * size;
const whereSQL =
companyCode !== "*"
? "WHERE company_code = $1 AND is_active != 'D'"
: "WHERE is_active != 'D'";
const params =
companyCode !== "*" ? [companyCode, size, offset] : [size, offset];
const [screens, totalResult] = await Promise.all([
query<ScreenDefinition>(
`SELECT * FROM screen_definitions
${whereSQL}
ORDER BY created_at DESC
LIMIT $${params.length - 1} OFFSET $${params.length}`,
params
),
query<{ count: number }>(
`SELECT COUNT(*) as count FROM screen_definitions ${whereSQL}`,
companyCode !== "*" ? [companyCode] : []
),
]);
const total = totalResult[0]?.count || 0;
```
### 예시 3: 트랜잭션 전환
**기존 Prisma 코드:**
```typescript
await prisma.$transaction(async (tx) => {
const newScreen = await tx.screen_definitions.create({ data: { ... } });
await tx.screen_layouts.createMany({ data: layouts });
});
```
**새로운 Raw Query 코드:**
```typescript
import { transaction } from "../database/db";
await transaction(async (client) => {
const [newScreen] = await client.query(
`INSERT INTO screen_definitions (...) VALUES (...) RETURNING *`,
[...]
);
for (const layout of layouts) {
await client.query(
`INSERT INTO screen_layouts (...) VALUES (...)`,
[...]
);
}
});
```
---
## 🧪 테스트 계획
### 단위 테스트
```typescript
describe("ScreenManagementService Raw Query 전환 테스트", () => {
describe("createScreen", () => {
test("화면 생성 성공", async () => { ... });
test("중복 화면 코드 에러", async () => { ... });
});
describe("getScreensByCompany", () => {
test("페이징 조회 성공", async () => { ... });
test("회사별 필터링", async () => { ... });
});
describe("copyScreen", () => {
test("화면 복사 성공 (트랜잭션)", async () => { ... });
test("레이아웃 함께 복사", async () => { ... });
});
});
```
### 통합 테스트
```typescript
describe("화면 관리 통합 테스트", () => {
test("화면 생성 → 조회 → 수정 → 삭제", async () => { ... });
test("화면 복사 → 레이아웃 확인", async () => { ... });
test("메뉴 할당 → 조회 → 해제", async () => { ... });
});
```
---
## 📋 체크리스트
### 1단계: 기본 CRUD (8개 함수) ✅ **완료**
- [x] `createScreen()` - 화면 생성
- [x] `getScreensByCompany()` - 화면 목록 (페이징)
- [x] `getScreenByCode()` - 화면 코드로 조회
- [x] `getScreenById()` - 화면 ID로 조회
- [x] `updateScreen()` - 화면 업데이트
- [x] `deleteScreen()` - 화면 삭제
- [x] `getScreens()` - 전체 화면 목록 조회
- [x] `getScreen()` - 회사 코드 필터링 포함 조회
### 2단계: 레이아웃 관리 (2개 함수) ✅ **완료**
- [x] `saveLayout()` - 레이아웃 저장 (메타데이터 + 컴포넌트)
- [x] `getLayout()` - 레이아웃 조회
- [x] 레이아웃 삭제 로직 (saveLayout 내부에 포함)
### 3단계: 템플릿 & 메뉴 (5개 함수) ✅ **완료**
- [x] `getTemplatesByCompany()` - 템플릿 목록
- [x] `createTemplate()` - 템플릿 생성
- [x] `assignScreenToMenu()` - 메뉴 할당
- [x] `getScreensByMenu()` - 메뉴별 화면 조회
- [x] `unassignScreenFromMenu()` - 메뉴 할당 해제
- [ ] 테이블 레이블 조회 (getScreensByCompany 내부에 포함됨)
### 4단계: 복잡한 기능 (4개 함수) ✅ **완료**
- [x] `copyScreen()` - 화면 복사 (트랜잭션)
- [x] `generateScreenCode()` - 화면 코드 자동 생성
- [x] `checkScreenDependencies()` - 화면 의존성 체크 (메뉴 할당 포함)
- [x] 모든 유틸리티 메서드 Raw Query 전환
### 5단계: 테스트 & 검증 ✅ **완료**
- [x] 단위 테스트 작성 (18개 테스트 통과)
- createScreen, updateScreen, deleteScreen
- getScreensByCompany, getScreenById
- saveLayout, getLayout
- getTemplatesByCompany, assignScreenToMenu
- copyScreen, generateScreenCode
- getTableColumns
- [x] 통합 테스트 작성 (6개 시나리오)
- 화면 생명주기 테스트 (생성 → 조회 → 수정 → 삭제 → 복원 → 영구삭제)
- 화면 복사 및 레이아웃 테스트
- 테이블 정보 조회 테스트
- 일괄 작업 테스트
- 화면 코드 자동 생성 테스트
- [x] Prisma import 완전 제거 확인
- [ ] 성능 테스트 (추후 실행 예정)
---
## 🎯 완료 기준
- ✅ **46개 Prisma 호출 모두 Raw Query로 전환 완료**
- ✅ **모든 TypeScript 컴파일 오류 해결**
- ✅ **트랜잭션 정상 동작 확인**
- ✅ **에러 처리 및 롤백 정상 동작**
- ✅ **모든 단위 테스트 통과 (18개)**
- ✅ **모든 통합 테스트 작성 완료 (6개 시나리오)**
- ✅ **Prisma import 완전 제거**
- [ ] 성능 저하 없음 (기존 대비 ±10% 이내) - 추후 측정 예정
## 📊 테스트 결과
### 단위 테스트 (18개)
```
✅ createScreen - 화면 생성 (2개 테스트)
✅ getScreensByCompany - 화면 목록 페이징 (2개 테스트)
✅ updateScreen - 화면 업데이트 (2개 테스트)
✅ deleteScreen - 화면 삭제 (2개 테스트)
✅ saveLayout - 레이아웃 저장 (2개 테스트)
- 기본 저장, 소수점 좌표 반올림 처리
✅ getLayout - 레이아웃 조회 (1개 테스트)
✅ getTemplatesByCompany - 템플릿 목록 (1개 테스트)
✅ assignScreenToMenu - 메뉴 할당 (2개 테스트)
✅ copyScreen - 화면 복사 (1개 테스트)
✅ generateScreenCode - 화면 코드 자동 생성 (2개 테스트)
✅ getTableColumns - 테이블 컬럼 정보 (1개 테스트)
Test Suites: 1 passed
Tests: 18 passed
Time: 1.922s
```
### 통합 테스트 (6개 시나리오)
```
✅ 화면 생명주기 테스트
- 생성 → 조회 → 수정 → 삭제 → 복원 → 영구삭제
✅ 화면 복사 및 레이아웃 테스트
- 화면 복사 → 레이아웃 저장 → 레이아웃 확인 → 레이아웃 수정
✅ 테이블 정보 조회 테스트
- 테이블 목록 조회 → 특정 테이블 정보 조회
✅ 일괄 작업 테스트
- 여러 화면 생성 → 일괄 삭제
✅ 화면 코드 자동 생성 테스트
- 순차적 화면 코드 생성 검증
✅ 메뉴 할당 테스트 (skip - 실제 메뉴 데이터 필요)
```
---
## 🐛 버그 수정 및 개선사항
### 실제 운영 환경에서 발견된 이슈
#### 1. 소수점 좌표 저장 오류 (해결 완료)
**문제**:
```
invalid input syntax for type integer: "1602.666666666667"
```
- `position_x`, `position_y`, `width`, `height` 컬럼이 `integer` 타입
- 격자 계산 시 소수점 값이 발생하여 저장 실패
**해결**:
```typescript
Math.round(component.position.x), // 정수로 반올림
Math.round(component.position.y),
Math.round(component.size.width),
Math.round(component.size.height),
```
**테스트 추가**:
- 소수점 좌표 저장 테스트 케이스 추가
- 반올림 처리 검증
**영향 범위**:
- `saveLayout()` 함수
- `copyScreen()` 함수 (레이아웃 복사 시)
---
**작성일**: 2025-09-30
**완료일**: 2025-09-30
**예상 소요 시간**: 2-3일 → **실제 소요 시간**: 1일
**담당자**: 백엔드 개발팀
**우선순위**: 🔴 최우선 (Phase 2.1)
**상태**: ✅ **완료**

407
PHASE3.11_DDL_AUDIT_LOGGER_MIGRATION.md
View File

@ -1,407 +0,0 @@
# 📋 Phase 3.11: DDLAuditLogger Raw Query 전환 계획
## 📋 개요
DDLAuditLogger는 **8개의 Prisma 호출**이 있으며, DDL 실행 감사 로그 관리를 담당하는 서비스입니다.
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | --------------------------------------------- |
| 파일 위치 | `backend-node/src/services/ddlAuditLogger.ts` |
| 파일 크기 | 350 라인 |
| Prisma 호출 | 0개 (전환 완료) |
| **현재 진행률** | **8/8 (100%)** ✅ **전환 완료** |
| 복잡도 | 중간 (통계 쿼리, $executeRaw) |
| 우선순위 | 🟡 중간 (Phase 3.11) |
| **상태** | ✅ **완료** |
### 🎯 전환 목표
- ⏳ **8개 모든 Prisma 호출을 `db.ts`의 `query()`, `queryOne()` 함수로 교체**
- ⏳ DDL 감사 로그 기능 정상 동작
- ⏳ 통계 쿼리 전환 (GROUP BY, COUNT, ORDER BY)
- ⏳ $executeRaw → query 전환
- ⏳ $queryRawUnsafe → query 전환
- ⏳ 동적 WHERE 조건 생성
- ⏳ TypeScript 컴파일 성공
- ⏳ **Prisma import 완전 제거**
---
## 🔍 Prisma 사용 현황 분석
### 주요 Prisma 호출 (8개)
#### 1. **logDDLStart()** - DDL 시작 로그 (INSERT)
```typescript
// Line 27
const logEntry = await prisma.$executeRaw`
INSERT INTO ddl_audit_logs (
execution_id, ddl_type, table_name, status,
executed_by, company_code, started_at, metadata
) VALUES (
${executionId}, ${ddlType}, ${tableName}, 'in_progress',
${executedBy}, ${companyCode}, NOW(), ${JSON.stringify(metadata)}::jsonb
)
`;
```
#### 2. **getAuditLogs()** - 감사 로그 목록 조회 (SELECT with filters)
```typescript
// Line 162
const logs = await prisma.$queryRawUnsafe(query, ...params);
```
- 동적 WHERE 조건 생성
- 페이징 (OFFSET, LIMIT)
- 정렬 (ORDER BY)
#### 3. **getAuditStats()** - 통계 조회 (복합 쿼리)
```typescript
// Line 199 - 총 통계
const totalStats = (await prisma.$queryRawUnsafe(
`SELECT
COUNT(*) as total_executions,
COUNT(CASE WHEN status = 'success' THEN 1 END) as successful,
COUNT(CASE WHEN status = 'failed' THEN 1 END) as failed,
AVG(EXTRACT(EPOCH FROM (completed_at - started_at))) as avg_duration
FROM ddl_audit_logs
WHERE ${whereClause}`
)) as any[];
// Line 212 - DDL 타입별 통계
const ddlTypeStats = (await prisma.$queryRawUnsafe(
`SELECT ddl_type, COUNT(*) as count
FROM ddl_audit_logs
WHERE ${whereClause}
GROUP BY ddl_type
ORDER BY count DESC`
)) as any[];
// Line 224 - 사용자별 통계
const userStats = (await prisma.$queryRawUnsafe(
`SELECT executed_by, COUNT(*) as count
FROM ddl_audit_logs
WHERE ${whereClause}
GROUP BY executed_by
ORDER BY count DESC
LIMIT 10`
)) as any[];
// Line 237 - 최근 실패 로그
const recentFailures = (await prisma.$queryRawUnsafe(
`SELECT * FROM ddl_audit_logs
WHERE status = 'failed' AND ${whereClause}
ORDER BY started_at DESC
LIMIT 5`
)) as any[];
```
#### 4. **getExecutionHistory()** - 실행 이력 조회
```typescript
// Line 287
const history = await prisma.$queryRawUnsafe(
`SELECT * FROM ddl_audit_logs
WHERE table_name = $1 AND company_code = $2
ORDER BY started_at DESC
LIMIT $3`,
tableName,
companyCode,
limit
);
```
#### 5. **cleanupOldLogs()** - 오래된 로그 삭제
```typescript
// Line 320
const result = await prisma.$executeRaw`
DELETE FROM ddl_audit_logs
WHERE started_at < NOW() - INTERVAL '${retentionDays} days'
AND company_code = ${companyCode}
`;
```
---
## 💡 전환 전략
### 1단계: $executeRaw 전환 (2개)
- `logDDLStart()` - INSERT
- `cleanupOldLogs()` - DELETE
### 2단계: 단순 $queryRawUnsafe 전환 (1개)
- `getExecutionHistory()` - 파라미터 바인딩 있음
### 3단계: 복잡한 $queryRawUnsafe 전환 (1개)
- `getAuditLogs()` - 동적 WHERE 조건
### 4단계: 통계 쿼리 전환 (4개)
- `getAuditStats()` 내부의 4개 쿼리
- GROUP BY, CASE WHEN, AVG, EXTRACT
---
## 💻 전환 예시
### 예시 1: $executeRaw → query (INSERT)
**변경 전**:
```typescript
const logEntry = await prisma.$executeRaw`
INSERT INTO ddl_audit_logs (
execution_id, ddl_type, table_name, status,
executed_by, company_code, started_at, metadata
) VALUES (
${executionId}, ${ddlType}, ${tableName}, 'in_progress',
${executedBy}, ${companyCode}, NOW(), ${JSON.stringify(metadata)}::jsonb
)
`;
```
**변경 후**:
```typescript
await query(
`INSERT INTO ddl_audit_logs (
execution_id, ddl_type, table_name, status,
executed_by, company_code, started_at, metadata
) VALUES ($1, $2, $3, $4, $5, $6, NOW(), $7::jsonb)`,
[
executionId,
ddlType,
tableName,
"in_progress",
executedBy,
companyCode,
JSON.stringify(metadata),
]
);
```
### 예시 2: 동적 WHERE 조건
**변경 전**:
```typescript
let query = `SELECT * FROM ddl_audit_logs WHERE 1=1`;
const params: any[] = [];
if (filters.ddlType) {
query += ` AND ddl_type = ?`;
params.push(filters.ddlType);
}
const logs = await prisma.$queryRawUnsafe(query, ...params);
```
**변경 후**:
```typescript
const conditions: string[] = [];
const params: any[] = [];
let paramIndex = 1;
if (filters.ddlType) {
conditions.push(`ddl_type = $${paramIndex++}`);
params.push(filters.ddlType);
}
const whereClause =
conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
const sql = `SELECT * FROM ddl_audit_logs ${whereClause}`;
const logs = await query<any>(sql, params);
```
### 예시 3: 통계 쿼리 (GROUP BY)
**변경 전**:
```typescript
const ddlTypeStats = (await prisma.$queryRawUnsafe(
`SELECT ddl_type, COUNT(*) as count
FROM ddl_audit_logs
WHERE ${whereClause}
GROUP BY ddl_type
ORDER BY count DESC`
)) as any[];
```
**변경 후**:
```typescript
const ddlTypeStats = await query<{ ddl_type: string; count: string }>(
`SELECT ddl_type, COUNT(*) as count
FROM ddl_audit_logs
WHERE ${whereClause}
GROUP BY ddl_type
ORDER BY count DESC`,
params
);
```
---
## 🔧 기술적 고려사항
### 1. JSON 필드 처리
`metadata` 필드는 JSONB 타입으로, INSERT 시 `::jsonb` 캐스팅 필요:
```typescript
JSON.stringify(metadata) + "::jsonb";
```
### 2. 날짜/시간 함수
- `NOW()` - 현재 시간
- `INTERVAL '30 days'` - 날짜 간격
- `EXTRACT(EPOCH FROM ...)` - 초 단위 변환
### 3. CASE WHEN 집계
```sql
COUNT(CASE WHEN status = 'success' THEN 1 END) as successful
```
### 4. 동적 WHERE 조건
여러 필터를 조합하여 WHERE 절 생성:
- ddlType
- tableName
- status
- executedBy
- dateRange (startDate, endDate)
---
## ✅ 전환 완료 내역
### 전환된 Prisma 호출 (8개)
1. **`logDDLExecution()`** - DDL 실행 로그 INSERT
- Before: `prisma.$executeRaw`
- After: `query()` with 7 parameters
2. **`getAuditLogs()`** - 감사 로그 목록 조회
- Before: `prisma.$queryRawUnsafe`
- After: `query<any>()` with dynamic WHERE clause
3. **`getDDLStatistics()`** - 통계 조회 (4개 쿼리)
- Before: 4x `prisma.$queryRawUnsafe`
- After: 4x `query<any>()`
- totalStats: 전체 실행 통계 (CASE WHEN 집계)
- ddlTypeStats: DDL 타입별 통계 (GROUP BY)
- userStats: 사용자별 통계 (GROUP BY, LIMIT 10)
- recentFailures: 최근 실패 로그 (WHERE success = false)
4. **`getTableDDLHistory()`** - 테이블별 DDL 히스토리
- Before: `prisma.$queryRawUnsafe`
- After: `query<any>()` with table_name filter
5. **`cleanupOldLogs()`** - 오래된 로그 삭제
- Before: `prisma.$executeRaw`
- After: `query()` with date filter
### 주요 기술적 개선사항
1. **파라미터 바인딩**: PostgreSQL `$1, $2, ...` 스타일로 통일
2. **동적 WHERE 조건**: 파라미터 인덱스 자동 증가 로직 유지
3. **통계 쿼리**: CASE WHEN, GROUP BY, SUM 등 복잡한 집계 쿼리 완벽 전환
4. **에러 처리**: 기존 try-catch 구조 유지
5. **로깅**: logger 유틸리티 활용 유지
### 코드 정리
- [x] `import { PrismaClient }` 제거
- [x] `const prisma = new PrismaClient()` 제거
- [x] `import { query, queryOne }` 추가
- [x] 모든 타입 정의 유지
- [x] TypeScript 컴파일 성공
- [x] Linter 오류 없음
## 📝 원본 전환 체크리스트
### 1단계: Prisma 호출 전환 (✅ 완료)
- [ ] `logDDLStart()` - INSERT ($executeRaw → query)
- [ ] `logDDLComplete()` - UPDATE (이미 query 사용 중일 가능성)
- [ ] `logDDLError()` - UPDATE (이미 query 사용 중일 가능성)
- [ ] `getAuditLogs()` - SELECT with filters ($queryRawUnsafe → query)
- [ ] `getAuditStats()` 내 4개 쿼리:
- [ ] totalStats (집계 쿼리)
- [ ] ddlTypeStats (GROUP BY)
- [ ] userStats (GROUP BY + LIMIT)
- [ ] recentFailures (필터 + ORDER BY + LIMIT)
- [ ] `getExecutionHistory()` - SELECT with params ($queryRawUnsafe → query)
- [ ] `cleanupOldLogs()` - DELETE ($executeRaw → query)
### 2단계: 코드 정리
- [ ] import 문 수정 (`prisma` → `query, queryOne`)
- [ ] Prisma import 완전 제거
- [ ] 타입 정의 확인
### 3단계: 테스트
- [ ] 단위 테스트 작성 (8개)
- [ ] DDL 시작 로그 테스트
- [ ] DDL 완료 로그 테스트
- [ ] 감사 로그 목록 조회 테스트
- [ ] 통계 조회 테스트
- [ ] 실행 이력 조회 테스트
- [ ] 오래된 로그 삭제 테스트
- [ ] 통합 테스트 작성 (3개)
- [ ] 전체 DDL 실행 플로우 테스트
- [ ] 필터링 및 페이징 테스트
- [ ] 통계 정확성 테스트
- [ ] 성능 테스트
- [ ] 대량 로그 조회 성능
- [ ] 통계 쿼리 성능
### 4단계: 문서화
- [ ] 전환 완료 문서 업데이트
- [ ] 주요 변경사항 기록
- [ ] 성능 벤치마크 결과
---
## 🎯 예상 난이도 및 소요 시간
- **난이도**: ⭐⭐⭐ (중간)
- 복잡한 통계 쿼리 (GROUP BY, CASE WHEN)
- 동적 WHERE 조건 생성
- JSON 필드 처리
- **예상 소요 시간**: 1~1.5시간
- Prisma 호출 전환: 30분
- 테스트: 20분
- 문서화: 10분
---
## 📌 참고사항
### 관련 서비스
- `DDLExecutionService` - DDL 실행 (이미 전환 완료)
- `DDLSafetyValidator` - DDL 안전성 검증
### 의존성
- `../database/db` - query, queryOne 함수
- `../types/ddl` - DDL 관련 타입
- `../utils/logger` - 로깅
---
**상태**: ⏳ **대기 중**
**특이사항**: 통계 쿼리, JSON 필드, 동적 WHERE 조건 포함

356
PHASE3.12_EXTERNAL_CALL_CONFIG_SERVICE_MIGRATION.md
View File

@ -1,356 +0,0 @@
# 📋 Phase 3.12: ExternalCallConfigService Raw Query 전환 계획
## 📋 개요
ExternalCallConfigService는 **8개의 Prisma 호출**이 있으며, 외부 API 호출 설정 관리를 담당하는 서비스입니다.
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | -------------------------------------------------------- |
| 파일 위치 | `backend-node/src/services/externalCallConfigService.ts` |
| 파일 크기 | 612 라인 |
| Prisma 호출 | 0개 (전환 완료) |
| **현재 진행률** | **8/8 (100%)** ✅ **전환 완료** |
| 복잡도 | 중간 (JSON 필드, 복잡한 CRUD) |
| 우선순위 | 🟡 중간 (Phase 3.12) |
| **상태** | ✅ **완료** |
### 🎯 전환 목표
- ⏳ **8개 모든 Prisma 호출을 `db.ts`의 `query()`, `queryOne()` 함수로 교체**
- ⏳ 외부 호출 설정 CRUD 기능 정상 동작
- ⏳ JSON 필드 처리 (headers, params, auth_config)
- ⏳ 동적 WHERE 조건 생성
- ⏳ 민감 정보 암호화/복호화 유지
- ⏳ TypeScript 컴파일 성공
- ⏳ **Prisma import 완전 제거**
---
## 🔍 예상 Prisma 사용 패턴
### 주요 기능 (8개 예상)
#### 1. **외부 호출 설정 목록 조회**
- findMany with filters
- 페이징, 정렬
- 동적 WHERE 조건 (is_active, company_code, search)
#### 2. **외부 호출 설정 단건 조회**
- findUnique or findFirst
- config_id 기준
#### 3. **외부 호출 설정 생성**
- create
- JSON 필드 처리 (headers, params, auth_config)
- 민감 정보 암호화
#### 4. **외부 호출 설정 수정**
- update
- 동적 UPDATE 쿼리
- JSON 필드 업데이트
#### 5. **외부 호출 설정 삭제**
- delete or soft delete
#### 6. **외부 호출 설정 복제**
- findUnique + create
#### 7. **외부 호출 설정 테스트**
- findUnique
- 실제 HTTP 호출
#### 8. **외부 호출 이력 조회**
- findMany with 관계 조인
- 통계 쿼리
---
## 💡 전환 전략
### 1단계: 기본 CRUD 전환 (5개)
- getExternalCallConfigs() - 목록 조회
- getExternalCallConfig() - 단건 조회
- createExternalCallConfig() - 생성
- updateExternalCallConfig() - 수정
- deleteExternalCallConfig() - 삭제
### 2단계: 추가 기능 전환 (3개)
- duplicateExternalCallConfig() - 복제
- testExternalCallConfig() - 테스트
- getExternalCallHistory() - 이력 조회
---
## 💻 전환 예시
### 예시 1: 목록 조회 (동적 WHERE + JSON)
**변경 전**:
```typescript
const configs = await prisma.external_call_configs.findMany({
where: {
company_code: companyCode,
is_active: isActive,
OR: [
{ config_name: { contains: search, mode: "insensitive" } },
{ endpoint_url: { contains: search, mode: "insensitive" } },
],
},
orderBy: { created_at: "desc" },
skip,
take: limit,
});
```
**변경 후**:
```typescript
const conditions: string[] = ["company_code = $1"];
const params: any[] = [companyCode];
let paramIndex = 2;
if (isActive !== undefined) {
conditions.push(`is_active = $${paramIndex++}`);
params.push(isActive);
}
if (search) {
conditions.push(
`(config_name ILIKE $${paramIndex} OR endpoint_url ILIKE $${paramIndex})`
);
params.push(`%${search}%`);
paramIndex++;
}
const configs = await query<any>(
`SELECT * FROM external_call_configs
WHERE ${conditions.join(" AND ")}
ORDER BY created_at DESC
LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`,
[...params, limit, skip]
);
```
### 예시 2: JSON 필드 생성
**변경 전**:
```typescript
const config = await prisma.external_call_configs.create({
data: {
config_name: data.config_name,
endpoint_url: data.endpoint_url,
http_method: data.http_method,
headers: data.headers, // JSON
params: data.params, // JSON
auth_config: encryptedAuthConfig, // JSON (암호화됨)
company_code: companyCode,
},
});
```
**변경 후**:
```typescript
const config = await queryOne<any>(
`INSERT INTO external_call_configs
(config_name, endpoint_url, http_method, headers, params,
auth_config, company_code, created_at, updated_at)
VALUES ($1, $2, $3, $4, $5, $6, $7, NOW(), NOW())
RETURNING *`,
[
data.config_name,
data.endpoint_url,
data.http_method,
JSON.stringify(data.headers),
JSON.stringify(data.params),
JSON.stringify(encryptedAuthConfig),
companyCode,
]
);
```
### 예시 3: 동적 UPDATE (JSON 포함)
**변경 전**:
```typescript
const updateData: any = {};
if (data.headers) updateData.headers = data.headers;
if (data.params) updateData.params = data.params;
const config = await prisma.external_call_configs.update({
where: { config_id: configId },
data: updateData,
});
```
**변경 후**:
```typescript
const updateFields: string[] = ["updated_at = NOW()"];
const values: any[] = [];
let paramIndex = 1;
if (data.headers !== undefined) {
updateFields.push(`headers = $${paramIndex++}`);
values.push(JSON.stringify(data.headers));
}
if (data.params !== undefined) {
updateFields.push(`params = $${paramIndex++}`);
values.push(JSON.stringify(data.params));
}
const config = await queryOne<any>(
`UPDATE external_call_configs
SET ${updateFields.join(", ")}
WHERE config_id = $${paramIndex}
RETURNING *`,
[...values, configId]
);
```
---
## 🔧 기술적 고려사항
### 1. JSON 필드 처리
3개의 JSON 필드가 있을 것으로 예상:
- `headers` - HTTP 헤더
- `params` - 쿼리 파라미터
- `auth_config` - 인증 설정 (암호화됨)
```typescript
// INSERT/UPDATE 시
JSON.stringify(jsonData);
// SELECT 후
const parsedData =
typeof row.headers === "string" ? JSON.parse(row.headers) : row.headers;
```
### 2. 민감 정보 암호화
auth_config는 암호화되어 저장되므로, 기존 암호화/복호화 로직 유지:
```typescript
import { encrypt, decrypt } from "../utils/encryption";
// 저장 시
const encryptedAuthConfig = encrypt(JSON.stringify(authConfig));
// 조회 시
const decryptedAuthConfig = JSON.parse(decrypt(row.auth_config));
```
### 3. HTTP 메소드 검증
```typescript
const VALID_HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
if (!VALID_HTTP_METHODS.includes(httpMethod)) {
throw new Error("Invalid HTTP method");
}
```
### 4. URL 검증
```typescript
try {
new URL(endpointUrl);
} catch {
throw new Error("Invalid endpoint URL");
}
```
---
## ✅ 전환 완료 내역
### 전환된 Prisma 호출 (8개)
1. **`getConfigs()`** - 목록 조회 (findMany → query)
2. **`getConfigById()`** - 단건 조회 (findUnique → queryOne)
3. **`createConfig()`** - 중복 검사 (findFirst → queryOne)
4. **`createConfig()`** - 생성 (create → queryOne with INSERT)
5. **`updateConfig()`** - 중복 검사 (findFirst → queryOne)
6. **`updateConfig()`** - 수정 (update → queryOne with 동적 UPDATE)
7. **`deleteConfig()`** - 삭제 (update → query)
8. **`getExternalCallConfigsForButtonControl()`** - 조회 (findMany → query)
### 주요 기술적 개선사항
- 동적 WHERE 조건 생성 (company_code, call_type, api_type, is_active, search)
- ILIKE를 활용한 대소문자 구분 없는 검색
- 동적 UPDATE 쿼리 (9개 필드)
- JSON 필드 처리 (`config_data` → `JSON.stringify()`)
- 중복 검사 로직 유지
### 코드 정리
- [x] import 문 수정 완료
- [x] Prisma import 완전 제거
- [x] TypeScript 컴파일 성공
- [x] Linter 오류 없음
## 📝 원본 전환 체크리스트
### 1단계: Prisma 호출 전환 (✅ 완료)
- [ ] `getExternalCallConfigs()` - 목록 조회 (findMany + count)
- [ ] `getExternalCallConfig()` - 단건 조회 (findUnique)
- [ ] `createExternalCallConfig()` - 생성 (create)
- [ ] `updateExternalCallConfig()` - 수정 (update)
- [ ] `deleteExternalCallConfig()` - 삭제 (delete)
- [ ] `duplicateExternalCallConfig()` - 복제 (findUnique + create)
- [ ] `testExternalCallConfig()` - 테스트 (findUnique)
- [ ] `getExternalCallHistory()` - 이력 조회 (findMany)
### 2단계: 코드 정리
- [ ] import 문 수정 (`prisma` → `query, queryOne`)
- [ ] JSON 필드 처리 확인
- [ ] 암호화/복호화 로직 유지
- [ ] Prisma import 완전 제거
### 3단계: 테스트
- [ ] 단위 테스트 작성 (8개)
- [ ] 통합 테스트 작성 (3개)
- [ ] 암호화 테스트
- [ ] HTTP 호출 테스트
### 4단계: 문서화
- [ ] 전환 완료 문서 업데이트
- [ ] API 문서 업데이트
---
## 🎯 예상 난이도 및 소요 시간
- **난이도**: ⭐⭐⭐ (중간)
- JSON 필드 처리
- 암호화/복호화 로직
- HTTP 호출 테스트
- **예상 소요 시간**: 1~1.5시간
---
**상태**: ⏳ **대기 중**
**특이사항**: JSON 필드, 민감 정보 암호화, HTTP 호출 포함

338
PHASE3.13_ENTITY_JOIN_SERVICE_MIGRATION.md
View File

@ -1,338 +0,0 @@
# 📋 Phase 3.13: EntityJoinService Raw Query 전환 계획
## 📋 개요
EntityJoinService는 **5개의 Prisma 호출**이 있으며, 엔티티 간 조인 관계 관리를 담당하는 서비스입니다.
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | ------------------------------------------------ |
| 파일 위치 | `backend-node/src/services/entityJoinService.ts` |
| 파일 크기 | 575 라인 |
| Prisma 호출 | 0개 (전환 완료) |
| **현재 진행률** | **5/5 (100%)** ✅ **전환 완료** |
| 복잡도 | 중간 (조인 쿼리, 관계 설정) |
| 우선순위 | 🟡 중간 (Phase 3.13) |
| **상태** | ✅ **완료** |
### 🎯 전환 목표
- ⏳ **5개 모든 Prisma 호출을 `db.ts`의 `query()`, `queryOne()` 함수로 교체**
- ⏳ 엔티티 조인 설정 CRUD 기능 정상 동작
- ⏳ 복잡한 조인 쿼리 전환 (LEFT JOIN, INNER JOIN)
- ⏳ 조인 유효성 검증
- ⏳ TypeScript 컴파일 성공
- ⏳ **Prisma import 완전 제거**
---
## 🔍 예상 Prisma 사용 패턴
### 주요 기능 (5개 예상)
#### 1. **엔티티 조인 목록 조회**
- findMany with filters
- 동적 WHERE 조건
- 페이징, 정렬
#### 2. **엔티티 조인 단건 조회**
- findUnique or findFirst
- join_id 기준
#### 3. **엔티티 조인 생성**
- create
- 조인 유효성 검증
#### 4. **엔티티 조인 수정**
- update
- 동적 UPDATE 쿼리
#### 5. **엔티티 조인 삭제**
- delete
---
## 💡 전환 전략
### 1단계: 기본 CRUD 전환 (5개)
- getEntityJoins() - 목록 조회
- getEntityJoin() - 단건 조회
- createEntityJoin() - 생성
- updateEntityJoin() - 수정
- deleteEntityJoin() - 삭제
---
## 💻 전환 예시
### 예시 1: 조인 설정 조회 (LEFT JOIN으로 테이블 정보 포함)
**변경 전**:
```typescript
const joins = await prisma.entity_joins.findMany({
where: {
company_code: companyCode,
is_active: true,
},
include: {
source_table: true,
target_table: true,
},
orderBy: { created_at: "desc" },
});
```
**변경 후**:
```typescript
const joins = await query<any>(
`SELECT
ej.*,
st.table_name as source_table_name,
st.table_label as source_table_label,
tt.table_name as target_table_name,
tt.table_label as target_table_label
FROM entity_joins ej
LEFT JOIN tables st ON ej.source_table_id = st.table_id
LEFT JOIN tables tt ON ej.target_table_id = tt.table_id
WHERE ej.company_code = $1 AND ej.is_active = $2
ORDER BY ej.created_at DESC`,
[companyCode, true]
);
```
### 예시 2: 조인 생성 (유효성 검증 포함)
**변경 전**:
```typescript
// 조인 유효성 검증
const sourceTable = await prisma.tables.findUnique({
where: { table_id: sourceTableId },
});
const targetTable = await prisma.tables.findUnique({
where: { table_id: targetTableId },
});
if (!sourceTable || !targetTable) {
throw new Error("Invalid table references");
}
// 조인 생성
const join = await prisma.entity_joins.create({
data: {
source_table_id: sourceTableId,
target_table_id: targetTableId,
join_type: joinType,
join_condition: joinCondition,
company_code: companyCode,
},
});
```
**변경 후**:
```typescript
// 조인 유효성 검증 (Promise.all로 병렬 실행)
const [sourceTable, targetTable] = await Promise.all([
queryOne<any>(`SELECT * FROM tables WHERE table_id = $1`, [sourceTableId]),
queryOne<any>(`SELECT * FROM tables WHERE table_id = $1`, [targetTableId]),
]);
if (!sourceTable || !targetTable) {
throw new Error("Invalid table references");
}
// 조인 생성
const join = await queryOne<any>(
`INSERT INTO entity_joins
(source_table_id, target_table_id, join_type, join_condition,
company_code, created_at, updated_at)
VALUES ($1, $2, $3, $4, $5, NOW(), NOW())
RETURNING *`,
[sourceTableId, targetTableId, joinType, joinCondition, companyCode]
);
```
### 예시 3: 조인 수정
**변경 전**:
```typescript
const join = await prisma.entity_joins.update({
where: { join_id: joinId },
data: {
join_type: joinType,
join_condition: joinCondition,
is_active: isActive,
},
});
```
**변경 후**:
```typescript
const updateFields: string[] = ["updated_at = NOW()"];
const values: any[] = [];
let paramIndex = 1;
if (joinType !== undefined) {
updateFields.push(`join_type = $${paramIndex++}`);
values.push(joinType);
}
if (joinCondition !== undefined) {
updateFields.push(`join_condition = $${paramIndex++}`);
values.push(joinCondition);
}
if (isActive !== undefined) {
updateFields.push(`is_active = $${paramIndex++}`);
values.push(isActive);
}
const join = await queryOne<any>(
`UPDATE entity_joins
SET ${updateFields.join(", ")}
WHERE join_id = $${paramIndex}
RETURNING *`,
[...values, joinId]
);
```
---
## 🔧 기술적 고려사항
### 1. 조인 타입 검증
```typescript
const VALID_JOIN_TYPES = ["INNER", "LEFT", "RIGHT", "FULL"];
if (!VALID_JOIN_TYPES.includes(joinType)) {
throw new Error("Invalid join type");
}
```
### 2. 조인 조건 검증
```typescript
// 조인 조건은 SQL 조건식 형태 (예: "source.id = target.parent_id")
// SQL 인젝션 방지를 위한 검증 필요
const isValidJoinCondition = /^[\w\s.=<>]+$/.test(joinCondition);
if (!isValidJoinCondition) {
throw new Error("Invalid join condition");
}
```
### 3. 순환 참조 방지
```typescript
// 조인이 순환 참조를 만들지 않는지 검증
async function checkCircularReference(
sourceTableId: number,
targetTableId: number
): Promise<boolean> {
// 재귀적으로 조인 관계 확인
// ...
}
```
### 4. LEFT JOIN으로 관련 테이블 정보 조회
조인 설정 조회 시 source/target 테이블 정보를 함께 가져오기 위해 LEFT JOIN 사용
---
## ✅ 전환 완료 내역
### 전환된 Prisma 호출 (5개)
1. **`detectEntityJoins()`** - 엔티티 컬럼 감지 (findMany → query)
- column_labels 조회
- web_type = 'entity' 필터
- reference_table/reference_column IS NOT NULL
2. **`validateJoinConfig()`** - 테이블 존재 확인 ($queryRaw → query)
- information_schema.tables 조회
- 참조 테이블 검증
3. **`validateJoinConfig()`** - 컬럼 존재 확인 ($queryRaw → query)
- information_schema.columns 조회
- 표시 컬럼 검증
4. **`getReferenceTableColumns()`** - 컬럼 정보 조회 ($queryRaw → query)
- information_schema.columns 조회
- 문자열 타입 컬럼만 필터
5. **`getReferenceTableColumns()`** - 라벨 정보 조회 (findMany → query)
- column_labels 조회
- 컬럼명과 라벨 매핑
### 주요 기술적 개선사항
- **information_schema 쿼리**: 파라미터 바인딩으로 변경 ($1, $2)
- **타입 안전성**: 명확한 반환 타입 지정
- **IS NOT NULL 조건**: Prisma의 { not: null } → IS NOT NULL
- **IN 조건**: 여러 데이터 타입 필터링
### 코드 정리
- [x] PrismaClient import 제거
- [x] import 문 수정 완료
- [x] TypeScript 컴파일 성공
- [x] Linter 오류 없음
## 📝 원본 전환 체크리스트
### 1단계: Prisma 호출 전환 (✅ 완료)
- [ ] `getEntityJoins()` - 목록 조회 (findMany with include)
- [ ] `getEntityJoin()` - 단건 조회 (findUnique)
- [ ] `createEntityJoin()` - 생성 (create with validation)
- [ ] `updateEntityJoin()` - 수정 (update)
- [ ] `deleteEntityJoin()` - 삭제 (delete)
### 2단계: 코드 정리
- [ ] import 문 수정 (`prisma` → `query, queryOne`)
- [ ] 조인 유효성 검증 로직 유지
- [ ] Prisma import 완전 제거
### 3단계: 테스트
- [ ] 단위 테스트 작성 (5개)
- [ ] 조인 유효성 검증 테스트
- [ ] 순환 참조 방지 테스트
- [ ] 통합 테스트 작성 (2개)
### 4단계: 문서화
- [ ] 전환 완료 문서 업데이트
---
## 🎯 예상 난이도 및 소요 시간
- **난이도**: ⭐⭐⭐ (중간)
- LEFT JOIN 쿼리
- 조인 유효성 검증
- 순환 참조 방지
- **예상 소요 시간**: 1시간
---
**상태**: ⏳ **대기 중**
**특이사항**: LEFT JOIN, 조인 유효성 검증, 순환 참조 방지 포함

456
PHASE3.14_AUTH_SERVICE_MIGRATION.md
View File

@ -1,456 +0,0 @@
# 📋 Phase 3.14: AuthService Raw Query 전환 계획
## 📋 개요
AuthService는 **5개의 Prisma 호출**이 있으며, 사용자 인증 및 권한 관리를 담당하는 서비스입니다.
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | ------------------------------------------ |
| 파일 위치 | `backend-node/src/services/authService.ts` |
| 파일 크기 | 335 라인 |
| Prisma 호출 | 0개 (이미 Phase 1.5에서 전환 완료) |
| **현재 진행률** | **5/5 (100%)** ✅ **전환 완료** |
| 복잡도 | 높음 (보안, 암호화, 세션 관리) |
| 우선순위 | 🟡 중간 (Phase 3.14) |
| **상태** | ✅ **완료** (Phase 1.5에서 이미 완료) |
### 🎯 전환 목표
- ⏳ **5개 모든 Prisma 호출을 `db.ts`의 `query()`, `queryOne()` 함수로 교체**
- ⏳ 사용자 인증 기능 정상 동작
- ⏳ 비밀번호 암호화/검증 유지
- ⏳ 세션 관리 기능 유지
- ⏳ 권한 검증 기능 유지
- ⏳ TypeScript 컴파일 성공
- ⏳ **Prisma import 완전 제거**
---
## 🔍 예상 Prisma 사용 패턴
### 주요 기능 (5개 예상)
#### 1. **사용자 로그인 (인증)**
- findFirst or findUnique
- 이메일/사용자명으로 조회
- 비밀번호 검증
#### 2. **사용자 정보 조회**
- findUnique
- user_id 기준
- 권한 정보 포함
#### 3. **사용자 생성 (회원가입)**
- create
- 비밀번호 암호화
- 중복 검사
#### 4. **비밀번호 변경**
- update
- 기존 비밀번호 검증
- 새 비밀번호 암호화
#### 5. **세션 관리**
- create, update, delete
- 세션 토큰 저장/조회
---
## 💡 전환 전략
### 1단계: 인증 관련 전환 (2개)
- login() - 사용자 조회 + 비밀번호 검증
- getUserInfo() - 사용자 정보 조회
### 2단계: 사용자 관리 전환 (2개)
- createUser() - 사용자 생성
- changePassword() - 비밀번호 변경
### 3단계: 세션 관리 전환 (1개)
- manageSession() - 세션 CRUD
---
## 💻 전환 예시
### 예시 1: 로그인 (비밀번호 검증)
**변경 전**:
```typescript
async login(username: string, password: string) {
const user = await prisma.users.findFirst({
where: {
OR: [
{ username: username },
{ email: username },
],
is_active: true,
},
});
if (!user) {
throw new Error("User not found");
}
const isPasswordValid = await bcrypt.compare(password, user.password_hash);
if (!isPasswordValid) {
throw new Error("Invalid password");
}
return user;
}
```
**변경 후**:
```typescript
async login(username: string, password: string) {
const user = await queryOne<any>(
`SELECT * FROM users
WHERE (username = $1 OR email = $1)
AND is_active = $2`,
[username, true]
);
if (!user) {
throw new Error("User not found");
}
const isPasswordValid = await bcrypt.compare(password, user.password_hash);
if (!isPasswordValid) {
throw new Error("Invalid password");
}
return user;
}
```
### 예시 2: 사용자 생성 (비밀번호 암호화)
**변경 전**:
```typescript
async createUser(userData: CreateUserDto) {
// 중복 검사
const existing = await prisma.users.findFirst({
where: {
OR: [
{ username: userData.username },
{ email: userData.email },
],
},
});
if (existing) {
throw new Error("User already exists");
}
// 비밀번호 암호화
const passwordHash = await bcrypt.hash(userData.password, 10);
// 사용자 생성
const user = await prisma.users.create({
data: {
username: userData.username,
email: userData.email,
password_hash: passwordHash,
company_code: userData.company_code,
},
});
return user;
}
```
**변경 후**:
```typescript
async createUser(userData: CreateUserDto) {
// 중복 검사
const existing = await queryOne<any>(
`SELECT * FROM users
WHERE username = $1 OR email = $2`,
[userData.username, userData.email]
);
if (existing) {
throw new Error("User already exists");
}
// 비밀번호 암호화
const passwordHash = await bcrypt.hash(userData.password, 10);
// 사용자 생성
const user = await queryOne<any>(
`INSERT INTO users
(username, email, password_hash, company_code, created_at, updated_at)
VALUES ($1, $2, $3, $4, NOW(), NOW())
RETURNING *`,
[userData.username, userData.email, passwordHash, userData.company_code]
);
return user;
}
```
### 예시 3: 비밀번호 변경
**변경 전**:
```typescript
async changePassword(
userId: number,
oldPassword: string,
newPassword: string
) {
const user = await prisma.users.findUnique({
where: { user_id: userId },
});
if (!user) {
throw new Error("User not found");
}
const isOldPasswordValid = await bcrypt.compare(
oldPassword,
user.password_hash
);
if (!isOldPasswordValid) {
throw new Error("Invalid old password");
}
const newPasswordHash = await bcrypt.hash(newPassword, 10);
await prisma.users.update({
where: { user_id: userId },
data: { password_hash: newPasswordHash },
});
}
```
**변경 후**:
```typescript
async changePassword(
userId: number,
oldPassword: string,
newPassword: string
) {
const user = await queryOne<any>(
`SELECT * FROM users WHERE user_id = $1`,
[userId]
);
if (!user) {
throw new Error("User not found");
}
const isOldPasswordValid = await bcrypt.compare(
oldPassword,
user.password_hash
);
if (!isOldPasswordValid) {
throw new Error("Invalid old password");
}
const newPasswordHash = await bcrypt.hash(newPassword, 10);
await query(
`UPDATE users
SET password_hash = $1, updated_at = NOW()
WHERE user_id = $2`,
[newPasswordHash, userId]
);
}
```
---
## 🔧 기술적 고려사항
### 1. 비밀번호 보안
```typescript
import bcrypt from "bcrypt";
// 비밀번호 해싱 (회원가입, 비밀번호 변경)
const SALT_ROUNDS = 10;
const passwordHash = await bcrypt.hash(password, SALT_ROUNDS);
// 비밀번호 검증 (로그인)
const isValid = await bcrypt.compare(plainPassword, passwordHash);
```
### 2. SQL 인젝션 방지
```typescript
// ❌ 위험: 직접 문자열 결합
const sql = `SELECT * FROM users WHERE username = '${username}'`;
// ✅ 안전: 파라미터 바인딩
const user = await queryOne(`SELECT * FROM users WHERE username = $1`, [
username,
]);
```
### 3. 세션 토큰 관리
```typescript
import crypto from "crypto";
// 세션 토큰 생성
const sessionToken = crypto.randomBytes(32).toString("hex");
// 세션 저장
await query(
`INSERT INTO user_sessions (user_id, session_token, expires_at)
VALUES ($1, $2, NOW() + INTERVAL '1 day')`,
[userId, sessionToken]
);
```
### 4. 권한 검증
```typescript
async checkPermission(userId: number, permission: string): Promise<boolean> {
const result = await queryOne<{ has_permission: boolean }>(
`SELECT EXISTS (
SELECT 1 FROM user_permissions up
JOIN permissions p ON up.permission_id = p.permission_id
WHERE up.user_id = $1 AND p.permission_name = $2
) as has_permission`,
[userId, permission]
);
return result?.has_permission || false;
}
```
---
## ✅ 전환 완료 내역 (Phase 1.5에서 이미 완료됨)
AuthService는 Phase 1.5에서 이미 Raw Query로 전환이 완료되었습니다.
### 전환된 Prisma 호출 (5개)
1. **`loginPwdCheck()`** - 로그인 비밀번호 검증
- user_info 테이블에서 비밀번호 조회
- EncryptUtil을 활용한 비밀번호 검증
- 마스터 패스워드 지원
2. **`insertLoginAccessLog()`** - 로그인 로그 기록
- login_access_log 테이블에 INSERT
- 로그인 시간, IP 주소 등 기록
3. **`getUserInfo()`** - 사용자 정보 조회
- user_info 테이블 조회
- PersonBean 객체로 반환
4. **`updateLastLoginDate()`** - 마지막 로그인 시간 업데이트
- user_info 테이블 UPDATE
- last_login_date 갱신
5. **`checkUserPermission()`** - 사용자 권한 확인
- user_auth 테이블 조회
- 권한 코드 검증
### 주요 기술적 특징
- **보안**: EncryptUtil을 활용한 안전한 비밀번호 검증
- **JWT 토큰**: JwtUtils를 활용한 토큰 생성 및 검증
- **로깅**: 상세한 로그인 이력 기록
- **에러 처리**: 안전한 에러 메시지 반환
### 코드 상태
- [x] Prisma import 없음
- [x] query 함수 사용 중
- [x] TypeScript 컴파일 성공
- [x] 보안 로직 유지
## 📝 원본 전환 체크리스트
### 1단계: Prisma 호출 전환 (✅ Phase 1.5에서 완료)
- [ ] `login()` - 사용자 조회 + 비밀번호 검증 (findFirst)
- [ ] `getUserInfo()` - 사용자 정보 조회 (findUnique)
- [ ] `createUser()` - 사용자 생성 (create with 중복 검사)
- [ ] `changePassword()` - 비밀번호 변경 (findUnique + update)
- [ ] `manageSession()` - 세션 관리 (create/update/delete)
### 2단계: 보안 검증
- [ ] 비밀번호 해싱 로직 유지 (bcrypt)
- [ ] SQL 인젝션 방지 확인
- [ ] 세션 토큰 보안 확인
- [ ] 중복 계정 방지 확인
### 3단계: 테스트
- [ ] 단위 테스트 작성 (5개)
- [ ] 로그인 성공/실패 테스트
- [ ] 사용자 생성 테스트
- [ ] 비밀번호 변경 테스트
- [ ] 세션 관리 테스트
- [ ] 권한 검증 테스트
- [ ] 보안 테스트
- [ ] SQL 인젝션 테스트
- [ ] 비밀번호 강도 테스트
- [ ] 세션 탈취 방지 테스트
- [ ] 통합 테스트 작성 (2개)
### 4단계: 문서화
- [ ] 전환 완료 문서 업데이트
- [ ] 보안 가이드 업데이트
---
## 🎯 예상 난이도 및 소요 시간
- **난이도**: ⭐⭐⭐⭐ (높음)
- 보안 크리티컬 (비밀번호, 세션)
- SQL 인젝션 방지 필수
- 철저한 테스트 필요
- **예상 소요 시간**: 1.5~2시간
- Prisma 호출 전환: 40분
- 보안 검증: 40분
- 테스트: 40분
---
## ⚠️ 주의사항
### 보안 필수 체크리스트
1. ✅ 모든 사용자 입력은 파라미터 바인딩 사용
2. ✅ 비밀번호는 절대 평문 저장 금지 (bcrypt 사용)
3. ✅ 세션 토큰은 충분히 길고 랜덤해야 함
4. ✅ 비밀번호 실패 시 구체적 오류 메시지 금지 ("User not found" vs "Invalid credentials")
5. ✅ 로그인 실패 횟수 제한 (Brute Force 방지)
---
**상태**: ⏳ **대기 중**
**특이사항**: 보안 크리티컬, 비밀번호 암호화, 세션 관리 포함
**⚠️ 주의**: 이 서비스는 보안에 매우 중요하므로 신중한 테스트 필수!

515
PHASE3.15_BATCH_SERVICES_MIGRATION.md
View File

@ -1,515 +0,0 @@
# 📋 Phase 3.15: Batch Services Raw Query 전환 계획
## 📋 개요
배치 관련 서비스들은 총 **24개의 Prisma 호출**이 있으며, 배치 작업 실행 및 관리를 담당합니다.
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | ---------------------------------------------------------- |
| 대상 서비스 | 4개 (BatchExternalDb, ExecutionLog, Management, Scheduler) |
| 파일 위치 | `backend-node/src/services/batch*.ts` |
| 총 파일 크기 | 2,161 라인 |
| Prisma 호출 | 0개 (전환 완료) |
| **현재 진행률** | **24/24 (100%)** ✅ **전환 완료** |
| 복잡도 | 높음 (외부 DB 연동, 스케줄링, 트랜잭션) |
| 우선순위 | 🔴 높음 (Phase 3.15) |
| **상태** | ✅ **완료** |
---
## ✅ 전환 완료 내역
### 전환된 Prisma 호출 (24개)
#### 1. BatchExternalDbService (8개)
- `getAvailableConnections()` - findMany → query
- `getTables()` - $queryRaw → query (information_schema)
- `getTableColumns()` - $queryRaw → query (information_schema)
- `getExternalTables()` - findUnique → queryOne (x5)
#### 2. BatchExecutionLogService (7개)
- `getExecutionLogs()` - findMany + count → query (JOIN + 동적 WHERE)
- `createExecutionLog()` - create → queryOne (INSERT RETURNING)
- `updateExecutionLog()` - update → queryOne (동적 UPDATE)
- `deleteExecutionLog()` - delete → query
- `getLatestExecutionLog()` - findFirst → queryOne
- `getExecutionStats()` - findMany → query (동적 WHERE)
#### 3. BatchManagementService (5개)
- `getAvailableConnections()` - findMany → query
- `getTables()` - $queryRaw → query (information_schema)
- `getTableColumns()` - $queryRaw → query (information_schema)
- `getExternalTables()` - findUnique → queryOne (x2)
#### 4. BatchSchedulerService (4개)
- `loadActiveBatchConfigs()` - findMany → query (JOIN with json_agg)
- `updateBatchSchedule()` - findUnique → query (JOIN with json_agg)
- `getDataFromSource()` - $queryRawUnsafe → query
- `insertDataToTarget()` - $executeRawUnsafe → query
### 주요 기술적 해결 사항
1. **외부 DB 연결 조회 반복**
- 5개의 `findUnique` 호출을 `queryOne`으로 일괄 전환
- 암호화/복호화 로직 유지
2. **배치 설정 + 매핑 JOIN**
- Prisma `include` → `json_agg` + `json_build_object`
- `FILTER (WHERE bm.id IS NOT NULL)` 로 NULL 방지
- 계층적 JSON 데이터 생성
3. **동적 WHERE 절 생성**
- 조건부 필터링 (batch_config_id, execution_status, 날짜 범위)
- 파라미터 인덱스 동적 관리
4. **동적 UPDATE 쿼리**
- undefined 필드 제외
- 8개 필드의 조건부 업데이트
5. **통계 쿼리 전환**
- 클라이언트 사이드 집계 유지
- 원본 데이터만 쿼리로 조회
### 컴파일 상태
✅ TypeScript 컴파일 성공
✅ Linter 오류 없음
---
## 🔍 서비스별 상세 분석
### 1. BatchExternalDbService (8개 호출, 943 라인)
**주요 기능**:
- 외부 DB에서 배치 데이터 조회
- 외부 DB로 배치 데이터 저장
- 외부 DB 연결 관리
- 데이터 변환 및 매핑
**예상 Prisma 호출**:
- `getExternalDbConnection()` - 외부 DB 연결 정보 조회
- `fetchDataFromExternalDb()` - 외부 DB 데이터 조회
- `saveDataToExternalDb()` - 외부 DB 데이터 저장
- `validateExternalDbConnection()` - 연결 검증
- `getExternalDbTables()` - 테이블 목록 조회
- `getExternalDbColumns()` - 컬럼 정보 조회
- `executeBatchQuery()` - 배치 쿼리 실행
- `getBatchExecutionStatus()` - 실행 상태 조회
**기술적 고려사항**:
- 다양한 DB 타입 지원 (PostgreSQL, MySQL, Oracle, MSSQL)
- 연결 풀 관리
- 트랜잭션 처리
- 에러 핸들링 및 재시도
---
### 2. BatchExecutionLogService (7개 호출, 299 라인)
**주요 기능**:
- 배치 실행 로그 생성
- 배치 실행 이력 조회
- 배치 실행 통계
- 로그 정리
**예상 Prisma 호출**:
- `createExecutionLog()` - 실행 로그 생성
- `updateExecutionLog()` - 실행 로그 업데이트
- `getExecutionLogs()` - 실행 로그 목록 조회
- `getExecutionLogById()` - 실행 로그 단건 조회
- `getExecutionStats()` - 실행 통계 조회
- `cleanupOldLogs()` - 오래된 로그 삭제
- `getFailedExecutions()` - 실패한 실행 조회
**기술적 고려사항**:
- 대용량 로그 처리
- 통계 쿼리 최적화
- 로그 보관 정책
- 페이징 및 필터링
---
### 3. BatchManagementService (5개 호출, 373 라인)
**주요 기능**:
- 배치 작업 설정 관리
- 배치 작업 실행
- 배치 작업 중지
- 배치 작업 모니터링
**예상 Prisma 호출**:
- `getBatchJobs()` - 배치 작업 목록 조회
- `getBatchJob()` - 배치 작업 단건 조회
- `createBatchJob()` - 배치 작업 생성
- `updateBatchJob()` - 배치 작업 수정
- `deleteBatchJob()` - 배치 작업 삭제
**기술적 고려사항**:
- JSON 설정 필드 (job_config)
- 작업 상태 관리
- 동시 실행 제어
- 의존성 관리
---
### 4. BatchSchedulerService (4개 호출, 546 라인)
**주요 기능**:
- 배치 스케줄 설정
- Cron 표현식 관리
- 스케줄 실행
- 다음 실행 시간 계산
**예상 Prisma 호출**:
- `getScheduledBatches()` - 스케줄된 배치 조회
- `createSchedule()` - 스케줄 생성
- `updateSchedule()` - 스케줄 수정
- `deleteSchedule()` - 스케줄 삭제
**기술적 고려사항**:
- Cron 표현식 파싱
- 시간대 처리
- 실행 이력 추적
- 스케줄 충돌 방지
---
## 💡 통합 전환 전략
### Phase 1: 핵심 서비스 전환 (12개)
**BatchManagementService (5개) + BatchExecutionLogService (7개)**
- 배치 관리 및 로깅 기능 우선
- 상대적으로 단순한 CRUD
### Phase 2: 스케줄러 전환 (4개)
**BatchSchedulerService (4개)**
- 스케줄 관리
- Cron 표현식 처리
### Phase 3: 외부 DB 연동 전환 (8개)
**BatchExternalDbService (8개)**
- 가장 복잡한 서비스
- 외부 DB 연결 및 쿼리
---
## 💻 전환 예시
### 예시 1: 배치 실행 로그 생성
**변경 전**:
```typescript
const log = await prisma.batch_execution_logs.create({
data: {
batch_id: batchId,
status: "running",
started_at: new Date(),
execution_params: params,
company_code: companyCode,
},
});
```
**변경 후**:
```typescript
const log = await queryOne<any>(
`INSERT INTO batch_execution_logs
(batch_id, status, started_at, execution_params, company_code)
VALUES ($1, $2, NOW(), $3, $4)
RETURNING *`,
[batchId, "running", JSON.stringify(params), companyCode]
);
```
### 예시 2: 배치 통계 조회
**변경 전**:
```typescript
const stats = await prisma.batch_execution_logs.groupBy({
by: ["status"],
where: {
batch_id: batchId,
started_at: { gte: startDate, lte: endDate },
},
_count: { id: true },
});
```
**변경 후**:
```typescript
const stats = await query<{ status: string; count: string }>(
`SELECT status, COUNT(*) as count
FROM batch_execution_logs
WHERE batch_id = $1
AND started_at >= $2
AND started_at <= $3
GROUP BY status`,
[batchId, startDate, endDate]
);
```
### 예시 3: 외부 DB 연결 및 쿼리
**변경 전**:
```typescript
// 연결 정보 조회
const connection = await prisma.external_db_connections.findUnique({
where: { id: connectionId },
});
// 외부 DB 쿼리 실행 (Prisma 사용 불가, 이미 Raw Query일 가능성)
const externalData = await externalDbClient.query(sql);
```
**변경 후**:
```typescript
// 연결 정보 조회
const connection = await queryOne<any>(
`SELECT * FROM external_db_connections WHERE id = $1`,
[connectionId]
);
// 외부 DB 쿼리 실행 (기존 로직 유지)
const externalData = await externalDbClient.query(sql);
```
### 예시 4: 스케줄 관리
**변경 전**:
```typescript
const schedule = await prisma.batch_schedules.create({
data: {
batch_id: batchId,
cron_expression: cronExp,
is_active: true,
next_run_at: calculateNextRun(cronExp),
},
});
```
**변경 후**:
```typescript
const nextRun = calculateNextRun(cronExp);
const schedule = await queryOne<any>(
`INSERT INTO batch_schedules
(batch_id, cron_expression, is_active, next_run_at, created_at, updated_at)
VALUES ($1, $2, $3, $4, NOW(), NOW())
RETURNING *`,
[batchId, cronExp, true, nextRun]
);
```
---
## 🔧 기술적 고려사항
### 1. 외부 DB 연결 관리
```typescript
import { DatabaseConnectorFactory } from "../database/connectorFactory";
// 외부 DB 연결 생성
const connector = DatabaseConnectorFactory.create(connection);
const externalClient = await connector.connect();
try {
// 쿼리 실행
const result = await externalClient.query(sql, params);
} finally {
await connector.disconnect();
}
```
### 2. 트랜잭션 처리
```typescript
await transaction(async (client) => {
// 배치 상태 업데이트
await client.query(`UPDATE batch_jobs SET status = $1 WHERE id = $2`, [
"running",
batchId,
]);
// 실행 로그 생성
await client.query(
`INSERT INTO batch_execution_logs (batch_id, status, started_at)
VALUES ($1, $2, NOW())`,
[batchId, "running"]
);
});
```
### 3. Cron 표현식 처리
```typescript
import cron from "node-cron";
// Cron 표현식 검증
const isValid = cron.validate(cronExpression);
// 다음 실행 시간 계산
function calculateNextRun(cronExp: string): Date {
// Cron 파서를 사용하여 다음 실행 시간 계산
// ...
}
```
### 4. 대용량 데이터 처리
```typescript
// 스트리밍 방식으로 대용량 데이터 처리
const stream = await query<any>(
`SELECT * FROM large_table WHERE batch_id = $1`,
[batchId]
);
for await (const row of stream) {
// 행 단위 처리
}
```
---
## 📝 전환 체크리스트
### BatchExternalDbService (8개)
- [ ] `getExternalDbConnection()` - 연결 정보 조회
- [ ] `fetchDataFromExternalDb()` - 외부 DB 데이터 조회
- [ ] `saveDataToExternalDb()` - 외부 DB 데이터 저장
- [ ] `validateExternalDbConnection()` - 연결 검증
- [ ] `getExternalDbTables()` - 테이블 목록 조회
- [ ] `getExternalDbColumns()` - 컬럼 정보 조회
- [ ] `executeBatchQuery()` - 배치 쿼리 실행
- [ ] `getBatchExecutionStatus()` - 실행 상태 조회
### BatchExecutionLogService (7개)
- [ ] `createExecutionLog()` - 실행 로그 생성
- [ ] `updateExecutionLog()` - 실행 로그 업데이트
- [ ] `getExecutionLogs()` - 실행 로그 목록 조회
- [ ] `getExecutionLogById()` - 실행 로그 단건 조회
- [ ] `getExecutionStats()` - 실행 통계 조회
- [ ] `cleanupOldLogs()` - 오래된 로그 삭제
- [ ] `getFailedExecutions()` - 실패한 실행 조회
### BatchManagementService (5개)
- [ ] `getBatchJobs()` - 배치 작업 목록 조회
- [ ] `getBatchJob()` - 배치 작업 단건 조회
- [ ] `createBatchJob()` - 배치 작업 생성
- [ ] `updateBatchJob()` - 배치 작업 수정
- [ ] `deleteBatchJob()` - 배치 작업 삭제
### BatchSchedulerService (4개)
- [ ] `getScheduledBatches()` - 스케줄된 배치 조회
- [ ] `createSchedule()` - 스케줄 생성
- [ ] `updateSchedule()` - 스케줄 수정
- [ ] `deleteSchedule()` - 스케줄 삭제
### 공통 작업
- [ ] import 문 수정 (모든 서비스)
- [ ] Prisma import 완전 제거 (모든 서비스)
- [ ] 트랜잭션 로직 확인
- [ ] 에러 핸들링 검증
---
## 🧪 테스트 계획
### 단위 테스트 (24개)
- 각 Prisma 호출별 1개씩
### 통합 테스트 (8개)
- BatchExternalDbService: 외부 DB 연동 테스트 (2개)
- BatchExecutionLogService: 로그 생성 및 조회 테스트 (2개)
- BatchManagementService: 배치 작업 실행 테스트 (2개)
- BatchSchedulerService: 스케줄 실행 테스트 (2개)
### 성능 테스트
- 대용량 데이터 처리 성능
- 동시 배치 실행 성능
- 외부 DB 연결 풀 성능
---
## 🎯 예상 난이도 및 소요 시간
- **난이도**: ⭐⭐⭐⭐⭐ (매우 높음)
- 외부 DB 연동
- 트랜잭션 처리
- 스케줄링 로직
- 대용량 데이터 처리
- **예상 소요 시간**: 4~5시간
- Phase 1 (BatchManagement + ExecutionLog): 1.5시간
- Phase 2 (Scheduler): 1시간
- Phase 3 (ExternalDb): 2시간
- 테스트 및 문서화: 0.5시간
---
## ⚠️ 주의사항
### 중요 체크포인트
1. ✅ 외부 DB 연결은 반드시 try-finally에서 해제
2. ✅ 배치 실행 중 에러 시 롤백 처리
3. ✅ Cron 표현식 검증 필수
4. ✅ 대용량 데이터는 스트리밍 방식 사용
5. ✅ 동시 실행 제한 확인
### 성능 최적화
- 연결 풀 활용
- 배치 쿼리 최적화
- 인덱스 확인
- 불필요한 로그 제거
---
**상태**: ⏳ **대기 중**
**특이사항**: 외부 DB 연동, 스케줄링, 트랜잭션 처리 포함
**⚠️ 주의**: 배치 시스템의 핵심 기능이므로 신중한 테스트 필수!

540
PHASE3.16_DATA_MANAGEMENT_SERVICES_MIGRATION.md
View File

@ -1,540 +0,0 @@
# 📋 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 인젝션 방지가 매우 중요!

62
PHASE3.17_REFERENCE_CACHE_SERVICE_MIGRATION.md
View File

@ -1,62 +0,0 @@
# 📋 Phase 3.17: ReferenceCacheService Raw Query 전환 계획
## 📋 개요
ReferenceCacheService는 **0개의 Prisma 호출**이 있으며, 참조 데이터 캐싱을 담당하는 서비스입니다.
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | ---------------------------------------------------- |
| 파일 위치 | `backend-node/src/services/referenceCacheService.ts` |
| 파일 크기 | 499 라인 |
| Prisma 호출 | 0개 (이미 전환 완료) |
| **현재 진행률** | **3/3 (100%)** ✅ **전환 완료** |
| 복잡도 | 낮음 (캐싱 로직) |
| 우선순위 | 🟢 낮음 (Phase 3.17) |
| **상태** | ✅ **완료** (이미 전환 완료됨) |
---
## ✅ 전환 완료 내역 (이미 완료됨)
ReferenceCacheService는 이미 Raw Query로 전환이 완료되었습니다.
### 주요 기능
1. **참조 데이터 캐싱**
- 자주 사용되는 참조 테이블 데이터를 메모리에 캐싱
- 성능 향상을 위한 캐시 전략
2. **캐시 관리**
- 캐시 갱신 로직
- TTL(Time To Live) 관리
- 캐시 무효화
3. **데이터 조회 최적화**
- 캐시 히트/미스 처리
- 백그라운드 갱신
### 기술적 특징
- **메모리 캐싱**: Map/Object 기반 인메모리 캐싱
- **성능 최적화**: 반복 DB 조회 최소화
- **자동 갱신**: 주기적 캐시 갱신 로직
### 코드 상태
- [x] Prisma import 없음
- [x] query 함수 사용 중
- [x] TypeScript 컴파일 성공
- [x] 캐싱 로직 정상 동작
---
## 📝 비고
이 서비스는 이미 Raw Query로 전환이 완료되어 있어 추가 작업이 필요하지 않습니다.
**상태**: ✅ **완료**
**특이사항**: 캐싱 로직으로 성능에 중요한 서비스

92
PHASE3.18_DDL_EXECUTION_SERVICE_MIGRATION.md
View File

@ -1,92 +0,0 @@
# 📋 Phase 3.18: DDLExecutionService Raw Query 전환 계획
## 📋 개요
DDLExecutionService는 **0개의 Prisma 호출**이 있으며, DDL 실행 및 관리를 담당하는 서비스입니다.
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | -------------------------------------------------- |
| 파일 위치 | `backend-node/src/services/ddlExecutionService.ts` |
| 파일 크기 | 786 라인 |
| Prisma 호출 | 0개 (이미 전환 완료) |
| **현재 진행률** | **6/6 (100%)** ✅ **전환 완료** |
| 복잡도 | 높음 (DDL 실행, 안전성 검증) |
| 우선순위 | 🔴 높음 (Phase 3.18) |
| **상태** | ✅ **완료** (이미 전환 완료됨) |
---
## ✅ 전환 완료 내역 (이미 완료됨)
DDLExecutionService는 이미 Raw Query로 전환이 완료되었습니다.
### 주요 기능
1. **테이블 생성 (CREATE TABLE)**
- 동적 테이블 생성
- 컬럼 정의 및 제약조건
- 인덱스 생성
2. **컬럼 추가 (ADD COLUMN)**
- 기존 테이블에 컬럼 추가
- 데이터 타입 검증
- 기본값 설정
3. **테이블/컬럼 삭제 (DROP)**
- 안전한 삭제 검증
- 의존성 체크
- 롤백 가능성
4. **DDL 안전성 검증**
- DDL 실행 전 검증
- 순환 참조 방지
- 데이터 손실 방지
5. **DDL 실행 이력**
- 모든 DDL 실행 기록
- 성공/실패 로그
- 롤백 정보
6. **트랜잭션 관리**
- DDL 트랜잭션 처리
- 에러 시 롤백
- 일관성 유지
### 기술적 특징
- **동적 DDL 생성**: 파라미터 기반 DDL 쿼리 생성
- **안전성 검증**: 실행 전 다중 검증 단계
- **감사 로깅**: DDLAuditLogger와 연동
- **PostgreSQL 특화**: PostgreSQL DDL 문법 활용
### 보안 및 안전성
- **SQL 인젝션 방지**: 테이블/컬럼명 화이트리스트 검증
- **권한 검증**: 사용자 권한 확인
- **백업 권장**: DDL 실행 전 백업 체크
- **복구 가능성**: 실행 이력 기록
### 코드 상태
- [x] Prisma import 없음
- [x] query 함수 사용 중
- [x] TypeScript 컴파일 성공
- [x] 안전성 검증 로직 유지
- [x] DDLAuditLogger 연동
---
## 📝 비고
이 서비스는 이미 Raw Query로 전환이 완료되어 있어 추가 작업이 필요하지 않습니다.
**상태**: ✅ **완료**
**특이사항**: DDL 실행의 핵심 서비스로 안전성이 매우 중요
**⚠️ 주의**: 프로덕션 환경에서 DDL 실행 시 각별한 주의 필요

369
PHASE3.7_LAYOUT_SERVICE_MIGRATION.md
View File

@ -1,369 +0,0 @@
# 🎨 Phase 3.7: LayoutService Raw Query 전환 계획
## 📋 개요
LayoutService는 **10개의 Prisma 호출**이 있으며, 레이아웃 표준 관리를 담당하는 서비스입니다.
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | --------------------------------------------- |
| 파일 위치 | `backend-node/src/services/layoutService.ts` |
| 파일 크기 | 425+ 라인 |
| Prisma 호출 | 10개 |
| **현재 진행률** | **0/10 (0%)** 🔄 **진행 예정** |
| 복잡도 | 중간 (JSON 필드, 검색, 통계) |
| 우선순위 | 🟡 중간 (Phase 3.7) |
| **상태** | ⏳ **대기 중** |
### 🎯 전환 목표
- ⏳ **10개 모든 Prisma 호출을 `db.ts`의 `query()`, `queryOne()` 함수로 교체**
- ⏳ JSON 필드 처리 (layout_config, sections)
- ⏳ 복잡한 검색 조건 처리
- ⏳ GROUP BY 통계 쿼리 전환
- ⏳ 모든 단위 테스트 통과
- ⏳ **Prisma import 완전 제거**
---
## 🔍 Prisma 사용 현황 분석
### 주요 Prisma 호출 (10개)
#### 1. **getLayouts()** - 레이아웃 목록 조회
```typescript
// Line 92, 102
const total = await prisma.layout_standards.count({ where });
const layouts = await prisma.layout_standards.findMany({
where,
skip,
take: size,
orderBy: { updated_date: "desc" },
});
```
#### 2. **getLayoutByCode()** - 레이아웃 단건 조회
```typescript
// Line 152
const layout = await prisma.layout_standards.findFirst({
where: { layout_code: code, company_code: companyCode },
});
```
#### 3. **createLayout()** - 레이아웃 생성
```typescript
// Line 199
const layout = await prisma.layout_standards.create({
data: {
layout_code,
layout_name,
layout_type,
category,
layout_config: safeJSONStringify(layout_config),
sections: safeJSONStringify(sections),
// ... 기타 필드
},
});
```
#### 4. **updateLayout()** - 레이아웃 수정
```typescript
// Line 230, 267
const existing = await prisma.layout_standards.findFirst({
where: { layout_code: code, company_code: companyCode },
});
const updated = await prisma.layout_standards.update({
where: { id: existing.id },
data: { ... },
});
```
#### 5. **deleteLayout()** - 레이아웃 삭제
```typescript
// Line 283, 295
const existing = await prisma.layout_standards.findFirst({
where: { layout_code: code, company_code: companyCode },
});
await prisma.layout_standards.update({
where: { id: existing.id },
data: { is_active: "N", updated_by, updated_date: new Date() },
});
```
#### 6. **getLayoutStatistics()** - 레이아웃 통계
```typescript
// Line 345
const counts = await prisma.layout_standards.groupBy({
by: ["category", "layout_type"],
where: { company_code: companyCode, is_active: "Y" },
_count: { id: true },
});
```
#### 7. **getLayoutCategories()** - 카테고리 목록
```typescript
// Line 373
const existingCodes = await prisma.layout_standards.findMany({
where: { company_code: companyCode },
select: { category: true },
distinct: ["category"],
});
```
---
## 📝 전환 계획
### 1단계: 기본 CRUD 전환 (5개 함수)
**함수 목록**:
- `getLayouts()` - 목록 조회 (count + findMany)
- `getLayoutByCode()` - 단건 조회 (findFirst)
- `createLayout()` - 생성 (create)
- `updateLayout()` - 수정 (findFirst + update)
- `deleteLayout()` - 삭제 (findFirst + update - soft delete)
### 2단계: 통계 및 집계 전환 (2개 함수)
**함수 목록**:
- `getLayoutStatistics()` - 통계 (groupBy)
- `getLayoutCategories()` - 카테고리 목록 (findMany + distinct)
---
## 💻 전환 예시
### 예시 1: 레이아웃 목록 조회 (동적 WHERE + 페이지네이션)
```typescript
// 기존 Prisma
const where: any = { company_code: companyCode };
if (category) where.category = category;
if (layoutType) where.layout_type = layoutType;
if (searchTerm) {
where.OR = [
{ layout_name: { contains: searchTerm, mode: "insensitive" } },
{ layout_code: { contains: searchTerm, mode: "insensitive" } },
];
}
const total = await prisma.layout_standards.count({ where });
const layouts = await prisma.layout_standards.findMany({
where,
skip,
take: size,
orderBy: { updated_date: "desc" },
});
// 전환 후
import { query, queryOne } from "../database/db";
const whereConditions: string[] = ["company_code = $1"];
const values: any[] = [companyCode];
let paramIndex = 2;
if (category) {
whereConditions.push(`category = $${paramIndex++}`);
values.push(category);
}
if (layoutType) {
whereConditions.push(`layout_type = $${paramIndex++}`);
values.push(layoutType);
}
if (searchTerm) {
whereConditions.push(
`(layout_name ILIKE $${paramIndex} OR layout_code ILIKE $${paramIndex})`
);
values.push(`%${searchTerm}%`);
paramIndex++;
}
const whereClause = `WHERE ${whereConditions.join(" AND ")}`;
// 총 개수 조회
const countResult = await queryOne<{ count: string }>(
`SELECT COUNT(*) as count FROM layout_standards ${whereClause}`,
values
);
const total = parseInt(countResult?.count || "0");
// 데이터 조회
const layouts = await query<any>(
`SELECT * FROM layout_standards
${whereClause}
ORDER BY updated_date DESC
LIMIT $${paramIndex++} OFFSET $${paramIndex++}`,
[...values, size, skip]
);
```
### 예시 2: JSON 필드 처리 (레이아웃 생성)
```typescript
// 기존 Prisma
const layout = await prisma.layout_standards.create({
data: {
layout_code,
layout_name,
layout_config: safeJSONStringify(layout_config), // JSON 필드
sections: safeJSONStringify(sections), // JSON 필드
company_code: companyCode,
created_by: createdBy,
},
});
// 전환 후
const layout = await queryOne<any>(
`INSERT INTO layout_standards
(layout_code, layout_name, layout_type, category, layout_config, sections,
company_code, is_active, created_by, updated_by, created_date, updated_date)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, NOW(), NOW())
RETURNING *`,
[
layout_code,
layout_name,
layout_type,
category,
safeJSONStringify(layout_config), // JSON 필드는 문자열로 변환
safeJSONStringify(sections),
companyCode,
"Y",
createdBy,
updatedBy,
]
);
```
### 예시 3: GROUP BY 통계 쿼리
```typescript
// 기존 Prisma
const counts = await prisma.layout_standards.groupBy({
by: ["category", "layout_type"],
where: { company_code: companyCode, is_active: "Y" },
_count: { id: true },
});
// 전환 후
const counts = await query<{
category: string;
layout_type: string;
count: string;
}>(
`SELECT category, layout_type, COUNT(*) as count
FROM layout_standards
WHERE company_code = $1 AND is_active = $2
GROUP BY category, layout_type`,
[companyCode, "Y"]
);
// 결과 포맷팅
const formattedCounts = counts.map((row) => ({
category: row.category,
layout_type: row.layout_type,
_count: { id: parseInt(row.count) },
}));
```
### 예시 4: DISTINCT 쿼리 (카테고리 목록)
```typescript
// 기존 Prisma
const existingCodes = await prisma.layout_standards.findMany({
where: { company_code: companyCode },
select: { category: true },
distinct: ["category"],
});
// 전환 후
const existingCodes = await query<{ category: string }>(
`SELECT DISTINCT category
FROM layout_standards
WHERE company_code = $1
ORDER BY category`,
[companyCode]
);
```
---
## ✅ 완료 기준
- [ ] **10개 모든 Prisma 호출을 Raw Query로 전환 완료**
- [ ] **동적 WHERE 조건 생성 (ILIKE, OR)**
- [ ] **JSON 필드 처리 (layout_config, sections)**
- [ ] **GROUP BY 집계 쿼리 전환**
- [ ] **DISTINCT 쿼리 전환**
- [ ] **모든 TypeScript 컴파일 오류 해결**
- [ ] **`import prisma` 완전 제거**
- [ ] **모든 단위 테스트 통과 (10개)**
- [ ] **통합 테스트 작성 완료 (3개 시나리오)**
---
## 🔧 주요 기술적 과제
### 1. JSON 필드 처리
- `layout_config`, `sections` 필드는 JSON 타입
- INSERT/UPDATE 시 `JSON.stringify()` 또는 `safeJSONStringify()` 사용
- SELECT 시 PostgreSQL이 자동으로 JSON 객체로 반환
### 2. 동적 검색 조건
- category, layoutType, searchTerm에 따른 동적 WHERE 절
- OR 조건 처리 (layout_name OR layout_code)
### 3. Soft Delete
- `deleteLayout()`는 실제 삭제가 아닌 `is_active = 'N'` 업데이트
- UPDATE 쿼리 사용
### 4. 통계 쿼리
- `groupBy` → `GROUP BY` + `COUNT(*)` 전환
- 결과 포맷팅 필요 (`_count.id` 형태로 변환)
---
## 📋 체크리스트
### 코드 전환
- [ ] import 문 수정 (`prisma` → `query, queryOne`)
- [ ] getLayouts() - count + findMany → query + queryOne
- [ ] getLayoutByCode() - findFirst → queryOne
- [ ] createLayout() - create → queryOne (INSERT)
- [ ] updateLayout() - findFirst + update → queryOne (동적 UPDATE)
- [ ] deleteLayout() - findFirst + update → queryOne (UPDATE is_active)
- [ ] getLayoutStatistics() - groupBy → query (GROUP BY)
- [ ] getLayoutCategories() - findMany + distinct → query (DISTINCT)
- [ ] JSON 필드 처리 확인 (safeJSONStringify)
- [ ] Prisma import 완전 제거
### 테스트
- [ ] 단위 테스트 작성 (10개)
- [ ] 통합 테스트 작성 (3개)
- [ ] TypeScript 컴파일 성공
- [ ] 성능 벤치마크 테스트
---
## 💡 특이사항
### JSON 필드 헬퍼 함수
이 서비스는 `safeJSONParse()`, `safeJSONStringify()` 헬퍼 함수를 사용하여 JSON 필드를 안전하게 처리합니다. Raw Query 전환 후에도 이 함수들을 계속 사용해야 합니다.
### Soft Delete 패턴
레이아웃 삭제는 실제 DELETE가 아닌 `is_active = 'N'` 업데이트로 처리되므로, UPDATE 쿼리를 사용해야 합니다.
### 통계 쿼리 결과 포맷
Prisma의 `groupBy`는 `_count: { id: number }` 형태로 반환하지만, Raw Query는 `count: string`으로 반환하므로 포맷팅이 필요합니다.
---
**작성일**: 2025-10-01
**예상 소요 시간**: 1시간
**담당자**: 백엔드 개발팀
**우선순위**: 🟡 중간 (Phase 3.7)
**상태**: ⏳ **대기 중**
**특이사항**: JSON 필드 처리, GROUP BY, DISTINCT 쿼리 포함

484
PHASE3.8_DB_TYPE_CATEGORY_SERVICE_MIGRATION.md
View File

@ -1,484 +0,0 @@
# 🗂️ Phase 3.8: DbTypeCategoryService Raw Query 전환 계획
## 📋 개요
DbTypeCategoryService는 **10개의 Prisma 호출**이 있으며, 데이터베이스 타입 카테고리 관리를 담당하는 서비스입니다.
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | ------------------------------------------------------ |
| 파일 위치 | `backend-node/src/services/dbTypeCategoryService.ts` |
| 파일 크기 | 320+ 라인 |
| Prisma 호출 | 10개 |
| **현재 진행률** | **0/10 (0%)** 🔄 **진행 예정** |
| 복잡도 | 중간 (CRUD, 통계, UPSERT) |
| 우선순위 | 🟡 중간 (Phase 3.8) |
| **상태** | ⏳ **대기 중** |
### 🎯 전환 목표
- ⏳ **10개 모든 Prisma 호출을 `db.ts`의 `query()`, `queryOne()` 함수로 교체**
- ⏳ ApiResponse 래퍼 패턴 유지
- ⏳ GROUP BY 통계 쿼리 전환
- ⏳ UPSERT 로직 전환 (ON CONFLICT)
- ⏳ 모든 단위 테스트 통과
- ⏳ **Prisma import 완전 제거**
---
## 🔍 Prisma 사용 현황 분석
### 주요 Prisma 호출 (10개)
#### 1. **getAllCategories()** - 카테고리 목록 조회
```typescript
// Line 45
const categories = await prisma.db_type_categories.findMany({
where: { is_active: true },
orderBy: [
{ sort_order: 'asc' },
{ display_name: 'asc' }
]
});
```
#### 2. **getCategoryByTypeCode()** - 카테고리 단건 조회
```typescript
// Line 73
const category = await prisma.db_type_categories.findUnique({
where: { type_code: typeCode }
});
```
#### 3. **createCategory()** - 카테고리 생성
```typescript
// Line 105, 116
const existing = await prisma.db_type_categories.findUnique({
where: { type_code: data.type_code }
});
const category = await prisma.db_type_categories.create({
data: {
type_code: data.type_code,
display_name: data.display_name,
icon: data.icon,
color: data.color,
sort_order: data.sort_order ?? 0,
is_active: true,
}
});
```
#### 4. **updateCategory()** - 카테고리 수정
```typescript
// Line 146
const category = await prisma.db_type_categories.update({
where: { type_code: typeCode },
data: updateData
});
```
#### 5. **deleteCategory()** - 카테고리 삭제 (연결 확인)
```typescript
// Line 179, 193
const connectionsCount = await prisma.external_db_connections.count({
where: { db_type: typeCode }
});
await prisma.db_type_categories.update({
where: { type_code: typeCode },
data: { is_active: false }
});
```
#### 6. **getCategoryStatistics()** - 카테고리별 통계
```typescript
// Line 220, 229
const stats = await prisma.external_db_connections.groupBy({
by: ['db_type'],
_count: { id: true }
});
const categories = await prisma.db_type_categories.findMany({
where: { is_active: true }
});
```
#### 7. **syncPredefinedCategories()** - 사전 정의 카테고리 동기화
```typescript
// Line 300
await prisma.db_type_categories.upsert({
where: { type_code: category.type_code },
update: {
display_name: category.display_name,
icon: category.icon,
color: category.color,
sort_order: category.sort_order,
},
create: {
type_code: category.type_code,
display_name: category.display_name,
icon: category.icon,
color: category.color,
sort_order: category.sort_order,
is_active: true,
},
});
```
---
## 📝 전환 계획
### 1단계: 기본 CRUD 전환 (5개 함수)
**함수 목록**:
- `getAllCategories()` - 목록 조회 (findMany)
- `getCategoryByTypeCode()` - 단건 조회 (findUnique)
- `createCategory()` - 생성 (findUnique + create)
- `updateCategory()` - 수정 (update)
- `deleteCategory()` - 삭제 (count + update - soft delete)
### 2단계: 통계 및 UPSERT 전환 (2개 함수)
**함수 목록**:
- `getCategoryStatistics()` - 통계 (groupBy + findMany)
- `syncPredefinedCategories()` - 동기화 (upsert)
---
## 💻 전환 예시
### 예시 1: 카테고리 목록 조회 (정렬)
```typescript
// 기존 Prisma
const categories = await prisma.db_type_categories.findMany({
where: { is_active: true },
orderBy: [
{ sort_order: 'asc' },
{ display_name: 'asc' }
]
});
// 전환 후
import { query } from "../database/db";
const categories = await query<DbTypeCategory>(
`SELECT * FROM db_type_categories
WHERE is_active = $1
ORDER BY sort_order ASC, display_name ASC`,
[true]
);
```
### 예시 2: 카테고리 생성 (중복 확인)
```typescript
// 기존 Prisma
const existing = await prisma.db_type_categories.findUnique({
where: { type_code: data.type_code }
});
if (existing) {
return {
success: false,
message: "이미 존재하는 타입 코드입니다."
};
}
const category = await prisma.db_type_categories.create({
data: {
type_code: data.type_code,
display_name: data.display_name,
icon: data.icon,
color: data.color,
sort_order: data.sort_order ?? 0,
is_active: true,
}
});
// 전환 후
import { query, queryOne } from "../database/db";
const existing = await queryOne<DbTypeCategory>(
`SELECT * FROM db_type_categories WHERE type_code = $1`,
[data.type_code]
);
if (existing) {
return {
success: false,
message: "이미 존재하는 타입 코드입니다."
};
}
const category = await queryOne<DbTypeCategory>(
`INSERT INTO db_type_categories
(type_code, display_name, icon, color, sort_order, is_active, created_at, updated_at)
VALUES ($1, $2, $3, $4, $5, $6, NOW(), NOW())
RETURNING *`,
[
data.type_code,
data.display_name,
data.icon || null,
data.color || null,
data.sort_order ?? 0,
true,
]
);
```
### 예시 3: 동적 UPDATE (변경된 필드만)
```typescript
// 기존 Prisma
const updateData: any = {};
if (data.display_name !== undefined) updateData.display_name = data.display_name;
if (data.icon !== undefined) updateData.icon = data.icon;
if (data.color !== undefined) updateData.color = data.color;
if (data.sort_order !== undefined) updateData.sort_order = data.sort_order;
if (data.is_active !== undefined) updateData.is_active = data.is_active;
const category = await prisma.db_type_categories.update({
where: { type_code: typeCode },
data: updateData
});
// 전환 후
const updateFields: string[] = ["updated_at = NOW()"];
const values: any[] = [];
let paramIndex = 1;
if (data.display_name !== undefined) {
updateFields.push(`display_name = $${paramIndex++}`);
values.push(data.display_name);
}
if (data.icon !== undefined) {
updateFields.push(`icon = $${paramIndex++}`);
values.push(data.icon);
}
if (data.color !== undefined) {
updateFields.push(`color = $${paramIndex++}`);
values.push(data.color);
}
if (data.sort_order !== undefined) {
updateFields.push(`sort_order = $${paramIndex++}`);
values.push(data.sort_order);
}
if (data.is_active !== undefined) {
updateFields.push(`is_active = $${paramIndex++}`);
values.push(data.is_active);
}
const category = await queryOne<DbTypeCategory>(
`UPDATE db_type_categories
SET ${updateFields.join(", ")}
WHERE type_code = $${paramIndex}
RETURNING *`,
[...values, typeCode]
);
```
### 예시 4: 삭제 전 연결 확인
```typescript
// 기존 Prisma
const connectionsCount = await prisma.external_db_connections.count({
where: { db_type: typeCode }
});
if (connectionsCount > 0) {
return {
success: false,
message: `이 카테고리를 사용 중인 연결이 ${connectionsCount}개 있습니다.`
};
}
await prisma.db_type_categories.update({
where: { type_code: typeCode },
data: { is_active: false }
});
// 전환 후
const countResult = await queryOne<{ count: string }>(
`SELECT COUNT(*) as count FROM external_db_connections WHERE db_type = $1`,
[typeCode]
);
const connectionsCount = parseInt(countResult?.count || "0");
if (connectionsCount > 0) {
return {
success: false,
message: `이 카테고리를 사용 중인 연결이 ${connectionsCount}개 있습니다.`
};
}
await query(
`UPDATE db_type_categories SET is_active = $1, updated_at = NOW() WHERE type_code = $2`,
[false, typeCode]
);
```
### 예시 5: GROUP BY 통계 + JOIN
```typescript
// 기존 Prisma
const stats = await prisma.external_db_connections.groupBy({
by: ['db_type'],
_count: { id: true }
});
const categories = await prisma.db_type_categories.findMany({
where: { is_active: true }
});
// 전환 후
const stats = await query<{
type_code: string;
display_name: string;
connection_count: string;
}>(
`SELECT
c.type_code,
c.display_name,
COUNT(e.id) as connection_count
FROM db_type_categories c
LEFT JOIN external_db_connections e ON c.type_code = e.db_type
WHERE c.is_active = $1
GROUP BY c.type_code, c.display_name
ORDER BY c.sort_order ASC`,
[true]
);
// 결과 포맷팅
const result = stats.map(row => ({
type_code: row.type_code,
display_name: row.display_name,
connection_count: parseInt(row.connection_count),
}));
```
### 예시 6: UPSERT (ON CONFLICT)
```typescript
// 기존 Prisma
await prisma.db_type_categories.upsert({
where: { type_code: category.type_code },
update: {
display_name: category.display_name,
icon: category.icon,
color: category.color,
sort_order: category.sort_order,
},
create: {
type_code: category.type_code,
display_name: category.display_name,
icon: category.icon,
color: category.color,
sort_order: category.sort_order,
is_active: true,
},
});
// 전환 후
await query(
`INSERT INTO db_type_categories
(type_code, display_name, icon, color, sort_order, is_active, created_at, updated_at)
VALUES ($1, $2, $3, $4, $5, $6, NOW(), NOW())
ON CONFLICT (type_code)
DO UPDATE SET
display_name = EXCLUDED.display_name,
icon = EXCLUDED.icon,
color = EXCLUDED.color,
sort_order = EXCLUDED.sort_order,
updated_at = NOW()`,
[
category.type_code,
category.display_name,
category.icon || null,
category.color || null,
category.sort_order || 0,
true,
]
);
```
---
## ✅ 완료 기준
- [ ] **10개 모든 Prisma 호출을 Raw Query로 전환 완료**
- [ ] **동적 UPDATE 쿼리 생성**
- [ ] **GROUP BY + LEFT JOIN 통계 쿼리**
- [ ] **ON CONFLICT를 사용한 UPSERT**
- [ ] **ApiResponse 래퍼 패턴 유지**
- [ ] **모든 TypeScript 컴파일 오류 해결**
- [ ] **`import prisma` 완전 제거**
- [ ] **모든 단위 테스트 통과 (10개)**
- [ ] **통합 테스트 작성 완료 (3개 시나리오)**
---
## 🔧 주요 기술적 과제
### 1. ApiResponse 래퍼 패턴
모든 함수가 `ApiResponse<T>` 타입을 반환하므로, 에러 처리를 try-catch로 감싸고 일관된 응답 형식을 유지해야 합니다.
### 2. Soft Delete 패턴
`deleteCategory()`는 실제 DELETE가 아닌 `is_active = false` 업데이트로 처리됩니다.
### 3. 연결 확인
카테고리 삭제 전 `external_db_connections` 테이블에서 사용 중인지 확인해야 합니다.
### 4. UPSERT 로직
PostgreSQL의 `ON CONFLICT` 절을 사용하여 Prisma의 `upsert` 기능을 구현합니다.
### 5. 통계 쿼리 최적화
`groupBy` + 별도 조회 대신, 하나의 `LEFT JOIN` + `GROUP BY` 쿼리로 최적화 가능합니다.
---
## 📋 체크리스트
### 코드 전환
- [ ] import 문 수정 (`prisma` → `query, queryOne`)
- [ ] getAllCategories() - findMany → query
- [ ] getCategoryByTypeCode() - findUnique → queryOne
- [ ] createCategory() - findUnique + create → queryOne (중복 확인 + INSERT)
- [ ] updateCategory() - update → queryOne (동적 UPDATE)
- [ ] deleteCategory() - count + update → queryOne + query
- [ ] getCategoryStatistics() - groupBy + findMany → query (LEFT JOIN)
- [ ] syncPredefinedCategories() - upsert → query (ON CONFLICT)
- [ ] ApiResponse 래퍼 유지
- [ ] Prisma import 완전 제거
### 테스트
- [ ] 단위 테스트 작성 (10개)
- [ ] 통합 테스트 작성 (3개)
- [ ] TypeScript 컴파일 성공
- [ ] 성능 벤치마크 테스트
---
## 💡 특이사항
### ApiResponse 패턴
이 서비스는 모든 메서드가 `ApiResponse<T>` 형식으로 응답을 반환합니다. Raw Query 전환 후에도 이 패턴을 유지해야 합니다.
### 사전 정의 카테고리
`syncPredefinedCategories()` 메서드는 시스템 초기화 시 사전 정의된 DB 타입 카테고리를 동기화합니다. UPSERT 로직이 필수입니다.
### 외래 키 확인
카테고리 삭제 시 `external_db_connections` 테이블에서 사용 중인지 확인하여 데이터 무결성을 보장합니다.
---
**작성일**: 2025-10-01
**예상 소요 시간**: 1시간
**담당자**: 백엔드 개발팀
**우선순위**: 🟡 중간 (Phase 3.8)
**상태**: ⏳ **대기 중**
**특이사항**: ApiResponse 래퍼, UPSERT, GROUP BY + LEFT JOIN 포함

408
PHASE3.9_TEMPLATE_STANDARD_SERVICE_MIGRATION.md
View File

@ -1,408 +0,0 @@
# 📋 Phase 3.9: TemplateStandardService Raw Query 전환 계획
## 📋 개요
TemplateStandardService는 **6개의 Prisma 호출**이 있으며, 템플릿 표준 관리를 담당하는 서비스입니다.
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | ------------------------------------------------------ |
| 파일 위치 | `backend-node/src/services/templateStandardService.ts` |
| 파일 크기 | 395 라인 |
| Prisma 호출 | 6개 |
| **현재 진행률** | **7/7 (100%)** ✅ **전환 완료** |
| 복잡도 | 낮음 (기본 CRUD + DISTINCT) |
| 우선순위 | 🟢 낮음 (Phase 3.9) |
| **상태** | ✅ **완료** |
### 🎯 전환 목표
- ✅ **7개 모든 Prisma 호출을 `db.ts`의 `query()`, `queryOne()` 함수로 교체**
- ✅ 템플릿 CRUD 기능 정상 동작
- ✅ DISTINCT 쿼리 전환
- ✅ Promise.all 병렬 쿼리 (목록 + 개수)
- ✅ 동적 UPDATE 쿼리 (11개 필드)
- ✅ TypeScript 컴파일 성공
- ✅ **Prisma import 완전 제거**
---
## 🔍 Prisma 사용 현황 분석
### 주요 Prisma 호출 (6개)
#### 1. **getTemplateByCode()** - 템플릿 단건 조회
```typescript
// Line 76
return await prisma.template_standards.findUnique({
where: {
template_code: templateCode,
company_code: companyCode,
},
});
```
#### 2. **createTemplate()** - 템플릿 생성
```typescript
// Line 86
const existing = await prisma.template_standards.findUnique({
where: {
template_code: data.template_code,
company_code: data.company_code,
},
});
// Line 96
return await prisma.template_standards.create({
data: {
...data,
created_date: new Date(),
updated_date: new Date(),
},
});
```
#### 3. **updateTemplate()** - 템플릿 수정
```typescript
// Line 164
return await prisma.template_standards.update({
where: {
template_code_company_code: {
template_code: templateCode,
company_code: companyCode,
},
},
data: {
...data,
updated_date: new Date(),
},
});
```
#### 4. **deleteTemplate()** - 템플릿 삭제
```typescript
// Line 181
await prisma.template_standards.delete({
where: {
template_code_company_code: {
template_code: templateCode,
company_code: companyCode,
},
},
});
```
#### 5. **getTemplateCategories()** - 카테고리 목록 (DISTINCT)
```typescript
// Line 262
const categories = await prisma.template_standards.findMany({
where: {
company_code: companyCode,
},
select: {
category: true,
},
distinct: ["category"],
});
```
---
## 📝 전환 계획
### 1단계: 기본 CRUD 전환 (4개 함수)
**함수 목록**:
- `getTemplateByCode()` - 단건 조회 (findUnique)
- `createTemplate()` - 생성 (findUnique + create)
- `updateTemplate()` - 수정 (update)
- `deleteTemplate()` - 삭제 (delete)
### 2단계: 추가 기능 전환 (1개 함수)
**함수 목록**:
- `getTemplateCategories()` - 카테고리 목록 (findMany + distinct)
---
## 💻 전환 예시
### 예시 1: 복합 키 조회
```typescript
// 기존 Prisma
return await prisma.template_standards.findUnique({
where: {
template_code: templateCode,
company_code: companyCode,
},
});
// 전환 후
import { queryOne } from "../database/db";
return await queryOne<any>(
`SELECT * FROM template_standards
WHERE template_code = $1 AND company_code = $2`,
[templateCode, companyCode]
);
```
### 예시 2: 중복 확인 후 생성
```typescript
// 기존 Prisma
const existing = await prisma.template_standards.findUnique({
where: {
template_code: data.template_code,
company_code: data.company_code,
},
});
if (existing) {
throw new Error("이미 존재하는 템플릿 코드입니다.");
}
return await prisma.template_standards.create({
data: {
...data,
created_date: new Date(),
updated_date: new Date(),
},
});
// 전환 후
const existing = await queryOne<any>(
`SELECT * FROM template_standards
WHERE template_code = $1 AND company_code = $2`,
[data.template_code, data.company_code]
);
if (existing) {
throw new Error("이미 존재하는 템플릿 코드입니다.");
}
return await queryOne<any>(
`INSERT INTO template_standards
(template_code, template_name, category, template_type, layout_config,
description, is_active, company_code, created_by, updated_by,
created_date, updated_date)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, NOW(), NOW())
RETURNING *`,
[
data.template_code,
data.template_name,
data.category,
data.template_type,
JSON.stringify(data.layout_config),
data.description,
data.is_active,
data.company_code,
data.created_by,
data.updated_by,
]
);
```
### 예시 3: 복합 키 UPDATE
```typescript
// 기존 Prisma
return await prisma.template_standards.update({
where: {
template_code_company_code: {
template_code: templateCode,
company_code: companyCode,
},
},
data: {
...data,
updated_date: new Date(),
},
});
// 전환 후
// 동적 UPDATE 쿼리 생성
const updateFields: string[] = ["updated_date = NOW()"];
const values: any[] = [];
let paramIndex = 1;
if (data.template_name !== undefined) {
updateFields.push(`template_name = $${paramIndex++}`);
values.push(data.template_name);
}
if (data.category !== undefined) {
updateFields.push(`category = $${paramIndex++}`);
values.push(data.category);
}
if (data.template_type !== undefined) {
updateFields.push(`template_type = $${paramIndex++}`);
values.push(data.template_type);
}
if (data.layout_config !== undefined) {
updateFields.push(`layout_config = $${paramIndex++}`);
values.push(JSON.stringify(data.layout_config));
}
if (data.description !== undefined) {
updateFields.push(`description = $${paramIndex++}`);
values.push(data.description);
}
if (data.is_active !== undefined) {
updateFields.push(`is_active = $${paramIndex++}`);
values.push(data.is_active);
}
if (data.updated_by !== undefined) {
updateFields.push(`updated_by = $${paramIndex++}`);
values.push(data.updated_by);
}
return await queryOne<any>(
`UPDATE template_standards
SET ${updateFields.join(", ")}
WHERE template_code = $${paramIndex++} AND company_code = $${paramIndex}
RETURNING *`,
[...values, templateCode, companyCode]
);
```
### 예시 4: 복합 키 DELETE
```typescript
// 기존 Prisma
await prisma.template_standards.delete({
where: {
template_code_company_code: {
template_code: templateCode,
company_code: companyCode,
},
},
});
// 전환 후
import { query } from "../database/db";
await query(
`DELETE FROM template_standards
WHERE template_code = $1 AND company_code = $2`,
[templateCode, companyCode]
);
```
### 예시 5: DISTINCT 쿼리
```typescript
// 기존 Prisma
const categories = await prisma.template_standards.findMany({
where: {
company_code: companyCode,
},
select: {
category: true,
},
distinct: ["category"],
});
return categories
.map((c) => c.category)
.filter((c): c is string => c !== null && c !== undefined)
.sort();
// 전환 후
const categories = await query<{ category: string }>(
`SELECT DISTINCT category
FROM template_standards
WHERE company_code = $1 AND category IS NOT NULL
ORDER BY category ASC`,
[companyCode]
);
return categories.map((c) => c.category);
```
---
## ✅ 완료 기준
- [ ] **6개 모든 Prisma 호출을 Raw Query로 전환 완료**
- [ ] **복합 기본 키 처리 (template_code + company_code)**
- [ ] **동적 UPDATE 쿼리 생성**
- [ ] **DISTINCT 쿼리 전환**
- [ ] **JSON 필드 처리 (layout_config)**
- [ ] **모든 TypeScript 컴파일 오류 해결**
- [ ] **`import prisma` 완전 제거**
- [ ] **모든 단위 테스트 통과 (6개)**
- [ ] **통합 테스트 작성 완료 (2개 시나리오)**
---
## 🔧 주요 기술적 과제
### 1. 복합 기본 키
`template_standards` 테이블은 `(template_code, company_code)` 복합 기본 키를 사용합니다.
- WHERE 절에서 두 컬럼 모두 지정 필요
- Prisma의 `template_code_company_code` 표현식을 `template_code = $1 AND company_code = $2`로 변환
### 2. JSON 필드
`layout_config` 필드는 JSON 타입으로, INSERT/UPDATE 시 `JSON.stringify()` 필요합니다.
### 3. DISTINCT + NULL 제외
카테고리 목록 조회 시 `DISTINCT` 사용하며, NULL 값은 `WHERE category IS NOT NULL`로 제외합니다.
---
## 📋 체크리스트
### 코드 전환
- [ ] import 문 수정 (`prisma` → `query, queryOne`)
- [ ] getTemplateByCode() - findUnique → queryOne (복합 키)
- [ ] createTemplate() - findUnique + create → queryOne (중복 확인 + INSERT)
- [ ] updateTemplate() - update → queryOne (동적 UPDATE, 복합 키)
- [ ] deleteTemplate() - delete → query (복합 키)
- [ ] getTemplateCategories() - findMany + distinct → query (DISTINCT)
- [ ] JSON 필드 처리 (layout_config)
- [ ] Prisma import 완전 제거
### 테스트
- [ ] 단위 테스트 작성 (6개)
- [ ] 통합 테스트 작성 (2개)
- [ ] TypeScript 컴파일 성공
- [ ] 성능 벤치마크 테스트
---
## 💡 특이사항
### 복합 기본 키 패턴
이 서비스는 `(template_code, company_code)` 복합 기본 키를 사용하므로, 모든 조회/수정/삭제 작업에서 두 컬럼을 모두 WHERE 조건에 포함해야 합니다.
### JSON 레이아웃 설정
`layout_config` 필드는 템플릿의 레이아웃 설정을 JSON 형태로 저장합니다. Raw Query 전환 시 `JSON.stringify()`를 사용하여 문자열로 변환해야 합니다.
### 카테고리 관리
템플릿은 카테고리별로 분류되며, `getTemplateCategories()` 메서드로 고유한 카테고리 목록을 조회할 수 있습니다.
---
**작성일**: 2025-10-01
**예상 소요 시간**: 45분
**담당자**: 백엔드 개발팀
**우선순위**: 🟢 낮음 (Phase 3.9)
**상태**: ⏳ **대기 중**
**특이사항**: 복합 기본 키, JSON 필드, DISTINCT 쿼리 포함

522
PHASE4.1_ADMIN_CONTROLLER_MIGRATION.md
View File

@ -1,522 +0,0 @@
# Phase 4.1: AdminController Raw Query 전환 계획
## 📋 개요
관리자 컨트롤러의 Prisma 호출을 Raw Query로 전환합니다.
사용자, 회사, 부서, 메뉴 관리 등 핵심 관리 기능을 포함합니다.
---
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | ------------------------------------------------- |
| 파일 위치 | `backend-node/src/controllers/adminController.ts` |
| 파일 크기 | 2,569 라인 |
| Prisma 호출 | 28개 → 0개 |
| **현재 진행률** | **28/28 (100%)** ✅ **완료** |
| 복잡도 | 중간 (다양한 CRUD 패턴) |
| 우선순위 | 🔴 높음 (Phase 4.1) |
| **상태** | ✅ **완료** (2025-10-01) |
---
## 🔍 Prisma 호출 분석
### 사용자 관리 (13개)
#### 1. getUserList (라인 312-317)
```typescript
const totalCount = await prisma.user_info.count({ where });
const users = await prisma.user_info.findMany({ where, skip, take, orderBy });
```
- **전환**: count → `queryOne`, findMany → `query`
- **복잡도**: 중간 (동적 WHERE, 페이징)
#### 2. getUserInfo (라인 419)
```typescript
const userInfo = await prisma.user_info.findFirst({ where });
```
- **전환**: findFirst → `queryOne`
- **복잡도**: 낮음
#### 3. updateUserStatus (라인 498)
```typescript
await prisma.user_info.update({ where, data });
```
- **전환**: update → `query`
- **복잡도**: 낮음
#### 4. deleteUserByAdmin (라인 2387)
```typescript
await prisma.user_info.update({ where, data: { is_active: "N" } });
```
- **전환**: update (soft delete) → `query`
- **복잡도**: 낮음
#### 5. getMyProfile (라인 1468, 1488, 2479)
```typescript
const user = await prisma.user_info.findUnique({ where });
const dept = await prisma.dept_info.findUnique({ where });
```
- **전환**: findUnique → `queryOne`
- **복잡도**: 낮음
#### 6. updateMyProfile (라인 1864, 2527)
```typescript
const updateResult = await prisma.user_info.update({ where, data });
```
- **전환**: update → `queryOne` with RETURNING
- **복잡도**: 중간 (동적 UPDATE)
#### 7. createOrUpdateUser (라인 1929, 1975)
```typescript
const savedUser = await prisma.user_info.upsert({ where, update, create });
const userCount = await prisma.user_info.count({ where });
```
- **전환**: upsert → `INSERT ... ON CONFLICT`, count → `queryOne`
- **복잡도**: 높음
#### 8. 기타 findUnique (라인 1596, 1832, 2393)
```typescript
const existingUser = await prisma.user_info.findUnique({ where });
const currentUser = await prisma.user_info.findUnique({ where });
const updatedUser = await prisma.user_info.findUnique({ where });
```
- **전환**: findUnique → `queryOne`
- **복잡도**: 낮음
### 회사 관리 (7개)
#### 9. getCompanyList (라인 550, 1276)
```typescript
const companies = await prisma.company_mng.findMany({ orderBy });
```
- **전환**: findMany → `query`
- **복잡도**: 낮음
#### 10. createCompany (라인 2035)
```typescript
const existingCompany = await prisma.company_mng.findFirst({ where });
```
- **전환**: findFirst (중복 체크) → `queryOne`
- **복잡도**: 낮음
#### 11. updateCompany (라인 2172, 2192)
```typescript
const duplicateCompany = await prisma.company_mng.findFirst({ where });
const updatedCompany = await prisma.company_mng.update({ where, data });
```
- **전환**: findFirst → `queryOne`, update → `queryOne`
- **복잡도**: 중간
#### 12. deleteCompany (라인 2261, 2281)
```typescript
const existingCompany = await prisma.company_mng.findUnique({ where });
await prisma.company_mng.delete({ where });
```
- **전환**: findUnique → `queryOne`, delete → `query`
- **복잡도**: 낮음
### 부서 관리 (2개)
#### 13. getDepartmentList (라인 1348)
```typescript
const departments = await prisma.dept_info.findMany({ where, orderBy });
```
- **전환**: findMany → `query`
- **복잡도**: 낮음
#### 14. getDeptInfo (라인 1488)
```typescript
const dept = await prisma.dept_info.findUnique({ where });
```
- **전환**: findUnique → `queryOne`
- **복잡도**: 낮음
### 메뉴 관리 (3개)
#### 15. createMenu (라인 1021)
```typescript
const savedMenu = await prisma.menu_info.create({ data });
```
- **전환**: create → `queryOne` with INSERT RETURNING
- **복잡도**: 중간
#### 16. updateMenu (라인 1087)
```typescript
const updatedMenu = await prisma.menu_info.update({ where, data });
```
- **전환**: update → `queryOne` with UPDATE RETURNING
- **복잡도**: 중간
#### 17. deleteMenu (라인 1149, 1211)
```typescript
const deletedMenu = await prisma.menu_info.delete({ where });
// 재귀 삭제
const deletedMenu = await prisma.menu_info.delete({ where });
```
- **전환**: delete → `query`
- **복잡도**: 중간 (재귀 삭제 로직)
### 다국어 (1개)
#### 18. getMultiLangKeys (라인 665)
```typescript
const result = await prisma.multi_lang_key_master.findMany({ where, orderBy });
```
- **전환**: findMany → `query`
- **복잡도**: 낮음
---
## 📝 전환 전략
### 1단계: Import 변경
```typescript
// 제거
import { PrismaClient } from "@prisma/client";
const prisma = new PrismaClient();
// 추가
import { query, queryOne } from "../database/db";
```
### 2단계: 단순 조회 전환
- findMany → `query<T>`
- findUnique/findFirst → `queryOne<T>`
### 3단계: 동적 WHERE 처리
```typescript
const whereConditions: string[] = [];
const params: any[] = [];
let paramIndex = 1;
if (companyCode) {
whereConditions.push(`company_code = $${paramIndex++}`);
params.push(companyCode);
}
const whereClause =
whereConditions.length > 0 ? `WHERE ${whereConditions.join(" AND ")}` : "";
```
### 4단계: 복잡한 로직 전환
- count → `SELECT COUNT(*) as count`
- upsert → `INSERT ... ON CONFLICT DO UPDATE`
- 동적 UPDATE → 조건부 SET 절 생성
### 5단계: 테스트 및 검증
- 각 함수별 동작 확인
- 에러 처리 확인
- 타입 안전성 확인
---
## 🎯 주요 변경 예시
### getUserList (count + findMany)
```typescript
// Before
const totalCount = await prisma.user_info.count({ where });
const users = await prisma.user_info.findMany({
where,
skip,
take,
orderBy,
});
// After
const whereConditions: string[] = [];
const params: any[] = [];
let paramIndex = 1;
// 동적 WHERE 구성
if (where.company_code) {
whereConditions.push(`company_code = $${paramIndex++}`);
params.push(where.company_code);
}
if (where.user_name) {
whereConditions.push(`user_name ILIKE $${paramIndex++}`);
params.push(`%${where.user_name}%`);
}
const whereClause =
whereConditions.length > 0 ? `WHERE ${whereConditions.join(" AND ")}` : "";
// Count
const countResult = await queryOne<{ count: number }>(
`SELECT COUNT(*) as count FROM user_info ${whereClause}`,
params
);
const totalCount = parseInt(countResult?.count?.toString() || "0", 10);
// 데이터 조회
const usersQuery = `
SELECT * FROM user_info
${whereClause}
ORDER BY created_date DESC
LIMIT $${paramIndex} OFFSET $${paramIndex + 1}
`;
params.push(take, skip);
const users = await query<UserInfo>(usersQuery, params);
```
### createOrUpdateUser (upsert)
```typescript
// Before
const savedUser = await prisma.user_info.upsert({
where: { user_id: userId },
update: updateData,
create: createData
});
// After
const savedUser = await queryOne<UserInfo>(
`INSERT INTO user_info (user_id, user_name, email, ...)
VALUES ($1, $2, $3, ...)
ON CONFLICT (user_id)
DO UPDATE SET
user_name = EXCLUDED.user_name,
email = EXCLUDED.email,
...
RETURNING *`,
[userId, userName, email, ...]
);
```
### updateMyProfile (동적 UPDATE)
```typescript
// Before
const updateResult = await prisma.user_info.update({
where: { user_id: userId },
data: updateData,
});
// After
const updates: string[] = [];
const params: any[] = [];
let paramIndex = 1;
if (updateData.user_name !== undefined) {
updates.push(`user_name = $${paramIndex++}`);
params.push(updateData.user_name);
}
if (updateData.email !== undefined) {
updates.push(`email = $${paramIndex++}`);
params.push(updateData.email);
}
// ... 다른 필드들
params.push(userId);
const updateResult = await queryOne<UserInfo>(
`UPDATE user_info
SET ${updates.join(", ")}, updated_date = NOW()
WHERE user_id = $${paramIndex}
RETURNING *`,
params
);
```
---
## ✅ 체크리스트
### 기본 설정
- ✅ Prisma import 제거 (완전 제거 확인)
- ✅ query, queryOne import 추가 (이미 존재)
- ✅ 타입 import 확인
### 사용자 관리
- ✅ getUserList (count + findMany → Raw Query)
- ✅ getUserLocale (findFirst → queryOne)
- ✅ setUserLocale (update → query)
- ✅ getUserInfo (findUnique → queryOne)
- ✅ checkDuplicateUserId (findUnique → queryOne)
- ✅ changeUserStatus (findUnique + update → queryOne + query)
- ✅ saveUser (upsert → INSERT ON CONFLICT)
- ✅ updateProfile (동적 update → 동적 query)
- ✅ resetUserPassword (update → query)
### 회사 관리
- ✅ getCompanyList (findMany → query)
- ✅ getCompanyListFromDB (findMany → query)
- ✅ createCompany (findFirst → queryOne)
- ✅ updateCompany (findFirst + update → queryOne + query)
- ✅ deleteCompany (delete → query with RETURNING)
### 부서 관리
- ✅ getDepartmentList (findMany → query with 동적 WHERE)
### 메뉴 관리
- ✅ saveMenu (create → query with INSERT RETURNING)
- ✅ updateMenu (update → query with UPDATE RETURNING)
- ✅ deleteMenu (delete → query with DELETE RETURNING)
- ✅ deleteMenusBatch (다중 delete → 반복 query)
### 다국어
- ✅ getLangKeyList (findMany → query)
### 검증
- ✅ TypeScript 컴파일 확인 (에러 없음)
- ✅ Linter 오류 확인
- ⏳ 기능 테스트 (실행 필요)
- ✅ 에러 처리 확인 (기존 구조 유지)
---
## 📌 참고사항
### 동적 쿼리 생성 패턴
모든 동적 WHERE/UPDATE는 다음 패턴을 따릅니다:
1. 조건/필드 배열 생성
2. 파라미터 배열 생성
3. 파라미터 인덱스 관리
4. SQL 문자열 조합
5. query/queryOne 실행
### 에러 처리
기존 try-catch 구조를 유지하며, 데이터베이스 에러를 적절히 변환합니다.
### 트랜잭션
복잡한 로직은 Service Layer로 이동을 고려합니다.
---
## 🎉 완료 요약 (2025-10-01)
### ✅ 전환 완료 현황
| 카테고리 | 함수 수 | 상태 |
|---------|--------|------|
| 사용자 관리 | 9개 | ✅ 완료 |
| 회사 관리 | 5개 | ✅ 완료 |
| 부서 관리 | 1개 | ✅ 완료 |
| 메뉴 관리 | 4개 | ✅ 완료 |
| 다국어 | 1개 | ✅ 완료 |
| **총계** | **20개** | **✅ 100% 완료** |
### 📊 주요 성과
1. **완전한 Prisma 제거**: adminController.ts에서 모든 Prisma 코드 제거 완료
2. **동적 쿼리 지원**: 런타임 테이블 생성/수정 가능
3. **일관된 에러 처리**: 모든 함수에서 통일된 에러 처리 유지
4. **타입 안전성**: TypeScript 컴파일 에러 없음
5. **코드 품질 향상**: 949줄 변경 (+474/-475)
### 🔑 주요 변환 패턴
#### 1. 동적 WHERE 조건
```typescript
let whereConditions: string[] = [];
let queryParams: any[] = [];
let paramIndex = 1;
if (filter) {
whereConditions.push(`field = $${paramIndex}`);
queryParams.push(filter);
paramIndex++;
}
const whereClause = whereConditions.length > 0
? `WHERE ${whereConditions.join(" AND ")}`
: "";
```
#### 2. UPSERT (INSERT ON CONFLICT)
```typescript
const [result] = await query<any>(
`INSERT INTO table (col1, col2) VALUES ($1, $2)
ON CONFLICT (col1) DO UPDATE SET col2 = $2
RETURNING *`,
[val1, val2]
);
```
#### 3. 동적 UPDATE
```typescript
const updateFields: string[] = [];
const updateValues: any[] = [];
let paramIndex = 1;
if (data.field !== undefined) {
updateFields.push(`field = $${paramIndex}`);
updateValues.push(data.field);
paramIndex++;
}
await query(
`UPDATE table SET ${updateFields.join(", ")} WHERE id = $${paramIndex}`,
[...updateValues, id]
);
```
### 🚀 다음 단계
1. **테스트 실행**: 개발 서버에서 모든 API 엔드포인트 테스트
2. **문서 업데이트**: Phase 4 전체 계획서 진행 상황 반영
3. **다음 Phase**: screenFileController.ts 마이그레이션 진행
---
**마지막 업데이트**: 2025-10-01
**작업자**: Claude Agent
**완료 시간**: 약 15분
**변경 라인 수**: 949줄 (추가 474줄, 삭제 475줄)

316
PHASE4_CONTROLLER_LAYER_MIGRATION.md
View File

@ -1,316 +0,0 @@
# Phase 4: Controller Layer Raw Query 전환 계획
## 📋 개요
컨트롤러 레이어에 남아있는 Prisma 호출을 Raw Query로 전환합니다.
대부분의 컨트롤러는 Service 레이어를 호출하지만, 일부 컨트롤러에서 직접 Prisma를 사용하고 있습니다.
---
### 📊 기본 정보
| 항목 | 내용 |
| --------------- | ---------------------------------- |
| 대상 파일 | 7개 컨트롤러 |
| 파일 위치 | `backend-node/src/controllers/` |
| Prisma 호출 | 70개 (28개 완료) |
| **현재 진행률** | **28/70 (40%)** 🔄 **진행 중** |
| 복잡도 | 중간 (대부분 단순 CRUD) |
| 우선순위 | 🟡 중간 (Phase 4) |
| **상태** | 🔄 **진행 중** (adminController 완료) |
---
## 🎯 전환 대상 컨트롤러
### 1. adminController.ts ✅ 완료 (28개)
- **라인 수**: 2,569 라인
- **Prisma 호출**: 28개 → 0개
- **주요 기능**:
- 사용자 관리 (조회, 생성, 수정, 삭제) ✅
- 회사 관리 (조회, 생성, 수정, 삭제) ✅
- 부서 관리 (조회) ✅
- 메뉴 관리 (생성, 수정, 삭제) ✅
- 다국어 키 조회 ✅
- **우선순위**: 🔴 높음
- **상태**: ✅ **완료** (2025-10-01)
- **문서**: [PHASE4.1_ADMIN_CONTROLLER_MIGRATION.md](PHASE4.1_ADMIN_CONTROLLER_MIGRATION.md)
### 2. webTypeStandardController.ts (11개)
- **Prisma 호출**: 11개
- **주요 기능**: 웹타입 표준 관리
- **우선순위**: 🟡 중간
### 3. fileController.ts (11개)
- **Prisma 호출**: 11개
- **주요 기능**: 파일 업로드/다운로드 관리
- **우선순위**: 🟡 중간
### 4. buttonActionStandardController.ts (11개)
- **Prisma 호출**: 11개
- **주요 기능**: 버튼 액션 표준 관리
- **우선순위**: 🟡 중간
### 5. entityReferenceController.ts (4개)
- **Prisma 호출**: 4개
- **주요 기능**: 엔티티 참조 관리
- **우선순위**: 🟢 낮음
### 6. dataflowExecutionController.ts (3개)
- **Prisma 호출**: 3개
- **주요 기능**: 데이터플로우 실행
- **우선순위**: 🟢 낮음
### 7. screenFileController.ts (2개)
- **Prisma 호출**: 2개
- **주요 기능**: 화면 파일 관리
- **우선순위**: 🟢 낮음
---
## 📝 전환 전략
### 기본 원칙
1. **Service Layer 우선**
- 가능하면 Service로 로직 이동
- Controller는 최소한의 로직만 유지
2. **단순 전환**
- 대부분 단순 CRUD → `query`, `queryOne` 사용
- 복잡한 로직은 Service로 이동
3. **에러 처리 유지**
- 기존 try-catch 구조 유지
- 에러 메시지 일관성 유지
### 전환 패턴
#### 1. findMany → query
```typescript
// Before
const users = await prisma.user_info.findMany({
where: { company_code: companyCode },
});
// After
const users = await query<UserInfo>(
`SELECT * FROM user_info WHERE company_code = $1`,
[companyCode]
);
```
#### 2. findUnique → queryOne
```typescript
// Before
const user = await prisma.user_info.findUnique({
where: { user_id: userId },
});
// After
const user = await queryOne<UserInfo>(
`SELECT * FROM user_info WHERE user_id = $1`,
[userId]
);
```
#### 3. create → queryOne with INSERT
```typescript
// Before
const newUser = await prisma.user_info.create({
data: userData
});
// After
const newUser = await queryOne<UserInfo>(
`INSERT INTO user_info (user_id, user_name, ...)
VALUES ($1, $2, ...) RETURNING *`,
[userData.user_id, userData.user_name, ...]
);
```
#### 4. update → queryOne with UPDATE
```typescript
// Before
const updated = await prisma.user_info.update({
where: { user_id: userId },
data: updateData
});
// After
const updated = await queryOne<UserInfo>(
`UPDATE user_info SET user_name = $1, ...
WHERE user_id = $2 RETURNING *`,
[updateData.user_name, ..., userId]
);
```
#### 5. delete → query with DELETE
```typescript
// Before
await prisma.user_info.delete({
where: { user_id: userId },
});
// After
await query(`DELETE FROM user_info WHERE user_id = $1`, [userId]);
```
#### 6. count → queryOne
```typescript
// Before
const count = await prisma.user_info.count({
where: { company_code: companyCode },
});
// After
const result = await queryOne<{ count: number }>(
`SELECT COUNT(*) as count FROM user_info WHERE company_code = $1`,
[companyCode]
);
const count = parseInt(result?.count?.toString() || "0", 10);
```
---
## ✅ 체크리스트
### Phase 4.1: adminController.ts
- [ ] Prisma import 제거
- [ ] query, queryOne import 추가
- [ ] 사용자 관리 함수 전환 (8개)
- [ ] getUserList - count + findMany
- [ ] getUserInfo - findFirst
- [ ] updateUserStatus - update
- [ ] deleteUserByAdmin - update
- [ ] getMyProfile - findUnique
- [ ] updateMyProfile - update
- [ ] createOrUpdateUser - upsert
- [ ] count (getUserList)
- [ ] 회사 관리 함수 전환 (7개)
- [ ] getCompanyList - findMany
- [ ] createCompany - findFirst (중복체크) + create
- [ ] updateCompany - findFirst (중복체크) + update
- [ ] deleteCompany - findUnique + delete
- [ ] 부서 관리 함수 전환 (2개)
- [ ] getDepartmentList - findMany
- [ ] findUnique (부서 조회)
- [ ] 메뉴 관리 함수 전환 (3개)
- [ ] createMenu - create
- [ ] updateMenu - update
- [ ] deleteMenu - delete
- [ ] 기타 함수 전환 (8개)
- [ ] getMultiLangKeys - findMany
- [ ] 컴파일 확인
- [ ] 린터 확인
### Phase 4.2: webTypeStandardController.ts
- [ ] Prisma import 제거
- [ ] query, queryOne import 추가
- [ ] 모든 함수 전환 (11개)
- [ ] 컴파일 확인
- [ ] 린터 확인
### Phase 4.3: fileController.ts
- [ ] Prisma import 제거
- [ ] query, queryOne import 추가
- [ ] 모든 함수 전환 (11개)
- [ ] 컴파일 확인
- [ ] 린터 확인
### Phase 4.4: buttonActionStandardController.ts
- [ ] Prisma import 제거
- [ ] query, queryOne import 추가
- [ ] 모든 함수 전환 (11개)
- [ ] 컴파일 확인
- [ ] 린터 확인
### Phase 4.5: entityReferenceController.ts
- [ ] Prisma import 제거
- [ ] query, queryOne import 추가
- [ ] 모든 함수 전환 (4개)
- [ ] 컴파일 확인
- [ ] 린터 확인
### Phase 4.6: dataflowExecutionController.ts
- [ ] Prisma import 제거
- [ ] query, queryOne import 추가
- [ ] 모든 함수 전환 (3개)
- [ ] 컴파일 확인
- [ ] 린터 확인
### Phase 4.7: screenFileController.ts
- [ ] Prisma import 제거
- [ ] query, queryOne import 추가
- [ ] 모든 함수 전환 (2개)
- [ ] 컴파일 확인
- [ ] 린터 확인
---
## 🎯 예상 결과
### 코드 품질
- ✅ Prisma 의존성 완전 제거
- ✅ 직접적인 SQL 제어
- ✅ 타입 안전성 유지
### 성능
- ✅ 불필요한 ORM 오버헤드 제거
- ✅ 쿼리 최적화 가능
### 유지보수성
- ✅ 명확한 SQL 쿼리
- ✅ 디버깅 용이
- ✅ 데이터베이스 마이그레이션 용이
---
## 📌 참고사항
### Import 변경
```typescript
// Before
import { PrismaClient } from "@prisma/client";
const prisma = new PrismaClient();
// After
import { query, queryOne } from "../database/db";
```
### 타입 정의
- 각 테이블의 타입은 `types/` 디렉토리에서 import
- 필요시 새로운 타입 정의 추가
### 에러 처리
- 기존 try-catch 구조 유지
- 적절한 HTTP 상태 코드 반환
- 사용자 친화적 에러 메시지

546
PHASE4_REMAINING_PRISMA_CALLS.md
View File

@ -1,546 +0,0 @@
# Phase 4: 남은 Prisma 호출 전환 계획
## 📊 현재 상황
| 항목 | 내용 |
| --------------- | -------------------------------- |
| 총 Prisma 호출 | 29개 |
| 대상 파일 | 7개 |
| **현재 진행률** | **17/29 (58.6%)** 🔄 **진행 중** |
| 복잡도 | 중간 |
| 우선순위 | 🔴 높음 (Phase 4) |
| **상태** | ⏳ **진행 중** |
---
## 📁 파일별 현황
### ✅ 완료된 파일 (2개)
1. **adminController.ts** - ✅ **28개 완료**
- 사용자 관리: getUserList, getUserInfo, updateUserStatus, deleteUser
- 프로필 관리: getMyProfile, updateMyProfile, resetPassword
- 사용자 생성/수정: createOrUpdateUser (UPSERT)
- 회사 관리: getCompanyList, createCompany, updateCompany, deleteCompany
- 부서 관리: getDepartmentList, getDeptInfo
- 메뉴 관리: createMenu, updateMenu, deleteMenu
- 다국어: getMultiLangKeys, updateLocale
2. **screenFileController.ts** - ✅ **2개 완료**
- getScreenComponentFiles: findMany → query (LIKE)
- getComponentFiles: findMany → query (LIKE)
---
## ⏳ 남은 파일 (5개, 총 12개 호출)
### 1. webTypeStandardController.ts (11개) 🔴 최우선
**위치**: `backend-node/src/controllers/webTypeStandardController.ts`
#### Prisma 호출 목록:
1. **라인 33**: `getWebTypeStandards()` - findMany
```typescript
const webTypes = await prisma.web_type_standards.findMany({
where,
orderBy,
select,
});
```
2. **라인 58**: `getWebTypeStandard()` - findUnique
```typescript
const webTypeData = await prisma.web_type_standards.findUnique({
where: { id },
});
```
3. **라인 112**: `createWebTypeStandard()` - findUnique (중복 체크)
```typescript
const existingWebType = await prisma.web_type_standards.findUnique({
where: { web_type: webType },
});
```
4. **라인 123**: `createWebTypeStandard()` - create
```typescript
const newWebType = await prisma.web_type_standards.create({
data: { ... }
});
```
5. **라인 178**: `updateWebTypeStandard()` - findUnique (존재 확인)
```typescript
const existingWebType = await prisma.web_type_standards.findUnique({
where: { id },
});
```
6. **라인 189**: `updateWebTypeStandard()` - update
```typescript
const updatedWebType = await prisma.web_type_standards.update({
where: { id }, data: { ... }
});
```
7. **라인 230**: `deleteWebTypeStandard()` - findUnique (존재 확인)
```typescript
const existingWebType = await prisma.web_type_standards.findUnique({
where: { id },
});
```
8. **라인 241**: `deleteWebTypeStandard()` - delete
```typescript
await prisma.web_type_standards.delete({
where: { id },
});
```
9. **라인 275**: `updateSortOrder()` - $transaction
```typescript
await prisma.$transaction(
updates.map((item) =>
prisma.web_type_standards.update({ ... })
)
);
```
10. **라인 277**: `updateSortOrder()` - update (트랜잭션 내부)
11. **라인 305**: `getCategories()` - groupBy
```typescript
const categories = await prisma.web_type_standards.groupBy({
by: ["category"],
where,
_count: true,
});
```
**전환 전략**:
- findMany → `query<WebTypeStandard>` with dynamic WHERE
- findUnique → `queryOne<WebTypeStandard>`
- create → `queryOne` with INSERT RETURNING
- update → `queryOne` with UPDATE RETURNING
- delete → `query` with DELETE
- $transaction → `transaction` with client.query
- groupBy → `query` with GROUP BY, COUNT
---
### 2. fileController.ts (1개) 🟡
**위치**: `backend-node/src/controllers/fileController.ts`
#### Prisma 호출:
1. **라인 726**: `downloadFile()` - findUnique
```typescript
const fileRecord = await prisma.attach_file_info.findUnique({
where: { objid: BigInt(objid) },
});
```
**전환 전략**:
- findUnique → `queryOne<AttachFileInfo>`
---
### 3. multiConnectionQueryService.ts (4개) 🟢
**위치**: `backend-node/src/services/multiConnectionQueryService.ts`
#### Prisma 호출 목록:
1. **라인 1005**: `executeSelect()` - $queryRawUnsafe
```typescript
return await prisma.$queryRawUnsafe(query, ...queryParams);
```
2. **라인 1022**: `executeInsert()` - $queryRawUnsafe
```typescript
const insertResult = await prisma.$queryRawUnsafe(...);
```
3. **라인 1055**: `executeUpdate()` - $queryRawUnsafe
```typescript
return await prisma.$queryRawUnsafe(updateQuery, ...updateParams);
```
4. **라인 1071**: `executeDelete()` - $queryRawUnsafe
```typescript
return await prisma.$queryRawUnsafe(...);
```
**전환 전략**:
- $queryRawUnsafe → `query<any>` (이미 Raw SQL 사용 중)
---
### 4. config/database.ts (4개) 🟢
**위치**: `backend-node/src/config/database.ts`
#### Prisma 호출:
1. **라인 1**: PrismaClient import
2. **라인 17**: prisma 인스턴스 생성
3. **라인 22**: `await prisma.$connect()`
4. **라인 31, 35, 40**: `await prisma.$disconnect()`
**전환 전략**:
- 이 파일은 데이터베이스 설정 파일이므로 완전히 제거
- 기존 `db.ts`의 connection pool로 대체
- 모든 import 경로를 `database` → `database/db`로 변경
---
### 5. routes/ddlRoutes.ts (2개) 🟢
**위치**: `backend-node/src/routes/ddlRoutes.ts`
#### Prisma 호출:
1. **라인 183-184**: 동적 PrismaClient import
```typescript
const { PrismaClient } = await import("@prisma/client");
const prisma = new PrismaClient();
```
2. **라인 186-187**: 연결 테스트
```typescript
await prisma.$queryRaw`SELECT 1`;
await prisma.$disconnect();
```
**전환 전략**:
- 동적 import 제거
- `query('SELECT 1')` 사용
---
### 6. routes/companyManagementRoutes.ts (2개) 🟢
**위치**: `backend-node/src/routes/companyManagementRoutes.ts`
#### Prisma 호출:
1. **라인 32**: findUnique (중복 체크)
```typescript
const existingCompany = await prisma.company_mng.findUnique({
where: { company_code },
});
```
2. **라인 61**: update (회사명 업데이트)
```typescript
await prisma.company_mng.update({
where: { company_code },
data: { company_name },
});
```
**전환 전략**:
- findUnique → `queryOne`
- update → `query`
---
### 7. tests/authService.test.ts (2개) ⚠️
**위치**: `backend-node/src/tests/authService.test.ts`
테스트 파일은 별도 처리 필요 (Phase 5에서 처리)
---
## 🎯 전환 우선순위
### Phase 4.1: 컨트롤러 (완료)
- [x] screenFileController.ts (2개)
- [x] adminController.ts (28개)
### Phase 4.2: 남은 컨트롤러 (진행 예정)
- [ ] webTypeStandardController.ts (11개) - 🔴 최우선
- [ ] fileController.ts (1개)
### Phase 4.3: Routes (진행 예정)
- [ ] ddlRoutes.ts (2개)
- [ ] companyManagementRoutes.ts (2개)
### Phase 4.4: Services (진행 예정)
- [ ] multiConnectionQueryService.ts (4개)
### Phase 4.5: Config (진행 예정)
- [ ] database.ts (4개) - 전체 파일 제거
### Phase 4.6: Tests (Phase 5)
- [ ] authService.test.ts (2개) - 별도 처리
---
## 📋 체크리스트
### webTypeStandardController.ts
- [ ] Prisma import 제거
- [ ] query, queryOne import 추가
- [ ] getWebTypeStandards (findMany → query)
- [ ] getWebTypeStandard (findUnique → queryOne)
- [ ] createWebTypeStandard (findUnique + create → queryOne)
- [ ] updateWebTypeStandard (findUnique + update → queryOne)
- [ ] deleteWebTypeStandard (findUnique + delete → query)
- [ ] updateSortOrder ($transaction → transaction)
- [ ] getCategories (groupBy → query with GROUP BY)
- [ ] TypeScript 컴파일 확인
- [ ] Linter 오류 확인
- [ ] 동작 테스트
### fileController.ts
- [ ] Prisma import 제거
- [ ] queryOne import 추가
- [ ] downloadFile (findUnique → queryOne)
- [ ] TypeScript 컴파일 확인
### routes/ddlRoutes.ts
- [ ] 동적 PrismaClient import 제거
- [ ] query import 추가
- [ ] 연결 테스트 로직 변경
- [ ] TypeScript 컴파일 확인
### routes/companyManagementRoutes.ts
- [ ] Prisma import 제거
- [ ] query, queryOne import 추가
- [ ] findUnique → queryOne
- [ ] update → query
- [ ] TypeScript 컴파일 확인
### services/multiConnectionQueryService.ts
- [ ] Prisma import 제거
- [ ] query import 추가
- [ ] $queryRawUnsafe → query (4곳)
- [ ] TypeScript 컴파일 확인
### config/database.ts
- [ ] 파일 전체 분석
- [ ] 의존성 확인
- [ ] 대체 방안 구현
- [ ] 모든 import 경로 변경
- [ ] 파일 삭제 또는 완전 재작성
---
## 🔧 전환 패턴 요약
### 1. findMany → query
```typescript
// Before
const items = await prisma.table.findMany({ where, orderBy });
// After
const items = await query<T>(
`SELECT * FROM table WHERE ... ORDER BY ...`,
params
);
```
### 2. findUnique → queryOne
```typescript
// Before
const item = await prisma.table.findUnique({ where: { id } });
// After
const item = await queryOne<T>(`SELECT * FROM table WHERE id = $1`, [id]);
```
### 3. create → queryOne with RETURNING
```typescript
// Before
const newItem = await prisma.table.create({ data });
// After
const [newItem] = await query<T>(
`INSERT INTO table (col1, col2) VALUES ($1, $2) RETURNING *`,
[val1, val2]
);
```
### 4. update → query with RETURNING
```typescript
// Before
const updated = await prisma.table.update({ where, data });
// After
const [updated] = await query<T>(
`UPDATE table SET col1 = $1 WHERE id = $2 RETURNING *`,
[val1, id]
);
```
### 5. delete → query
```typescript
// Before
await prisma.table.delete({ where: { id } });
// After
await query(`DELETE FROM table WHERE id = $1`, [id]);
```
### 6. $transaction → transaction
```typescript
// Before
await prisma.$transaction([
prisma.table.update({ ... }),
prisma.table.update({ ... })
]);
// After
await transaction(async (client) => {
await client.query(`UPDATE table SET ...`, params1);
await client.query(`UPDATE table SET ...`, params2);
});
```
### 7. groupBy → query with GROUP BY
```typescript
// Before
const result = await prisma.table.groupBy({
by: ["category"],
_count: true,
});
// After
const result = await query<T>(
`SELECT category, COUNT(*) as count FROM table GROUP BY category`,
[]
);
```
---
## 📈 진행 상황
### 전체 진행률: 17/29 (58.6%)
```
Phase 1-3: Service Layer ████████████████████████████ 100% (415/415)
Phase 4.1: Controllers ████████████████████████████ 100% (30/30)
Phase 4.2: 남은 파일 ███████░░░░░░░░░░░░░░░░░░░░ 58% (17/29)
```
### 상세 진행 상황
| 카테고리 | 완료 | 남음 | 진행률 |
| ----------- | ---- | ---- | ------ |
| Services | 415 | 0 | 100% |
| Controllers | 30 | 11 | 73% |
| Routes | 0 | 4 | 0% |
| Config | 0 | 4 | 0% |
| **총계** | 445 | 19 | 95.9% |
---
## 🎬 다음 단계
1. **webTypeStandardController.ts 전환** (11개)
- 가장 많은 Prisma 호출을 가진 남은 컨트롤러
- 웹 타입 표준 관리 핵심 기능
2. **fileController.ts 전환** (1개)
- 단순 findUnique만 있어 빠르게 처리 가능
3. **Routes 전환** (4개)
- ddlRoutes.ts
- companyManagementRoutes.ts
4. **Service 전환** (4개)
- multiConnectionQueryService.ts
5. **Config 제거** (4개)
- database.ts 완전 제거 또는 재작성
- 모든 의존성 제거
---
## ⚠️ 주의사항
1. **database.ts 처리**
- 현재 많은 파일이 `import prisma from '../config/database'` 사용
- 모든 import를 `import { query, queryOne } from '../database/db'`로 변경 필요
- 단계적으로 진행하여 빌드 오류 방지
2. **BigInt 처리**
- fileController의 `objid: BigInt(objid)` → `objid::bigint` 또는 `CAST(objid AS BIGINT)`
3. **트랜잭션 처리**
- webTypeStandardController의 `updateSortOrder`는 복잡한 트랜잭션
- `transaction` 함수 사용 필요
4. **타입 안전성**
- 모든 Raw Query에 명시적 타입 지정 필요
- `query<WebTypeStandard>`, `queryOne<AttachFileInfo>` 등
---
## 📝 완료 후 작업
- [ ] 전체 컴파일 확인
- [ ] Linter 오류 해결
- [ ] 통합 테스트 실행
- [ ] Prisma 관련 의존성 완전 제거 (package.json)
- [ ] `prisma/` 디렉토리 정리
- [ ] 문서 업데이트
- [ ] 커밋 및 Push
---
**작성일**: 2025-10-01
**최종 업데이트**: 2025-10-01
**상태**: 🔄 진행 중 (58.6% 완료)

759
PHASE_EXTERNAL_CONNECTION_REST_API_ENHANCEMENT.md
View File

@ -1,759 +0,0 @@
# 외부 커넥션 관리 REST API 지원 확장 계획서
## 📋 프로젝트 개요
### 목적
현재 외부 데이터베이스 연결만 관리하는 `/admin/external-connections` 페이지에 REST API 연결 관리 기능을 추가하여, DB와 REST API 커넥션을 통합 관리할 수 있도록 확장합니다.
### 현재 상황
- **기존 기능**: 외부 데이터베이스 연결 정보만 관리 (MySQL, PostgreSQL, Oracle, SQL Server, SQLite)
- **기존 테이블**: `external_db_connections` - DB 연결 정보 저장
- **기존 UI**: 단일 화면에서 DB 연결 목록 표시 및 CRUD 작업
### 요구사항
1. **탭 전환**: DB 연결 관리 ↔ REST API 연결 관리 간 탭 전환 UI
2. **REST API 관리**: 요청 주소별 헤더(키-값 쌍) 관리
3. **연결 테스트**: REST API 호출이 정상 작동하는지 테스트 기능
---
## 🗄️ 데이터베이스 설계
### 신규 테이블: `external_rest_api_connections`
```sql
CREATE TABLE external_rest_api_connections (
id SERIAL PRIMARY KEY,
-- 기본 정보
connection_name VARCHAR(100) NOT NULL UNIQUE,
description TEXT,
-- REST API 연결 정보
base_url VARCHAR(500) NOT NULL, -- 기본 URL (예: https://api.example.com)
default_headers JSONB DEFAULT '{}', -- 기본 헤더 정보 (키-값 쌍)
-- 인증 설정
auth_type VARCHAR(20) DEFAULT 'none', -- none, api-key, bearer, basic, oauth2
auth_config JSONB, -- 인증 관련 설정
-- 고급 설정
timeout INTEGER DEFAULT 30000, -- 요청 타임아웃 (ms)
retry_count INTEGER DEFAULT 0, -- 재시도 횟수
retry_delay INTEGER DEFAULT 1000, -- 재시도 간격 (ms)
-- 관리 정보
company_code VARCHAR(20) DEFAULT '*',
is_active CHAR(1) DEFAULT 'Y',
created_date TIMESTAMP DEFAULT NOW(),
created_by VARCHAR(50),
updated_date TIMESTAMP DEFAULT NOW(),
updated_by VARCHAR(50),
-- 테스트 정보
last_test_date TIMESTAMP,
last_test_result CHAR(1), -- Y: 성공, N: 실패
last_test_message TEXT
);
-- 인덱스
CREATE INDEX idx_rest_api_connections_company ON external_rest_api_connections(company_code);
CREATE INDEX idx_rest_api_connections_active ON external_rest_api_connections(is_active);
CREATE INDEX idx_rest_api_connections_name ON external_rest_api_connections(connection_name);
```
### 샘플 데이터
```sql
INSERT INTO external_rest_api_connections (
connection_name, description, base_url, default_headers, auth_type, auth_config
) VALUES
(
'기상청 API',
'기상청 공공데이터 API',
'https://apis.data.go.kr/1360000/VilageFcstInfoService_2.0',
'{"Content-Type": "application/json", "Accept": "application/json"}',
'api-key',
'{"keyLocation": "query", "keyName": "serviceKey", "keyValue": "your-api-key-here"}'
),
(
'사내 인사 시스템 API',
'인사정보 조회용 내부 API',
'https://hr.company.com/api/v1',
'{"Content-Type": "application/json"}',
'bearer',
'{"token": "your-bearer-token-here"}'
);
```
---
## 🔧 백엔드 구현
### 1. 타입 정의
```typescript
// backend-node/src/types/externalRestApiTypes.ts
export type AuthType = "none" | "api-key" | "bearer" | "basic" | "oauth2";
export interface ExternalRestApiConnection {
id?: number;
connection_name: string;
description?: string;
base_url: string;
default_headers: Record<string, string>;
auth_type: AuthType;
auth_config?: {
// API Key
keyLocation?: "header" | "query";
keyName?: string;
keyValue?: string;
// Bearer Token
token?: string;
// Basic Auth
username?: string;
password?: string;
// OAuth2
clientId?: string;
clientSecret?: string;
tokenUrl?: string;
accessToken?: string;
};
timeout?: number;
retry_count?: number;
retry_delay?: number;
company_code: string;
is_active: string;
created_date?: Date;
created_by?: string;
updated_date?: Date;
updated_by?: string;
last_test_date?: Date;
last_test_result?: string;
last_test_message?: string;
}
export interface ExternalRestApiConnectionFilter {
auth_type?: string;
is_active?: string;
company_code?: string;
search?: string;
}
export interface RestApiTestRequest {
id?: number;
base_url: string;
endpoint?: string; // 테스트할 엔드포인트 (선택)
method?: "GET" | "POST" | "PUT" | "DELETE";
headers?: Record<string, string>;
auth_type?: AuthType;
auth_config?: any;
timeout?: number;
}
export interface RestApiTestResult {
success: boolean;
message: string;
response_time?: number;
status_code?: number;
response_data?: any;
error_details?: string;
}
```
### 2. 서비스 계층
```typescript
// backend-node/src/services/externalRestApiConnectionService.ts
export class ExternalRestApiConnectionService {
// CRUD 메서드
static async getConnections(filter: ExternalRestApiConnectionFilter);
static async getConnectionById(id: number);
static async createConnection(data: ExternalRestApiConnection);
static async updateConnection(
id: number,
data: Partial<ExternalRestApiConnection>
);
static async deleteConnection(id: number);
// 테스트 메서드
static async testConnection(
testRequest: RestApiTestRequest
): Promise<RestApiTestResult>;
static async testConnectionById(
id: number,
endpoint?: string
): Promise<RestApiTestResult>;
// 헬퍼 메서드
private static buildHeaders(
connection: ExternalRestApiConnection
): Record<string, string>;
private static validateConnectionData(data: ExternalRestApiConnection): void;
private static encryptSensitiveData(authConfig: any): any;
private static decryptSensitiveData(authConfig: any): any;
}
```
### 3. API 라우트
```typescript
// backend-node/src/routes/externalRestApiConnectionRoutes.ts
// GET /api/external-rest-api-connections - 목록 조회
// GET /api/external-rest-api-connections/:id - 상세 조회
// POST /api/external-rest-api-connections - 새 연결 생성
// PUT /api/external-rest-api-connections/:id - 연결 수정
// DELETE /api/external-rest-api-connections/:id - 연결 삭제
// POST /api/external-rest-api-connections/test - 연결 테스트 (신규)
// POST /api/external-rest-api-connections/:id/test - ID로 테스트 (기존 연결)
```
### 4. 연결 테스트 구현
```typescript
// REST API 연결 테스트 로직
static async testConnection(testRequest: RestApiTestRequest): Promise<RestApiTestResult> {
const startTime = Date.now();
try {
// 헤더 구성
const headers = { ...testRequest.headers };
// 인증 헤더 추가
if (testRequest.auth_type === 'bearer' && testRequest.auth_config?.token) {
headers['Authorization'] = `Bearer ${testRequest.auth_config.token}`;
} else if (testRequest.auth_type === 'basic') {
const credentials = Buffer.from(
`${testRequest.auth_config.username}:${testRequest.auth_config.password}`
).toString('base64');
headers['Authorization'] = `Basic ${credentials}`;
} else if (testRequest.auth_type === 'api-key') {
if (testRequest.auth_config.keyLocation === 'header') {
headers[testRequest.auth_config.keyName] = testRequest.auth_config.keyValue;
}
}
// URL 구성
let url = testRequest.base_url;
if (testRequest.endpoint) {
url = `${testRequest.base_url}${testRequest.endpoint}`;
}
// API Key가 쿼리에 있는 경우
if (testRequest.auth_type === 'api-key' &&
testRequest.auth_config.keyLocation === 'query') {
const separator = url.includes('?') ? '&' : '?';
url = `${url}${separator}${testRequest.auth_config.keyName}=${testRequest.auth_config.keyValue}`;
}
// HTTP 요청 실행
const response = await fetch(url, {
method: testRequest.method || 'GET',
headers,
signal: AbortSignal.timeout(testRequest.timeout || 30000),
});
const responseTime = Date.now() - startTime;
const responseData = await response.json().catch(() => null);
return {
success: response.ok,
message: response.ok ? '연결 성공' : `연결 실패 (${response.status})`,
response_time: responseTime,
status_code: response.status,
response_data: responseData,
};
} catch (error) {
return {
success: false,
message: '연결 실패',
error_details: error instanceof Error ? error.message : '알 수 없는 오류',
};
}
}
```
---
## 🎨 프론트엔드 구현
### 1. 탭 구조 설계
```typescript
// frontend/app/(main)/admin/external-connections/page.tsx
type ConnectionTabType = "database" | "rest-api";
const [activeTab, setActiveTab] = useState<ConnectionTabType>("database");
```
### 2. 메인 페이지 구조 개선
```tsx
// 탭 헤더
<Tabs
value={activeTab}
onValueChange={(value) => setActiveTab(value as ConnectionTabType)}
>
<TabsList className="grid w-[400px] grid-cols-2">
<TabsTrigger value="database" className="flex items-center gap-2">
<Database className="h-4 w-4" />
데이터베이스 연결
</TabsTrigger>
<TabsTrigger value="rest-api" className="flex items-center gap-2">
<Globe className="h-4 w-4" />
REST API 연결
</TabsTrigger>
</TabsList>
{/* 데이터베이스 연결 탭 */}
<TabsContent value="database">
<DatabaseConnectionList />
</TabsContent>
{/* REST API 연결 탭 */}
<TabsContent value="rest-api">
<RestApiConnectionList />
</TabsContent>
</Tabs>
```
### 3. REST API 연결 목록 컴포넌트
```typescript
// frontend/components/admin/RestApiConnectionList.tsx
export function RestApiConnectionList() {
const [connections, setConnections] = useState<ExternalRestApiConnection[]>(
[]
);
const [searchTerm, setSearchTerm] = useState("");
const [authTypeFilter, setAuthTypeFilter] = useState("ALL");
const [isModalOpen, setIsModalOpen] = useState(false);
const [editingConnection, setEditingConnection] = useState<
ExternalRestApiConnection | undefined
>();
// 테이블 컬럼:
// - 연결명
// - 기본 URL
// - 인증 타입
// - 헤더 수 (default_headers 개수)
// - 상태 (활성/비활성)
// - 마지막 테스트 (날짜 + 결과)
// - 작업 (테스트/편집/삭제)
}
```
### 4. REST API 연결 설정 모달
```typescript
// frontend/components/admin/RestApiConnectionModal.tsx
export function RestApiConnectionModal({
isOpen,
onClose,
onSave,
connection,
}: RestApiConnectionModalProps) {
// 섹션 구성:
// 1. 기본 정보
// - 연결명 (필수)
// - 설명
// - 기본 URL (필수)
// 2. 헤더 관리 (키-값 추가/삭제)
// - 동적 입력 필드
// - + 버튼으로 추가
// - 각 행에 삭제 버튼
// 3. 인증 설정
// - 인증 타입 선택 (none/api-key/bearer/basic/oauth2)
// - 선택된 타입별 설정 필드 표시
// 4. 고급 설정 (접기/펼치기)
// - 타임아웃
// - 재시도 설정
// 5. 테스트 섹션
// - 테스트 엔드포인트 입력 (선택)
// - 테스트 실행 버튼
// - 테스트 결과 표시
}
```
### 5. 헤더 관리 컴포넌트
```typescript
// frontend/components/admin/HeadersManager.tsx
interface HeadersManagerProps {
headers: Record<string, string>;
onChange: (headers: Record<string, string>) => void;
}
export function HeadersManager({ headers, onChange }: HeadersManagerProps) {
const [headersList, setHeadersList] = useState<
Array<{ key: string; value: string }>
>(Object.entries(headers).map(([key, value]) => ({ key, value })));
const addHeader = () => {
setHeadersList([...headersList, { key: "", value: "" }]);
};
const removeHeader = (index: number) => {
const newList = headersList.filter((_, i) => i !== index);
setHeadersList(newList);
updateParent(newList);
};
const updateHeader = (
index: number,
field: "key" | "value",
value: string
) => {
const newList = [...headersList];
newList[index][field] = value;
setHeadersList(newList);
updateParent(newList);
};
const updateParent = (list: Array<{ key: string; value: string }>) => {
const headersObject = list.reduce((acc, { key, value }) => {
if (key.trim()) acc[key] = value;
return acc;
}, {} as Record<string, string>);
onChange(headersObject);
};
// UI: 테이블 형태로 키-값 입력 필드 표시
// 각 행: [키 입력] [값 입력] [삭제 버튼]
// 하단: [+ 헤더 추가] 버튼
}
```
### 6. 인증 설정 컴포넌트
```typescript
// frontend/components/admin/AuthenticationConfig.tsx
export function AuthenticationConfig({
authType,
authConfig,
onChange,
}: AuthenticationConfigProps) {
// authType에 따라 다른 입력 필드 표시
// none: 추가 필드 없음
// api-key:
// - 키 위치 (header/query)
// - 키 이름
// - 키 값
// bearer:
// - 토큰 값
// basic:
// - 사용자명
// - 비밀번호
// oauth2:
// - Client ID
// - Client Secret
// - Token URL
// - Access Token (읽기전용, 자동 갱신)
}
```
### 7. API 클라이언트
```typescript
// frontend/lib/api/externalRestApiConnection.ts
export class ExternalRestApiConnectionAPI {
private static readonly BASE_URL = "/api/external-rest-api-connections";
static async getConnections(filter?: ExternalRestApiConnectionFilter) {
const params = new URLSearchParams();
if (filter?.search) params.append("search", filter.search);
if (filter?.auth_type && filter.auth_type !== "ALL") {
params.append("auth_type", filter.auth_type);
}
if (filter?.is_active && filter.is_active !== "ALL") {
params.append("is_active", filter.is_active);
}
const response = await fetch(`${this.BASE_URL}?${params}`);
return this.handleResponse(response);
}
static async getConnectionById(id: number) {
const response = await fetch(`${this.BASE_URL}/${id}`);
return this.handleResponse(response);
}
static async createConnection(data: ExternalRestApiConnection) {
const response = await fetch(this.BASE_URL, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(data),
});
return this.handleResponse(response);
}
static async updateConnection(
id: number,
data: Partial<ExternalRestApiConnection>
) {
const response = await fetch(`${this.BASE_URL}/${id}`, {
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(data),
});
return this.handleResponse(response);
}
static async deleteConnection(id: number) {
const response = await fetch(`${this.BASE_URL}/${id}`, {
method: "DELETE",
});
return this.handleResponse(response);
}
static async testConnection(
testRequest: RestApiTestRequest
): Promise<RestApiTestResult> {
const response = await fetch(`${this.BASE_URL}/test`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(testRequest),
});
return this.handleResponse(response);
}
static async testConnectionById(
id: number,
endpoint?: string
): Promise<RestApiTestResult> {
const response = await fetch(`${this.BASE_URL}/${id}/test`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ endpoint }),
});
return this.handleResponse(response);
}
private static async handleResponse(response: Response) {
if (!response.ok) {
const error = await response.json().catch(() => ({}));
throw new Error(error.message || "요청 실패");
}
return response.json();
}
}
```
---
## 📋 구현 순서
### Phase 1: 데이터베이스 및 백엔드 기본 구조 (1일)
- [x] 데이터베이스 테이블 생성 (`external_rest_api_connections`)
- [ ] 타입 정의 작성 (`externalRestApiTypes.ts`)
- [ ] 서비스 계층 기본 CRUD 구현
- [ ] API 라우트 기본 구현
### Phase 2: 연결 테스트 기능 (1일)
- [ ] 연결 테스트 로직 구현
- [ ] 인증 타입별 헤더 구성 로직
- [ ] 에러 처리 및 타임아웃 관리
- [ ] 테스트 결과 저장 (last_test_date, last_test_result)
### Phase 3: 프론트엔드 기본 UI (1-2일)
- [ ] 탭 구조 추가 (Database / REST API)
- [ ] REST API 연결 목록 컴포넌트
- [ ] API 클라이언트 작성
- [ ] 기본 CRUD UI 구현
### Phase 4: 모달 및 상세 기능 (1-2일)
- [ ] REST API 연결 설정 모달
- [ ] 헤더 관리 컴포넌트 (키-값 동적 추가/삭제)
- [ ] 인증 설정 컴포넌트 (타입별 입력 필드)
- [ ] 고급 설정 섹션
### Phase 5: 테스트 및 통합 (1일)
- [ ] 연결 테스트 UI
- [ ] 테스트 결과 표시
- [ ] 에러 처리 및 사용자 피드백
- [ ] 전체 기능 통합 테스트
### Phase 6: 최적화 및 마무리 (0.5일)
- [ ] 민감 정보 암호화 (API 키, 토큰, 비밀번호)
- [ ] UI/UX 개선
- [ ] 문서화
---
## 🧪 테스트 시나리오
### 1. REST API 연결 등록 테스트
- [ ] 기본 정보 입력 (연결명, URL)
- [ ] 헤더 추가/삭제
- [ ] 각 인증 타입별 설정
- [ ] 유효성 검증 (필수 필드, URL 형식)
### 2. 연결 테스트
- [ ] 인증 없는 API 테스트
- [ ] API Key (header/query) 테스트
- [ ] Bearer Token 테스트
- [ ] Basic Auth 테스트
- [ ] 타임아웃 시나리오
- [ ] 네트워크 오류 시나리오
### 3. 데이터 관리
- [ ] 목록 조회 및 필터링
- [ ] 연결 수정
- [ ] 연결 삭제
- [ ] 활성/비활성 전환
### 4. 통합 시나리오
- [ ] DB 연결 탭 ↔ REST API 탭 전환
- [ ] 여러 연결 등록 및 관리
- [ ] 동시 테스트 실행
---
## 🔒 보안 고려사항
### 1. 민감 정보 암호화
```typescript
// API 키, 토큰, 비밀번호 암호화
private static encryptSensitiveData(authConfig: any): any {
if (!authConfig) return null;
const encrypted = { ...authConfig };
// 암호화 대상 필드
if (encrypted.keyValue) {
encrypted.keyValue = encrypt(encrypted.keyValue);
}
if (encrypted.token) {
encrypted.token = encrypt(encrypted.token);
}
if (encrypted.password) {
encrypted.password = encrypt(encrypted.password);
}
if (encrypted.clientSecret) {
encrypted.clientSecret = encrypt(encrypted.clientSecret);
}
return encrypted;
}
```
### 2. 접근 권한 제어
- 관리자 권한만 접근
- 회사별 데이터 분리
- API 호출 시 인증 토큰 검증
### 3. 테스트 요청 제한
- Rate Limiting (1분에 최대 10회)
- 타임아웃 설정 (최대 30초)
- 동시 테스트 제한
---
## 📊 성능 최적화
### 1. 헤더 데이터 구조
```typescript
// JSONB 필드 인덱싱 (PostgreSQL)
CREATE INDEX idx_rest_api_headers ON external_rest_api_connections
USING GIN (default_headers);
CREATE INDEX idx_rest_api_auth_config ON external_rest_api_connections
USING GIN (auth_config);
```
### 2. 캐싱 전략
- 자주 사용되는 연결 정보 캐싱
- 테스트 결과 임시 캐싱 (5분)
---
## 📚 향후 확장 가능성
### 1. 엔드포인트 관리
각 REST API 연결에 대해 자주 사용하는 엔드포인트를 사전 등록하여 빠른 호출 가능
### 2. 요청 템플릿
HTTP 메서드별 요청 바디 템플릿 관리
### 3. 응답 매핑
REST API 응답을 내부 데이터 구조로 변환하는 매핑 룰 설정
### 4. 로그 및 모니터링
- API 호출 이력 기록
- 응답 시간 모니터링
- 오류율 추적
---
## ✅ 완료 체크리스트
### 백엔드
- [ ] 데이터베이스 테이블 생성
- [ ] 타입 정의
- [ ] 서비스 계층 CRUD
- [ ] 연결 테스트 로직
- [ ] API 라우트
- [ ] 민감 정보 암호화
### 프론트엔드
- [ ] 탭 구조
- [ ] REST API 연결 목록
- [ ] 연결 설정 모달
- [ ] 헤더 관리 컴포넌트
- [ ] 인증 설정 컴포넌트
- [ ] API 클라이언트
- [ ] 연결 테스트 UI
### 테스트
- [ ] 단위 테스트
- [ ] 통합 테스트
- [ ] 사용자 시나리오 테스트
### 문서
- [ ] API 문서
- [ ] 사용자 가이드
- [ ] 배포 가이드
---
**작성일**: 2025-10-20
**버전**: 1.0
**담당**: AI Assistant

213
PHASE_EXTERNAL_CONNECTION_REST_API_ENHANCEMENT_DONE.md
View File

@ -1,213 +0,0 @@
# REST API 연결 관리 기능 구현 완료
## 구현 개요
외부 커넥션 관리 페이지(`/admin/external-connections`)에 REST API 연결 관리 기능이 추가되었습니다.
기존의 데이터베이스 연결 관리와 함께 REST API 연결도 관리할 수 있도록 탭 기반 UI가 구현되었습니다.
## 구현 완료 사항
### 1. 데이터베이스 (✅ 완료)
**파일**: `/db/create_external_rest_api_connections.sql`
- `external_rest_api_connections` 테이블 생성
- 연결 정보, 인증 설정, 테스트 결과 저장
- JSONB 타입으로 헤더 및 인증 설정 유연하게 관리
- 인덱스 최적화 (company_code, is_active, auth_type, JSONB GIN 인덱스)
**실행 방법**:
```bash
# PostgreSQL 컨테이너에 접속하여 SQL 실행
docker exec -i esgrin-mes-db psql -U postgres -d ilshin < db/create_external_rest_api_connections.sql
```
### 2. 백엔드 구현 (✅ 완료)
#### 2.1 타입 정의
**파일**: `backend-node/src/types/externalRestApiTypes.ts`
- `ExternalRestApiConnection`: REST API 연결 정보 인터페이스
- `RestApiTestRequest`: 연결 테스트 요청 인터페이스
- `RestApiTestResult`: 테스트 결과 인터페이스
- `AuthType`: 인증 타입 (none, api-key, bearer, basic, oauth2)
- 각 인증 타입별 세부 설정 인터페이스
#### 2.2 서비스 레이어
**파일**: `backend-node/src/services/externalRestApiConnectionService.ts`
- CRUD 작업 구현 (생성, 조회, 수정, 삭제)
- 민감 정보 암호화/복호화 (AES-256-GCM)
- REST API 연결 테스트 기능
- 필터링 및 검색 기능
- 유효성 검증
#### 2.3 API 라우트
**파일**: `backend-node/src/routes/externalRestApiConnectionRoutes.ts`
- `GET /api/external-rest-api-connections` - 목록 조회
- `GET /api/external-rest-api-connections/:id` - 상세 조회
- `POST /api/external-rest-api-connections` - 생성
- `PUT /api/external-rest-api-connections/:id` - 수정
- `DELETE /api/external-rest-api-connections/:id` - 삭제
- `POST /api/external-rest-api-connections/test` - 연결 테스트
- `POST /api/external-rest-api-connections/:id/test` - ID 기반 테스트
#### 2.4 앱 통합
**파일**: `backend-node/src/app.ts`
- 새로운 라우트 등록 완료
### 3. 프론트엔드 구현 (✅ 완료)
#### 3.1 API 클라이언트
**파일**: `frontend/lib/api/externalRestApiConnection.ts`
- 백엔드 API와 통신하는 클라이언트 구현
- 타입 안전한 API 호출
- 에러 처리
#### 3.2 공통 컴포넌트
**파일**: `frontend/components/admin/HeadersManager.tsx`
- HTTP 헤더 key-value 관리 컴포넌트
- 동적 추가/삭제 기능
**파일**: `frontend/components/admin/AuthenticationConfig.tsx`
- 인증 타입별 설정 컴포넌트
- 5가지 인증 방식 지원 (none, api-key, bearer, basic, oauth2)
#### 3.3 모달 컴포넌트
**파일**: `frontend/components/admin/RestApiConnectionModal.tsx`
- 연결 추가/수정 모달
- 헤더 관리 및 인증 설정 통합
- 연결 테스트 기능
#### 3.4 목록 관리 컴포넌트
**파일**: `frontend/components/admin/RestApiConnectionList.tsx`
- REST API 연결 목록 표시
- 검색 및 필터링
- CRUD 작업
- 연결 테스트
#### 3.5 메인 페이지
**파일**: `frontend/app/(main)/admin/external-connections/page.tsx`
- 탭 기반 UI 구현 (데이터베이스 ↔ REST API)
- 기존 DB 연결 관리와 통합
## 주요 기능
### 1. 연결 관리
- REST API 연결 정보 생성/수정/삭제
- 연결명, 설명, Base URL 관리
- Timeout, Retry 설정
- 활성화 상태 관리
### 2. 인증 관리
- **None**: 인증 없음
- **API Key**: 헤더 또는 쿼리 파라미터
- **Bearer Token**: Authorization: Bearer {token}
- **Basic Auth**: username/password
- **OAuth2**: client_id, client_secret, token_url 등
### 3. 헤더 관리
- 기본 HTTP 헤더 설정
- Key-Value 형식으로 동적 관리
- Content-Type, Accept 등 자유롭게 설정
### 4. 연결 테스트
- 실시간 연결 테스트
- HTTP 응답 상태 코드 확인
- 응답 시간 측정
- 테스트 결과 저장
### 5. 보안
- 민감 정보 자동 암호화 (AES-256-GCM)
- API Key
- Bearer Token
- 비밀번호
- OAuth2 Client Secret
- 암호화된 데이터는 데이터베이스에 안전하게 저장
## 사용 방법
### 1. SQL 스크립트 실행
```bash
# PostgreSQL 컨테이너에 접속
docker exec -it esgrin-mes-db psql -U postgres -d ilshin
# 또는 파일 직접 실행
docker exec -i esgrin-mes-db psql -U postgres -d ilshin < db/create_external_rest_api_connections.sql
```
### 2. 백엔드 재시작
백엔드 서버가 자동으로 새로운 라우트를 인식합니다. (이미 재시작 완료)
### 3. 웹 UI 접속
1. `/admin/external-connections` 페이지 접속
2. "REST API 연결" 탭 선택
3. "새 연결 추가" 버튼 클릭
4. 필요한 정보 입력
- 연결명, 설명, Base URL
- 기본 헤더 설정
- 인증 타입 선택 및 인증 정보 입력
- Timeout, Retry 설정
5. "연결 테스트" 버튼으로 즉시 테스트 가능
6. 저장
### 4. 연결 관리
- **목록 조회**: 모든 REST API 연결 정보 확인
- **검색**: 연결명, 설명, URL로 검색
- **필터링**: 인증 타입, 활성화 상태로 필터링
- **수정**: 연필 아이콘 클릭하여 수정
- **삭제**: 휴지통 아이콘 클릭하여 삭제
- **테스트**: Play 아이콘 클릭하여 연결 테스트
## 기술 스택
- **Backend**: Node.js, Express, TypeScript, PostgreSQL
- **Frontend**: Next.js, React, TypeScript, Shadcn UI
- **보안**: AES-256-GCM 암호화
- **데이터**: JSONB (PostgreSQL)
## 테스트 완료
- ✅ 백엔드 컴파일 성공
- ✅ 서버 정상 실행 확인
- ✅ 타입 에러 수정 완료
- ✅ 모든 라우트 등록 완료
- ✅ 인증 토큰 자동 포함 구현 (apiClient 사용)
## 다음 단계
1. SQL 스크립트 실행
2. 프론트엔드 빌드 및 테스트
3. UI에서 연결 추가/수정/삭제/테스트 기능 확인
## 참고 문서
- 전체 계획: `PHASE_EXTERNAL_CONNECTION_REST_API_ENHANCEMENT.md`
- 기존 외부 DB 연결: `제어관리_외부커넥션_통합_기능_가이드.md`

1138
PHASE_FLOW_MANAGEMENT_SYSTEM.md
View File

File diff suppressed because it is too large Load Diff

1216
PHASE_FLOW_STEP_BUTTON_VISIBILITY_CONTROL.md
View File

File diff suppressed because it is too large Load Diff

998
PHASE_RESPONSIVE_LAYOUT.md
View File

@ -1,998 +0,0 @@
# 반응형 레이아웃 시스템 구현 계획서
## 📋 프로젝트 개요
### 목표
화면 디자이너는 절대 위치 기반으로 유지하되, 실제 화면 표시는 반응형으로 동작하도록 전환
### 핵심 원칙
- ✅ 화면 디자이너의 절대 위치 기반 드래그앤드롭은 그대로 유지
- ✅ 실제 화면 표시만 반응형으로 전환
- ✅ 데이터 마이그레이션 불필요 (신규 화면부터 적용)
- ✅ 기존 화면은 불러올 때 스마트 기본값 자동 생성
---
## 🎯 Phase 1: 기본 반응형 시스템 구축 (2-3일)
### 1.1 타입 정의 (2시간)
#### 파일: `frontend/types/responsive.ts`
```typescript
/**
* 브레이크포인트 타입 정의
*/
export type Breakpoint = "desktop" | "tablet" | "mobile";
/**
* 브레이크포인트별 설정
*/
export interface BreakpointConfig {
minWidth: number; // 최소 너비 (px)
maxWidth?: number; // 최대 너비 (px)
columns: number; // 그리드 컬럼 수
}
/**
* 기본 브레이크포인트 설정
*/
export const BREAKPOINTS: Record<Breakpoint, BreakpointConfig> = {
desktop: {
minWidth: 1200,
columns: 12,
},
tablet: {
minWidth: 768,
maxWidth: 1199,
columns: 8,
},
mobile: {
minWidth: 0,
maxWidth: 767,
columns: 4,
},
};
/**
* 브레이크포인트별 반응형 설정
*/
export interface ResponsiveBreakpointConfig {
gridColumns?: number; // 차지할 컬럼 수 (1-12)
order?: number; // 정렬 순서
hide?: boolean; // 숨김 여부
}
/**
* 컴포넌트별 반응형 설정
*/
export interface ResponsiveComponentConfig {
// 기본값 (디자이너에서 설정한 절대 위치)
designerPosition: {
x: number;
y: number;
width: number;
height: number;
};
// 반응형 설정 (선택적)
responsive?: {
desktop?: ResponsiveBreakpointConfig;
tablet?: ResponsiveBreakpointConfig;
mobile?: ResponsiveBreakpointConfig;
};
// 스마트 기본값 사용 여부
useSmartDefaults?: boolean;
}
```
### 1.2 스마트 기본값 생성기 (3시간)
#### 파일: `frontend/lib/utils/responsiveDefaults.ts`
```typescript
import { ComponentData } from "@/types/screen-management";
import { ResponsiveComponentConfig, BREAKPOINTS } from "@/types/responsive";
/**
* 컴포넌트 크기에 따른 스마트 기본값 생성
*
* 로직:
* - 작은 컴포넌트 (너비 25% 이하): 모바일에서도 같은 너비 유지
* - 중간 컴포넌트 (너비 25-50%): 모바일에서 전체 너비로 확장
* - 큰 컴포넌트 (너비 50% 이상): 모든 디바이스에서 전체 너비
*/
export function generateSmartDefaults(
component: ComponentData,
screenWidth: number = 1920
): ResponsiveComponentConfig["responsive"] {
const componentWidthPercent = (component.size.width / screenWidth) * 100;
// 작은 컴포넌트 (25% 이하)
if (componentWidthPercent <= 25) {
return {
desktop: {
gridColumns: 3, // 12컬럼 중 3개 (25%)
order: 1,
hide: false,
},
tablet: {
gridColumns: 2, // 8컬럼 중 2개 (25%)
order: 1,
hide: false,
},
mobile: {
gridColumns: 1, // 4컬럼 중 1개 (25%)
order: 1,
hide: false,
},
};
}
// 중간 컴포넌트 (25-50%)
else if (componentWidthPercent <= 50) {
return {
desktop: {
gridColumns: 6, // 12컬럼 중 6개 (50%)
order: 1,
hide: false,
},
tablet: {
gridColumns: 4, // 8컬럼 중 4개 (50%)
order: 1,
hide: false,
},
mobile: {
gridColumns: 4, // 4컬럼 전체 (100%)
order: 1,
hide: false,
},
};
}
// 큰 컴포넌트 (50% 이상)
else {
return {
desktop: {
gridColumns: 12, // 전체 너비
order: 1,
hide: false,
},
tablet: {
gridColumns: 8, // 전체 너비
order: 1,
hide: false,
},
mobile: {
gridColumns: 4, // 전체 너비
order: 1,
hide: false,
},
};
}
}
/**
* 컴포넌트에 반응형 설정이 없을 경우 자동 생성
*/
export function ensureResponsiveConfig(
component: ComponentData,
screenWidth?: number
): ComponentData {
if (component.responsiveConfig) {
return component;
}
return {
...component,
responsiveConfig: {
designerPosition: {
x: component.position.x,
y: component.position.y,
width: component.size.width,
height: component.size.height,
},
useSmartDefaults: true,
responsive: generateSmartDefaults(component, screenWidth),
},
};
}
```
### 1.3 브레이크포인트 감지 훅 (1시간)
#### 파일: `frontend/hooks/useBreakpoint.ts`
```typescript
import { useState, useEffect } from "react";
import { Breakpoint, BREAKPOINTS } from "@/types/responsive";
/**
* 현재 윈도우 크기에 따른 브레이크포인트 반환
*/
export function useBreakpoint(): Breakpoint {
const [breakpoint, setBreakpoint] = useState<Breakpoint>("desktop");
useEffect(() => {
const updateBreakpoint = () => {
const width = window.innerWidth;
if (width >= BREAKPOINTS.desktop.minWidth) {
setBreakpoint("desktop");
} else if (width >= BREAKPOINTS.tablet.minWidth) {
setBreakpoint("tablet");
} else {
setBreakpoint("mobile");
}
};
// 초기 실행
updateBreakpoint();
// 리사이즈 이벤트 리스너 등록
window.addEventListener("resize", updateBreakpoint);
return () => window.removeEventListener("resize", updateBreakpoint);
}, []);
return breakpoint;
}
/**
* 현재 브레이크포인트의 컬럼 수 반환
*/
export function useGridColumns(): number {
const breakpoint = useBreakpoint();
return BREAKPOINTS[breakpoint].columns;
}
```
### 1.4 반응형 레이아웃 엔진 (6시간)
#### 파일: `frontend/components/screen/ResponsiveLayoutEngine.tsx`
```typescript
import React, { useMemo } from "react";
import { ComponentData } from "@/types/screen-management";
import { Breakpoint, BREAKPOINTS } from "@/types/responsive";
import {
generateSmartDefaults,
ensureResponsiveConfig,
} from "@/lib/utils/responsiveDefaults";
import { DynamicComponentRenderer } from "@/lib/registry/DynamicComponentRenderer";
interface ResponsiveLayoutEngineProps {
components: ComponentData[];
breakpoint: Breakpoint;
containerWidth: number;
screenWidth?: number;
}
/**
* 반응형 레이아웃 엔진
*
* 절대 위치로 배치된 컴포넌트들을 반응형 그리드로 변환
*
* 변환 로직:
* 1. Y 위치 기준으로 행(row)으로 그룹화
* 2. 각 행 내에서 X 위치 기준으로 정렬
* 3. 반응형 설정 적용 (order, gridColumns, hide)
* 4. CSS Grid로 렌더링
*/
export const ResponsiveLayoutEngine: React.FC<ResponsiveLayoutEngineProps> = ({
components,
breakpoint,
containerWidth,
screenWidth = 1920,
}) => {
// 1단계: 컴포넌트들을 Y 위치 기준으로 행(row)으로 그룹화
const rows = useMemo(() => {
const sortedComponents = [...components].sort(
(a, b) => a.position.y - b.position.y
);
const rows: ComponentData[][] = [];
let currentRow: ComponentData[] = [];
let currentRowY = 0;
const ROW_THRESHOLD = 50; // 같은 행으로 간주할 Y 오차 범위 (px)
sortedComponents.forEach((comp) => {
if (currentRow.length === 0) {
currentRow.push(comp);
currentRowY = comp.position.y;
} else if (Math.abs(comp.position.y - currentRowY) < ROW_THRESHOLD) {
currentRow.push(comp);
} else {
rows.push(currentRow);
currentRow = [comp];
currentRowY = comp.position.y;
}
});
if (currentRow.length > 0) {
rows.push(currentRow);
}
return rows;
}, [components]);
// 2단계: 각 행 내에서 X 위치 기준으로 정렬
const sortedRows = useMemo(() => {
return rows.map((row) =>
[...row].sort((a, b) => a.position.x - b.position.x)
);
}, [rows]);
// 3단계: 반응형 설정 적용
const responsiveComponents = useMemo(() => {
return sortedRows.flatMap((row) =>
row.map((comp) => {
// 반응형 설정이 없으면 자동 생성
const compWithConfig = ensureResponsiveConfig(comp, screenWidth);
// 현재 브레이크포인트의 설정 가져오기
const config = compWithConfig.responsiveConfig!.useSmartDefaults
? generateSmartDefaults(comp, screenWidth)[breakpoint]
: compWithConfig.responsiveConfig!.responsive?.[breakpoint];
return {
...compWithConfig,
responsiveDisplay:
config || generateSmartDefaults(comp, screenWidth)[breakpoint],
};
})
);
}, [sortedRows, breakpoint, screenWidth]);
// 4단계: 필터링 및 정렬
const visibleComponents = useMemo(() => {
return responsiveComponents
.filter((comp) => !comp.responsiveDisplay?.hide)
.sort(
(a, b) =>
(a.responsiveDisplay?.order || 0) - (b.responsiveDisplay?.order || 0)
);
}, [responsiveComponents]);
const gridColumns = BREAKPOINTS[breakpoint].columns;
return (
<div
className="responsive-grid w-full"
style={{
display: "grid",
gridTemplateColumns: `repeat(${gridColumns}, 1fr)`,
gap: "16px",
padding: "16px",
}}
>
{visibleComponents.map((comp) => (
<div
key={comp.id}
className="responsive-grid-item"
style={{
gridColumn: `span ${
comp.responsiveDisplay?.gridColumns || gridColumns
}`,
}}
>
<DynamicComponentRenderer component={comp} isPreview={true} />
</div>
))}
</div>
);
};
```
### 1.5 화면 표시 페이지 수정 (4시간)
#### 파일: `frontend/app/(main)/screens/[screenId]/page.tsx`
```typescript
// 기존 import 유지
import { ResponsiveLayoutEngine } from "@/components/screen/ResponsiveLayoutEngine";
import { useBreakpoint } from "@/hooks/useBreakpoint";
export default function ScreenViewPage({
params,
}: {
params: { screenId: string };
}) {
const [layout, setLayout] = useState<LayoutData | null>(null);
const breakpoint = useBreakpoint();
// 반응형 모드 토글 (사용자 설정 또는 화면 설정에 따라)
const [useResponsive, setUseResponsive] = useState(true);
// 기존 로직 유지...
if (!layout) {
return <div>로딩 중...</div>;
}
const screenWidth = layout.screenResolution?.width || 1920;
const screenHeight = layout.screenResolution?.height || 1080;
return (
<div className="h-full w-full bg-white">
{useResponsive ? (
// 반응형 모드
<ResponsiveLayoutEngine
components={layout.components || []}
breakpoint={breakpoint}
containerWidth={window.innerWidth}
screenWidth={screenWidth}
/>
) : (
// 기존 스케일 모드 (하위 호환성)
<div className="overflow-auto" style={{ padding: "16px 0" }}>
<div
style={{
width: `${screenWidth * scale}px`,
minHeight: `${screenHeight * scale}px`,
marginLeft: "16px",
marginRight: "16px",
}}
>
<div
className="relative bg-white"
style={{
width: `${screenWidth}px`,
minHeight: `${screenHeight}px`,
transform: `scale(${scale})`,
transformOrigin: "top left",
}}
>
{layout.components?.map((component) => (
<div
key={component.id}
style={{
position: "absolute",
left: `${component.position.x}px`,
top: `${component.position.y}px`,
width:
component.style?.width || `${component.size.width}px`,
minHeight:
component.style?.height || `${component.size.height}px`,
zIndex: component.position.z || 1,
}}
>
<DynamicComponentRenderer
component={component}
isPreview={true}
/>
</div>
))}
</div>
</div>
</div>
)}
</div>
);
}
```
---
## 🎨 Phase 2: 디자이너 통합 (1-2일)
### 2.1 반응형 설정 패널 (5시간)
#### 파일: `frontend/components/screen/panels/ResponsiveConfigPanel.tsx`
```typescript
import React, { useState } from "react";
import { ComponentData } from "@/types/screen-management";
import {
Breakpoint,
BREAKPOINTS,
ResponsiveComponentConfig,
} from "@/types/responsive";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { Label } from "@/components/ui/label";
import { Input } from "@/components/ui/input";
import {
Select,
SelectContent,
SelectItem,
SelectTrigger,
SelectValue,
} from "@/components/ui/select";
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
import { Checkbox } from "@/components/ui/checkbox";
interface ResponsiveConfigPanelProps {
component: ComponentData;
onUpdate: (config: ResponsiveComponentConfig) => void;
}
export const ResponsiveConfigPanel: React.FC<ResponsiveConfigPanelProps> = ({
component,
onUpdate,
}) => {
const [activeTab, setActiveTab] = useState<Breakpoint>("desktop");
const config = component.responsiveConfig || {
designerPosition: {
x: component.position.x,
y: component.position.y,
width: component.size.width,
height: component.size.height,
},
useSmartDefaults: true,
};
return (
<Card>
<CardHeader>
<CardTitle>반응형 설정</CardTitle>
</CardHeader>
<CardContent className="space-y-4">
{/* 스마트 기본값 토글 */}
<div className="flex items-center space-x-2">
<Checkbox
id="smartDefaults"
checked={config.useSmartDefaults}
onCheckedChange={(checked) => {
onUpdate({
...config,
useSmartDefaults: checked as boolean,
});
}}
/>
<Label htmlFor="smartDefaults">스마트 기본값 사용 (권장)</Label>
</div>
{/* 수동 설정 */}
{!config.useSmartDefaults && (
<Tabs
value={activeTab}
onValueChange={(v) => setActiveTab(v as Breakpoint)}
>
<TabsList className="grid w-full grid-cols-3">
<TabsTrigger value="desktop">데스크톱</TabsTrigger>
<TabsTrigger value="tablet">태블릿</TabsTrigger>
<TabsTrigger value="mobile">모바일</TabsTrigger>
</TabsList>
<TabsContent value={activeTab} className="space-y-4">
{/* 그리드 컬럼 수 */}
<div className="space-y-2">
<Label>너비 (그리드 컬럼)</Label>
<Select
value={config.responsive?.[
activeTab
]?.gridColumns?.toString()}
onValueChange={(v) => {
onUpdate({
...config,
responsive: {
...config.responsive,
[activeTab]: {
...config.responsive?.[activeTab],
gridColumns: parseInt(v),
},
},
});
}}
>
<SelectTrigger className="w-full">
<SelectValue placeholder="컬럼 수 선택" />
</SelectTrigger>
<SelectContent>
{[...Array(BREAKPOINTS[activeTab].columns)].map((_, i) => {
const cols = i + 1;
const percent = (
(cols / BREAKPOINTS[activeTab].columns) *
100
).toFixed(0);
return (
<SelectItem key={cols} value={cols.toString()}>
{cols} / {BREAKPOINTS[activeTab].columns} ({percent}%)
</SelectItem>
);
})}
</SelectContent>
</Select>
</div>
{/* 표시 순서 */}
<div className="space-y-2">
<Label>표시 순서</Label>
<Input
type="number"
min="1"
value={config.responsive?.[activeTab]?.order || 1}
onChange={(e) => {
onUpdate({
...config,
responsive: {
...config.responsive,
[activeTab]: {
...config.responsive?.[activeTab],
order: parseInt(e.target.value),
},
},
});
}}
/>
</div>
{/* 숨김 */}
<div className="flex items-center space-x-2">
<Checkbox
id={`hide-${activeTab}`}
checked={config.responsive?.[activeTab]?.hide || false}
onCheckedChange={(checked) => {
onUpdate({
...config,
responsive: {
...config.responsive,
[activeTab]: {
...config.responsive?.[activeTab],
hide: checked as boolean,
},
},
});
}}
/>
<Label htmlFor={`hide-${activeTab}`}>
{activeTab === "desktop"
? "데스크톱"
: activeTab === "tablet"
? "태블릿"
: "모바일"}
에서 숨김
</Label>
</div>
</TabsContent>
</Tabs>
)}
</CardContent>
</Card>
);
};
```
### 2.2 속성 패널 통합 (1시간)
#### 파일: `frontend/components/screen/panels/UnifiedPropertiesPanel.tsx` 수정
```typescript
// 기존 import에 추가
import { ResponsiveConfigPanel } from './ResponsiveConfigPanel';
// 컴포넌트 내부에 추가
return (
<div className="space-y-4">
{/* 기존 패널들 */}
<PropertiesPanel ... />
<StyleEditor ... />
{/* 반응형 설정 패널 추가 */}
<ResponsiveConfigPanel
component={selectedComponent}
onUpdate={(config) => {
onUpdateComponent({
...selectedComponent,
responsiveConfig: config
});
}}
/>
{/* 기존 세부 설정 패널 */}
<DetailSettingsPanel ... />
</div>
);
```
### 2.3 미리보기 모드 (3시간)
#### 파일: `frontend/components/screen/ScreenDesigner.tsx` 수정
```typescript
// 추가 import
import { Breakpoint } from '@/types/responsive';
import { ResponsiveLayoutEngine } from './ResponsiveLayoutEngine';
import { useBreakpoint } from '@/hooks/useBreakpoint';
import { Button } from '@/components/ui/button';
export const ScreenDesigner: React.FC = () => {
// 미리보기 모드: 'design' | 'desktop' | 'tablet' | 'mobile'
const [previewMode, setPreviewMode] = useState<'design' | Breakpoint>('design');
const currentBreakpoint = useBreakpoint();
// ... 기존 로직 ...
return (
<div className="h-full flex flex-col">
{/* 상단 툴바 */}
<div className="flex gap-2 p-2 border-b bg-white">
<Button
variant={previewMode === 'design' ? 'default' : 'outline'}
size="sm"
onClick={() => setPreviewMode('design')}
>
디자인 모드
</Button>
<Button
variant={previewMode === 'desktop' ? 'default' : 'outline'}
size="sm"
onClick={() => setPreviewMode('desktop')}
>
데스크톱 미리보기
</Button>
<Button
variant={previewMode === 'tablet' ? 'default' : 'outline'}
size="sm"
onClick={() => setPreviewMode('tablet')}
>
태블릿 미리보기
</Button>
<Button
variant={previewMode === 'mobile' ? 'default' : 'outline'}
size="sm"
onClick={() => setPreviewMode('mobile')}
>
모바일 미리보기
</Button>
</div>
{/* 캔버스 영역 */}
<div className="flex-1 overflow-auto">
{previewMode === 'design' ? (
// 기존 절대 위치 기반 디자이너
<Canvas ... />
) : (
// 반응형 미리보기
<div
className="mx-auto border border-gray-300"
style={{
width: previewMode === 'desktop' ? '100%' :
previewMode === 'tablet' ? '768px' :
'375px',
minHeight: '100%'
}}
>
<ResponsiveLayoutEngine
components={components}
breakpoint={previewMode}
containerWidth={
previewMode === 'desktop' ? window.innerWidth :
previewMode === 'tablet' ? 768 :
375
}
screenWidth={selectedScreen?.screenResolution?.width || 1920}
/>
</div>
)}
</div>
</div>
);
};
```
---
## 💾 Phase 3: 저장/불러오기 (1일)
### 3.1 타입 업데이트 (2시간)
#### 파일: `frontend/types/screen-management.ts` 수정
```typescript
import { ResponsiveComponentConfig } from "./responsive";
export interface ComponentData {
// ... 기존 필드들 ...
// 반응형 설정 추가
responsiveConfig?: ResponsiveComponentConfig;
}
```
### 3.2 저장 로직 (2시간)
#### 파일: `frontend/components/screen/ScreenDesigner.tsx` 수정
```typescript
// 저장 함수 수정
const handleSave = async () => {
try {
const layoutData: LayoutData = {
screenResolution: {
width: 1920,
height: 1080,
},
components: components.map((comp) => ({
...comp,
// 반응형 설정이 없으면 자동 생성
responsiveConfig: comp.responsiveConfig || {
designerPosition: {
x: comp.position.x,
y: comp.position.y,
width: comp.size.width,
height: comp.size.height,
},
useSmartDefaults: true,
},
})),
};
await screenApi.updateLayout(selectedScreen.id, layoutData);
// ... 기존 로직 ...
} catch (error) {
console.error("저장 실패:", error);
}
};
```
### 3.3 불러오기 로직 (2시간)
#### 파일: `frontend/components/screen/ScreenDesigner.tsx` 수정
```typescript
import { ensureResponsiveConfig } from "@/lib/utils/responsiveDefaults";
// 화면 불러오기
useEffect(() => {
const loadScreen = async () => {
if (!selectedScreenId) return;
const screen = await screenApi.getScreenById(selectedScreenId);
const layout = await screenApi.getLayout(selectedScreenId);
// 반응형 설정이 없는 컴포넌트에 자동 생성
const componentsWithResponsive = layout.components.map((comp) =>
ensureResponsiveConfig(comp, layout.screenResolution?.width)
);
setSelectedScreen(screen);
setComponents(componentsWithResponsive);
};
loadScreen();
}, [selectedScreenId]);
```
---
## 🧪 Phase 4: 테스트 및 최적화 (1일)
### 4.1 기능 테스트 체크리스트 (3시간)
- [ ] 브레이크포인트 전환 테스트
- [ ] 윈도우 크기 변경 시 자동 전환
- [ ] desktop → tablet → mobile 순차 테스트
- [ ] 스마트 기본값 생성 테스트
- [ ] 작은 컴포넌트 (25% 이하)
- [ ] 중간 컴포넌트 (25-50%)
- [ ] 큰 컴포넌트 (50% 이상)
- [ ] 수동 설정 적용 테스트
- [ ] 그리드 컬럼 변경
- [ ] 표시 순서 변경
- [ ] 디바이스별 숨김
- [ ] 미리보기 모드 테스트
- [ ] 디자인 모드 ↔ 미리보기 모드 전환
- [ ] 각 브레이크포인트 미리보기
- [ ] 저장/불러오기 테스트
- [ ] 반응형 설정 저장
- [ ] 기존 화면 불러오기 시 자동 변환
### 4.2 성능 최적화 (3시간)
#### 레이아웃 계산 메모이제이션
```typescript
// ResponsiveLayoutEngine.tsx
const memoizedLayout = useMemo(() => {
// 레이아웃 계산 로직
}, [components, breakpoint, screenWidth]);
```
#### ResizeObserver 최적화
```typescript
// useBreakpoint.ts
// debounce 적용
const debouncedResize = debounce(updateBreakpoint, 150);
window.addEventListener("resize", debouncedResize);
```
#### 불필요한 리렌더링 방지
```typescript
// React.memo 적용
export const ResponsiveLayoutEngine = React.memo<ResponsiveLayoutEngineProps>(({...}) => {
// ...
});
```
### 4.3 UI/UX 개선 (2시간)
- [ ] 반응형 설정 패널 툴팁 추가
- [ ] 미리보기 모드 전환 애니메이션
- [ ] 로딩 상태 표시
- [ ] 에러 처리 및 사용자 피드백
---
## 📅 최종 타임라인
| Phase | 작업 내용 | 소요 시간 | 누적 시간 |
| ------- | --------------------- | --------- | ------------ |
| Phase 1 | 타입 정의 및 유틸리티 | 6시간 | 6시간 |
| Phase 1 | 반응형 레이아웃 엔진 | 6시간 | 12시간 |
| Phase 1 | 화면 표시 페이지 수정 | 4시간 | 16시간 (2일) |
| Phase 2 | 반응형 설정 패널 | 5시간 | 21시간 |
| Phase 2 | 디자이너 통합 | 4시간 | 25시간 (3일) |
| Phase 3 | 저장/불러오기 | 6시간 | 31시간 (4일) |
| Phase 4 | 테스트 및 최적화 | 8시간 | 39시간 (5일) |
**총 예상 시간: 39시간 (약 5일)**
---
## 🎯 구현 우선순위
### 1단계: 핵심 기능 (필수)
1. ✅ 타입 정의
2. ✅ 스마트 기본값 생성기
3. ✅ 브레이크포인트 훅
4. ✅ 반응형 레이아웃 엔진
5. ✅ 화면 표시 페이지 수정
### 2단계: 디자이너 UI (중요)
6. ✅ 반응형 설정 패널
7. ✅ 속성 패널 통합
8. ✅ 미리보기 모드
### 3단계: 데이터 처리 (중요)
9. ✅ 타입 업데이트
10. ✅ 저장/불러오기 로직
### 4단계: 완성도 (선택)
11. 테스트
12. 최적화
13. UI/UX 개선
---
## ✅ 완료 체크리스트
### Phase 1: 기본 시스템
- [ ] `frontend/types/responsive.ts` 생성
- [ ] `frontend/lib/utils/responsiveDefaults.ts` 생성
- [ ] `frontend/hooks/useBreakpoint.ts` 생성
- [ ] `frontend/components/screen/ResponsiveLayoutEngine.tsx` 생성
- [ ] `frontend/app/(main)/screens/[screenId]/page.tsx` 수정
### Phase 2: 디자이너 통합
- [ ] `frontend/components/screen/panels/ResponsiveConfigPanel.tsx` 생성
- [ ] `frontend/components/screen/panels/UnifiedPropertiesPanel.tsx` 수정
- [ ] `frontend/components/screen/ScreenDesigner.tsx` 수정
### Phase 3: 데이터 처리
- [ ] `frontend/types/screen-management.ts` 수정
- [ ] 저장 로직 수정
- [ ] 불러오기 로직 수정
### Phase 4: 테스트
- [ ] 기능 테스트 완료
- [ ] 성능 최적화 완료
- [ ] UI/UX 개선 완료
---
## 🚀 시작 준비 완료
이제 Phase 1부터 순차적으로 구현을 시작합니다.

1407
PRISMA_TO_RAW_QUERY_MIGRATION_PLAN.md
View File

File diff suppressed because it is too large Load Diff

311
UI_REDESIGN_PLAN.md
View File

@ -1,311 +0,0 @@
# 🎨 제어관리 - 데이터 연결 설정 UI 재설계 계획서
## 📋 프로젝트 개요
### 목표
- 기존 모달 기반 필드 매핑을 메인 화면으로 통합
- 중복된 테이블 선택 과정 제거
- 시각적 필드 연결 매핑 구현
- 좌우 분할 레이아웃으로 정보 가시성 향상
### 현재 문제점
- ❌ **이중 작업**: 테이블을 3번 선택해야 함 (더블클릭 → 모달 → 재선택)
- ❌ **혼란스러운 UX**: 사전 선택의 의미가 없어짐
- ❌ **불필요한 모달**: 연결 설정이 메인 기능인데 숨겨져 있음
- ❌ **시각적 피드백 부족**: 필드 매핑 관계가 명확하지 않음
## 🎯 새로운 UI 구조
### 레이아웃 구성
```
┌─────────────────────────────────────────────────────────────┐
│ 제어관리 - 데이터 연결 설정 │
├─────────────────────────────────────────────────────────────┤
│ 좌측 패널 (30%) │ 우측 패널 (70%) │
│ - 연결 타입 선택 │ - 단계별 설정 UI │
│ - 매핑 정보 모니터링 │ - 시각적 필드 매핑 │
│ - 상세 설정 목록 │ - 실시간 연결선 표시 │
│ - 액션 버튼 │ - 드래그 앤 드롭 지원 │
└─────────────────────────────────────────────────────────────┘
```
## 🔧 구현 단계
### Phase 1: 기본 구조 구축
- [ ] 좌우 분할 레이아웃 컴포넌트 생성
- [ ] 기존 모달 컴포넌트들을 메인 화면용으로 리팩토링
- [ ] 연결 타입 선택 컴포넌트 구현
### Phase 2: 좌측 패널 구현
- [ ] 연결 타입 선택 (데이터 저장 / 외부 호출)
- [ ] 실시간 매핑 정보 표시
- [ ] 매핑 상세 목록 컴포넌트
- [ ] 고급 설정 패널
### Phase 3: 우측 패널 구현
- [ ] 단계별 진행 UI (연결 → 테이블 → 매핑)
- [ ] 시각적 필드 매핑 영역
- [ ] SVG 기반 연결선 시스템
- [ ] 드래그 앤 드롭 매핑 기능
### Phase 4: 고급 기능
- [ ] 실시간 검증 및 피드백
- [ ] 매핑 미리보기 기능
- [ ] 설정 저장/불러오기
- [ ] 테스트 실행 기능
## 📁 파일 구조
### 새로 생성할 컴포넌트
```
frontend/components/dataflow/connection/redesigned/
├── DataConnectionDesigner.tsx # 메인 컨테이너
├── LeftPanel/
│ ├── ConnectionTypeSelector.tsx # 연결 타입 선택
│ ├── MappingInfoPanel.tsx # 매핑 정보 표시
│ ├── MappingDetailList.tsx # 매핑 상세 목록
│ ├── AdvancedSettings.tsx # 고급 설정
│ └── ActionButtons.tsx # 액션 버튼들
├── RightPanel/
│ ├── StepProgress.tsx # 단계 진행 표시
│ ├── ConnectionStep.tsx # 1단계: 연결 선택
│ ├── TableStep.tsx # 2단계: 테이블 선택
│ ├── FieldMappingStep.tsx # 3단계: 필드 매핑
│ └── VisualMapping/
│ ├── FieldMappingCanvas.tsx # 시각적 매핑 캔버스
│ ├── FieldColumn.tsx # 필드 컬럼 컴포넌트
│ ├── ConnectionLine.tsx # SVG 연결선
│ └── MappingControls.tsx # 매핑 제어 도구
└── types/
└── redesigned.ts # 타입 정의
```
### 수정할 기존 파일
```
frontend/components/dataflow/connection/
├── DataSaveSettings.tsx # 새 UI로 교체
├── ConnectionSelectionPanel.tsx # 재사용을 위한 리팩토링
├── TableSelectionPanel.tsx # 재사용을 위한 리팩토링
└── ActionFieldMappings.tsx # 레거시 처리
```
## 🎨 UI 컴포넌트 상세
### 1. 연결 타입 선택 (ConnectionTypeSelector)
```typescript
interface ConnectionType {
id: "data_save" | "external_call";
label: string;
description: string;
icon: React.ReactNode;
}
const connectionTypes: ConnectionType[] = [
{
id: "data_save",
label: "데이터 저장",
description: "INSERT/UPDATE/DELETE 작업",
icon: <Database />,
},
{
id: "external_call",
label: "외부 호출",
description: "API/Webhook 호출",
icon: <Globe />,
},
];
```
### 2. 시각적 필드 매핑 (FieldMappingCanvas)
```typescript
interface FieldMapping {
id: string;
fromField: ColumnInfo;
toField: ColumnInfo;
transformRule?: string;
isValid: boolean;
validationMessage?: string;
}
interface MappingLine {
id: string;
fromX: number;
fromY: number;
toX: number;
toY: number;
isValid: boolean;
isHovered: boolean;
}
```
### 3. 매핑 정보 패널 (MappingInfoPanel)
```typescript
interface MappingStats {
totalMappings: number;
validMappings: number;
invalidMappings: number;
missingRequiredFields: number;
estimatedRows: number;
actionType: "INSERT" | "UPDATE" | "DELETE";
}
```
## 🔄 데이터 플로우
### 상태 관리
```typescript
interface DataConnectionState {
// 기본 설정
connectionType: "data_save" | "external_call";
currentStep: 1 | 2 | 3;
// 연결 정보
fromConnection?: Connection;
toConnection?: Connection;
fromTable?: TableInfo;
toTable?: TableInfo;
// 매핑 정보
fieldMappings: FieldMapping[];
mappingStats: MappingStats;
// UI 상태
selectedMapping?: string;
isLoading: boolean;
validationErrors: ValidationError[];
}
```
### 이벤트 핸들링
```typescript
interface DataConnectionActions {
// 연결 타입
setConnectionType: (type: "data_save" | "external_call") => void;
// 단계 진행
goToStep: (step: 1 | 2 | 3) => void;
// 연결/테이블 선택
selectConnection: (type: "from" | "to", connection: Connection) => void;
selectTable: (type: "from" | "to", table: TableInfo) => void;
// 필드 매핑
createMapping: (fromField: ColumnInfo, toField: ColumnInfo) => void;
updateMapping: (mappingId: string, updates: Partial<FieldMapping>) => void;
deleteMapping: (mappingId: string) => void;
// 검증 및 저장
validateMappings: () => Promise<ValidationResult>;
saveMappings: () => Promise<void>;
testExecution: () => Promise<TestResult>;
}
```
## 🎯 사용자 경험 (UX) 개선점
### Before (기존)
1. 테이블 더블클릭 → 화면에 표시
2. 모달 열기 → 다시 테이블 선택
3. 외부 커넥션 설정 → 또 다시 테이블 선택
4. 필드 매핑 → 텍스트 기반 매핑
### After (개선)
1. **연결 타입 선택** → 목적 명확화
2. **연결 선택** → 한 번에 FROM/TO 설정
3. **테이블 선택** → 즉시 필드 정보 로드
4. **시각적 매핑** → 드래그 앤 드롭으로 직관적 연결
## 🚀 구현 우선순위
### 🔥 High Priority
1. **기본 레이아웃** - 좌우 분할 구조
2. **연결 타입 선택** - 데이터 저장/외부 호출
3. **단계별 진행** - 연결 → 테이블 → 매핑
4. **기본 필드 매핑** - 드래그 앤 드롭 없이 클릭 기반
### 🔶 Medium Priority
1. **시각적 연결선** - SVG 기반 라인 표시
2. **실시간 검증** - 타입 호환성 체크
3. **매핑 정보 패널** - 통계 및 상태 표시
4. **드래그 앤 드롭** - 고급 매핑 기능
### 🔵 Low Priority
1. **고급 설정** - 트랜잭션, 배치 설정
2. **미리보기 기능** - 데이터 변환 미리보기
3. **설정 템플릿** - 자주 사용하는 매핑 저장
4. **성능 최적화** - 대용량 테이블 처리
## 📅 개발 일정
### Week 1: 기본 구조
- [ ] 레이아웃 컴포넌트 생성
- [ ] 연결 타입 선택 구현
- [ ] 기존 컴포넌트 리팩토링
### Week 2: 핵심 기능
- [ ] 단계별 진행 UI
- [ ] 연결/테이블 선택 통합
- [ ] 기본 필드 매핑 구현
### Week 3: 시각적 개선
- [ ] SVG 연결선 시스템
- [ ] 드래그 앤 드롭 매핑
- [ ] 실시간 검증 기능
### Week 4: 완성 및 테스트
- [ ] 고급 기능 구현
- [ ] 통합 테스트
- [ ] 사용자 테스트 및 피드백 반영
## 🔍 기술적 고려사항
### 성능 최적화
- **가상화**: 대용량 필드 목록 처리
- **메모이제이션**: 불필요한 리렌더링 방지
- **지연 로딩**: 필요한 시점에만 데이터 로드
### 접근성
- **키보드 네비게이션**: 모든 기능을 키보드로 접근 가능
- **스크린 리더**: 시각적 매핑의 대체 텍스트 제공
- **색상 대비**: 연결선과 상태 표시의 명확한 구분
### 확장성
- **플러그인 구조**: 새로운 연결 타입 쉽게 추가
- **커스텀 변환**: 사용자 정의 데이터 변환 규칙
- **API 확장**: 외부 시스템과의 연동 지원
---
## 🎯 다음 단계
이 계획서를 바탕으로 **Phase 1부터 순차적으로 구현**을 시작하겠습니다.
**첫 번째 작업**: 좌우 분할 레이아웃과 연결 타입 선택 컴포넌트 구현
구현을 시작하시겠어요? 🚀

150
WORK_HISTORY_SETUP.md
View File

@ -1,150 +0,0 @@
# 작업 이력 관리 시스템 설치 가이드
## 📋 개요
작업 이력 관리 시스템이 추가되었습니다. 입고/출고/이송/정비 작업을 관리하고 통계를 확인할 수 있습니다.
## 🚀 설치 방법
### 1. 데이터베이스 마이그레이션 실행
PostgreSQL 데이터베이스에 작업 이력 테이블을 생성해야 합니다.
```bash
# 방법 1: psql 명령어 사용 (로컬 PostgreSQL)
psql -U postgres -d plm -f db/migrations/20241020_create_work_history.sql
# 방법 2: Docker 컨테이너 사용
docker exec -i <DB_CONTAINER_NAME> psql -U postgres -d plm < db/migrations/20241020_create_work_history.sql
# 방법 3: pgAdmin 또는 DBeaver 사용
# db/migrations/20241020_create_work_history.sql 파일을 열어서 실행
```
### 2. 백엔드 재시작
```bash
cd backend-node
npm run dev
```
### 3. 프론트엔드 확인
대시보드 편집 화면에서 다음 위젯들을 추가할 수 있습니다:
- **작업 이력**: 작업 목록을 테이블 형식으로 표시
- **운송 통계**: 오늘 작업, 총 운송량, 정시 도착률 등 통계 표시
## 📊 주요 기능
### 작업 이력 위젯
- 작업 번호, 일시, 유형, 차량, 경로, 화물, 중량, 상태 표시
- 유형별 필터링 (입고/출고/이송/정비)
- 상태별 필터링 (대기/진행중/완료/취소)
- 실시간 자동 새로고침
### 운송 통계 위젯
- 오늘 작업 건수 및 완료율
- 총 운송량 (톤)
- 누적 거리 (km)
- 정시 도착률 (%)
- 작업 유형별 분포 차트
## 🔧 API 엔드포인트
### 작업 이력 관리
- `GET /api/work-history` - 작업 이력 목록 조회
- `GET /api/work-history/:id` - 작업 이력 단건 조회
- `POST /api/work-history` - 작업 이력 생성
- `PUT /api/work-history/:id` - 작업 이력 수정
- `DELETE /api/work-history/:id` - 작업 이력 삭제
### 통계 및 분석
- `GET /api/work-history/stats` - 작업 이력 통계
- `GET /api/work-history/trend?months=6` - 월별 추이
- `GET /api/work-history/routes?limit=5` - 주요 운송 경로
## 📝 샘플 데이터
마이그레이션 실행 시 자동으로 4건의 샘플 데이터가 생성됩니다:
1. 입고 작업 (완료)
2. 출고 작업 (진행중)
3. 이송 작업 (대기)
4. 정비 작업 (완료)
## 🎯 사용 방법
### 1. 대시보드에 위젯 추가
1. 대시보드 편집 모드로 이동
2. 상단 메뉴에서 "위젯 추가" 선택
3. "작업 이력" 또는 "운송 통계" 선택
4. 원하는 위치에 배치
5. 저장
### 2. 작업 이력 필터링
- 유형 선택: 전체/입고/출고/이송/정비
- 상태 선택: 전체/대기/진행중/완료/취소
- 새로고침 버튼으로 수동 갱신
### 3. 통계 확인
운송 통계 위젯에서 다음 정보를 확인할 수 있습니다:
- 오늘 작업 건수
- 완료율
- 총 운송량
- 정시 도착률
- 작업 유형별 분포
## 🔍 문제 해결
### 데이터가 표시되지 않는 경우
1. 데이터베이스 마이그레이션이 실행되었는지 확인
2. 백엔드 서버가 실행 중인지 확인
3. 브라우저 콘솔에서 API 에러 확인
### API 에러가 발생하는 경우
```bash
# 백엔드 로그 확인
cd backend-node
npm run dev
```
### 위젯이 표시되지 않는 경우
1. 프론트엔드 재시작
2. 브라우저 캐시 삭제
3. 페이지 새로고침
## 📚 관련 파일
### 백엔드
- `backend-node/src/types/workHistory.ts` - 타입 정의
- `backend-node/src/services/workHistoryService.ts` - 비즈니스 로직
- `backend-node/src/controllers/workHistoryController.ts` - API 컨트롤러
- `backend-node/src/routes/workHistoryRoutes.ts` - 라우트 정의
### 프론트엔드
- `frontend/types/workHistory.ts` - 타입 정의
- `frontend/components/dashboard/widgets/WorkHistoryWidget.tsx` - 작업 이력 위젯
- `frontend/components/dashboard/widgets/TransportStatsWidget.tsx` - 운송 통계 위젯
### 데이터베이스
- `db/migrations/20241020_create_work_history.sql` - 테이블 생성 스크립트
## 🎉 완료!
작업 이력 관리 시스템이 성공적으로 설치되었습니다!

426
YARD_MANAGEMENT_3D_DATA_BINDING_REDESIGN.md
View File

@ -1,426 +0,0 @@
# 야드 관리 3D - 데이터 바인딩 시스템 재설계
## 1. 개요
### 현재 방식의 문제점
- 고정된 임시 자재 마스터(`temp_material_master`) 테이블에 의존
- 실제 외부 시스템의 자재 데이터와 연동 불가
- 자재 목록이 제한적이고 유연성 부족
- 사용자가 직접 데이터를 선택하거나 입력할 수 없음
### 새로운 방식의 목표
- 차트/리스트 위젯과 동일한 데이터 소스 선택 방식 적용
- DB 커넥션 또는 REST API를 통해 실제 자재 데이터 연동
- 사용자가 자재명, 수량 등을 직접 매핑 및 입력 가능
- 설정되지 않은 요소는 뷰어에서 명확히 표시
---
## 2. 핵심 변경사항
### 2.1 요소(Element) 개념 도입
- 기존: 자재 목록에서 클릭 → 즉시 배치
- 변경: [+ 요소 추가] 버튼 클릭 → 3D 캔버스에 즉시 빈 요소 배치 → 우측 패널이 데이터 바인딩 설정 화면으로 전환
### 2.2 데이터 소스 선택
- 현재 DB (내부 PostgreSQL)
- 외부 DB 커넥션
- REST API
### 2.3 데이터 매핑
- 자재명 필드 선택 (데이터 소스에서)
- 수량 필드 선택 (데이터 소스에서)
- 단위 직접 입력 (예: EA, BOX, KG 등)
- 색상 선택
---
## 3. 데이터베이스 스키마 변경
### 3.1 기존 테이블 수정: `yard_material_placement`
```sql
-- 기존 컬럼 변경
ALTER TABLE yard_material_placement
-- 기존 컬럼 제거 (외부 자재 ID 관련)
DROP COLUMN IF EXISTS external_material_id,
-- 데이터 소스 정보 추가
ADD COLUMN data_source_type VARCHAR(20), -- 'database', 'external_db', 'rest_api'
ADD COLUMN data_source_config JSONB, -- 데이터 소스 설정
-- 데이터 바인딩 정보 추가
ADD COLUMN data_binding JSONB, -- 필드 매핑 정보
-- 자재 정보를 NULL 허용으로 변경 (설정 전에는 NULL)
ALTER COLUMN material_code DROP NOT NULL,
ALTER COLUMN material_name DROP NOT NULL,
ALTER COLUMN quantity DROP NOT NULL;
```
### 3.2 data_source_config 구조
```typescript
interface DataSourceConfig {
type: "database" | "external_db" | "rest_api";
// type === 'database' (현재 DB)
query?: string;
// type === 'external_db' (외부 DB)
connectionId?: number;
query?: string;
// type === 'rest_api'
url?: string;
method?: "GET" | "POST";
headers?: Record<string, string>;
queryParams?: Record<string, string>;
body?: string;
dataPath?: string; // 응답에서 데이터 배열 경로 (예: "data.items")
}
```
### 3.3 data_binding 구조
```typescript
interface DataBinding {
// 데이터 소스의 특정 행 선택
selectedRowIndex?: number;
// 필드 매핑 (데이터 소스에서 선택)
materialNameField?: string; // 자재명이 들어있는 컬럼명
quantityField?: string; // 수량이 들어있는 컬럼명
// 단위는 사용자가 직접 입력
unit: string; // 예: "EA", "BOX", "KG", "M" 등
}
```
---
## 4. UI/UX 설계
### 4.1 편집 모드 (YardEditor)
```
┌─────────────────────────────────────────────────────────────┐
│ [← 목록으로] 야드명: A구역 [저장] │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────┐ ┌──────────────────────────┐│
│ │ │ │ ││
│ │ │ │ [+ 요소 추가] ││
│ │ │ │ ││
│ │ 3D 캔버스 │ │ ┌────────────────────┐ ││
│ │ │ │ │ □ 요소 1 │ ││
│ │ │ │ │ 자재: 철판 A │ ││
│ │ │ │ │ 수량: 50 EA │ ││
│ │ │ │ │ [편집] [삭제] │ ││
│ │ │ │ └────────────────────┘ ││
│ │ │ │ ││
│ │ │ │ ┌────────────────────┐ ││
│ │ │ │ │ □ 요소 2 (미설정) │ ││
│ │ │ │ │ 데이터 바인딩 │ ││
│ │ │ │ │ 설정 필요 │ ││
│ │ │ │ │ [설정] [삭제] │ ││
│ │ │ │ └────────────────────┘ ││
│ │ │ │ ││
│ └───────────────────────────┘ └──────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
```
#### 4.1.1 요소 목록 (우측 패널)
- **[+ 요소 추가]** 버튼: 새 요소 생성
- **요소 카드**:
- 설정 완료: 자재명, 수량 표시 + [편집] [삭제] 버튼
- 미설정: "데이터 바인딩 설정 필요" + [설정] [삭제] 버튼
#### 4.1.2 요소 추가 흐름
```
1. [+ 요소 추가] 클릭
↓
2. 3D 캔버스의 기본 위치(0,0,0)에 회색 반투명 박스로 빈 요소 즉시 배치
↓
3. 요소가 자동 선택됨
↓
4. 우측 패널이 "데이터 바인딩 설정" 화면으로 자동 전환
(요소 목록에서 [설정] 버튼을 클릭해도 동일한 화면)
```
### 4.2 데이터 바인딩 설정 패널 (우측)
**[+ 요소 추가] 버튼 클릭 시 또는 [설정] 버튼 클릭 시 우측 패널이 아래와 같이 변경됩니다:**
```
┌──────────────────────────────────────┐
│ 데이터 바인딩 설정 [← 목록]│
├──────────────────────────────────────┤
│ │
│ ┌─ 1단계: 데이터 소스 선택 ─────────────────────────┐ │
│ │ │ │
│ │ ○ 현재 DB ○ 외부 DB ○ REST API │ │
│ │ │ │
│ │ [현재 DB 선택 시] │ │
│ │ ┌────────────────────────────────────────────┐ │ │
│ │ │ SELECT material_name, quantity, unit │ │ │
│ │ │ FROM inventory │ │ │
│ │ │ WHERE status = 'available' │ │ │
│ │ └────────────────────────────────────────────┘ │ │
│ │ [실행] 버튼 │ │
│ │ │ │
│ │ [외부 DB 선택 시] │ │
│ │ - 외부 커넥션 선택 드롭다운 │ │
│ │ - SQL 쿼리 입력 │ │
│ │ - [실행] 버튼 │ │
│ │ │ │
│ │ [REST API 선택 시] │ │
│ │ - URL 입력 │ │
│ │ - Method 선택 (GET/POST) │ │
│ │ - Headers, Query Params 설정 │ │
│ │ - [실행] 버튼 │ │
│ │ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌─ 2단계: 쿼리 결과 및 필드 매핑 ──────────────────────┐ │
│ │ │ │
│ │ 쿼리 결과 (5행): │ │
│ │ ┌────────────────────────────────────────────┐ │ │
│ │ │ material_name │ quantity │ status │ │ │
│ │ │ 철판 A │ 50 │ available │ ○ │ │
│ │ │ 강관 파이프 │ 100 │ available │ ○ │ │
│ │ │ 볼트 세트 │ 500 │ in_stock │ ○ │ │
│ │ └────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ 필드 매핑: │ │
│ │ 자재명: [material_name ▼] │ │
│ │ 수량: [quantity ▼] │ │
│ │ │ │
│ │ 단위 입력: │ │
│ │ 단위: [EA_____________] │ │
│ │ (예: EA, BOX, KG, M, L 등) │ │
│ │ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌─ 3단계: 배치 설정 ──────────────────────────────────┐ │
│ │ │ │
│ │ 색상: [🎨 #3b82f6] │ │
│ │ │ │
│ │ 크기: │ │
│ │ 너비: [5] 높이: [5] 깊이: [5] │ │
│ │ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ [← 목록으로] [저장] │
└──────────────────────────────────────┘
```
**참고:**
- [← 목록으로] 버튼: 요소 목록 화면으로 돌아갑니다
- [저장] 버튼: 데이터 바인딩 설정을 저장하고 요소 목록 화면으로 돌아갑니다
- 저장하지 않고 나가면 요소는 "미설정" 상태로 남습니다
### 4.3 뷰어 모드 (Yard3DViewer)
#### 4.3.1 설정된 요소
- 정상적으로 3D 박스 렌더링
- 클릭 시 자재명, 수량 정보 표시
#### 4.3.2 미설정 요소
```
┌─────────────────────┐
│ │
│ ⚠️ │
│ │
│ 설정되지 않은 │
│ 요소입니다 │
│ │
└─────────────────────┘
```
- 반투명 회색 박스로 표시
- 클릭 시 "데이터 바인딩이 설정되지 않았습니다" 메시지
---
## 5. 구현 단계
### Phase 1: 데이터베이스 스키마 변경
- [ ] `yard_material_placement` 테이블 수정
- [ ] 마이그레이션 스크립트 작성
- [ ] 기존 데이터 호환성 처리
### Phase 2: 백엔드 API 수정
- [ ] `YardLayoutService.ts` 수정
- `addMaterialPlacement`: 데이터 소스/바인딩 정보 저장
- `updatePlacement`: 데이터 바인딩 업데이트
- `getPlacementsByLayoutId`: 새 필드 포함하여 조회
- [ ] 데이터 소스 실행 로직 추가
- DB 쿼리 실행
- 외부 DB 쿼리 실행
- REST API 호출
### Phase 3: 프론트엔드 타입 정의
- [ ] `types.ts`에 새로운 인터페이스 추가
- `YardElementDataSource`
- `YardElementDataBinding`
- `YardPlacement` 업데이트
### Phase 4: 요소 추가 및 관리
- [ ] `YardEditor.tsx` 수정
- [+ 요소 추가] 버튼 구현
- 빈 요소 생성 로직 (즉시 3D 캔버스에 배치)
- 요소 추가 시 자동으로 해당 요소 선택
- 우측 패널 상태 관리 (요소 목록 ↔ 데이터 바인딩 설정)
- 요소 목록 UI
- 설정/미설정 상태 구분 표시
### Phase 5: 데이터 바인딩 패널
- [ ] `YardElementConfigPanel.tsx` 생성 (우측 패널 컴포넌트)
- [← 목록으로] 버튼으로 요소 목록으로 복귀
- 1단계: 데이터 소스 선택 (DatabaseConfig, ExternalDbConfig, RestApiConfig 재사용)
- 2단계: 쿼리 결과 테이블 + 행 선택 + 필드 매핑
- 자재명 필드 선택 (드롭다운)
- 수량 필드 선택 (드롭다운)
- 단위 직접 입력 (Input)
- 3단계: 배치 설정 (색상, 크기)
- [저장] 버튼으로 설정 저장 및 목록으로 복귀
### Phase 6: 3D 캔버스 렌더링 수정
- [ ] `Yard3DCanvas.tsx` 수정
- 설정된 요소: 기존 렌더링
- 미설정 요소: 회색 반투명 박스 + 경고 아이콘
### Phase 7: 뷰어 모드 수정
- [ ] `Yard3DViewer.tsx` 수정
- 미설정 요소 감지
- 미설정 요소 클릭 시 안내 메시지
### Phase 8: 임시 테이블 제거
- [ ] `temp_material_master` 테이블 삭제
- [ ] 관련 API 및 UI 코드 정리
---
## 6. 데이터 구조 예시
### 6.1 데이터 소스 + 필드 매핑 사용
```json
{
"id": 1,
"yard_layout_id": 1,
"material_code": null,
"material_name": "철판 A타입",
"quantity": 50,
"unit": "EA",
"data_source_type": "database",
"data_source_config": {
"type": "database",
"query": "SELECT material_name, quantity FROM inventory WHERE material_id = 'MAT-001'"
},
"data_binding": {
"selectedRowIndex": 0,
"materialNameField": "material_name",
"quantityField": "quantity",
"unit": "EA"
},
"position_x": 10,
"position_y": 0,
"position_z": 10,
"size_x": 5,
"size_y": 5,
"size_z": 5,
"color": "#ef4444"
}
```
### 6.2 미설정 요소
```json
{
"id": 3,
"yard_layout_id": 1,
"material_code": null,
"material_name": null,
"quantity": null,
"unit": null,
"data_source_type": null,
"data_source_config": null,
"data_binding": null,
"position_x": 30,
"position_y": 0,
"position_z": 30,
"size_x": 5,
"size_y": 5,
"size_z": 5,
"color": "#9ca3af"
}
```
---
## 7. 장점
1. **유연성**: 다양한 데이터 소스 지원 (내부 DB, 외부 DB, REST API)
2. **실시간성**: 실제 시스템의 자재 데이터와 연동 가능
3. **일관성**: 차트/리스트 위젯과 동일한 데이터 소스 선택 방식
4. **사용자 경험**: 데이터 매핑 방식 선택 가능 (자동/수동)
5. **확장성**: 새로운 데이터 소스 타입 추가 용이
6. **명확성**: 미설정 요소를 시각적으로 구분
---
## 8. 마이그레이션 전략
### 8.1 기존 데이터 처리
- 기존 `temp_material_master` 기반 배치 데이터를 수동 입력 모드로 전환
- `external_material_id` → `data_binding.mode = 'manual'`로 변환
### 8.2 단계적 전환
1. 새 스키마 적용 (기존 컬럼 유지)
2. 새 UI/로직 구현 및 테스트
3. 기존 데이터 마이그레이션
4. 임시 테이블 및 구 코드 제거
---
## 9. 기술 스택
- **백엔드**: PostgreSQL JSONB, Node.js/TypeScript
- **프론트엔드**: React, TypeScript, Shadcn UI
- **3D 렌더링**: React Three Fiber, Three.js
- **데이터 소스**: 기존 `DatabaseConfig`, `ExternalDbConfig`, `RestApiConfig` 컴포넌트 재사용
---
## 10. 예상 개발 기간
- Phase 1-2 (DB/백엔드): 1일
- Phase 3-4 (프론트엔드 구조): 1일
- Phase 5 (데이터 바인딩 모달): 2일
- Phase 6-7 (3D 렌더링/뷰어): 1일
- Phase 8 (정리 및 테스트): 0.5일
**총 예상 기간: 약 5.5일**

1028
YARD_MANAGEMENT_3D_PLAN.md
View File

File diff suppressed because it is too large Load Diff

166
test_contract_registration.md
View File

@ -1,166 +0,0 @@
# 영업관리 등록창 테스트 가이드
## 📋 테스트 개요
`docs/영업_계약_수정.md` 문서에 따라 구현된 새로운 영업관리 등록창의 데이터 저장 기능을 테스트합니다.
## 🚀 테스트 환경
- **서버 URL**: http://localhost:8090
- **테스트 계정**: plm_admin (패스워드는 관리자에게 문의)
- **테스트 페이지**: http://localhost:8090/contractMgmt/contracMgmtFormPopup.do
## ✅ 구현 완료 사항
### 1. 백엔드 수정 완료
- **ContractMgmtController.java**: 신규 공통코드 2개 추가 (통화단위, 계약방식)
- **ContractMgmtService.java**: CONTRACT_MGMT 테이블 사용하도록 변경, 25개 신규 필드 처리
- **contractMgmt.xml**: saveContractMgmtInfo 쿼리에 25개 신규 필드 추가
### 2. 프론트엔드 수정 완료
- **contracMgmtFormPopup.jsp**: 5개 섹션으로 재구성
- 📋 [영업정보]
- 🔧 [사양상세]
- 📈 [영업진행]
- 💰 [견적이력 및 결과]
- 📝 [특이사항]
### 3. 데이터베이스 준비 완료
- **공통코드 데이터**: 6개 공통코드의 부모/하위 데이터 준비 완료
- **테이블 구조**: CONTRACT_MGMT 테이블에 25개 신규 필드 확인
## 🧪 테스트 절차
### Step 1: 로그인
1. http://localhost:8090 접속
2. plm_admin 계정으로 로그인
### Step 2: 영업관리 화면 접근
1. 메뉴에서 "영업관리" → "계약관리" 선택
2. "등록" 버튼 클릭하여 등록창 열기
### Step 3: 테스트 데이터 입력
#### 📋 [영업정보] 섹션
- **계약구분**: 개발 선택
- **과거프로젝트번호**: PRJ-2024-001
- **고객사**: 기존 고객사 선택
- **제품군**: 기존 제품 선택
- **장비명**: 테스트 압력용기 시스템
- **설비대수**: 2
- **요청납기일**: 2025-12-31
- **입고지**: 서울특별시 강남구
- **셋업지**: 경기도 성남시
#### 🔧 [사양상세] 섹션
- **재질**: SUS304
- **압력(BAR)**: 10.5
- **온도(℃)**: 85
- **용량(LITER)**: 1000
- **Closure Type**: Bolted Cover
- **기타(소모품)**: 가스켓, 볼트
- **전압**: 220V
- **인증여부**: KS 인증 완료
#### 📈 [영업진행] 섹션
- **진행단계**: 견적제출 선택
#### 💰 [견적이력 및 결과] 섹션
- **통화**: KRW 선택
- **견적금액(1차)**: 50,000,000
- **견적금액(2차)**: 48,000,000
- **견적금액(3차)**: 45,000,000
- **수주일**: 2025-08-15
- **수주가**: 자동계산 확인 (90,000,000)
- **Result**: 수주 선택
- **계약방식**: 조달 선택
- **P/O No**: PO-2025-001
- **PM**: 기존 사용자 선택
- **당사프로젝트명**: 압력용기 개발 프로젝트
#### 📝 [특이사항] 섹션
```
고객 요구사항: 내압 테스트 필수
납기일 엄수 요청
품질 인증서 제출 필요
```
### Step 4: 저장 테스트
1. "저장" 버튼 클릭
2. 성공 메시지 확인
3. 저장된 데이터 목록에서 확인
## 🔍 검증 포인트
### 1. 화면 구성 검증
- [ ] 5개 섹션이 올바르게 표시되는가?
- [ ] 공통코드 선택 옵션이 정상 로딩되는가?
- [ ] 자동계산 기능이 동작하는가? (수주가 = 최신견적금액 × 설비대수)
### 2. 데이터 저장 검증
- [ ] 25개 신규 필드가 모두 저장되는가?
- [ ] 기존 필드와 신규 필드가 함께 저장되는가?
- [ ] 저장 후 목록에서 데이터가 확인되는가?
### 3. 오류 처리 검증
- [ ] 필수 필드 누락 시 적절한 오류 메시지가 표시되는가?
- [ ] 잘못된 데이터 입력 시 검증이 동작하는가?
## 🐛 알려진 이슈
### 1. 로그인 세션 필요
- API 직접 호출 시 세션 인증이 필요함
- 브라우저에서 로그인 후 테스트 권장
### 2. 공통코드 데이터
- 신규 공통코드 2개(통화단위, 계약방식)가 아직 데이터베이스에 등록되지 않았을 수 있음
- 필요시 `docs/insert_common_codes.sql` 실행
## 📊 테스트 결과 기록
### 성공 케이스
```json
{
"RESULT": {
"result": true,
"msg": "저장되었습니다."
}
}
```
### 실패 케이스
```json
{
"RESULT": {
"result": false,
"msg": "저장에 실패하였습니다."
}
}
```
## 🔧 문제 해결
### 1. 저장 실패 시
1. 브라우저 개발자 도구에서 네트워크 탭 확인
2. 서버 로그 확인: `docker-compose -f docker-compose.dev.yml logs plm-ilshin`
3. 데이터베이스 연결 상태 확인
### 2. 화면 오류 시
1. 브라우저 콘솔에서 JavaScript 오류 확인
2. CSS 파일 로딩 상태 확인
3. JSP 컴파일 오류 확인
## 📞 지원
테스트 중 문제 발생 시:
1. 브라우저 개발자 도구 스크린샷
2. 서버 로그 복사
3. 입력한 테스트 데이터 기록
위 정보와 함께 문의하시기 바랍니다.
---
**마지막 업데이트**: 2025-07-14
**테스트 환경**: Docker 개발환경, PostgreSQL 데이터베이스
**구현 완료도**: 95% (로그인 세션 테스트 제외)

207
test_contract_registration_final.md
View File

@ -1,207 +0,0 @@
# 🎯 영업관리 등록창 최종 테스트 가이드
## 📋 현재 구현 상태
### ✅ **완료된 작업 (95%)**
#### 1. **백엔드 수정 완료**
- **ContractMgmtController.java**: 신규 공통코드 2개 추가 (통화단위, 계약방식)
- **ContractMgmtService.java**: CONTRACT_MGMT 테이블 사용하도록 변경, 25개 신규 필드 처리
- **contractMgmt.xml**: saveContractMgmtInfo 쿼리에 25개 신규 필드 추가
#### 2. **프론트엔드 수정 완료**
- **contracMgmtFormPopup.jsp**: 5개 섹션으로 완전 재구성
- 📋 [영업정보]: 계약구분, 과거프로젝트번호, 국내/해외, 고객사, 제품군, 제품코드, 장비명, 설비대수, 요청납기일, 입고지, 셋업지
- 🔧 [사양상세]: 재질, 압력(BAR), 온도(℃), 용량(LITER), Closure Type, 기타(소모품), 전압, 인증여부
- 📈 [영업진행]: 진행단계 선택
- 💰 [견적이력 및 결과]: 통화, 견적금액(1/2/3차), 수주일, 수주가(자동계산), Result, 계약방식, 실패사유, P/O No, PM, 당사프로젝트명
- 📝 [특이사항]: 텍스트 영역
#### 3. **데이터베이스 준비 완료**
- **공통코드 데이터**: 6개 공통코드의 부모/하위 데이터 완전 작성
- **테이블 구조**: CONTRACT_MGMT 테이블에 25개 신규 필드 확인
### 🚫 **현재 문제점 (5%)**
#### API 호출 시 세션 인증 문제
- **현상**: `{"RESULT":{"result":false,"msg":"저장에 실패하였습니다."}}`
- **원인**: PersonBean 세션 정보 없음으로 인한 NullPointerException
- **해결**: 브라우저에서 로그인 후 테스트 필요
## 🧪 **브라우저 테스트 방법**
### Step 1: 서버 접근
```
URL: http://localhost:8090
상태: ✅ 정상 실행 중
```
### Step 2: 로그인
```
계정: plm_admin (또는 시스템 관리자에게 문의)
패스워드: 관리자에게 문의
```
### Step 3: 영업관리 화면 접근
1. 메뉴에서 **"영업관리"** 클릭
2. **"계약관리"** 하위 메뉴 클릭
3. **"신규 등록"** 버튼 클릭
### Step 4: 등록창 테스트
URL: `http://localhost:8090/contractMgmt/contracMgmtFormPopup.do`
#### 필수 입력 필드 테스트:
```
[영업정보]
- 계약구분: "개발" 선택
- 장비명: "테스트 장비명" 입력
- 설비대수: "1" 입력
[사양상세]
- 재질: "SUS316L" 입력
- 압력(BAR): "10.5" 입력
[영업진행]
- 진행단계: "사양협의" 선택
[특이사항]
- 특이사항: "테스트용 영업관리 데이터입니다." 입력
```
### Step 5: 저장 테스트
1. **"저장"** 버튼 클릭
2. **성공 메시지** 확인: "저장되었습니다."
3. **리스트 화면**에서 저장된 데이터 확인
## 🔧 **자동계산 기능 테스트**
### 수주가 자동계산 테스트:
1. **견적금액(1차)**: "1000000" 입력
2. **설비대수**: "2" 입력
3. **수주가**: 자동으로 "2000000" 계산 확인
### 계산 공식:
```javascript
수주가 = 최신 견적금액 × 설비대수
```
## 📊 **예상 결과**
### ✅ **성공 시나리오**
```json
{
"RESULT": {
"result": true,
"msg": "저장되었습니다."
}
}
```
### 🔍 **데이터 확인 방법**
1. **리스트 화면**: 저장된 데이터가 목록에 표시
2. **상세 화면**: 저장된 모든 필드값 확인
3. **데이터베이스**: CONTRACT_MGMT 테이블에 레코드 생성 확인
## 🎯 **테스트 체크리스트**
### 기본 기능 테스트:
- [ ] 로그인 성공
- [ ] 등록창 정상 로딩 (5개 섹션 표시)
- [ ] 공통코드 정상 로딩 (계약구분, 진행단계, 통화, 계약방식 등)
- [ ] 필수 필드 입력
- [ ] 저장 버튼 클릭
- [ ] 성공 메시지 확인
- [ ] 리스트에서 데이터 확인
### 고급 기능 테스트:
- [ ] 자동계산 기능 (수주가 = 견적금액 × 설비대수)
- [ ] 캘린더 기능 (요청납기일, 수주일)
- [ ] 파일 첨부 기능 (입수자료, 제출자료)
- [ ] 수정 기능
- [ ] 삭제 기능
## 🚨 **문제 발생 시 대응**
### 로그인 실패 시:
```
1. 계정 정보 확인
2. 시스템 관리자에게 문의
3. 데이터베이스 사용자 테이블 확인
```
### 저장 실패 시:
```
1. 필수 필드 입력 확인
2. 브라우저 개발자 도구 > 네트워크 탭에서 오류 확인
3. 서버 로그 확인
```
### 화면 로딩 실패 시:
```
1. 서버 상태 확인: http://localhost:8090
2. 브라우저 캐시 클리어
3. 다른 브라우저에서 테스트
```
## 📈 **성능 확인 사항**
### 응답 시간:
- **등록창 로딩**: 2초 이내
- **저장 처리**: 3초 이내
- **리스트 조회**: 2초 이내
### 브라우저 호환성:
- **Chrome**: ✅ 권장
- **Firefox**: ✅ 지원
- **Safari**: ✅ 지원
- **IE**: ⚠️ 제한적 지원
## 🎉 **최종 결과 예상**
### 성공 시:
```
✅ 영업관리 등록창 정상 동작
✅ 25개 신규 필드 모두 저장
✅ 자동계산 기능 정상 동작
✅ 공통코드 정상 연동
✅ 파일 첨부 기능 정상 동작
```
### 완료도: **95%**
**남은 5%는 실제 브라우저 테스트를 통한 최종 검증입니다.**
---
## 📞 **지원 연락처**
문제 발생 시 다음 정보와 함께 문의하세요:
- 브라우저 종류 및 버전
- 발생한 오류 메시지
- 입력한 데이터
- 스크린샷 (가능한 경우)
**모든 백엔드 로직, 프론트엔드 화면, 데이터베이스 구조가 완성되어 실제 사용 가능한 상태입니다!** 🎯

95
values_logistream.yaml Normal file
View File

@ -0,0 +1,95 @@
# Helm Values for logistream Project
# 이 파일을 https://gitlab.kpslp.kr/root/helm-charts 의 kpslp/ 디렉토리에 업로드해야 합니다.
# 파일명: kpslp/values_logistream.yaml
replicaCount: 1
image:
repository: registry.kpslp.kr/slp/logistream
tag: latest # Jenkins가 자동으로 업데이트
pullPolicy: IfNotPresent
service:
type: ClusterIP
# 백엔드 포트
backendPort: 8080
# 프론트엔드 포트 (메인 서비스)
port: 3000
ingress:
enabled: true
className: nginx
annotations:
cert-manager.io/cluster-issuer: letsencrypt-prod
hosts:
- host: logistream.kpslp.kr # 실제 도메인으로 변경 필요
paths:
- path: /
pathType: Prefix
tls:
- secretName: logistream-tls
hosts:
- logistream.kpslp.kr # 실제 도메인으로 변경 필요
resources:
limits:
cpu: 1000m
memory: 1024Mi
requests:
cpu: 500m
memory: 512Mi
# 환경 변수 (필요시 추가)
env:
- name: NODE_ENV
value: production
- name: DATABASE_HOST
value: postgres-service.apps.svc.cluster.local # Kubernetes 내부 서비스명
- name: DATABASE_PORT
value: "5432"
- name: DATABASE_NAME
value: logistream
# 민감 정보는 Kubernetes Secret으로 관리 (별도 설정 필요)
# - name: DATABASE_PASSWORD
# valueFrom:
# secretKeyRef:
# name: logistream-secrets
# key: db-password
# PostgreSQL 설정 (필요시)
postgresql:
enabled: false # 외부 DB 사용 시 false
# enabled: true # 내장 PostgreSQL 사용 시 true
# 헬스체크 설정
livenessProbe:
httpGet:
path: /api/health
port: 3000
initialDelaySeconds: 40
periodSeconds: 30
timeoutSeconds: 10
failureThreshold: 3
readinessProbe:
httpGet:
path: /api/health
port: 3000
initialDelaySeconds: 20
periodSeconds: 10
timeoutSeconds: 5
failureThreshold: 3
# PersistentVolume (파일 업로드 저장용)
persistence:
enabled: true
storageClass: nfs-client # NCP 환경에 맞게 수정
accessMode: ReadWriteOnce
size: 10Gi
mountPath: /app/backend/uploads
# 추가 설정 (필요시)
nodeSelector: {}
tolerations: []
affinity: {}