⏳
Temporal 치트시트

Temporal 1.2x+ 핵심 완전 가이드: Temporal CLI 및 Docker 로컬 개발 환경 1초 구축, Workflow vs Activity 멘탈 모델 및 Event Sourcing 아키텍처, TypeScript/Node.js 즉시 실행 코드(Hello World부터 분산 트랜잭션 Saga 패턴, Human-in-the-Loop 승인, Signals & Queries, 내구성 타이머), 결정론적(Determinism) 제약 규칙 및 프로덕션 운영 체크리스트
#temporal#workflow#orchestration#microservices#saga-pattern#distributed-systems#typescript#golang#event-driven#backend최종 업데이트: 2026-10-10
Temporal 치트시트 핵심 명령어 및 실전 가이드

## 1. 필수 사전 설치 요건 & 환경 구성 (Prerequisites)

### 💻 시스템 설치 및 실행 요구사양 (System Requirements)

| 항목 | 최소 사양 (Minimum) | 권장 사양 (Recommended) | 참고 및 비고 |
| :--- | :--- | :--- | :--- |
| **운영체제 (OS)** | Linux (모든 배포판), macOS (Apple Silicon / Intel), Windows (WSL2 또는 네이티브 CLI) | Ubuntu 22.04 LTS / macOS Sonoma / Windows 11 WSL2 | 네이티브 단일 바이너리 또는 Docker 컨테이너 지원 |
| **CPU** | 2 코어 이상 (로컬 개발 환경 기준) | 4 코어 ~ 8 코어 이상 (프로덕션 워커 및 클러스터) | Workflow Replay 및 gRPC 동시 작업 처리 성능 좌우 |
| **메모리 (RAM)** | 2 GB 이상 (로컬 개발 서버 구동 시) | 4 GB ~ 8 GB 이상 (PostgreSQL 영속화 및 웹 UI 포함) | 프로덕션 Temporal Cluster는 노드당 8GB~16GB 권장 |
| **디스크 (Storage)** | 1 GB 이상의 여유 공간 | 10 GB ~ 50 GB 이상의 고속 NVMe SSD | SQLite(개발) 또는 PostgreSQL/Cassandra(이벤트 히스토리 보관) |
| **네트워크 / 런타임** | Node.js 18+ (LTS), Python 3.10+, Go 1.21+, Java 17+ | Node.js 20+ / TypeScript 5+, Go 1.22+ | 포트 7233 (Temporal Server gRPC), 8233 (Temporal Web UI) |

---

### ⏳ Temporal이란?

**Temporal**은 분산 시스템에서 발생하는 네트워크 단절, 서버 다운, 서드파티 API 오류 속에서도 **'절대 실패하지 않고 코드가 작성된 순서대로 끝까지 완주'**하도록 보장하는 **오픈소스 코드 기반 워크플로우 오케스트레이션 엔진(Durable Execution Engine)**입니다.

- **Durable Execution (내구성 있는 실행)**: 워커 프로세스가 강제 종료되거나 서버 전원이 꺼져도, 재부팅 시 정확히 중단되었던 코드 라인(Line)에서 상태를 그대로 복원하여 계속 실행합니다.
- **코드 기반 오케스트레이션**: 복잡한 YAML이나 JSON, Drag & Drop GUI가 아닌 일반 프로그래밍 언어(TypeScript, Python, Go, Java)의 순수 코드(`async/await`, `try/catch`, `sleep()`)로 비즈니스 파이프라인을 작성합니다.
- **자동 장애 복구 & 무한 재시도**: 일시적인 네트워크 오류는 Activity 재시도 정책(`RetryPolicy`)으로 자동 복구되며, 분산 트랜잭션 롤백은 Saga 패턴으로 직관적이게 처리합니다.

---

### 🚀 1. Temporal CLI로 1초 만에 로컬 개발 서버 실행하기 (가장 추천)

Temporal 공식 CLI는 자체 내장 SQLite 스토리지와 웹 UI(Web Dashboard)를 포함하고 있어, 외부 데이터베이스 설치 없이 명령어 한 줄로 즉시 로컬 개발 클러스터를 띄울 수 있습니다.

#### ① CLI 설치

```bash
# macOS (Homebrew)
brew install temporal

# Linux / WSL (공식 설치 스크립트)
curl -sSf https://temporal.download/cli.sh | sh

# Windows (Scoop 또는 Winget)
scoop install temporal
# 또는 winget install TemporalTechnologies.temporal
```

#### ② 로컬 개발 서버 시작 (내장 웹 대시보드 포함)

```bash
# 로컬 개발 서버 실행 (SQLite 기반 데이터 유지, Web UI 자동 구동)
temporal server start-dev
```

서버가 구동되면 다음 두 엔드포인트가 즉시 활성화됩니다:
- **`localhost:7233`**: 클라이언트 및 워커가 연결하는 gRPC 서버 엔드포인트
- **`http://localhost:8233`**: 실행 중인 워크플로우, 상태, 이벤트 히스토리를 시각적으로 확인하는 **Temporal Web UI**

#### ✅ CLI 실행 상태 확인
다른 터미널 창을 열고 클러스터 상태를 확인합니다:
```bash
temporal operator cluster health
# 출력 예시: {"status": "SERVING"}
```

---

### 🐳 2. Docker Compose로 완전한 Temporal 클러스터 구동 (선택)

프로덕션과 동일하게 PostgreSQL 영속 데이터베이스와 독립적인 Frontend/History/Matching 서비스를 실행하고 싶다면 공식 Docker Compose 저장소를 활용합니다:

```bash
# 공식 temporalio/docker-compose 저장소 복제 후 구동
git clone https://github.com/temporalio/docker-compose.git
cd docker-compose
docker compose up -d
```

---

## 2. Temporal 핵심 아키텍처 & 멘탈 모델 (Core Concepts)

Temporal을 제대로 이해하기 위한 4가지 핵심 구성 요소와 이벤트 소싱(Event Sourcing) 기반 멘탈 모델입니다.

### 📐 Temporal 아키텍처 흐름도 (ASCII Diagram)

```text
  ┌─────────────────┐           gRPC (7233)           ┌──────────────────────────────────────┐
  │   Client App    │ ──────────────────────────────> │           Temporal Cluster           │
  │ (API Server 등) │  workflow.start("OrderFlow")   │  ┌──────────────────────────────────┐ │
  └─────────────────┘                                 │  │ Frontend Service (gRPC 게이트웨이)│ │
                                                      │  ├──────────────────────────────────┤ │
                                                      │  │ Matching Service (작업 큐 중개)  │ │
                                                      │  ├──────────────────────────────────┤ │
                                                      │  │ History Service (상태 머신 엔진)  │ │
                                                      │  └────────────────┬─────────────────┘ │
                                                      │                   │ Event Sourcing     │
                                                      │                   ▼                    │
                                                      │         [(PostgreSQL / SQLite)]        │
                                                      └───────────────────┬──────────────────┘
                                                                          │
                                                  Task Queue Polling      │ Task Queue
                                                 ("order-task-queue")     │ (작업 분배 큐)
                                                                          ▼
                                                      ┌──────────────────────────────────────┐
                                                      │            Worker Process            │
                                                      │  ┌────────────────────────────────┐  │
                                                      │  │ Workflow Worker (오케스트레이션) │  │
                                                      │  │  - Deterministic 순수 로직     │  │
                                                      │  ├────────────────────────────────┤  │
                                                      │  │ Activity Worker (실제 작업 실행)│  │
                                                      │  │  - 외부 결제 API 호출, DB I/O  │  │
                                                      │  └────────────────────────────────┘  │
                                                      └──────────────────────────────────────┘
```

---

### ⚖️ Workflow vs Activity 비교 (가장 중요한 차이)

| 구분 | 워크플로우 (Workflow) | 액티비티 (Activity) |
| :--- | :--- | :--- |
| **역할** | 작업 순서 지휘 및 상태 조율 (오케스트레이터) | 실제 외부 I/O, 연산, 부작용(Side Effect) 수행 |
| **코드 제약** | **반드시 결정론적(Deterministic)**이어야 함 | 일반적인 모든 코드 허용 (HTTP, DB, 무작위값 등) |
| **허용 작업** | `sleep()`, 조건 분기, Signal/Query 처리, Activity 호출 | Stripe 결제, 메일 발송, DB CRUD, AI 모델 추론 |
| **금지 작업** | `Date.now()`, `Math.random()`, 직접 네트워크 호출, 전역 변수 | 없음 |
| **장애 시 복구** | 이벤트 히스토리를 처음부터 빠르게 재실행(**Replay**)하여 상태 복원 | 실패 시 지정된 `RetryPolicy`에 따라 자동 재시도 |
| **실행 주체** | Workflow Worker (가상 스레드/이벤트 루프) | Activity Worker |

> [!IMPORTANT]
> **왜 Workflow는 결정론적(Deterministic)이어야 할까요?**
> Temporal 서버는 워크플로우의 메모리 덤프를 저장하지 않습니다. 대신 **실행된 이벤트 목록(Event History)**만을 DB에 영속화합니다. 워커 서버가 다운되었다가 살아나면, 과거의 이벤트를 그대로 재생(**Replay**)하여 당시의 코드 실행 위치와 지역 변수 값을 100% 동일하게 재구성합니다. 만약 Workflow 안에 `Math.random()`이나 `Date.now()`가 있다면 Replay 시 과거와 다른 경로로 분기되어 **`NonDeterministicWorkflowError`**가 발생합니다.

---

## 3. [초보자 1단계] 헬로월드 / 최소 동작 예제 (Quickstart)

Node.js + TypeScript 환경에서 단 5분 만에 동작하는 완전한 Temporal 워크플로우를 작성합니다.

### 📦 1. 실습 디렉토리 및 의존성 설치

```bash
mkdir temporal-starter && cd temporal-starter
npm init -y
npm install @temporalio/workflow @temporalio/activity @temporalio/worker @temporalio/client
npm install -D typescript tsx @types/node
npx tsc --init
```

---

### 🛠️ 2. 액티비티 정의 (`src/activities.ts`)

외부 API 호출이나 비즈니스 로직을 수행하는 함수입니다.

```typescript
// src/activities.ts
export async function greetUser(name: string): Promise<string> {
  console.log(`[Activity] 사용자 환영 메시지 생성 중: ${name}`);
  // 외부 API 호출이나 DB 조회를 시뮬레이션
  await new Promise((resolve) => setTimeout(resolve, 500));
  return `안녕하세요, ${name}님! Temporal의 내구성 있는 실행의 세계에 오신 것을 환영합니다.`;
}
```

---

### 📜 3. 워크플로우 정의 (`src/workflows.ts`)

액티비티를 호출하고 순서를 제어하는 오케스트레이션 코드입니다.

```typescript
// src/workflows.ts
import { proxyActivities } from '@temporalio/workflow';
import type * as activities from './activities';

// 액티비티 프록시 생성 (타임아웃 설정 필수)
const { greetUser } = proxyActivities<typeof activities>({
  startToCloseTimeout: '10 seconds', // 액티비티 1회 최대 실행 허용 시간
});

export async function exampleWorkflow(userName: string): Promise<string> {
  console.log(`[Workflow 시작] 대상: ${userName}`);

  // 액티비티 호출 (실패 시 기본 재시도 정책에 의해 자동 재시도됨)
  const greeting = await greetUser(userName);

  console.log(`[Workflow 완료] 결과: ${greeting}`);
  return greeting;
}
```

---

### ⚙️ 4. 워커 프로세스 구동 (`src/worker.ts`)

작업 큐(Task Queue)를 감시하고 실제 워크플로우 및 액티비티를 실행하는 백그라운드 프로세스입니다.

```typescript
// src/worker.ts
import { Worker } from '@temporalio/worker';
import * as activities from './activities';

async function run() {
  // 워커 인스턴스 생성 및 'hello-world-queue' 작업 큐 구독
  const worker = await Worker.create({
    workflowsPath: require.resolve('./workflows'),
    activities,
    taskQueue: 'hello-world-queue',
  });

  console.log('👷 [Temporal Worker] 작업 큐 수신 대기 중... (Task Queue: hello-world-queue)');
  await worker.run();
}

run().catch((err) => {
  console.error('워커 구동 실패:', err);
  process.exit(1);
});
```

---

### 🚀 5. 워크플로우 실행 클라이언트 (`src/client.ts`)

클러스터에 연결하여 워크플로우 실행을 요청하고 결과를 기다리는 클라이언트 코드입니다.

```typescript
// src/client.ts
import { Connection, Client } from '@temporalio/client';
import { exampleWorkflow } from './workflows';

async function main() {
  // 1. Temporal gRPC 서버 연결 (기본 localhost:7233)
  const connection = await Connection.connect({ address: 'localhost:7233' });
  const client = new Client({ connection });

  const workflowId = `greeting-wf-${Date.now()}`;

  console.log(`🚀 [Client] 워크플로우 시작 요청: ID=${workflowId}`);

  // 2. 워크플로우 시작 및 결과 대기
  const handle = await client.workflow.start(exampleWorkflow, {
    taskQueue: 'hello-world-queue',
    args: ['홍길동'],
    workflowId: workflowId,
  });

  console.log(`⏳ 실행 중... Workflow Run ID: ${handle.firstExecutionRunId}`);

  // 3. 최종 완료 결과 수신
  const result = await handle.result();
  console.log(`🎉 [Client 최종 완료 결과]:\n${result}`);
}

main().catch((err) => {
  console.error('클라이언트 실행 오류:', err);
  process.exit(1);
});
```

---

### 💻 6. 실행 및 검증 (Run & Verify)

터미널을 2개 열어 각각 워커와 클라이언트를 순차적으로 실행합니다:

```bash
# [터미널 1] 워커 프로세스 실행
npx tsx src/worker.ts
```

```bash
# [터미널 2] 클라이언트 실행
npx tsx src/client.ts
```

#### ✅ 터미널 2 예상 출력 결과:
```text
🚀 [Client] 워크플로우 시작 요청: ID=greeting-wf-1760070000000
⏳ 실행 중... Workflow Run ID: a82c1b92-4f9e-4e8c-8f4b-123456789abc
🎉 [Client 최종 완료 결과]:
안녕하세요, 홍길동님! Temporal의 내구성 있는 실행의 세계에 오신 것을 환영합니다.
```

#### 🌐 Web UI에서 시각적 확인
웹 브라우저에서 `http://localhost:8233`에 접속하면, 방금 실행된 `greeting-wf-...`의 **Status(Completed)**, **Execution Duration**, 그리고 클릭 시 나타나는 단계별 **Event History(WorkflowTaskStarted, ActivityTaskScheduled, ActivityTaskCompleted)**를 한눈에 볼 수 있습니다.

---

## 4. [초보자 2단계] 액티비티 제어: 재시도, 4대 타임아웃, 하트비트

외부 API는 언제든 실패할 수 있습니다. Temporal의 진가는 강력한 재시도 및 타임아웃 제어에서 나옵니다.

### ⏱️ Temporal의 4대 액티비티 타임아웃

| 타임아웃 종류 | 설명 | 권장 설정 가이드 |
| :--- | :--- | :--- |
| **`startToCloseTimeout`** | 워커가 액티비티 실행을 시작한 후 종료될 때까지의 **1회 최대 실행 시간** | **(필수 권장)** 개별 API 호출 예상 시간의 2~3배 (예: 5초, 30초) |
| **`scheduleToCloseTimeout`** | 최초 큐 인입부터 **모든 재시도를 거쳐 최종 완료될 때까지의 전체 상한 시간** | 전체 비즈니스 허용 마감 시간 (예: 10분, 1시간) |
| **`scheduleToStartTimeout`** | 액티비티가 Task Queue에 들어간 후 워커가 집어갈 때까지의 최대 대기 시간 | 워커 다운 감지용 (보통 미지정 권장, 기본 무제한) |
| **`heartbeatTimeout`** | 장기 실행 액티비티에서 워커가 "나 아직 살아있음" 신호를 보내야 하는 최대 주기 | 30초 이상의 긴 작업에 필수 지정 (예: 10초) |

---

### 🔄 재시도 정책 (`RetryPolicy`) 설정 예제

```typescript
// src/workflows.ts 내부
import { proxyActivities } from '@temporalio/workflow';
import type * as activities from './activities';

const { processPayment } = proxyActivities<typeof activities>({
  startToCloseTimeout: '15 seconds',
  retry: {
    initialInterval: '1 second',       // 최초 재시도 대기 시간
    backoffCoefficient: 2,             // 지수 백오프 배수 (1s -> 2s -> 4s -> 8s)
    maximumInterval: '30 seconds',     // 재시도 간격 최대 상한
    maximumAttempts: 5,                // 최대 재시도 횟수 (0 또는 미지정 시 무한 재시도)
    nonRetryableErrorTypes: ['InvalidCardError', 'CustomerNotFoundError'], // 재시도 없이 즉시 실패시킬 에러
  },
});
```

---

### 💓 장기 실행 액티비티와 하트비트 (Heartbeat)

수십 분 이상 걸리는 대용량 파일 다운로드, 영상 인코딩, AI 모델 추론 액티비티는 주기적으로 하트비트를 전송하여 워커 장애를 즉각 감지하고, 재시도 시 진행도를 이어서 수행할 수 있습니다.

```typescript
// src/activities.ts
import { Context } from '@temporalio/activity';

export async function processBatchData(totalChunks: number): Promise<void> {
  const activityContext = Context.current();

  // 이전 실패 지점의 체크포인트 확인
  let startChunk = 0;
  if (activityContext.info.heartbeatDetails) {
    startChunk = activityContext.info.heartbeatDetails as number;
    console.log(`[Activity] 이전 장애 지점(${startChunk}번 청크)부터 작업을 재개합니다.`);
  }

  for (let i = startChunk; i < totalChunks; i++) {
    await doHeavyComputation(i);

    // 하트비트 전송 (현재 진행 상태를 상세 데이터로 함께 전송)
    activityContext.heartbeat(i);
  }
}

async function doHeavyComputation(chunkIndex: number): Promise<void> {
  await new Promise((res) => setTimeout(res, 1000));
}
```

---

## 5. [초보자 3단계] 비동기 상호작용: Signals, Queries, Updates & 타이머

Temporal 워크플로우는 며칠, 몇 달 동안 백그라운드에서 살아있을 수 있습니다. 외부와의 동적 소통을 위해 **Signal**, **Query**, **Update**를 제공합니다.

### 📊 3대 상호작용 메커니즘 비교

```text
 ┌──────────────┐   1. Signal (비동기 이벤트 전달: "승인 완료됨", Fire-and-Forget)
 │              │ ─────────────────────────────────────────────────────────────> ┌──────────────┐
 │  External    │   2. Query (동기 상태 조회: "현재 진행률이 몇 %인가?", Read-Only)│   Running    │
 │  Client / UI │ <───────────────────────────────────────────────────────────── │   Workflow   │
 │              │   3. Update (동기 상태 변경 + 즉시 결과 반환: "아이템 추가하고 새 총액 반환")│              │
 └──────────────┘ <═════════════════════════════════════════════════════════════> └──────────────┘
```

---

### 💻 Signal과 Query를 활용한 주문 처리 워크플로우 예제

```typescript
// src/orderWorkflow.ts
import { defineSignal, defineQuery, setHandler, condition, sleep } from '@temporalio/workflow';

// 1. Signal 및 Query 시그니처 정의
export const approvePaymentSignal = defineSignal<[string]>('approvePayment');
export const cancelOrderSignal = defineSignal<[string]>('cancelOrder');
export const getOrderStatusQuery = defineQuery<string>('getOrderStatus');

export async function orderFulfillmentWorkflow(orderId: string): Promise<string> {
  let status = 'WAITING_FOR_PAYMENT';
  let paymentApproved = false;
  let orderCancelled = false;
  let cancellationReason = '';

  // 2. Query 핸들러 등록 (외부에서 현재 상태 실시간 조회 가능)
  setHandler(getOrderStatusQuery, () => status);

  // 3. Signal 핸들러 등록 (외부 결제 완료 알림 수신)
  setHandler(approvePaymentSignal, (transactionId) => {
    paymentApproved = true;
    status = `PAID_TX_${transactionId}`;
  });

  setHandler(cancelOrderSignal, (reason) => {
    orderCancelled = true;
    cancellationReason = reason;
    status = 'CANCELLED';
  });

  console.log(`[Order ${orderId}] 결제 승인 신호를 기다립니다 (최대 1일 대기)...`);

  // 4. condition: 조건이 참이 되거나 타임아웃(1일)이 지날 때까지 내구성 있게 대기
  const receivedInTime = await condition(() => paymentApproved || orderCancelled, '1 day');

  if (!receivedInTime) {
    status = 'EXPIRED';
    return `주문 번호 ${orderId}: 결제 시간 초과로 자동 취소되었습니다.`;
  }

  if (orderCancelled) {
    return `주문 번호 ${orderId}: 취소되었습니다 (사유: ${cancellationReason}).`;
  }

  // 5. 결제 승인 후 내구성 타이머(sleep)를 사용해 10초 후 배송 처리
  status = 'SHIPPING';
  await sleep('10 seconds');

  status = 'DELIVERED';
  return `주문 번호 ${orderId}: 배송이 완료되었습니다!`;
}
```

#### 📡 클라이언트에서 Signal 전송 및 Query 조회 방법:
```typescript
// 외부 클라이언트 코드 예시
const handle = client.workflow.getHandle(orderWorkflowId);

// 현재 상태 조회 (Query)
const currentStatus = await handle.query(getOrderStatusQuery);
console.log(`현재 주문 상태: ${currentStatus}`);

// 결제 승인 신호 전송 (Signal)
await handle.signal(approvePaymentSignal, 'TX-987654');
```

---

## 6. [실무 4단계] 프로덕션 분산 패턴: Saga 분산 트랜잭션 & Human-in-the-Loop

마이크로서비스 아키텍처(MSA)에서 가장 골치 아픈 문제는 **분산 트랜잭션**과 **사람의 승인을 기다리는 장기 워크플로우**입니다. Temporal에서는 순수 JavaScript 코드로 우아하게 해결할 수 있습니다.

### 🛡️ 1. Saga 패턴 (보상 트랜잭션 역순 롤백)

단계별로 액티비티를 실행하다가 중간에 실패하면, **성공했던 이전 단계들의 보상 액티비티(Compensation)를 역순(LIFO)으로 실행**하여 데이터 일관성을 맞춥니다.

```typescript
// src/sagaWorkflow.ts
import { proxyActivities } from '@temporalio/workflow';
import type * as activities from './activities';

const {
  reserveHotel,
  cancelHotelReservation,
  bookFlight,
  cancelFlightBooking,
  chargeCreditCard,
  refundCreditCard
} = proxyActivities<typeof activities>({
  startToCloseTimeout: '10 seconds',
  retry: { maximumAttempts: 3 },
});

export async function travelBookingSagaWorkflow(tripId: string): Promise<string> {
  // 보상 트랜잭션 함수 스택 (역순 실행용)
  const compensations: Array<() => Promise<void>> = [];

  try {
    // 1단계: 호텔 예약
    console.log('[Saga] 1. 호텔 예약 진행 중...');
    const hotelId = await reserveHotel(tripId);
    compensations.push(async () => {
      console.log('[보상 실행] 호텔 예약 취소 중...');
      await cancelHotelReservation(hotelId);
    });

    // 2단계: 항공권 예약
    console.log('[Saga] 2. 항공권 예약 진행 중...');
    const flightId = await bookFlight(tripId);
    compensations.push(async () => {
      console.log('[보상 실행] 항공권 예약 취소 중...');
      await cancelFlightBooking(flightId);
    });

    // 3단계: 신용카드 결제 (여기서 고의로 한도 초과 오류 발생 가정)
    console.log('[Saga] 3. 신용카드 결제 진행 중...');
    await chargeCreditCard(tripId, 500000);

    return `여행 예약 성공! TripId: ${tripId}`;
  } catch (err) {
    console.error(`🚨 [Saga 실패 발생] 트랜잭션 롤백(보상 작업)을 시작합니다: ${err}`);

    // 실패 시 등록된 보상 작업을 역순(LIFO)으로 실행
    for (const compensate of compensations.reverse()) {
      try {
        await compensate();
      } catch (compensationError) {
        console.error('보상 작업 실행 실패 (알림 및 수동 개입 필요):', compensationError);
      }
    }

    throw new Error(`여행 예약 전체 실패 및 롤백 완료: ${(err as Error).message}`);
  }
}
```

---

### 🧑‍💼 2. Human-in-the-Loop (관리자 승인 워크플로우)

비용 결재나 휴가 신청처럼 **사람의 승인이 필요한 작업**을 큐에 쌓아두고, 승인될 때까지 3일이든 7일이든 안전하게 대기합니다.

```typescript
// src/expenseApprovalWorkflow.ts
import { defineSignal, setHandler, condition, proxyActivities } from '@temporalio/workflow';
import type * as activities from './activities';

const { notifyEmployee, transferFunds, notifyRejection } = proxyActivities<typeof activities>({
  startToCloseTimeout: '10 seconds',
});

export const managerDecisionSignal = defineSignal<[boolean, string]>('managerDecision');

export async function expenseApprovalWorkflow(
  expenseId: string,
  amount: number
): Promise<string> {
  let isApproved: boolean | null = null;
  let reason = '';

  // 관리자의 승인/반려 시그널 핸들러
  setHandler(managerDecisionSignal, (decision, comment) => {
    isApproved = decision;
    reason = comment;
  });

  // 관리자 결정 대기 (최대 3일간 내구성 있게 sleep 대기)
  const decisionReceived = await condition(() => isApproved !== null, '3 days');

  if (!decisionReceived) {
    // 3일 내 승인이 없으면 자동 에스컬레이션 또는 자동 반려
    await notifyRejection(expenseId, '결재 대기 시간(3일) 초과로 자동 반려되었습니다.');
    return 'EXPIRED_REJECTED';
  }

  if (isApproved) {
    await transferFunds(expenseId, amount);
    await notifyEmployee(expenseId, `승인 완료 (사유: ${reason})`);
    return 'APPROVED';
  } else {
    await notifyRejection(expenseId, `관리자 반려 (사유: ${reason})`);
    return 'REJECTED';
  }
}
```

---

## 7. ⚠️ 가장 중요한 규칙: 결정론(Determinism) 제약 & 버전 관리

Temporal을 사용할 때 시니어 개발자도 자주 실수하는 핵심 주의사항입니다.

### 💥 절대 Workflow 내에 작성하면 안 되는 금지 코드

| 구분 | ❌ 절대 금지 (비결정론적 코드) | ✅ 올바른 해결 방법 |
| :--- | :--- | :--- |
| **현재 시각** | `Date.now()`, `new Date()` | `workflow.now()` 사용 (Replay 시 과거 시각 그대로 유지됨) |
| **난수 생성** | `Math.random()`, `crypto.randomUUID()` | `workflow.uuid4()` 사용 (결정론적 난수 시드 기반 생성) |
| **직접 네트워크 I/O** | `fetch()`, `axios.get()`, `axios.post()` | **반드시 Activity로 분리**하여 호출 |
| **직접 DB 접근** | Prisma, TypeORM, SQL 쿼리 직접 실행 | **반드시 Activity로 분리**하여 호출 |
| **프로세스 타이머** | `setTimeout()`, `setInterval()` | `workflow.sleep('10 seconds')` 사용 |
| **전역 가변 상태** | 파일 최상단 전역 변수 수정 (`globalCounter++`) | Workflow 내부 지역 변수 또는 Context 활용 |

---

### 🔄 워크플로우 코드 변경과 버전 관리 (`patched`)

이미 실행 중인 워크플로우가 수천 개 존재하는 상태에서 코드를 변경하면, Replay 시 기존 이벤트 히스토리와 불일치하여 장애가 발생합니다. 이를 위해 **`patched` API**를 사용합니다.

```typescript
// src/workflows.ts
import { patched, proxyActivities } from '@temporalio/workflow';
import type * as activities from './activities';

const { sendEmail, sendKakaoNotification } = proxyActivities<typeof activities>({
  startToCloseTimeout: '10 seconds',
});

export async function userOnboardingWorkflow(userId: string): Promise<void> {
  // 신규 패치 버전 식별자 지정
  if (patched('use-kakao-notification-v2')) {
    // 새로운 워크플로우 실행 시 실행되는 코드
    await sendKakaoNotification(userId);
  } else {
    // 기존에 이미 실행 중이었던 구버전 워크플로우의 Replay 시 실행되는 코드
    await sendEmail(userId);
  }
}
```

---

## 8. CLI 치트시트: `temporal` 명령줄 도구 완전 정복

자주 사용하는 `temporal` CLI 명령어 모음입니다.

### 🌐 1. 클러스터 및 개발 서버 관리
```bash
# 로컬 개발 서버 시작 (기본 포트 7233, 웹 UI 8233)
temporal server start-dev

# 데이터 영속화 디렉토리 지정하여 실행
temporal server start-dev --db-filename ~/temporal-data.db

# 클러스터 상태 확인
temporal operator cluster health
```

### 📜 2. 워크플로우 조회 및 실행
```bash
# 실행 중인 모든 워크플로우 목록 조회
temporal workflow list

# 특정 워크플로우 상세 정보 및 상태 조회
temporal workflow show --workflow-id <WORKFLOW_ID>

# CLI에서 즉시 워크플로우 트리거
temporal workflow start \
  --task-queue hello-world-queue \
  --type exampleWorkflow \
  --workflow-id my-first-wf \
  --input '"김철수"'

# 워크플로우 이벤트 히스토리 실시간 추적 (Follow)
temporal workflow show --workflow-id my-first-wf --follow
```

### 📡 3. Signal 전송 및 Query 조회
```bash
# 실행 중인 워크플로우에 시그널(Signal) 전송
temporal workflow signal \
  --workflow-id my-first-wf \
  --name approvePayment \
  --input '"TX-998877"'

# 워크플로우 상태 실시간 쿼리(Query)
temporal workflow query \
  --workflow-id my-first-wf \
  --name getOrderStatus
```

### 🛑 4. 취소 및 강제 종료
```bash
# 부드러운 취소 요청 (Workflow 내부 취소 핸들러 동작 가능)
temporal workflow cancel --workflow-id my-first-wf

# 강제 즉시 종료 (즉시 Terminated 상태로 강제 전환)
temporal workflow terminate --workflow-id my-first-wf --reason "긴급 운영자 중단"
```

---

## 9. 프로덕션 운영 & 아키텍처 체크리스트

실제 프로덕션 환경에 Temporal을 도입할 때 반드시 검토해야 하는 핵심 운영 수칙입니다.

```text
  ┌────────────────────────────────────────────────────────────────────────┐
  │                   프로덕션 운영 체크리스트 (Checklist)                 │
  ├────────────────────────────────────────────────────────────────────────┤
  │ [ ] Task Queue 분리: 무거운 CPU 작업과 가벼운 I/O 작업의 큐 분리 배정  │
  │ [ ] 워커 오토스케일링: Task Queue Backlog 지표 기반 HPA(쿠버네티스) 연동│
  │ [ ] Payload 2MB 제한: 대용량 데이터는 S3/GCS에 저장 후 Claim-Check 전달│
  │ [ ] Determinism 린터 도입: eslint-plugin-temporal로 비결정론 코드 차단  │
  │ [ ] TLS & mTLS 암호화: 클러스터와 워커 간 전송 구간 보안 인증서 적용   │
  │ [ ] 데이터 컨버터: 민감한 PII(개인정보)의 클라이언트 레벨 종단간 암호화│
  └────────────────────────────────────────────────────────────────────────┘
```

1. **Task Queue 분리 전략**:
   - `cpu-intensive-queue` (AI 모델 추론, 대용량 압축)와 `io-lightweight-queue` (웹훅 발송, 알림톡)를 별도의 Task Queue로 분리하고 각각 독립된 전용 워커 풀을 할당하여 상호 간섭을 차단합니다.
2. **대용량 Payload Claim-Check 패턴**:
   - Temporal의 단일 페이로드 제한은 2MB (gRPC 메시지 상한 4MB)입니다. 대용량 파일이나 수십 MB의 JSON은 S3, GCS 또는 MinIO에 저장하고, 워크플로우에는 객체 URL(Key)만 전달합니다.
3. **mTLS 및 데이터 암호화 (Data Converter)**:
   - 금융, 의료 등 민감한 개인정보(PII)를 처리할 때는 Custom Data Converter를 등록하여 워커가 클러스터로 이벤트를 전송하기 전에 페이로드를 AES-GCM 등으로 암호화합니다. (Temporal Server는 암호화된 내용을 읽지 못해도 정상 오케스트레이션 가능)
4. **핵심 모니터링 메트릭 (Prometheus & Grafana)**:
   - `temporal_workflow_task_schedule_to_start_latency`: 워커가 부족하여 작업이 큐에서 대기하는 시간 (스케일아웃 트리거 지표)
   - `temporal_activity_execution_failed`: 액티비티 실패율 (서드파티 장애 감지)
   - `temporal_workflow_execution_failed`: 최종 실패한 워크플로우 건수
💬
Temporal 치트시트

의견 및 질문

댓글 수정

댓글 삭제
