Flow
Flow(플로우)는 Tool의 실행 로직을 정의하는 방향 비순환 그래프(DAG, Directed Acyclic Graph)입니다. 각 노드는 특정 작업을 수행하고, 엣지는 노드 간 데이터 흐름과 실행 순서를 정의합니다. Flow는 Flow Studio에서 시각적으로 설계되며, Tool 스펙의 일부로 저장됩니다.
Flow 그래프 구조
모든 Flow는 세 가지 요소로 구성됩니다:
- Nodes(노드) -- 개별 작업 단위 (데이터 조회, 데이터 쓰기, 변환, 분기, 외부 서비스 호출 등)
- Edges(엣지) -- 실행 순서와 데이터 전달을 정의하는 노드 간 연결
- Start Node(시작 노드) -- Flow의 진입점. 정확히 하나의 시작 노드가 필요합니다.
노드 유형
노드는 네 가지 카테고리로 분류됩니다:
| Category | Node | Description |
|---|---|---|
| Data | Read | Entity 또는 Composite에서 레코드 조회 |
| Data | Write | Entity 레코드 생성, 수정, 상태 전이, 소프트 삭제 |
| Logic | Transform | Value DSL을 사용한 데이터 변환 |
| Logic | If/Switch | Value DSL 표현식 기반의 조건 분기 |
| Logic | Retry | 실패 시 재시도 (횟수 및 백오프 전략 설정 가능) |
| Logic | Timeout | 하위 노드에 대한 실행 시간 제한 설정 |
| External | Payment | 결제 서비스 호출 (Stripe 등) |
| External | Email/SMS | 이메일 또는 SMS 알림 전송 |
| External | HTTP Request | 외부 HTTP API 호출 |
| Safety | Transaction | 명시적 트랜잭션 경계 표시 (begin/commit/rollback) |
| Safety | Policy Check | Policy 검사 실행 (행 제한, 예산 제약 등) |
| Safety | Assert | 불변식 강제 -- 표현식이 거짓이면 Flow 중단 |
Data 노드
Read 노드는 선택적 필터, 정렬, 페이지네이션을 사용하여 Entity 또는 Composite를 조회합니다. 무제한 쿼리를 방지하기 위해 모든 Read 노드는 반드시 limit을 지정해야 합니다.
Write 노드는 Entity 레코드를 수정합니다. 지원되는 작업은 create, update, transition(상태 변경), softDelete입니다. 모든 Write 노드는 Transaction 경계 내에 배치해야 합니다.
Logic 노드
Transform 노드는 Value DSL 표현식을 사용하여 파생된 값을 계산합니다. 입력 데이터를 받아 부작용 없이 새로운 값을 생성합니다.
If 노드는 Value DSL 불리언 표현식을 평가하고 두 경로(then 또는 else) 중 하나로 분기합니다. Switch 노드는 표현식을 평가하고 여러 명명된 경로 중 하나로 분기합니다.
Retry 노드는 하위 작업에 재시도 로직을 적용하며, 최대 시도 횟수와 백오프 전략(고정 또는 지수)을 지정합니다.
Timeout 노드는 하위 작업에 대한 최대 실행 시간을 설정합니다.
External 노드
External 노드는 Fascia 실행기 외부의 서비스를 호출합니다. 항상 Retry와 Timeout 노드를 함께 설정해야 합니다. 부작용이 있는 External 노드는 Transaction 경계 내에 배치해서는 안 됩니다 -- 트랜잭션이 롤백되더라도 외부 부작용은 되돌릴 수 없기 때문입니다.
Safety 노드
Transaction 노드는 데이터베이스 트랜잭션의 시작과 끝을 표시합니다. 모든 Write 노드는 Transaction 경계 내에 포함되어야 합니다.
Policy Check 노드는 런타임에 Policy를 평가합니다. 정책 조건이 실패하면 정책 행동(block, warn, escalate)에 따라 Flow가 중단됩니다.
Assert 노드는 Value DSL 불리언 표현식을 평가합니다. 어설션이 실패하면 지정된 오류 메시지와 함께 Flow가 중단됩니다. Assert는 불변식과 사전 조건을 강제하는 데 사용됩니다.
엣지와 데이터 매핑
엣지는 실행 순서에 따라 노드를 연결합니다. 각 엣지는 소스 노드의 출력을 대상 노드의 예상 입력으로 변환하는 데이터 매핑을 선택적으로 정의할 수 있습니다. 데이터 매핑은 Value DSL 표현식을 사용합니다.
노드에 여러 개의 들어오는 엣지가 있는 경우(예: If/Switch 수렴 후), 모든 경로의 데이터가 매핑 규칙에 따라 병합됩니다.
검증 규칙
모든 Flow는 배포 전에 다음 구조적 규칙을 충족해야 합니다:
- 비순환(Acyclic) -- 그래프는 DAG여야 합니다. 순환은 허용되지 않습니다. 위상 정렬(Kahn's algorithm)로 검증됩니다.
- 단일 시작 노드 -- 정확히 하나의 노드가 진입점으로 지정되어야 합니다.
- 모든 경로 종료 -- 그래프를 통과하는 모든 경로는 종단 노드(나가는 엣지가 없는 노드)에 도달해야 합니다.
- 트랜잭션 내 쓰기 -- 모든 Write 노드는 Transaction begin/commit 경계 내에 포함되어야 합니다.
- 트랜잭션 외부의 External 노드 -- 부작용이 있는 External 노드는 복구 불가능한 상태를 방지하기 위해 Transaction 경계 내에 배치하지 않아야 합니다.
- External 노드 재시도 설정 -- External 노드(Payment, Email/SMS, HTTP Request)는 일시적 장애 처리를 위한 Retry 설정이 필요합니다.
- External 노드 타임아웃 설정 -- External 노드는 무한 대기를 방지하기 위한 Timeout 설정이 필요합니다.
규칙 14 위반은 Red 리스크 등급이 부여되어 배포가 차단됩니다. 규칙 57 위반은 Yellow 리스크 등급이 부여되어 확인이 필요합니다. 리스크 분류에 대한 자세한 내용은 Policy를 참고하세요.