workflow-management

ワークフロー管理スキル

このスキルは、apps/web/src/workflows/ にある Vercel WDK（Workflow Development Kit）のワークフローを扱う際に役立ちます。

このスキルを使用するタイミング

• データ取得用の新しいスケジュール済みワークフローを追加するとき
• ワークフローの実行エラーをデバッグするとき
• 既存のワークフローのスケジュールやロジックを変更するとき
• 更新パイプラインに新しいデータソースを統合するとき
• 新しいソーシャルメディア投稿ワークフローを追加するとき

ワークフローのアーキテクチャ

このプロジェクトでは、次の構成で Vercel WDK ワークフローを使用しています。

apps/web/src/workflows/
├── cars.ts              # Car registration data workflow
├── coe.ts               # COE bidding data workflow
├── deregistrations.ts   # Deregistration data workflow
├── regenerate-post.ts   # Blog post regeneration workflow
└── shared.ts            # Shared workflow steps (social media, cache)

主なパターン

1. ワークフローの定義

ワークフローは Vercel WDK ディレクティブを使って定義します。

import { fetch } from "workflow";

export async function carsWorkflow(payload: CarsWorkflowPayload) {
  "use workflow";

  // Enable WDK's durable fetch for AI SDK
  globalThis.fetch = fetch;

  // Step 1: Process data
  const result = await processCarsData();

  // Step 2: Revalidate cache
  await revalidateCarsCache(month, year);

  // Step 3: Generate blog post
  const post = await generateCarsPost(data, month);

  return { postId: post.postId };
}

async function processCarsData(): Promise<UpdaterResult> {
  "use step";
  // Processing logic - each step is durable and can retry
  return await updateCars();
}

2. ワークフローのスケジュール設定

ワークフローは、apps/web/vercel.json で設定された Vercel Cron スケジュールによって起動されます。

{
  "crons": [
    { "path": "/api/workflows/cars", "schedule": "0 10 * * *" },
    { "path": "/api/workflows/coe", "schedule": "0 10 * * *" },
    { "path": "/api/workflows/deregistrations", "schedule": "0 10 * * *" }
  ]
}

3. API ルートとの統合

API ルートは、WDK の start() 関数を使ってワークフローを起動します。

import { start } from "workflow/api";
import { carsWorkflow } from "@web/workflows/cars";

export async function POST(request: Request) {
  const payload = await request.json();
  const run = await start(carsWorkflow, [payload]);
  return Response.json({ message: "Workflow started", runId: run.runId });
}

4. 共有ステップ

共通の処理は shared.ts に切り出します。

export async function publishToSocialMedia(title: string, link: string) {
  "use step";
  await socialMediaManager.publishToAll({ message: `📰 ${title}`, link });
}

export async function revalidatePostsCache() {
  "use step";
  revalidateTag("posts:list", "max");
}

5. エラー処理

ステップは失敗時に自動で再試行されます。カスタムのエラー処理を行う場合は、次のようにします。

async function processData() {
  "use step";
  try {
    const result = await updateData();
    return result;
  } catch (error) {
    console.error("Step failed:", error);
    throw error; // Re-throw for automatic retry
  }
}

よくあるタスク

新しいワークフローを追加する

1. apps/web/src/workflows/ にワークフローファイルを作成します
2. "use workflow" ディレクティブを使ってワークフロー関数を定義します
3. "use step" ディレクティブを使ってロジックをステップに分割します
4. apps/web/src/app/api/workflows/ に API ルートを作成します
5. 必要に応じて vercel.json に Vercel Cron スケジュールを追加します
6. ワークフローのロジックをテストするテストを追加します

ワークフローの失敗をデバッグする

1. Vercel ダッシュボードでワークフローの実行ログを確認します
2. Vercel の関数ログを確認します
3. 環境変数が正しく設定されていることを確認します
4. 開発サーバーを使って、ローカルでワークフローをテストします
5. データベースへの接続と Redis の利用可能性を確認します

既存のワークフローを変更する

1. 既存のワークフローの実装を確認します
2. 変更が必要なステップを特定します
3. エラー処理を維持しながら、ステップのロジックを更新します
4. ローカルで変更をテストします
5. デプロイして実行状況を監視します

環境変数

ワークフローでは通常、次の環境変数が必要です。

• DATABASE_URL - PostgreSQL 接続
• UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN - Redis
• サービス固有のトークン（Discord webhook、Twitter API など）

ワークフローのテスト

ワークフローのテストを実行します。

pnpm -F @sgcarstrends/web test -- src/workflows

個々のワークフローをローカルでテストします。

# Start dev server
pnpm dev

# Trigger workflow via HTTP
curl -X POST http://localhost:3000/api/workflows/cars

参考資料

• Vercel WDK ドキュメント：https://vercel.com/docs/workflow-kit
• 関連ファイル：
  • apps/web/src/app/api/workflows/ - ワークフローのルートハンドラー
  • apps/web/src/config/platforms.ts - ソーシャルメディアの設定
  • apps/web/vercel.json - Vercel Cron スケジュール
  • apps/web/AGENTS.md - Web アプリケーションのドキュメント

ベストプラクティス

1. 冪等性：データが重複することなく安全に再試行できるようにします
2. ステップの粒度：ワークフローを "use step" を使った、小さく目的の明確なステップに分割します
3. 永続的なフェッチ：AI SDK の呼び出しでは globalThis.fetch = fetch を設定します
4. ロギング：デバッグ用に包括的なログを追加します
5. テスト：ワークフローのロジックの単体テストを作成します
6. 監視：Vercel ダッシュボードでワークフローの実行状況を追跡します