本文へスキップ
hdknr blog
戻る

Celery はメモリ不足、ECS タスクは起動待ち — 帳票・Saga・AI エージェントの窓口をデスクトップアプリに寄せる設計

はじめに

業務システムを機能ごとに分けた結果、受注・在庫・請求といった業務ごとに API サーバーが別々に立ち、React の SPA がそれらを横断して呼び出すという構成はよく見かけます。各 API は ECS(一部は EC2)で動き、それぞれ自分のデータベースを持っています。

最初のうちはこれで回ります。ところが業務が増えるにつれて、次の 2 つの問題が目立ってきます。

  1. 複数の API をまたぐ更新の作法が決まっていない。 「受注を登録して、在庫を引き当てて、請求を作る」という一連の処理を、画面ごと・担当者ごとに違うやり方で書いている。途中で失敗したときの後始末も画面によって違う。
  2. 帳票が遅い。 常駐している Celery のワーカーで帳票を作ると、同時リクエストが重なったときにメモリが足りなくなり、タスクが落ちる。それを避けるために、帳票ごとに ECS タスクを別に起動している。ところが今度はその起動に時間がかかり、利用者を待たせてしまう。CSV や Excel の一括ファイル取り込みも、同じ構造の重い処理である。

利用者からの要望は「帳票をもっと速く出してほしい」です。よくある答えは「サーバー側に仕組みを足す」ことです。ワーカーを大きくし、ジョブキューと常駐ワーカーの数を増やします。業務をまたぐ処理にはオーケストレーター(AWS Step Functions など)を置きます。これは正攻法ですが、同時リクエストのピークに合わせてサーバーを用意し続けることになります。

この記事では逆の方向を検討します。利用者の PC で動くデスクトップアプリに、帳票の生成と Saga の調整を寄せる方向です。サーバーは「データを返し、整合性を検査する」だけの薄い層に保ちます。デスクトップアプリにはもう一つ、利用者の PC で動く AI エージェントに業務を手伝わせる土台になるという利点もあります。方針は次の 4 つです。

方針 1 と 2 はつながっています。帳票のためにデスクトップアプリを配るなら、業務をまたぐ更新の調整役もそこに置けます。サーバーにオーケストレーターを新しく立てずに、問題 1 の「作法がばらばら」を 1 つの Saga ランナーに揃えられるわけです。既存の React の画面は、デスクトップアプリ基盤(Tauri など)の WebView でそのまま動かせます。帳票と Saga の部分だけをネイティブ側に足せばよく、利用者が社内に限られる業務システムなら配布のハードルも高くありません。方針 3 は、そうして置いたアプリに API の入口もまとめるものです。方針 4 は、アプリに閉じ込めた鍵を前提に、AI エージェントに業務を任せるものです。

「ブラウザで動く SPA に司令塔を任せてよい」という話ではない点に注意してください。後で詳しく書きますが、ブラウザのタブと、ローカルに状態を保存できるデスクトップアプリとでは、中断への強さがまったく違います。

用語とプロダクト

用語 / プロダクトこの記事での意味
Saga複数サービスにまたがる処理を、ローカルなトランザクションの列と「失敗時に打ち消す補償トランザクション」で組み立てるパターン
オーケストレーション型Saga の実装方式の 1 つ。司令塔が各サービスを順に呼び、失敗したら補償を指示する
結果整合性(Eventual Consistency)途中で一時的な不整合が見えても、最終的には整合した状態に落ち着くこと
補償トランザクション完了済みのステップを業務的に取り消す処理(引当解除、受注取消など)
冪等キー(Idempotency Key)同じリクエストを何度送っても 1 回分しか効果が出ないようにするための、クライアントが付ける一意な値
有効期限つきの仮状態「仮登録」「仮引当」に期限を持たせ、確定されないまま期限が切れたらサーバーが自動で解放する仕組み
決定論的なレンダラ同じ入力からは、OS や環境によらず同じ出力(PDF)を作る生成エンジン
TauriRust 製のデスクトップアプリ基盤。画面は OS の WebView で描き、ネイティブ処理を Rust で書く
WebViewアプリの中に埋め込むブラウザエンジン。macOS では WKWebView、Windows では WebView2
BFF(Backend for Frontend)特定のフロントエンド専用に置く薄いサーバー。認証の終端や読み取りの集約を担う
MCP(Model Context Protocol)AI エージェントが外部のツールやデータを呼び出すための標準プロトコル。アプリが MCP サーバーになり、エージェントが MCP クライアントとして呼ぶ
CeleryPython の非同期タスクキュー。常駐するワーカーがキューからタスクを取り出して実行する
Amazon ECS / AWS Fargateコンテナの実行基盤。常駐する「サービス」と、1 回だけ動かす「タスク」がある
AWS Step FunctionsAWS のワークフローサービス。サーバー側に Saga の司令塔を置くときの代表的な選択肢
Amazon SQSAWS のメッセージキュー。失敗したメッセージを隔離するデッドレターキュー(DLQ)を持てる

帳票が遅い理由: Celery のメモリ不足と ECS タスクの起動待ち

最初に、帳票が遅くなる仕組みを整理しておきます。手を打つ前に、今の遅さを分解して測っておくことをおすすめします。キューでの待ち時間、タスクの起動時間、帳票の生成時間、生成中のメモリのピークに分けると、どこを削れば速くなるかが分かります。

常駐ワーカーで作るとメモリが足りなくなる

Celery のような常駐ワーカーで帳票を作る構成では、1 つのコンテナのメモリ上限を、同時に走るタスクで分け合います。PDF の生成は、元データ・テンプレート・フォント・組版の途中結果をメモリに抱えるので、1 件あたりのメモリ消費が大きい処理です。同時に何件も走ると合計がワーカーの上限を超え、コンテナごと落ちます。落ちると、同じワーカーで処理していた他の帳票も巻き込まれます。

帳票ごとにタスクを起動すると待たされる

そこで帳票ごとに ECS タスクを起動して隔離すると、メモリ不足は起きにくくなります。ところが今度は、タスクの起動そのものに時間がかかります。コンテナイメージの取得、コンテナの起動、アプリの初期化が、帳票を 1 件作るたびに利用者の待ち時間に乗ります。帳票の生成自体が数秒で終わるものでも、起動の分だけ待たされます。

つまり、サーバー側だけで解こうとすると次の板挟みになります。

方式メモリ不足待ち時間
常駐ワーカーで作る起きる(同時リクエストが重なると落ちる)短い
帳票ごとにタスクを起動する起きにくい長い(起動待ちが毎回乗る)
常駐ワーカーを大きく・多くするピーク時の同時数まで用意すれば起きない短い

3 行目なら両方とも解決しますが、月末のような一番混む時間に合わせてサーバーを用意し続けることになります。それ以外の時間は、用意したメモリの大部分が使われません。しかもこれは、処理能力の天井をピークの高さまで押し上げるだけです。利用者や帳票が増えれば、また同じ板挟みに戻ります。

サーバー側でできる応急処置

板挟みを和らげる手段は、サーバー側にもあります。クライアントへの移行を待つ間の応急処置として有効です。

ただし、どれも「サーバー側の帳票の処理能力」という天井は動かせません。同時リクエストが増えれば、待ち行列か起動待ちのどちらかで、また待たされます。

クライアントで作れば板挟みが消える

一方、利用者の PC は複数コアの CPU と数 GB 以上のメモリを持ち、多くの時間は手が空いています。帳票を PC で作れば、次のようになります。

新しくかかるのは、出来上がった PDF をアップロードする時間です。ただし、アップロードするのは保存が必要な正式な帳票だけで、1 日に何度も出す確認用の帳票は送りません(詳しくは方針 1 で)。送る場合も、組み上がった PDF を送るだけなので、組版のようにサーバーのメモリを食うことはありません。生成しながら 1 件ずつ送れば、生成とアップロードが重なり、最後にまとめて待たされることもありません。

サーバーに残るのは、データとテンプレートを返すことと、正式な帳票だけを突合して保管することです。どちらもメモリをほとんど使いません。副次的な効果として、帳票用のワーカーやタスクを外せば、業務 API のタスクも小さくできます。

目標アーキテクチャの全体像

ここまでを踏まえて、この記事で目指す構成を図にすると次のようになります。左の利用者の PC 側に調整(Saga ランナー)と計算(帳票レンダラ)と入口(アプリ内 BFF としての API クライアント)があり、右のサーバー側はネットワークの入口(ALB)と業務 API と保管だけです。アプリの中の MCP サーバーは、同じ PC の AI エージェントに業務の操作をツールとして公開します(方針 4)。

利用者の PC で動くデスクトップアプリの中に、既存の React UI を再利用した業務画面、ステップを順に呼び失敗時に補償する Saga ランナー、その進み具合を記録するローカルの Saga ログ、同梱フォントで決定論的に PDF を生成する帳票レンダラ、業務の操作をツールとして公開しソースの検索も提供する MCP サーバー、トークンを OS のキーチェーンに保管して業務ごとの接続先へ振り分けるアプリ内 BFF としての API クライアントがある構成図。同じ PC の AI エージェントは、利用者の自然文の指示を受けて MCP でツールを呼ぶだけで、鍵は持たない。API クライアントは、HTTPS 終端と WAF を担う ALB だけを経由して受注・在庫・請求の業務 API を冪等キー付きで呼び、Saga の ID と状態は、その業務の持ち主である受注 API の DB に記録する。専用の DB やサービスは増やさない。業務 API はクライアントを信頼せずに認可を検査し、冪等キー、補償 API、有効期限つきの仮状態、件数と合計の突合を提供し、期限切れの仮状態を定期的に解放する。保存が必要な正式な帳票 PDF だけが突合のうえ S3 にバージョニング付きで保管され、監査ログに誰がいつどの版で作ったかが残る。無人の夜間バッチだけは SQS とワーカーで処理する

役割ごとに見ると、次のように分かれます。

層役割やらないこと
デスクトップアプリ画面、Saga の調整と再開、帳票の生成数字を自前で作ること(入力は必ず API から取る)
アプリ内の API クライアントトークンの保管、業務ごとの接続先への振り分け、読み取りの集約(従来の BFF の役割)権限の判断(認可は業務 API が行う)
アプリ内の MCP サーバー業務単位のツールの公開、更新前の確認画面トークンをエージェントに渡すこと
AI エージェント指示の解釈と、ツールの組み合わせ鍵を持つこと、更新を自分で承認すること
ALBHTTPS の終端、WAF などネットワークの入口業務ロジック、リクエストの組み替え
業務 API自分の業務データの整合性、冪等性、補償、期限切れの解放、帳票の突合長時間の処理、他業務の DB を直接触ること
保管と監査正式な帳票の保管、誰がいつ作ったかの記録帳票の生成、確認用の帳票の保管

方針 1: 帳票はクライアントで生成する

サーバーは「データ」と「テンプレート」を返すだけ

帳票をクライアントで作る場合、サーバーの役割は次のようになります。

  1. 帳票の元データを参照 API で返す
  2. 帳票のテンプレートを(版番号つきで)返す
  3. 保存が必要な正式な帳票だけ、出来上がったものを受け取り、突合して保管する

PDF を組み立てる CPU 処理は、すべて利用者の PC で行います。

保存する帳票と、確認用の帳票を分ける

帳票には 2 種類あります。請求書のように保存が必要な正式な帳票と、残高や進み具合を確かめるために1 日に何度も出す確認用の帳票です。数で言えば、確認用のほうがずっと多いのが普通です。

種類例生成サーバーに送るか
正式な帳票請求書、納品書、支払通知書PC で生成送る。突合して S3 に保管し、監査ログに残す
確認用の帳票残高一覧、進捗表、日々の集計表PC で生成送らない。画面に表示し、必要なら印刷するだけ

確認用の帳票は、PC で作って表示したら役目を終えます。アップロードも突合も保管も要りません。サーバーから見れば、データとテンプレートを返すだけの参照 API の呼び出しにすぎず、帳票のための負荷はほぼゼロです。アップロードの待ちもないので、利用者にとっても一番速くなります。

S3 に送るべき帳票は、正式なものだけで、数は少なくて済みます。以下の「3 つの条件」や突合の手続きは、この正式な帳票のためのものです。さらに、方針 4 の AI エージェントが入ると、確認用の帳票は「聞けば分かる」ものに置き換わっていき、出す回数自体も減っていきます。

正式な帳票の流れを図にすると次のようになります。

正式な帳票をクライアントで生成し、サーバーが突合して保管する流れのシーケンス図。確認用の帳票はテンプレートとデータの取得と PC での生成までで終わり、アップロードと確定は行わない。デスクトップアプリは業務 API から版番号つきのテンプレートと、参照 API で帳票データを取得し、決定論的なレンダラと同梱フォントを使って PC の複数コアで並列に PDF を生成する。サーバーの CPU とメモリは使わない。生成した PDF は 1 件ずつ Idempotency-Key 付きで業務 API にアップロードされ S3 に仮保存される。最後にアプリが件数・合計金額・テンプレート版を送って確定を求めると、業務 API は DB の値と突合し、一致すれば正本として確定して監査ログに誰がいつ何件どの版で作ったかを記録し、不一致なら拒否する

生成場所はブラウザかデスクトップアプリか

クライアントで帳票を作る方法は 2 つあります。

生成場所方法向いている場面
ブラウザWeb Worker 上で JavaScript / WebAssembly の PDF ライブラリを動かす件数が少ない帳票。配布の仕組みが要らない
デスクトップアプリネイティブ側(Rust など)で PDF を生成する一括発行のような大量の帳票、ローカルへの保存やプリンタ連携が要る帳票

ブラウザでも、Web Worker を論理プロセッサ数(navigator.hardwareConcurrency。ブラウザが実際より小さい値を返すこともある)を目安に立てれば、並列に生成できます。ただし、大量の帳票では、メモリの上限、多数のファイルのダウンロード、生成中にタブを閉じられる問題が出てきます。一括発行が主な用途なら、デスクトップアプリのほうが扱いやすいでしょう。

正式な帳票をクライアントで作るための 3 つの条件

請求書のように「正本」として扱う帳票をクライアントで作るなら、正本であることを生成場所ではなく手続きで担保する必要があります。次の 3 つは必須です。① と ③ は確認用の帳票にも効きます。同じテンプレートとレンダラを使えば、確認用で見た数字と正式な帳票の数字が食い違いません。

#起こりうる問題対策
①OS やブラウザで見た目が変わる。 Tauri は OS の WebView を使う(macOS は WKWebView、Windows は WebView2)。文字の組み方が違うので、同じ帳票が別の見た目になりうるWebView やブラウザの印刷機能(print-to-pdf)に頼らない。決定論的な PDF レンダラを使い、フォントをアプリに同梱する
②データと帳票が一致する保証がない。 クライアントが作ったものをそのまま正本にすると、差し替えの余地がある入力データは必ず API から取得する(クライアントが数字を作らない)。確定時にサーバーが件数と合計金額を DB と突合し、合わなければ受理しない。保管先はバージョニングを有効にする
③テンプレートの版がずれる。 古い版のアプリが、古いレイアウトで発行し続けるかもしれないテンプレートはサーバーから配信し、アプリに持たせない。発行時のテンプレート版を、帳票のメタデータと DB に記録する

① が最も重要です。OS の印刷機能に頼った瞬間に、Windows と macOS で別の正本が出てしまいます。

あわせて、生成の事実(誰が・いつ・何件・どの版で)を監査ログに送ります。生成と保管は分けて考え、保管はこれまでどおりサーバー側(S3 や文書管理基盤)が担います。確認用の帳票は、個人情報を含むなど出力の記録が求められる場合に限り、生成した事実だけを軽く記録すれば十分です。

振り分けるのは「件数」ではなく「保存の要否」

「少ない件数ならサーバー、大量ならクライアント」のように振り分けたくなりますが、おすすめしません。同じ帳票が、生成経路によって別物になりうるからです。どこで線を引くかも恣意的になり、運用の途中で必ず揉めます。

振り分けてよいのは、生成した後に保存するかどうかです。生成の経路(同じテンプレート、同じレンダラ)は 1 つに統一し、帳票の種類ごとに「保存が必要か」だけを決めておきます。正式な帳票には上の 3 条件を、確認用の帳票には生成までを適用します。

長い処理は「1 件単位の冪等 API」に分解する

一括発行のように件数の多い処理は、1 件単位の冪等な API をクライアントがループで呼ぶ形に分解します。

async function issueInvoices(month: string) {
  const { template, version } = await api.get(`/api/report-templates/invoice`);
  const invoices = await api.get(`/api/billing/invoices?month=${month}`);

  // 発行の単位を登録する。冪等キーを月と版から決めておけば、
  // 中断後にやり直しても同じ batchId が返る
  const { batchId } = await api.post(`/api/report-batches`, { month, version }, {
    headers: { "Idempotency-Key": `invoice:${month}:v${version}` },
  });

  // 再開時は、アップロード済みのものを飛ばす
  const uploaded = new Set(await api.get(`/api/report-batches/${batchId}/items`));
  const remaining = invoices.filter((inv) => !uploaded.has(inv.id));

  // PC の複数コアで並列に生成し、1 件ずつアップロードする
  await parallel(remaining, navigator.hardwareConcurrency, async (inv) => {
    const pdf = await renderer.render(template, inv);           // サーバーの CPU を使わない
    await api.put(`/api/report-batches/${batchId}/items/${inv.id}`, pdf, {
      headers: { "Idempotency-Key": `${batchId}:${inv.id}` },   // 再送しても二重にならない
    });
  });

  // 件数・合計金額・テンプレート版を送り、サーバーに突合させて確定する
  await api.post(`/api/report-batches/${batchId}/finalize`, {
    count: invoices.length,
    total: sum(invoices.map((i) => i.amount)),
    templateVersion: version,
  });
}

ここでは、後で述べる Saga(方針 2)のような巻き戻しは要りません。各アイテムは互いに独立していて、どれか 1 件の失敗が他を巻き戻す必要がないからです。途中で止まっても、アップロード済みのものはサーバーに残っています。batchId は冪等キーで固定されているので、再開時は残りだけを送り直せばよく、最後の finalize で件数と合計が合わなければ確定されません。

サーバー側に残すもの

クライアント生成にできない帳票もあります。

こうした帳票だけは、サーバー側で処理します。そのときも帳票ごとに ECS タスクを起動するのではなく、**SQS と常駐ワーカー(ECS サービス)**にするのが定石です。

数が少なければ、夜間だけワーカーを起動するスケジュールにしてもかまいません。

Saga とは: 業務をまたぐ更新を組み立てる考え方

方針 2 に入る前に、Saga とそれに付随する概念を整理しておきます。冒頭の問題 1(業務をまたぐ更新の作法がばらばら)を解く道具が Saga です。

なぜ必要か: トランザクションはサービスをまたげない

1 つの DB の中なら、BEGIN から COMMIT までをトランザクションで囲めば、「全部成功するか、全部なかったことにするか」を DB が保証してくれます。途中で失敗すれば ROLLBACK で元に戻ります。

ところが、受注・在庫・請求が別々の API サーバーと別々の DB に分かれていると、この保証は使えません。受注 API の DB のトランザクションは、在庫 API の DB には及ばないからです。

複数の DB をまたいで同じ保証を得る方法として、2 相コミット(2PC) があります。参加するすべての DB に「確定してよいか」を聞いて回り、全員がよいと答えたら一斉に確定する方式です。しかし、HTTP でつながった API 同士では一般に採りにくい方式です。全員の返事がそろうまで、各 DB がロックを持ったまま待つことになるので、1 つのサービスが遅いだけで全体が止まります。

そこで、「全部まとめて巻き戻す」ことをあきらめ、業務的に打ち消すことで整合性を取るのが Saga です。

Saga の仕組み: ローカルトランザクションと補償トランザクション

Saga は、業務をまたぐ 1 つの処理を、次の 2 種類の部品で組み立てます。

ローカルトランザクションを順に実行し、途中で失敗したら、それまでに完了したステップを補償トランザクションで打ち消します。打ち消す順番は基本的に逆順です(依存関係がなければ並列に打ち消してもかまいません)。受注確定の例では、次の表のようになります。

ステップローカルトランザクション失敗したときの補償トランザクション
①受注を仮登録する(受注 API)受注を取り消す
②在庫を引き当てる(在庫 API)引当を解除する
③請求を作成する(請求 API)請求を取り消す
④受注を確定する(受注 API)—

③ で失敗したら、② の引当解除 → ① の受注取消の順に補償します。

受注確定の Saga をオーケストレーション型で表した図。受注の仮登録、在庫の引当、請求の作成、受注の確定を順に実行し、すべて成功すれば状態が succeeded になる。請求の作成がリトライ上限を超えて失敗した場合は、在庫の引当解除、受注の取消という補償処理を逆順に実行し、状態が compensated になる。各ステップは Idempotency-Key 付きで呼ぶためリトライしても二重に引き当てない

補償はロールバックではない

補償トランザクションは、DB のロールバックとは性質が違います。

このため、取り消せない処理(メールの送信、外部への送信など)は Saga の最後のほうに置きます。それより前のステップが全部成功したことを確かめてから、取り返しのつかない操作をするためです。

一時的な不整合と「仮」状態

Saga の途中では、「在庫は引き当てたが、請求はまだ」のような一時的な不整合が見えます。最終的には全部確定するか、全部取り消されて整合するので、これを**結果整合性(Eventual Consistency)**と呼びます。

注意したいのは、Saga には DB のトランザクションのような分離性(Isolation)がないことです。途中の状態はほかの処理からも見えるので、確定前の引当を見て在庫が足りないと判断する、といったことが起こりえます。

そこで、途中の状態をほかの処理が本物と勘違いしないように、「仮」の状態をはっきり持たせます。Saga の対策としては「セマンティックロック(Semantic Lock)」と呼ばれるもので、「この行は処理中」と業務の状態で示します。受注をいきなり「確定」にせず、「仮登録 → 確定」の 2 段階にするのはこのためです。仮登録の受注は、一覧や集計で確定済みと区別でき、補償も「削除」ではなく「取消」という業務的に自然な操作になります。この記事では、さらに仮状態に有効期限を持たせ、司令塔が戻ってこなくても自動で解放される安全網にします(方針 2 で詳しく扱います)。

冪等性: 同じ呼び出しを何度送っても 1 回分

Saga では、呼び出しの再試行が頻繁に起きます。ネットワークが切れて、成功したのか失敗したのか分からないときは、もう一度呼ぶしかありません。補償も、成功するまで再試行します。

このとき、在庫の引当が 2 回効いてしまっては困ります。そこで各ステップを冪等(同じリクエストを何度送っても、効果は 1 回分)にします。具体的には、呼び出しに**冪等キー(Idempotency Key)**という一意な値を付け、サーバーは同じキーの再送に対して、処理をやり直さずに前回の結果を返します。実装は、方針 2 の「業務 API 側の約束事」で示します。

オーケストレーション型とコレオグラフィ型

Saga の実装方式は 2 つあります。

方式仕組み長所短所
オーケストレーション型司令塔(オーケストレーター)が各サービスを順に呼び、失敗したら補償を指示するフローが 1 か所に集まり、「どこまで進んだか」「どこで失敗したか」を 1 か所で確かめられる司令塔をどこかで動かす必要があり、その司令塔が止まると Saga も止まる
コレオグラフィ型各サービスがイベント(「受注を仮登録した」など)を発行し、ほかのサービスがそれに反応して次の処理を進めるサービス同士の結合が緩く、司令塔が要らないフローが各サービスに散らばり、全体の流れや失敗箇所を追いにくい

業務システムで「作法がばらばら」なことが問題になっているなら、オーケストレーション型を標準にするのがおすすめです。業務の流れが 1 つの定義に集まるので、業務担当者にも説明しやすくなります。上の図もオーケストレーション型です。

残る問いは、その司令塔をどこで動かすかです。それが方針 2 の主題です。

方針 2: Saga の司令塔をデスクトップアプリに置く

帳票のためにデスクトップアプリを入れるなら、冒頭の問題 1(業務をまたぐ更新の作法がばらばら)も、同じアプリで解けます。サーバーにオーケストレーターを新しく立てる代わりに、アプリの中の 1 つの Saga ランナーに作法を揃えます。

司令塔をどこに置くか

オーケストレーション型の Saga では、「司令塔をどこで動かすか」が設計の分かれ目になります。

置き場所中断への強さサーバー側に増えるもの向いている場面
ブラウザのタブ弱い。タブを閉じる・リロードすると、進み具合ごと消えるなし向かない
デスクトップアプリ進み具合をローカルに保存すれば、再起動後に続きから再開できるなし利用者の操作をきっかけに始まる業務
サーバー(Step Functions など)最も強い。利用者の PC と無関係に進むオーケストレーターの運用無人で動く処理、外部システムが起点の処理、厳しい締め切りがある処理

ブラウザの SPA が複数の API を順に呼ぶ、次のような実装は危険です。

// ブラウザのタブでこれをやると危ない
async function confirmOrder(input: OrderInput) {
  const order = await ordersApi.create(input);   // ① 成功
  await stockApi.reserve(order.id);              // ② 成功
  await billingApi.createInvoice(order.id);      // ③ ここでタブを閉じられたら?
  await ordersApi.confirm(order.id);
}

② まで終わって ③ の前にタブが閉じられると、在庫だけ引き当てられた受注が残ります。後始末をするはずのコードは、もう動いていません。どこまで進んだかの記録もメモリ上にしかないので、次に開いたときに続きから再開することもできません。

デスクトップアプリなら、この弱点を埋められます。各ステップを呼ぶ前に、進み具合をローカルの DB に書いておくからです。アプリが落ちても、PC が再起動しても、次に起動したときにログを読んで続きから再開するか、補償に回すかを決められます。

クライアントを司令塔にするための 5 つの約束事

ただし、デスクトップアプリでも「PC がそのまま戻ってこない」ことはあります。そこで、クライアントが途中で消えてもデータが壊れないように、サーバー側とクライアント側に次の約束事を置きます。

  1. 進み具合を先に書く(クライアント)。 各ステップを呼ぶ前に「これから ② を呼ぶ」とローカルの Saga ログに書く。終わったら「② 完了」と書く。再起動したらログを読んで再開する
  2. 冪等キーを Saga ID とステップ名から作る(クライアント → サーバー)。 "{sagaId}:reserve-stock" のようにする。再開時に同じステップをもう一度呼んでも、サーバーは前回の結果を返すだけで二重に処理しない
  3. 仮状態に有効期限を持たせる(サーバー)。 仮登録・仮引当には期限を付け、確定されないまま期限が切れたらサーバーが自動で解放する。PC が二度と戻らなくても、時間が経てばデータは元に戻る。これがオーケストレーターなしで成り立つための安全網になる
  4. 補償 API を用意する(サーバー)。 「引当」に対する「引当解除」、「仮登録」に対する「取消」を公開する。補償も冪等にする(2 回取り消しても壊れない)
  5. Saga をサーバーに登録する(クライアント → サーバー)。 開始時に Saga ID・種類・開始者を登録し、ステップが進むたびに状態を更新する。ほかの端末や管理者からも「誰の、どの処理が、どこで止まっているか」が見える

5 の登録先は、その業務の持ち主の業務 API の DB に置きます。受注確定の Saga なら受注 API の DB です。Saga 用のテーブルを足すか、受注レコードに Saga の ID と状態を持たせます。Saga の最初のステップが作る受注の「仮登録」は、もともと「仮 → 確定 / 取消」という状態を持っているので、それ自体が Saga の進み具合になります。3 の期限切れの解放も、同じ受注 API の中で完結します。

Saga 専用の DB や登録サービスを新しく立てる必要はありません。サーバーに常駐するものを増やさない、というこの記事の方針とも一致します。Saga の種類が増えて、管理者が 1 画面で一覧したくなった時点で、小さな専用の登録簿(DynamoDB のテーブルと、それを読み書きする小さな API など)を足せば十分です。業務 API の約束事は変わらないので、後から足しても既存の Saga には影響しません。

3 の「期限切れの解放」は、サーバー側に定期実行の小さな処理を 1 つ置くだけで実現できます。期限切れの行を探して解放するクエリを、スケジューラから 1 日数回起動する程度のものです。常駐するオーケストレーターに比べれば、運用の重さはずっと小さくなります。

デスクトップアプリ側の Saga ランナー

デスクトップアプリ側の Saga ランナーは、たとえば次のように書けます。ローカルの永続化には SQLite などを想定しています(ここでは sagaLog として抽象化しています)。registry は、上の 5 で述べた持ち主の業務 API に Saga の状態を書く呼び出しです。

type Step = {
  name: string;
  run: (sagaId: string, idempotencyKey: string) => Promise<void>;
  compensate?: (sagaId: string, idempotencyKey: string) => Promise<void>;
};

async function runSaga(sagaId: string, steps: Step[]) {
  // 補償の途中で落ちていたら、前へ進まずに補償を続ける
  if ((await sagaLog.status(sagaId)) === "compensating") {
    return compensate(sagaId, steps, await sagaLog.failedIndex(sagaId));
  }

  const done = await sagaLog.completedSteps(sagaId); // 再開時はここから続ける

  for (const [i, step] of steps.entries()) {
    if (done.includes(step.name)) continue;

    await sagaLog.markStarted(sagaId, step.name);    // ① 呼ぶ前に書く
    try {
      await withRetry(() => step.run(sagaId, `${sagaId}:${step.name}`));
      await sagaLog.markDone(sagaId, step.name);     // ② 終わったら書く
      await registry.update(sagaId, { step: step.name, status: "running" });
    } catch (e) {
      // 補償に入ったことを先に書く(補償の途中で落ちても、再起動後に補償へ戻れる)
      await sagaLog.markCompensating(sagaId, i);
      await compensate(sagaId, steps, i);
      throw e;
    }
  }
  await registry.update(sagaId, { status: "succeeded" });
}

// 失敗したステップ自身も含めて逆順に補償する。
// 失敗したステップは「サーバーでは処理済みで、応答だけ失われた」可能性があるため。
// 補償は冪等なので、未処理のステップに対して呼んでも、2 回呼んでも壊れない
async function compensate(sagaId: string, steps: Step[], failedIndex: number) {
  const compensated = await sagaLog.compensatedSteps(sagaId);
  for (const step of steps.slice(0, failedIndex + 1).reverse()) {
    if (compensated.includes(step.name)) continue;
    await withRetry(() => step.compensate?.(sagaId, `${sagaId}:${step.name}:compensate`));
    await sagaLog.markCompensated(sagaId, step.name);
  }
  await registry.update(sagaId, { status: "compensated" });
}

// アプリ起動時: 終わっていない Saga を探して再開する
for (const sagaId of await sagaLog.unfinished()) {
  await runSaga(sagaId, definitions[await sagaLog.typeOf(sagaId)]);
}

この Saga ランナーは画面(WebView)側で書いても動きます。ただし、Tauri のようにネイティブ側(Rust)を持てる基盤なら、画面を閉じても動き続けるネイティブ側に置くほうが堅牢です。

業務 API 側の約束事

クライアントが司令塔でも、サーバーが司令塔でも、業務 API に求められることは同じです。これを「社内 API の標準」として明文化しておくと、新しい業務を追加するときの議論が減ります。

  1. 更新系 API は冪等にする。 Idempotency-Key ヘッダー(IETF で標準化のドラフトが進んでいる)を受け付け、同じキーでの再送には前回と同じ結果を返す
  2. 補償用の API を用意する。 補償も冪等にする
  3. 「仮」の状態と有効期限を持つ。 仮登録 → 確定の 2 段階にすると、補償が「削除」ではなく「取消」という業務的に自然な操作になる。期限切れは自動で解放する
  4. エラー形式を揃える。 RFC 9457(Problem Details for HTTP APIs)の application/problem+json に揃えておくと、クライアントが同じ方法でエラーを解釈できる
  5. 相関 ID を引き回す。 Saga ID や W3C Trace Context の traceparent ヘッダーを全サービスに伝播させ、1 つの操作のログを横断して追えるようにする

冪等キーの実装は、キーとレスポンスを保存するテーブルを 1 つ持つだけで始められます。

# 更新系 API での冪等キーの扱い(擬似コード)
import hashlib

def handle(request):
    key = request.headers.get("Idempotency-Key")
    if key is None:
        return problem(400, "Idempotency-Key is required")

    # 組み込みの hash() はプロセスごとに値が変わるので、SHA-256 で比べる
    body_hash = hashlib.sha256(request.body).hexdigest()

    saved = idempotency_store.get(key)
    if saved:
        if saved.request_hash != body_hash:
            return problem(422, "Idempotency-Key reused with different payload")
        return saved.response  # 前回と同じ結果を返す

    with db.transaction():
        result = do_business_logic(request)
        # キー列にユニーク制約を付けておく。同じキーの同時リクエストが
        # ここで衝突したら、トランザクションを捨てて保存済みの結果を読み直す
        idempotency_store.put(key, body_hash, result)  # 業務の更新と同じトランザクションで保存
    return result

サーバー側に司令塔を置くべき場面

すべての Saga をクライアントに寄せられるわけではありません。次のような処理は、サーバー側(Step Functions など)に司令塔を置くほうが適しています。

AWS なら Step Functions で、リトライ(Retry)と失敗時の分岐(Catch)をステートマシンとして定義できます。業務 API の約束事は同じなので、最初はクライアントで動かし、必要になった Saga だけサーバーへ移すこともできます。

応用: 一括ファイル取り込みも PC で回す

帳票と同じ性質の重い処理に、一括ファイル取り込みがあります。数千行の CSV や Excel をサーバーに送り、サーバーが 1 回のリクエストの中で解析・検証・登録する作りだと、帳票と同じ問題が起きます。

これも、方針 1 と方針 2 を組み合わせて PC に寄せられます。

一括ファイル取り込みを PC で解析し、Saga で送って確定する流れの図。デスクトップアプリはまず PC の CPU で全行を解析・検証し、エラーがあれば送る前に表示して直してもらう。次に業務 API に取り込みのまとまりを、有効期限つきの仮の状態で、ファイルのハッシュを冪等キーにして登録する。続いて 500 行ずつなどのチャンクに分け、冪等キー付きで繰り返し送る。業務 API はチャンクごとにローカルトランザクションで仮保存する。アプリは送り終えたチャンクを Saga ログに記録して進捗バーに表示し、落ちても続きから再開できる。最後に件数と合計を添えて確定を依頼すると、業務 API が突合し、合えば仮から確定へ 1 トランザクションで切り替える。中止やリトライ上限超過のときは、補償としてまとまりごと取り消して仮の行を捨て、PC が戻らない場合も期限切れで自動的に破棄される

  1. 解析と検証は PC で行う(方針 1)。 ファイルを読み、形式・必須項目・コードの存在などを PC の CPU で検証する。エラーは送る前に一覧で見せ、利用者に直してもらう。サーバーとの往復なしに、何度でもやり直せる
  2. 取り込みのまとまりを「仮」で登録する。 取り込み 1 回分を、有効期限つきの仮の状態で登録する。冪等キーにはファイルのハッシュを使うと、同じファイルを送り直しても同じまとまりが返る
  3. チャンクに分けて送る(Saga のステップ)。 500 行ずつなどに分け、冪等キー付きで 1 チャンクずつ送る。サーバーはチャンクごとにローカルトランザクションで仮保存する。送り終えたチャンクは Saga ログに記録するので、アプリが落ちても続きから再開できる
  4. 最後に突合して一括で確定する。 件数と合計を添えて確定を依頼し、サーバーは合っていれば仮の行をまとめて確定に切り替える。確定は、取り込み先の業務 API の中の 1 トランザクションで済む。仮の行の状態を切り替えるだけなので、解析や検証に比べればずっと軽い
  5. 中止や失敗は、まとまりごと取り消す(補償)。 利用者が中止したときや、リトライの上限を超えたときは、仮の行をまとまりごと捨てる。PC が戻ってこなくても、有効期限が切れれば自動で捨てられる

取り込み途中の行は「仮」なので、確定するまでは一覧や集計に混ざりません。「途中まで入ってしまった」という中途半端な状態が、業務から見えなくなります。

async function importFile(file: File) {
  // ① PC の CPU で解析と検証。エラーは送る前に見せる
  const { valid, errors } = await parseAndValidate(file);
  if (errors.length > 0) return showErrors(errors);

  // ② 取り込みのまとまりを仮で登録。ファイルのハッシュを冪等キーにする
  const digest = await crypto.subtle.digest("SHA-256", await file.arrayBuffer());
  const fileHash = toHex(digest);
  const { batchId } = await api.post(`/api/imports`, { name: file.name, count: valid.length }, {
    headers: { "Idempotency-Key": `import:${fileHash}` },
  });

  // ③ チャンクに分けて送る。送信済みは飛ばすので、落ちても続きから再開できる
  const chunks = chunk(valid, 500);
  const sent = new Set(await api.get(`/api/imports/${batchId}/chunks`));
  for (const [i, rows] of chunks.entries()) {
    if (!sent.has(i)) {
      await api.put(`/api/imports/${batchId}/chunks/${i}`, rows, {
        headers: { "Idempotency-Key": `${batchId}:${i}` },
      });
    }
    showProgress(i + 1, chunks.length); // 進捗バーを更新
  }

  // ④ 件数と合計を添えて確定。サーバーが突合し、合えば仮 → 確定
  await api.post(`/api/imports/${batchId}/finalize`, {
    count: valid.length,
    total: sum(valid.map((r) => r.amount)),
  });
}

利用者から見た違いは大きく、ストレスが大きく下がります。

取り込みが複数の業務 API にまたがる場合(たとえば受注と在庫の両方に登録する場合)は、それぞれの API の「仮で送る」「確定する」が Saga のステップになり、取り消しがそれぞれの補償になります。取り込んだ元のファイルを保存しておく必要がある業務なら、正式な帳票と同じく、そのファイルだけをサーバーに預けます。

BFF とは: フロントエンドごとに置く専用のバックエンド

方針 3 に入る前に、BFF(Backend for Frontend)というデザインパターンを整理しておきます。パターン名としては、フロントエンドごとに複数置くことから、複数形の Backends for Frontends とも呼ばれます。

なぜ必要か: 汎用の API を画面から直接使うと苦しくなる

業務 API は、受注・在庫・請求といった業務の単位で作られています。どの画面からでも使える汎用の API です。ところが画面は、業務の単位ではなく、利用者の仕事の単位でできています。「受注の詳細画面」には、受注の中身に加えて、在庫の引当状況と請求の状態も並べたくなります。

この汎用の API を、ブラウザの SPA から直接呼ぶと、次のような困りごとが出てきます。

仕組み: クライアントの種類ごとに専用のバックエンドを置く

BFF は、特定のフロントエンド(クライアントの種類)専用に置く、薄いバックエンドです。Web 用の BFF、モバイル用の BFF のように、クライアントの種類ごとに用意するのが基本です。SoundCloud で Phil Calçado らが使い始めた呼び名で、Sam Newman が 2015 年に記事で整理して紹介し、広く知られるようになりました。

この記事では、BFF が担う役割を次の 4 つに整理します。最初の 2 つと 4 つ目が BFF の本来の役割で、3 つ目はセキュリティの文脈から加わった役割です。

役割中身
集約(API Composition)1 つの画面に必要なデータを、複数の業務 API から並列に取って 1 回で返す
画面用の整形業務 API の汎用の形を、その画面がそのまま使える形に変える。不要な項目は落とす
認証の終端ブラウザとは Cookie のセッションでやり取りし、アクセストークンは BFF が保持する。トークンがブラウザに渡らない
クライアントの違いの吸収Web とモバイルで違う都合を、それぞれの BFF が引き受ける。業務 API は汎用のまま保てる

3 つ目の「認証の終端」は、セキュリティのための BFF として独立して語られることもあります。OAuth のブラウザアプリ向けのベストプラクティス(“OAuth 2.0 for Browser-Based Applications”、2026 年 8 月に RFC 10017 として発行)でも、トークンを BFF に持たせ、ブラウザには Cookie だけを渡す BFF パターンが示されています。

次の図は、BFF を置かない構成、サーバー側に BFF を置く構成、そしてこの記事で採るアプリ内の BFF を比べたものです。

BFF の 3 つの置き方を比べた図。1 つ目の BFF なしの構成では、ブラウザの SPA が JavaScript でトークンを持ち、受注・在庫・請求の業務 API を画面ごとに何本も直接呼ぶため、オリジンごとに CORS が必要になり、画面の都合が汎用 API に入り込み、XSS でトークンを抜かれやすく、往復が多くて画面が遅い。2 つ目のサーバー側の BFF の構成では、ブラウザは HttpOnly の Cookie だけを持ち、BFF がトークンを保持して業務 API の結果を集約・整形して 1 回で返すが、BFF というサーバーの運用が増える。3 つ目のアプリ内の BFF の構成では、デスクトップアプリの中の API クライアントがトークンを OS のキーチェーンに保管して集約と整形を担い、サーバー側に BFF の運用がなく、CORS も関係なく、認可は各業務 API が行う

API Gateway との違い

BFF とよく比べられるのが API Gateway です。どちらも「クライアントと業務 API の間に立つ」点は同じですが、役割が違います。

API GatewayBFF
誰のためにあるかすべてのクライアントに共通特定のクライアント専用
主な仕事ルーティング、認証、流量制限など、横断的な処理集約、画面用の整形、トークンの保持
中身業務やクライアントの都合を知らないその画面の都合を知っている

両方を組み合わせることもよくあります。API Gateway を共通の入口に置き、その後ろにクライアントごとの BFF を並べる構成です。

よくある落とし穴

BFF は便利なぶん、気を抜くと太っていきます。

方針 3: 入口(BFF)もデスクトップアプリに組み込む

ここまで見てきた BFF の役割を、デスクトップアプリに当てはめます。ブラウザの SPA ではサーバー側に BFF を置くのが定石でしたが、デスクトップアプリなら、BFF の役割はどれもアプリのネイティブ側が引き受けられます(上の図の ③)。

BFF の役割デスクトップアプリでの置き場所
トークンを JavaScript から隠すOS の安全な保管場所(macOS のキーチェーンや Windows の資格情報マネージャー)に置き、ネイティブ側だけが使う
複数の API への振り分けネイティブ側の API クライアントが、業務ごとの接続先を知っていればよい
CORS の回避CORS はブラウザが強制する仕組み。ネイティブ側の HTTP クライアントはブラウザではないので、そもそも関係ない
読み取りの集約アプリの中で複数の API を並列に呼び、画面用にまとめればよい

つまり、アプリの中に BFF を持つ形になります。サーバー側から BFF というサービスが 1 つ消え、その分の運用もなくなります。

ただし、次の 3 つはアプリに移せません。

どの経路でも、クライアントが持つのは利用者自身のトークンだけにし、サービス用の鍵は配らないことが前提です。

ブラウザの画面が残る場合

デスクトップアプリを主役にしても、ブラウザから使う画面が残ることはあります。その画面のためだけに、サーバー側の入口を用意します。

方針 4: AI エージェントにはツールを渡し、鍵は渡さない

方針 3 で、トークンをアプリの中に閉じ込めました。この形は、AI エージェントに業務を手伝わせるときにも効いてきます。ここでは、API のアクセストークンなどのクレデンシャルをまとめて「鍵」と呼びます。利用者の PC では、Claude Desktop のような AI エージェントがすでに使えるようになっています。そのエージェントに「先月分の未入金を洗い出して督促状を作って」と頼めば、複数の API を組み合わせる面倒な処理を代わりにこなしてくれます。画面を何枚も渡り歩く必要がなくなります。

鍵はアプリの中に閉じ込める

エージェントに API を直接呼ばせようとすると、エージェントにアクセストークンを渡すことになります。トークンが設定ファイルや会話の履歴、ログに残ります。外から取り込んだデータに紛れ込んだ指示(プロンプトインジェクション)で、トークンを外に送らされるおそれもあります。

そこで、アプリが MCP サーバーになり、業務の操作をツールとして公開します。エージェントはツールを呼ぶだけです。API を実際に呼ぶのはアプリの API クライアント(方針 3 のアプリ内 BFF)で、トークンを付けるのもアプリです。エージェントに返るのは結果のデータだけで、トークンは一度もエージェントの手に渡りません。

AI エージェントがデスクトップアプリのツールを呼び出す流れのシーケンス図。利用者が先月分の未入金を洗い出して督促状を作るよう AI エージェントに指示すると、エージェントはアプリの MCP サーバーの参照ツールを呼ぶ。アプリの API クライアントが利用者のトークンで業務 API を呼び、エージェントにはトークンを含まないデータだけを返す。次にエージェントが更新ツールを呼ぶと、アプリは対象の一覧と件数を確認画面に表示し、利用者がアプリの画面で承認してから、Saga ランナーや帳票レンダラが冪等キー付きで業務 API を呼ぶ。業務 API は利用者の権限で認可を検査し、エージェント経由であることを監査ログに記録する。トークンがあるのは API クライアントと業務 API の側だけで、鍵の境界の外にいるエージェントは鍵を持たない

ツールの設計で守ること

ツールの切り方と、更新の扱いで安全性が決まります。

  1. ツールは業務の単位で切る。 list_unpaid(month)(未入金の一覧)、issue_reminders(ids)(督促状の発行)のように、業務の言葉でツールを作る。call_api(method, url, body) のような汎用のツールは作らない
    • 汎用のツールを渡すと、エージェントに利用者のすべての権限を丸ごと渡すのと同じになるため
  2. 参照と更新を分け、更新はアプリの画面で利用者に確認させる。 更新系のツールが呼ばれたら、アプリが対象の一覧と件数を確認画面に出し、利用者が承認してから実行する。承認はエージェントとの会話ではなく、アプリの画面で行う。エージェントが自分で「承認しました」と言えないようにするため
  3. 更新は Saga ランナーや帳票レンダラを通す。 エージェントの操作も、画面からの操作と同じ道を通す。冪等キー・補償・突合の保証がそのまま効き、エージェントが同じツールを何度呼び直しても二重に処理されない
  4. エージェント経由であることを記録する。 API を呼ぶとき、エージェント経由であることを示す印(独自のヘッダーなど)を付け、監査ログで画面からの操作と区別できるようにする
  5. 認可はサーバーで行う。 エージェントは利用者の権限の範囲でしか動けない。アプリ側でツールを絞っても、最終的な権限の判断は業務 API が行う
  6. API が返すデータを指示として扱わない。 取引先名や備考欄に、エージェントへの指示に見える文が入っているかもしれない。更新の前にアプリの画面で利用者が確認する仕組みが、ここでも防波堤になる

ローカルの MCP サーバーを守る

MCP では、エージェントとサーバーの間の通信方式(トランスポート)として、標準入出力(stdio)と HTTP(Streamable HTTP)が定められています。クレデンシャルを持つのは常駐しているアプリなので、つなぎ方は 2 通りです。

HTTP で待ち受けるなら、MCP の仕様のセキュリティ上の注意に従います。仕様は Origin ヘッダーの検証を必須とし、localhost での待ち受けと認証を推奨しています。

stdio の中継を使う場合も、中継と常駐アプリの間のプロセス間通信に同じ配慮が要ります。ソケットやパイプを、利用者本人しか開けない権限で作っておきます。

確認用の帳票そのものが減る

エージェントの補助が入ると、帳票の出し方も変わります。今は、確認用の帳票をダウンロードして目で確かめている業務がたくさんあります。たとえば「先月の未入金のうち、30 日を超えているものはあるか」を調べるために、残高一覧を出して眺める、といった使い方です。

こうした確認は、エージェントに聞けば済むようになります。エージェントは参照系のツールでデータを取り、条件に合うものだけを答えます。帳票を出して人が探す手間が省けるうえ、帳票を出す回数そのものが減ります。

帳票の速さが出発点だったこの記事にとって、これは大きな意味を持ちます。

応用: ソースを読ませて、ヘルプとマニュアルの代わりにする

エージェントにソースコードを読ませると、画面のヘルプや操作マニュアルを別に維持する必要がなくなります。「この画面の『請求残高』はどう計算されている?」「督促の対象になる条件は?」と聞けば、エージェントがソースを読んで答えます。マニュアルは書いた時点から古くなっていきますが、ソースは常に今の動きそのものです。

ただし、次の 4 つは押さえておきます。

  1. 動いている版のソースを読ませる。 利用者が使っているアプリと API の版に対応するソース(リリースのタグなど)を読ませる。開発中のブランチを読ませると、まだ出ていない機能を説明してしまう
  2. ここでも鍵を渡さない。 エージェントに git のクレデンシャルを持たせると、方針 4 の原則が崩れる。アプリの MCP サーバーが、その版のソースの読み取り専用のスナップショットを検索ツール(search_source、read_source など)として公開すれば、エージェントは鍵を持たずにソースを読める
  3. 秘密をソースに置かない。 読ませる範囲(画面、API、設計文書)にパスワードや鍵、社外秘の設定が入っていないことを確かめる。読ませるディレクトリを絞るのも有効
  4. 「なぜ」はソースの隣に書く。 ソースが教えてくれるのは「どう動くか」までで、「なぜその業務ルールなのか」は書かれていないことが多い。設計判断の記録(ADR)や業務ルールの説明はリポジトリの中に置き、ソースと一緒に読ませる。答えには根拠のファイルを示させると、利用者が確かめられる

手順書が要らなくなるわけではありません。「何をどこに書いておけばエージェントが答えられるか」が変わる、と捉えるのがよいでしょう。マニュアルを別に書いて維持する代わりに、ソースと設計文書をエージェントが読める形に保つことが、ヘルプの保守になります。

アプリの更新と配布をどう考えるか

デスクトップアプリにすると、Web の SPA のように「サーバーに置けば全員が最新になる」わけではなくなります。そこで、変更のたびにアプリを配り直さずに済む部分を増やし、配り直しが必要な部分は自動更新と互換性のルールで管理する、と考えます。

変わりやすいものをアプリの外に出す

どこまでをアプリのバイナリに入れるかで、配布の頻度が決まります。

部分置き場所変えたときに再配布が要るか
帳票のテンプレートサーバーから配信(方針 1)要らない
接続先・機能フラグ・最低バージョンサーバーの設定 API から起動時に読む要らない
業務ルール・認可業務 API要らない
画面(React)アプリに同梱する(推奨)か、サーバーから読み込むか同梱なら要る
ネイティブ側(Saga ランナー、帳票レンダラ、API クライアント、MCP サーバー)アプリのバイナリ要る

画面をサーバーから読み込めば、Web と同じ手軽さで更新できます。ただしその場合、外から読み込んだ画面に、トークンを使う API クライアントなどネイティブ側の機能を呼ばせることになります。Tauri ではリモートの画面に許す権限を設定で絞れますが、「鍵をアプリに閉じ込める」という前提は弱くなります。基本は画面も同梱し、自動更新で配るほうが安全です。

配り直しは自動更新にする

アプリと API の版のずれを管理する

全員が同時に更新するとは限らないので、古い版のアプリが残る前提で考えます。

  1. API は後方互換を基本にする。 項目の追加はしても、削除や意味の変更はしない。互換を壊す変更は、新しいエンドポイントを作って並べる
  2. 最低バージョンを決めて強制する。 アプリはリクエストごとに自分の版をヘッダーで送る。サーバーは最低バージョンより古ければ、更新を求めるエラー(application/problem+json の type で種類を表す)を返す。アプリは起動時にも設定 API から最低バージョンを読み、古ければ更新を促す
  3. 途中の Saga を壊さない。 更新の直前に、途中の Saga が残っていることがある。Saga の定義には版を付け、開始したときの版のまま最後まで進める(進行中の Saga のステップの意味を書き換えない)。ローカルの Saga ログの形を変えるときは、移行処理をアプリに入れる
  4. エージェント向けのツールとソースも版に揃える。 MCP で公開するツールの定義も、エージェントに読ませるソースのスナップショットも、アプリの版と一緒に変わる。方針 4 のとおり「動いている版」に揃える

段階的に出す

利用者が社内の数十〜数百人程度の業務システムなら、MDM と自動更新、それに最低バージョンの強制で十分に回ります。

段階的な移行の進め方

すべてを一度に作り替える必要はありません。利用者を待たせている帳票から順に進めるのがおすすめです。

  1. 今の遅さを分解して測る: キューでの待ち時間、タスクの起動時間、帳票の生成時間、生成中のメモリのピークを分けて集計する
  2. サーバー側の応急処置を入れる: 帳票専用のキューに分け、同時実行数を 1 件あたりのメモリから逆算して絞る。メモリ不足で落ちるのを止める
  3. デスクトップアプリを用意する: 既存の React の画面をデスクトップアプリの WebView に載せ、API の呼び出しとトークンの保管をネイティブ側の API クライアントに移す。コード署名、自動更新、最低バージョンの強制は、最初の配布の前に揃えておく
  4. 帳票をクライアント生成に移す: まずは保存の要らない確認用の帳票から移す。テンプレートの配信だけで始められ、出す回数が多いので効果も大きい。正式な帳票は、件数と合計の突合と監査ログを揃えてから移す
  5. 業務 API の約束事を入れる: 冪等キー、補償 API、有効期限つきの仮状態、application/problem+json を順次入れる。司令塔をどこに置く場合でも必要になる
  6. Saga を 1 つデスクトップアプリに移す: Saga ログと再開の仕組みを作り、最も事故が多い業務フローから移す。期限切れを解放する定期処理も同時に入れる。待ち時間への不満が大きい一括ファイル取り込みは、最初の題材に向いている
  7. サーバーを縮める: 帳票用のワーカーと帳票ごとのタスク起動を外し、業務 API のタスクサイズを下げる。ブラウザの画面がなくなれば、BFF も外せる
  8. AI エージェント向けのツールを公開する: まず参照系のツールと、動いている版のソースを検索するツールから始める。更新系のツールは、確認画面と監査の印を揃えてから足す

最後まで残った無人バッチや外部システム起点の処理だけを、SQS + ワーカーや Step Functions で扱います。

まとめ

分散したサービスの前に立つクライアントの設計で大事なのは、サーバーとクライアントのどちらが何を担うかを、速さ(重い処理をどこで走らせるか)と中断への強さで決めることです。ブラウザのタブは中断に弱いので、調整を任せられません。一方、状態を保存できるデスクトップアプリなら、サーバーが「壊れない約束事」を守っている限り、計算と調整を任せられます。帳票を速く出しつつ、サーバーも小さく保てます。さらに、鍵をアプリの中に閉じ込めておけば、AI エージェントにも安全に業務を任せられます。



前の記事
データ照会チャットボットはデータ分析基盤を作ってから?ツール呼び出し・Text-to-SQL・セマンティックレイヤーの関係と進め方
次の記事
Text-to-SQL vs ツール呼び出し — 権限管理のある業務システムに AI データ照会を組み込む