楽観的更新：ユーザー行動仕様

UIが暫定状態を適用し、サーバーの真実と調整し、競合や失敗時にロールバックし、永続的な証拠を表示してユーザーが古い楽観的データを黙って信用しないようにする方法を指定します。

パッケージステータス: AI支援リファレンスパッケージ。静的パッケージ検証は合格済み。実装シナリオは未実行であり、安定採用前に人間によるドメインレビューが必要です。

決定事項

レスポンシブなミューテーションには楽観的UI更新を適用しつつ、サーバーの応答を権威あるものとして扱います。すべての楽観的変更はクライアントミューテーションIDを持ち、復元可能なスナップショットを保持し、成功、ロールバック、競合、不確定なタイムアウト状態に明示的なユーザーフィードバックと共に調整されます。

範囲

• 暫定適用ルール、保留インジケーター、スナップショット保存。
• 成功、失敗、競合、タイムアウト時の調整。
• サーバーの冪等性と整合したクライアントミューテーション識別子を用いた冪等リトライ。
• 適用、成功、ロールバック、競合率のテレメトリ。

範囲外

• オフラインキューの永続化（オフラインミューテーションキューブロック参照）。
• サーバーサイドの楽観的ロックスキーマ（楽観的ロックブロック参照）。
• 一般的なフォーム検証UX。

契約

• 楽観的適用はクライアント契約で明示的に楽観的とマークされたミューテーションにのみ発生し、読み取りパスは決して楽観的に捏造されません。
• 各ミューテーションは安定したクライアントミューテーションIDを生成し、終端調整までのすべてのリトライで送信されます。
• UIは適用前にロールバックスナップショットを保存し、調整失敗時にスナップショットのフィールドを正確に復元します。
• サーバー競合（プロファイル選択：HTTP 409）は競合UXパスをトリガーし、同時のローカル編集を黙って上書きしません。
• プロファイルのタイムアウトを超える調整は不確定状態に入り、無期限保留ではなくIDによるフェッチやポーリングで解決します。
• 成功した調整は保留状態をクリアし、表示中のフィールドをエンティティバージョンメタデータを含むサーバー値で置き換えます。

実装ガイダンス

• 楽観的ミューテーションミドルウェアを集中化し、すべての機能で調整セマンティクスを共有します。
• サーバーが対応する場合、クライアントミューテーションIDをAPIの冪等キーと整合させます。
• ポリシーが要求しない限り、ビュー全体をブロックするのではなく微妙な保留表示を使用します。
• 操作レビューのために example.yaml に記載されたテレメトリイベントを発行します。

障害処理と安全策

• 重複した成功応答はUI状態マシンで副作用を二重適用してはなりません。
• 未解決の暫定IDに依存する楽観的ミューテーションを連鎖させず、依存ミューテーションは前任の調整完了を待つか安定したサーバーIDを参照します。
• 競合時は編集損失を防ぐために盲目的なリトライよりサーバー差分表示を優先します。

検証と運用

• ミューテーションタイプごとにロールバック率、競合率、不確定タイムアウト率を監視します。
• 自動テストは成功、失敗、競合、タイムアウト、冪等リトライパスをカバーします。
• ロールバック率が高いミューテーションはサーバーや検証の問題をレビューします。

このパッケージの実行例はフィクスチャおよび受け入れ契約です。採用前にパッケージ構造を検証し、対象リポジトリでシナリオを実装・実行してください。

採用前提

• example.yaml のタイムアウト、ステータスコード、ヘッダー名はタスクボードSPA向けのプロファイル選択であり、普遍的なデフォルトではありません。
• チームはエンティティバージョンフィールドを自分たちのAPIスキーマにマッピングする必要があります。

参考文献

• 外部の規範的なソースは不要です。採用時はAPI冪等性ブロックと冪等動作を整合させてください。