Temporal.io TypeScript SDK로 결제·승인·온보딩 워크플로우 구현하기 — Cron·메시지 큐 없이 장기 실행 비즈니스 프로세스를 내구성 있게 만드는 법

// activities.ts — 실제 부수효과 담당
export async function chargeCard(orderId: string): Promise<void> {
  await paymentGateway.charge(orderId);
}
 
export async function refundPayment(orderId: string): Promise<void> {
  await paymentGateway.refund(orderId);
}
 
export async function sendReceipt(orderId: string): Promise<void> {
  await emailService.send(orderId, 'receipt');
}

// worker.ts — Worker 프로세스 설정
import { Worker } from '@temporalio/worker';
import * as activities from './activities';
 
async function run() {
  const worker = await Worker.create({
    workflowsPath: require.resolve('./workflows'),
    activities,
    taskQueue: 'payment-queue',
  });
  await worker.run();
}
 
run().catch(console.error);

// workflows/orderWorkflow.ts
import { proxyActivities, defineSignal, setHandler } from '@temporalio/workflow';
import type * as activities from '../activities/orderActivities';
 
const {
  chargeCard,
  reserveInventory,
  scheduleShipment,
  refundPayment,
  releaseInventory,
  sendReceipt,
} = proxyActivities<typeof activities>({
  startToCloseTimeout: '30 seconds',
  retry: {
    maximumAttempts: 3,
    nonRetryableErrorTypes: ['InsufficientFundsError', 'CardDeclinedError'],
  },
});
 
export const cancelSignal = defineSignal<[{ reason: string }]>('cancel');
 
export async function orderWorkflow(orderId: string): Promise<string> {
  let cancelled = false;
  let cancelReason = '';
 
  setHandler(cancelSignal, ({ reason }) => {
    cancelled = true;
    cancelReason = reason;
  });
 
  let charged = false;
  let inventoryReserved = false;
 
  try {
    await chargeCard(orderId);
    charged = true;
 
    // 취소 체크는 Activity 사이에서만 일어남.
    // Activity 실행 중 즉시 중단하려면 CancellationScope로 감싸야 함.
    if (cancelled) throw new Error('취소 요청됨');
 
    await reserveInventory(orderId);
    inventoryReserved = true;
 
    if (cancelled) throw new Error('취소 요청됨');
 
    await scheduleShipment(orderId);
    await sendReceipt(orderId);
    return 'completed';
  } catch (err) {
    if (inventoryReserved) await releaseInventory(orderId);
    if (charged) await refundPayment(orderId);
    return `failed: ${cancelReason || String(err)}`;
  }
}

// workflows/purchaseApprovalWorkflow.ts
import {
  proxyActivities,
  defineSignal,
  setHandler,
  condition,
} from '@temporalio/workflow';
import type * as activities from '../activities/approvalActivities';
 
interface ApprovalDecision {
  approved: boolean;
  comment?: string;
}
 
interface PurchaseRequest {
  id: string;
  amount: number;
  requester: string;
  description: string;
}
 
const { notifyManager, notifyFinance, processPurchase, rejectRequest } =
  proxyActivities<typeof activities>({
    startToCloseTimeout: '10 seconds',
    retry: { maximumAttempts: 3 },
  });
 
export const managerApprovalSignal =
  defineSignal<[ApprovalDecision]>('managerApproval');
export const financeApprovalSignal =
  defineSignal<[ApprovalDecision]>('financeApproval');
 
export async function purchaseApprovalWorkflow(
  request: PurchaseRequest
): Promise<string> {
  let managerDecision: ApprovalDecision | null = null;
  let financeDecision: ApprovalDecision | null = null;
 
  setHandler(managerApprovalSignal, (d) => { managerDecision = d; });
  setHandler(financeApprovalSignal, (d) => { financeDecision = d; });
 
  await notifyManager(request);
 
  const managerResponded = await condition(
    () => managerDecision !== null,
    '7 days'
  );
 
  if (!managerResponded || !managerDecision?.approved) {
    await rejectRequest(request, '매니저 미승인 또는 타임아웃');
    return 'rejected';
  }
 
  if (request.amount > 10_000) {
    await notifyFinance(request);
 
    const financeResponded = await condition(
      () => financeDecision !== null,
      '3 days'
    );
 
    if (!financeResponded || !financeDecision?.approved) {
      await rejectRequest(request, '재무팀 미승인 또는 타임아웃');
      return 'rejected';
    }
  }
 
  await processPurchase(request);
  return 'approved';
}

// api/approval.ts — 승인 API 엔드포인트
import express from 'express';
import { Client } from '@temporalio/client';
import { managerApprovalSignal } from '../workflows/purchaseApprovalWorkflow';
 
const app = express();
const temporal = new Client();
 
app.post('/purchases/:id/approve', async (req, res) => {
  const handle = temporal.workflow.getHandle(`purchase-${req.params.id}`);
  await handle.signal(managerApprovalSignal, {
    approved: req.body.approved,
    comment: req.body.comment,
  });
  res.json({ ok: true });
});

// workflows/subscriptionWorkflow.ts
import {
  proxyActivities,
  sleep,
  defineSignal,
  setHandler,
  continueAsNew,
} from '@temporalio/workflow';
import type * as activities from '../activities/subscriptionActivities';
 
const { chargeMonthlyFee, sendPaymentFailureNotice, cancelSubscription } =
  proxyActivities<typeof activities>({
    startToCloseTimeout: '1 minute',
    retry: { maximumAttempts: 5, initialInterval: '1 hour' },
  });
 
export const cancelSignal = defineSignal('cancel');
 
const ITERATIONS_BEFORE_CONTINUE = 100;
 
export async function subscriptionWorkflow(
  customerId: string,
  iteration = 0
): Promise<void> {
  let isCancelled = false;
  setHandler(cancelSignal, () => { isCancelled = true; });
 
  let current = iteration;
 
  while (!isCancelled) {
    try {
      await chargeMonthlyFee(customerId);
    } catch (err) {
      await sendPaymentFailureNotice(customerId);
    }
 
    // 타이머는 Temporal Server가 관리 — Worker 재시작에 영향받지 않음
    await sleep('30 days');
    current += 1;
 
    if (current >= ITERATIONS_BEFORE_CONTINUE) {
      // 히스토리가 계속 누적되지 않도록 새 실행으로 이어짐
      await continueAsNew<typeof subscriptionWorkflow>(customerId, 0);
    }
  }
 
  await cancelSubscription(customerId);
}

// workflows/onboardingWorkflow.ts
import {
  proxyActivities,
  defineSignal,
  setHandler,
  condition,
} from '@temporalio/workflow';
import type * as activities from '../activities/onboardingActivities';
 
const {
  sendVerificationEmail,
  sendKycRequest,
  sendReminderEmail,
  activateAccount,
  expireOnboarding,
} = proxyActivities<typeof activities>({
  startToCloseTimeout: '30 seconds',
  retry: { maximumAttempts: 3 },
});
 
export const emailVerifiedSignal = defineSignal('emailVerified');
export const kycCompletedSignal =
  defineSignal<[{ passed: boolean }]>('kycCompleted');
 
export async function onboardingWorkflow(userId: string): Promise<string> {
  let emailVerified = false;
  let kycResult: { passed: boolean } | null = null;
 
  setHandler(emailVerifiedSignal, () => { emailVerified = true; });
  setHandler(kycCompletedSignal, (result) => { kycResult = result; });
 
  await sendVerificationEmail(userId);
 
  let verified = await condition(() => emailVerified, '24 hours');
  if (!verified) {
    await sendReminderEmail(userId, 'email-verification');
    verified = await condition(() => emailVerified, '48 hours');
  }
 
  if (!verified) {
    await expireOnboarding(userId);
    return 'expired';
  }
 
  await sendKycRequest(userId);
  const kycDone = await condition(() => kycResult !== null, '7 days');
 
  if (!kycDone || !kycResult?.passed) {
    await expireOnboarding(userId);
    return 'kyc-failed';
  }
 
  await activateAccount(userId);
  return 'activated';
}

// 잘못된 예 — Workflow 안에서 직접 외부 호출
export async function badWorkflow(orderId: string) {
  const result = await fetch(`/api/charge/${orderId}`); // 재실행 시 이중 청구 위험
}
 
// 올바른 예 — Activity로 분리
export async function goodWorkflow(orderId: string) {
  await chargeCard(orderId); // proxyActivities로 감싼 Activity 호출
}

import { patched } from '@temporalio/workflow';
 
export async function orderWorkflow(orderId: string) {
  if (patched('add-email-step-v2')) {
    // 새 Worker에서 실행되는 Workflow용 코드 경로
    await sendConfirmationEmail(orderId);
    await chargeCard(orderId);
  } else {
    // 이미 실행 중인 Workflow 호환 경로
    await chargeCard(orderId);
  }
}

// activities/index.ts에서 모든 activities 함수를 export한다고 가정
import type * as activities from '../activities';
 
type FastActivities = Pick<typeof activities, 'updateOrderStatus' | 'logEvent'>;
type PaymentActivities = Pick<typeof activities, 'chargeCard' | 'refundPayment'>;
 
// 빠른 내부 작업용
const { updateOrderStatus, logEvent } = proxyActivities<FastActivities>({
  startToCloseTimeout: '5 seconds',
});
 
// 외부 결제 API용 — 더 긴 타임아웃과 재시도
const { chargeCard, refundPayment } = proxyActivities<PaymentActivities>({
  startToCloseTimeout: '2 minutes',
  retry: { maximumAttempts: 3, initialInterval: '10 seconds' },
});