画面は情報設計の代弁者ではない — 共有バックエンドを画面ではなくドメインの語彙で切り直した話

境界の内側: トランザクションは usecase の外で張る

更新 API を行為ごとに分けると、「どこで原子性を保証するか」を決め直す必要が出る。丸ごと保存のときは 1 リクエストが 1 トランザクションで、それ以上考えることがなかった。分けた後は、1 つの行為の中と、行為をまたぐ間の二つを別々に扱う。

まず前提を一つ置く。

集約境界 ≠ トランザクション境界

集約境界はドメインモデル上の不変条件の境界で、トランザクション境界は永続化の原子性の境界。両者は一致しなくてよい。別集約でも「登録時には原子的に作られる」という業務要件があれば両者をまたぐトランザクションを張るし、同じ集約でも行為ごとにトランザクションを分ける。

境界を張るのは usecase ではない

usecase は tx を引数で受け取らない。境界を張るのは、権能（capabilities）を組み立てる側だ。

エントリポイント
  → withArtistWriteCapabilitiesById(deps, subId, artistId, work)
      → Actor を解決（誰として書くか）
      → runInTransaction(db, buildCaps, work)
          → トランザクション内の executor をリポジトリにバインドして権能を作る
          → usecase に権能を渡して実行

usecase から見えるのは「渡された権能で読む・書く」だけで、トランザクション内で動いているかどうかは知らない。知らなくてよい。

save(data, tx) のように tx を引数で渡す方式をやめたのは、渡し忘れが静かに通るからだ。tx を書き忘れてもコンパイルは通り、テストも通り、本番で「トランザクション外の書き込み」だけが残る。executor を権能の生成時にバインドしてしまえば、渡し忘れという操作自体が存在しない。

業務エラーでロールバックする

usecase は失敗を例外ではなく Result の err で返す。しかし Drizzle のトランザクションは throw でしかロールバックしない。両立させるために、境界を張る側で err を内部シグナルに載せて throw し、境界の外で Result に戻す。

class RollbackSignal<T, E> extends Error {
  constructor(readonly result: Result<T, E>) { super("rollback"); }
}

export const runInTransaction = async (db, buildCaps, work) => {
  try {
    return await db.transaction(async (tx) => {
      const result = await work(buildCaps(tx));
      if (!result.ok) throw new RollbackSignal(result);
      return result;
    });
  } catch (error) {
    if (error instanceof RollbackSignal) return error.result;
    throw error;
  }
};

usecase 側に try/catch は置かない。「業務エラーは err」という契約を usecase から見て崩さないまま、永続化の原子性を境界側で担保する。

行為の中は原子的、行為の間は原子的でない

この構造で、構造ごとの更新 API は次の性質を持つ。

後者を原子的にしないのは、それをすると「編集画面の保存」という画面の語彙をトランザクション境界にすることになり、api-server が再び画面の形を知ってしまうからだ。下書きの部分的な状態は情報設計上も許容される（不変条件を弾くのは publish のときだけ）ので、行為の間の原子性はドメインが要求していない。

例外は画像で、ストレージへの PUT は外部 I/O なのでトランザクションに入れない。ArtistStorageWriteCapabilities は境界を持たない権能として分け、「アップロード → URL を集約へ書く」の 2 つの usecase を順に呼ぶ。ストレージ書き込みと DB 更新の原子性は求めない。

現時点の前提と、その前提が崩れる契機

構造ごとの更新 API の実装は、集約全体を読み、振る舞いで一部を差し替え、集約全体を upsert する形にしている。並行更新は Last Write Wins。

これが成り立つのは「ArtistProfile を書くのは本人だけ」という現時点の前提があるからだ。同一ユーザーの単発操作で、しかも BFF が直列に送るので、構造同士が競合することはない。

前提が崩れるのは、運営ツールや別プロダクトが本人と並行して特定の構造だけを書き始めたときで、そのときは集約丸ごとの upsert が相手の構造を古いスナップショットで上書きする。API の表面は構造ごとに分かれているが、永続化はまだ分かれていない。契機が来たら、リポジトリの Writer を構造ごとに分ける（属性は profile 行の属性列だけ、リンクは links テーブルだけ）か、集約に version を持たせて楽観的ロックにする。「必要になってから」ではなく、この契機を並行更新ポリシーのドキュメントに書いておく。

境界の外側: BFF は「どこまで保存できたか」を型で返す

行為をまたぐ原子性を持たないと決めた以上、途中で失敗したときに何が起きたかを画面に伝える責務が BFF に残る。「保存に失敗しました」だけでは、属性は保存されたのか、Story はどうなのかが分からない。

直列に呼び、失敗したら止める

saveMyProfile は attributes → story/chapters（章ごと）→ links を順に呼ぶ。1 つ失敗したら後続は送らない。

const steps = createSaveSteps();

await steps.run("attributes", () => artist.attributes.$post({ ... }));
for (const chapter of body.chapters) {
  await steps.run(chapterStep(chapter.questionCode), () =>
    artist.story.chapters[":chapterKey"].$post({ ... }));
}
await steps.run("links", () => artist.links.$post({ ... }));

steps.run は成功したステップを saved[] に積み、失敗したら PartialSaveFailedError を投げる。

type PartialSaveFailedError = Error & {
  type: "PartialSaveFailedError";
  saved: readonly SaveStep[];   // 保存済みのステップ
  failedAt: SaveStep;           // 失敗したステップ
  upstream: UpstreamFailure;    // api-server が返した失敗そのもの
};

直列にしたのは、これらが互いに依存するからではない（属性とリンクは独立に書ける）。saved[] が「ここまでは確定している」という単純な意味を持てるようにするためだ。並列にすると「属性は成功、Story は失敗、リンクは不明」のような状態を表現する必要が出る。

エラーの翻訳は errorMap が持つ

BFF のルートはステータスコードを決めない。エラーを型で投げ、errorMap がステータス・レスポンスボディ・ログレベルに翻訳する。

PartialSaveFailedError は自分でステータスを持たない。包んでいる upstream の翻訳をそのまま使い、ボディに saved と failedAt を添えるだけだ。「途中で失敗した」ことと「なぜ失敗したか」を混ぜない。

画面は構造の語彙で伝える

fetcher はボディから saved / failedAt を progress として復元し、画面は章ごとのステップを「Story」という区画に畳んで文言にする。

基本・Story は保存済みです。リンクの保存に失敗しました。もう一度保存すると全体が反映されます。

各更新は置換型で冪等なので、同じ入力で再送すれば保存済みのステップは同じ結果に上書きされ、失敗したステップだけが新たに反映される。全体が収束する。

「どこまで保存できたか」は api-server の語彙（attributes / chapter:beginning / links）で BFF に届き、画面の語彙（基本 / Story / リンク）に翻訳されて表示される。ここでも境界の対応づけを持つのは BFF だ。

残っている課題

• 失敗の種別で文言を分けていない。 api-server が入力を拒否した（4xx）場合も、一時的な障害（5xx）の場合も、「もう一度保存すると」と出る。前者は入力を直さないと再送しても同じ結果になる。upstream の種別は BFF まで届いているので、分けられる状態にはある。
• BFF に届く前の失敗は progress を持たない。 BFF が途中まで送った後にレスポンスだけ失われた場合、画面には部分保存の事実が出ない。冪等なので再送で収束するが、その案内はまだない。
• 公開状態の変化が更新応答に現れない。 公開中のプロフィールが更新で公開条件を割ると enforcePublishInvariant が非公開へ降ろすが、更新 API は更新した構造だけを返すので、画面は published が変わったことを知らない。更新応答に含めるか、saveMyProfile の終了後に取得 API を一度引くか、どちらかが要る。