382 lines
10 KiB
Markdown
382 lines
10 KiB
Markdown
|
# 플로우 하이브리드 모드 사용 가이드
|
||
|
|
|
||
|
|
## 개요
|
||
|
|
|
||
|
|
플로우 관리 시스템은 세 가지 데이터 이동 방식을 지원합니다:
|
||
|
|
|
||
|
|
1. **상태 변경 방식(status)**: 같은 테이블 내에서 상태 컬럼만 업데이트
|
||
|
|
2. **테이블 이동 방식(table)**: 완전히 다른 테이블로 데이터 복사 및 이동
|
||
|
|
3. **하이브리드 방식(both)**: 두 가지 모두 수행
|
||
|
|
|
||
|
|
## 1. 상태 변경 방식 (Status Mode)
|
||
|
|
|
||
|
|
### 사용 시나리오
|
||
|
|
|
||
|
|
- 같은 엔티티가 여러 단계를 거치는 경우
|
||
|
|
- 예: 승인 프로세스 (대기 → 검토 → 승인 → 완료)
|
||
|
|
|
||
|
|
### 설정 방법
|
||
|
|
|
||
|
|
```sql
|
||
|
|
-- 플로우 정의 생성
|
||
|
|
INSERT INTO flow_definition (name, description, table_name, is_active)
|
||
|
|
VALUES ('문서 승인', '문서 승인 프로세스', 'documents', true);
|
||
|
|
|
||
|
|
-- 단계 생성 (상태 변경 방식)
|
||
|
|
INSERT INTO flow_step (
|
||
|
|
flow_definition_id, step_name, step_order,
|
||
|
|
table_name, move_type, status_column, status_value,
|
||
|
|
condition_json
|
||
|
|
) VALUES
|
||
|
|
(1, '대기', 1, 'documents', 'status', 'approval_status', 'pending',
|
||
|
|
'{"operator":"AND","conditions":[{"column":"approval_status","operator":"=","value":"pending"}]}'::jsonb),
|
||
|
|
|
||
|
|
(1, '검토중', 2, 'documents', 'status', 'approval_status', 'reviewing',
|
||
|
|
'{"operator":"AND","conditions":[{"column":"approval_status","operator":"=","value":"reviewing"}]}'::jsonb),
|
||
|
|
|
||
|
|
(1, '승인됨', 3, 'documents', 'status', 'approval_status', 'approved',
|
||
|
|
'{"operator":"AND","conditions":[{"column":"approval_status","operator":"=","value":"approved"}]}'::jsonb);
|
||
|
|
```
|
||
|
|
|
||
|
|
### 테이블 구조
|
||
|
|
|
||
|
|
```sql
|
||
|
|
CREATE TABLE documents (
|
||
|
|
id SERIAL PRIMARY KEY,
|
||
|
|
title VARCHAR(200),
|
||
|
|
content TEXT,
|
||
|
|
approval_status VARCHAR(50) DEFAULT 'pending', -- 상태 컬럼
|
||
|
|
created_at TIMESTAMP DEFAULT NOW(),
|
||
|
|
updated_at TIMESTAMP DEFAULT NOW()
|
||
|
|
);
|
||
|
|
```
|
||
|
|
|
||
|
|
### 데이터 이동
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
// 프론트엔드에서 호출
|
||
|
|
await moveData(flowId, currentStepId, nextStepId, documentId);
|
||
|
|
|
||
|
|
// 백엔드에서 처리
|
||
|
|
// documents 테이블의 approval_status가 'pending' → 'reviewing'으로 변경됨
|
||
|
|
```
|
||
|
|
|
||
|
|
## 2. 테이블 이동 방식 (Table Mode)
|
||
|
|
|
||
|
|
### 사용 시나리오
|
||
|
|
|
||
|
|
- 완전히 다른 엔티티를 다루는 경우
|
||
|
|
- 예: 제품 수명주기 (구매 주문 → 설치 작업 → 폐기 신청)
|
||
|
|
|
||
|
|
### 설정 방법
|
||
|
|
|
||
|
|
```sql
|
||
|
|
-- 플로우 정의 생성
|
||
|
|
INSERT INTO flow_definition (name, description, table_name, is_active)
|
||
|
|
VALUES ('제품 수명주기', '구매→설치→폐기 프로세스', 'purchase_orders', true);
|
||
|
|
|
||
|
|
-- 단계 생성 (테이블 이동 방식)
|
||
|
|
INSERT INTO flow_step (
|
||
|
|
flow_definition_id, step_name, step_order,
|
||
|
|
table_name, move_type, target_table,
|
||
|
|
field_mappings, required_fields
|
||
|
|
) VALUES
|
||
|
|
(2, '구매', 1, 'purchase_orders', 'table', 'installations',
|
||
|
|
'{"order_id":"purchase_order_id","product_name":"product_name","product_code":"product_code"}'::jsonb,
|
||
|
|
'["product_name","purchase_date","purchase_price"]'::jsonb),
|
||
|
|
|
||
|
|
(2, '설치', 2, 'installations', 'table', 'disposals',
|
||
|
|
'{"installation_id":"installation_id","product_name":"product_name","product_code":"product_code"}'::jsonb,
|
||
|
|
'["installation_date","installation_location","technician"]'::jsonb),
|
||
|
|
|
||
|
|
(2, '폐기', 3, 'disposals', 'table', NULL,
|
||
|
|
NULL,
|
||
|
|
'["disposal_date","disposal_method","disposal_cost"]'::jsonb);
|
||
|
|
```
|
||
|
|
|
||
|
|
### 테이블 구조
|
||
|
|
|
||
|
|
```sql
|
||
|
|
-- 단계 1: 구매 주문 테이블
|
||
|
|
CREATE TABLE purchase_orders (
|
||
|
|
id SERIAL PRIMARY KEY,
|
||
|
|
order_id VARCHAR(50) UNIQUE,
|
||
|
|
product_name VARCHAR(200),
|
||
|
|
product_code VARCHAR(50),
|
||
|
|
purchase_date DATE,
|
||
|
|
purchase_price DECIMAL(15,2),
|
||
|
|
vendor_name VARCHAR(200),
|
||
|
|
created_at TIMESTAMP DEFAULT NOW()
|
||
|
|
);
|
||
|
|
|
||
|
|
-- 단계 2: 설치 작업 테이블
|
||
|
|
CREATE TABLE installations (
|
||
|
|
id SERIAL PRIMARY KEY,
|
||
|
|
purchase_order_id VARCHAR(50), -- 매핑 필드
|
||
|
|
product_name VARCHAR(200),
|
||
|
|
product_code VARCHAR(50),
|
||
|
|
installation_date DATE,
|
||
|
|
installation_location TEXT,
|
||
|
|
technician VARCHAR(100),
|
||
|
|
created_at TIMESTAMP DEFAULT NOW()
|
||
|
|
);
|
||
|
|
|
||
|
|
-- 단계 3: 폐기 신청 테이블
|
||
|
|
CREATE TABLE disposals (
|
||
|
|
id SERIAL PRIMARY KEY,
|
||
|
|
installation_id INTEGER, -- 매핑 필드
|
||
|
|
product_name VARCHAR(200),
|
||
|
|
product_code VARCHAR(50),
|
||
|
|
disposal_date DATE,
|
||
|
|
disposal_method VARCHAR(100),
|
||
|
|
disposal_cost DECIMAL(15,2),
|
||
|
|
created_at TIMESTAMP DEFAULT NOW()
|
||
|
|
);
|
||
|
|
```
|
||
|
|
|
||
|
|
### 데이터 이동
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
// 구매 → 설치 단계로 이동
|
||
|
|
const result = await moveData(
|
||
|
|
flowId,
|
||
|
|
purchaseStepId,
|
||
|
|
installationStepId,
|
||
|
|
purchaseOrderId
|
||
|
|
);
|
||
|
|
|
||
|
|
// 결과:
|
||
|
|
// 1. purchase_orders 테이블에서 데이터 조회
|
||
|
|
// 2. field_mappings에 따라 필드 매핑
|
||
|
|
// 3. installations 테이블에 새 레코드 생성
|
||
|
|
// 4. flow_data_mapping 테이블에 매핑 정보 저장
|
||
|
|
// 5. flow_audit_log에 이동 이력 기록
|
||
|
|
```
|
||
|
|
|
||
|
|
### 매핑 정보 조회
|
||
|
|
|
||
|
|
```sql
|
||
|
|
-- 플로우 전체 이력 조회
|
||
|
|
SELECT * FROM flow_data_mapping
|
||
|
|
WHERE flow_definition_id = 2;
|
||
|
|
|
||
|
|
-- 결과 예시:
|
||
|
|
-- {
|
||
|
|
-- "current_step_id": 2,
|
||
|
|
-- "step_data_map": {
|
||
|
|
-- "1": "123", -- 구매 주문 ID
|
||
|
|
-- "2": "456" -- 설치 작업 ID
|
||
|
|
-- }
|
||
|
|
-- }
|
||
|
|
```
|
||
|
|
|
||
|
|
## 3. 하이브리드 방식 (Both Mode)
|
||
|
|
|
||
|
|
### 사용 시나리오
|
||
|
|
|
||
|
|
- 상태도 변경하면서 다른 테이블로도 이동해야 하는 경우
|
||
|
|
- 예: 검토 완료 후 승인 테이블로 이동하면서 원본 테이블의 상태도 변경
|
||
|
|
|
||
|
|
### 설정 방법
|
||
|
|
|
||
|
|
```sql
|
||
|
|
INSERT INTO flow_step (
|
||
|
|
flow_definition_id, step_name, step_order,
|
||
|
|
table_name, move_type,
|
||
|
|
status_column, status_value, -- 상태 변경용
|
||
|
|
target_table, field_mappings, -- 테이블 이동용
|
||
|
|
required_fields
|
||
|
|
) VALUES
|
||
|
|
(3, '검토 완료', 1, 'review_queue', 'both',
|
||
|
|
'status', 'reviewed',
|
||
|
|
'approved_items',
|
||
|
|
'{"item_id":"source_item_id","item_name":"name","review_score":"score"}'::jsonb,
|
||
|
|
'["review_date","reviewer_id","review_comment"]'::jsonb);
|
||
|
|
```
|
||
|
|
|
||
|
|
### 동작
|
||
|
|
|
||
|
|
1. **상태 변경**: review_queue 테이블의 status를 'reviewed'로 업데이트
|
||
|
|
2. **테이블 이동**: approved_items 테이블에 새 레코드 생성
|
||
|
|
3. **매핑 저장**: flow_data_mapping에 양쪽 ID 기록
|
||
|
|
|
||
|
|
## 4. 프론트엔드 구현
|
||
|
|
|
||
|
|
### FlowWidget에서 데이터 이동
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
// frontend/components/screen/widgets/FlowWidget.tsx
|
||
|
|
|
||
|
|
const handleMoveToNext = async () => {
|
||
|
|
// ... 선택된 데이터 준비 ...
|
||
|
|
|
||
|
|
for (const data of selectedData) {
|
||
|
|
// Primary Key 추출 (첫 번째 컬럼 또는 'id' 컬럼)
|
||
|
|
const dataId = data.id || data[stepDataColumns[0]];
|
||
|
|
|
||
|
|
// API 호출
|
||
|
|
const response = await moveData(flowId, currentStepId, nextStepId, dataId);
|
||
|
|
|
||
|
|
if (!response.success) {
|
||
|
|
toast.error(`이동 실패: ${response.message}`);
|
||
|
|
continue;
|
||
|
|
}
|
||
|
|
|
||
|
|
// 성공 시 targetDataId 확인 가능
|
||
|
|
if (response.data?.targetDataId) {
|
||
|
|
console.log(`새 테이블 ID: ${response.data.targetDataId}`);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
// 데이터 새로고침
|
||
|
|
await refreshStepData();
|
||
|
|
};
|
||
|
|
```
|
||
|
|
|
||
|
|
### 추가 데이터 전달
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
// 다음 단계로 이동하면서 추가 데이터 입력
|
||
|
|
const additionalData = {
|
||
|
|
installation_date: "2025-10-20",
|
||
|
|
technician: "John Doe",
|
||
|
|
installation_notes: "Installed successfully",
|
||
|
|
};
|
||
|
|
|
||
|
|
const response = await fetch(`/api/flow/${flowId}/move`, {
|
||
|
|
method: "POST",
|
||
|
|
headers: { "Content-Type": "application/json" },
|
||
|
|
body: JSON.stringify({
|
||
|
|
fromStepId: currentStepId,
|
||
|
|
toStepId: nextStepId,
|
||
|
|
dataId: dataId,
|
||
|
|
additionalData: additionalData,
|
||
|
|
}),
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
## 5. 감사 로그 조회
|
||
|
|
|
||
|
|
### 특정 데이터의 이력 조회
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
const auditLogs = await getFlowAuditLogs(flowId, dataId);
|
||
|
|
|
||
|
|
// 결과:
|
||
|
|
[
|
||
|
|
{
|
||
|
|
id: 1,
|
||
|
|
moveType: "table",
|
||
|
|
sourceTable: "purchase_orders",
|
||
|
|
targetTable: "installations",
|
||
|
|
sourceDataId: "123",
|
||
|
|
targetDataId: "456",
|
||
|
|
fromStepName: "구매",
|
||
|
|
toStepName: "설치",
|
||
|
|
changedBy: "system",
|
||
|
|
changedAt: "2025-10-20T10:30:00",
|
||
|
|
},
|
||
|
|
{
|
||
|
|
id: 2,
|
||
|
|
moveType: "table",
|
||
|
|
sourceTable: "installations",
|
||
|
|
targetTable: "disposals",
|
||
|
|
sourceDataId: "456",
|
||
|
|
targetDataId: "789",
|
||
|
|
fromStepName: "설치",
|
||
|
|
toStepName: "폐기",
|
||
|
|
changedBy: "user123",
|
||
|
|
changedAt: "2025-10-21T14:20:00",
|
||
|
|
},
|
||
|
|
];
|
||
|
|
```
|
||
|
|
|
||
|
|
## 6. 모범 사례
|
||
|
|
|
||
|
|
### 상태 변경 방식 사용 시
|
||
|
|
|
||
|
|
✅ **권장**:
|
||
|
|
|
||
|
|
- 단일 엔티티의 생명주기 관리
|
||
|
|
- 간단한 승인 프로세스
|
||
|
|
- 빠른 상태 조회가 필요한 경우
|
||
|
|
|
||
|
|
❌ **비권장**:
|
||
|
|
|
||
|
|
- 각 단계마다 완전히 다른 데이터 구조가 필요한 경우
|
||
|
|
|
||
|
|
### 테이블 이동 방식 사용 시
|
||
|
|
|
||
|
|
✅ **권장**:
|
||
|
|
|
||
|
|
- 각 단계가 독립적인 엔티티
|
||
|
|
- 단계별로 다른 팀/부서에서 관리
|
||
|
|
- 각 단계의 데이터 구조가 완전히 다른 경우
|
||
|
|
|
||
|
|
❌ **비권장**:
|
||
|
|
|
||
|
|
- 단순한 상태 변경만 필요한 경우 (오버엔지니어링)
|
||
|
|
- 실시간 조회 성능이 중요한 경우 (JOIN 비용)
|
||
|
|
|
||
|
|
### 하이브리드 방식 사용 시
|
||
|
|
|
||
|
|
✅ **권장**:
|
||
|
|
|
||
|
|
- 원본 데이터는 보존하면서 처리된 데이터는 별도 저장
|
||
|
|
- 이중 추적이 필요한 경우
|
||
|
|
|
||
|
|
## 7. 주의사항
|
||
|
|
|
||
|
|
1. **필드 매핑 주의**: `field_mappings`의 소스/타겟 필드가 정확해야 함
|
||
|
|
2. **필수 필드 검증**: `required_fields`에 명시된 필드는 반드시 입력
|
||
|
|
3. **트랜잭션**: 모든 이동은 트랜잭션으로 처리되어 원자성 보장
|
||
|
|
4. **Primary Key**: 테이블 이동 시 소스 데이터의 Primary Key가 명확해야 함
|
||
|
|
5. **순환 참조 방지**: 플로우 연결 시 사이클이 발생하지 않도록 주의
|
||
|
|
|
||
|
|
## 8. 트러블슈팅
|
||
|
|
|
||
|
|
### Q1: "데이터를 찾을 수 없습니다" 오류
|
||
|
|
|
||
|
|
- 원인: Primary Key가 잘못되었거나 데이터가 이미 이동됨
|
||
|
|
- 해결: `flow_audit_log`에서 이동 이력 확인
|
||
|
|
|
||
|
|
### Q2: "매핑할 데이터가 없습니다" 오류
|
||
|
|
|
||
|
|
- 원인: `field_mappings`가 비어있거나 소스 필드가 없음
|
||
|
|
- 해결: 소스 테이블에 매핑 필드가 존재하는지 확인
|
||
|
|
|
||
|
|
### Q3: 테이블 이동 후 원본 데이터 처리
|
||
|
|
|
||
|
|
- 원본 데이터는 자동으로 삭제되지 않음
|
||
|
|
- 필요시 별도 로직으로 처리하거나 `is_archived` 플래그 사용
|
||
|
|
|
||
|
|
## 9. 성능 최적화
|
||
|
|
|
||
|
|
1. **인덱스 생성**: 상태 컬럼에 인덱스 필수
|
||
|
|
|
||
|
|
```sql
|
||
|
|
CREATE INDEX idx_documents_status ON documents(approval_status);
|
||
|
|
```
|
||
|
|
|
||
|
|
2. **배치 이동**: 대량 데이터는 배치 API 사용
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
await moveBatchData(flowId, fromStepId, toStepId, dataIds);
|
||
|
|
```
|
||
|
|
|
||
|
|
3. **매핑 테이블 정리**: 주기적으로 완료된 플로우의 매핑 데이터 아카이빙
|
||
|
|
|
||
|
|
```sql
|
||
|
|
DELETE FROM flow_data_mapping
|
||
|
|
WHERE created_at < NOW() - INTERVAL '1 year'
|
||
|
|
AND current_step_id IN (SELECT id FROM flow_step WHERE step_order = (SELECT MAX(step_order) FROM flow_step WHERE flow_definition_id = ?));
|
||
|
|
```
|
||
|
|
|
||
|
|
## 결론
|
||
|
|
|
||
|
|
하이브리드 플로우 시스템은 다양한 비즈니스 요구사항에 유연하게 대응할 수 있습니다:
|
||
|
|
|
||
|
|
- 간단한 상태 관리부터
|
||
|
|
- 복잡한 다단계 프로세스까지
|
||
|
|
- 하나의 시스템으로 통합 관리 가능
|