バックエンド主権ランタイムリファクタリング は何をしますか？
実行時真実がどこに存在し、UIがそれをどのように読み取るかを正確に説明できるようになった後にのみリファクタリングを行うこと。
使用すべき場合
- UIが、バックエンドが認識しないグラフ、フェーズ、またはプロバイダ選択を合成している。
- 再起動や再接続によって、フロントエンドが権限をキャッシュしていたために可視ランタイム状態が変化する。
- アクティブなオーサリングパスに、新旧のスキーマ、スターター形式、またはノードタイプが共存している。
- 承認、レビュー、または下流の実行がフロントエンドのみの再構築に依存している。
使用すべきでない場合
- ランタイムの所有権に変更がない、見た目だけの視覚的クリーンアップ。
- バックエンドの契約がすでに権威的である、独立したコンポーネントのリファクタリング。
- 分割権限の継ぎ目を削除する前に、新しいビジネス機能を出荷すること。
- アーキテクチャにすでに単一の真実源がある場合の、純粋なバックエンドパフォーマンス改善作業。
判断ポイント
flowchart TD
A[ワークフローリファクタリング依頼] --> B{UIがまだランタイム真実を発明できるか?}
B -->|いいえ| C[より狭いドメインまたはUIスキルを使用]
B -->|はい| D[コマンド、クエリ、イベントの継ぎ目を棚卸し]
D --> E{すべてのユーザーアクションをコマンド、クエリ、またはイベントにマッピングできるか?}
E -->|いいえ| F[機能作業の前に契約を凍結]
E -->|はい| G[投影状態をバックエンド所有状態から分割]
G --> H{レガシー互換パスがまだアクティブか?}
H -->|はい| I[マイグレーションエッジに移動するか削除]
H -->|いいえ| J[評価機構、リプレイセーフな起動クエリ、イベントサブスクリプションを追加]
I --> J
J --> K[再接続、承認、下流の準備状態を検証]
まずこのルーティングモデルを使用すること：
- UIを「コマンド -> バックエンド遷移 -> クエリまたはイベント投影」として記述できない場合、継ぎ目は依然として間違っている。
- 「一時的な互換性」パスがホットパスにある場合、それを機能ではなくリファクタリング債務として扱うこと。
- 再起動や再接続がバックエンドの真実のみから可視状態を再構築できない場合、リファクタリングは不完全である。
作業方法
1. 分割された判断基盤を棚卸し
UIが以下のことを行っているすべての場所を見つける：
- 実行時真実を生成または変更している
- バックエンドが認識していないフェーズを発明している
- アクティブなコードパスで実行をシミュレートしている
- 同じオーサリングパスに新旧両方のスキーマを保持している
- 抽象的なルーティング階層と正確なプロバイダIDを混在させている
2. 契約を凍結
次の3クラスのみを定義する：
- コマンド：開始、停止、承認、再開、変更
- クエリ：起動状態、レビューペイロード、実行スナップショット、プロバイダヘルス
- イベント：権威的な遷移、評価機構の判定、ゲートステータス、リプレイマーカー
UIアクションがこれらのいずれかとして表現できない場合、アーキテクチャは依然として曖昧である。
3. 状態所有権を正規化
ストアを次のように分割する：
- 契約入力状態
- バックエンドスナップショット投影状態
- UIレイアウト状態
どのストアもランタイム真実とレイアウト懸念の両方を所有させてはならない。
4. アクティブな互換性の継ぎ目を削除
「とりあえず両方サポート」よりも削除を優先する。
典型的な削除対象：
- アクティブなオーサリングでの単数形と複数形のスキーマ互換性
- アクティブなデスクトップランタイムでのブラウザまたはデモシミュレーション
- メインパスでの非推奨ノードタイプ
- 重複したレビューサマリー
- 複数のスターターまたはインポート形式
5. リファクタリングを信頼する前に評価機構を追加
すべての実装ノードには以下が必要である：
- 正しさのためのローカル出力評価機構
- 契約安全性のための下流準備状態評価機構
- フロントエンドの推測ではなくバックエンドの真実から再水和する再起動または再接続パス
障害モード
権威を装う投影
症状：UIは「読み取り専用」に見えるが、フェーズ、グラフ、またはプロバイダの真実をローカルで静かに組み立てている。
修正：そのロジックをバックエンドのコマンドまたはクエリに移動し、フロントエンドをプロジェクターとして扱う。
互換性の継ぎ目の硬化
症状：「とりあえず両方サポート」が何週間もホットパスに残り、実際のアーキテクチャになる。
修正：互換性を明示的な削除日付付きの一方向マイグレーションエッジにプッシュするか、今すぐ削除する。
検査不可能な承認
症状：レビューペイロードが部分的またはフロントエンド合成であるため、人間が検査できない作業を承認できる。
修正：バックエンドが正確なレビューペイロードを出力しなければならず、UIはそれをレンダリングするだけにする。
リプレイに敵対的な起動
症状：フロントエンドが権限をキャッシュしていたため、アプリの再起動で可視状態が変化したり、ゲート位置が失われる。
修正：起動はバックエンドの真実に対するクエリとイベントリプレイでなければならず、ストアの再構築であってはならない。
シグナル
新しいバックエンドイベントなしにアプリの再起動で可視ランタイム状態が変化する場合、権限は依然として分割されている。
実例
フロントエンド所有のフェーズロジックを持つTauriワークフローエディタ
問題：
- Reactストアがグラフをオーサリングし、フェーズ状態を推論し、プロバイダ階層を正規化していた。
- バックエンド実行は異なる契約を使用していたため、レビューと再起動フローがずれていた。
リファクタリングパス：
- UIが実行時真実を発明していたすべての場所を棚卸し。
- ランタイムインタラクションをコマンド、クエリ、イベントに統合。
- プロバイダの正規化とフェーズ遷移をバックエンドコマンドの背後に移動。
- アクティブなオーサリングパスからスターター形式のユニオンを削除。
- 下流の作業がバックエンド検証済み出力からのみ進行するように、評価機構ゲートを追加。
成功条件：
- 再起動時に、UIはバックエンドスナップショットとイベントから同じ可視状態を再構築する。
- 承認画面は、Reactの再構成ではなく、バックエンドが出力したレビューペイロードをレンダリングする。
フォークガイダンス
作業がきれいに分離する場合にフォークする：
- 契約レーン：分割権限の継ぎ目を棚卸し、コマンド、クエリ、イベントを定義。
- 削除レーン：互換性レイヤー、非推奨ノードタイプ、スターター形式のユニオンを削除。
- 検証レーン：評価機構ゲート、リプレイテスト、再起動または再接続カバレッジを追加。
最終的な所有権の決定は親レーンに残し、1つのアクターがバックエンドが真に所有するものを決定するようにする。
品質ゲート
- UIがグラフ、フェーズ、プロバイダ、またはゲートの真実をローカルで捏造できない。
- すべてのユーザーアクションがコマンド、クエリ、またはイベントにマッピングされる。
- ランタイム状態が、バックエンドの真実のみからの再起動と再接続に耐える。
- レビューと承認のペイロードはバックエンドによって出力され、UIによってレンダリングされる。
- 互換性ロジックはアクティブパスではなく、マイグレーションエッジにのみ存在する。
- 下流の実行は上流の契約失敗時に停止する。
- 正確なプロバイダIDとモデル選択が契約境界で可視である。
- テストが再起動、再接続、承認、評価機構障害パスをカバーする。
リファレンスマップ
references/architecture-patterns.md— バックエンド所有のワークフロー契約パターンと状態所有権の分割。references/windags-lessons.md— 実際の分割権限ランタイムマイグレーションからの具体的な教訓。