app-renderer-systems

機能システム

systems/<domain>/ モジュールは、そのドメインの UI 向けアダプター、データアクセス、フック、コンポーネント、および公開バレルを管理します。既存のシステムを拡張し、機能に実際に必要なレイヤーのみを作成してください。ローカルコンポーネントの編集を理由に、CRUD アダプター、ストア、コンテキストプロバイダー、またはすべてのレイヤーに対するテストをひな型から作成する必要はありません。

配置場所や新しいシステムについては references/directory-layout.md を、変更する API／クエリ／フックのパターンについては references/patterns.md を参照してください。関連するスキルは必要に応じて使用します。コンポーネントやフックの動作には React、Query／Router／Form には TanStack、ストア API には XState Store、テスト編集には既存のテストランナーのガイダンスを使用してください。デバッグガイダンスは、システムの編集すべてに適用するのではなく、未解決の障害に対して使用してください。

• 依存関係の方向は下位レイヤーに向けます。コンポーネントはフックを使用し、フックはクエリ／オプションとアダプターを使用します。アダプターから UI をインポートしてはいけません。システムをまたぐ利用側は公開バレルを使用します。
• アダプターとクエリーキャッシュでは API エンベロープを保持し、読み取り境界でコンポーネント用のビューモデルにフラット化します。公開契約から型を導出し、信頼できない入力はそれを所有する境界で検証してください。
• ローダー、フック、ミューテーション、ストリームライター全体で、正規のクエリオプション／キーを再利用します。安定したスコープとフィルターを含めてください。無限クエリでは、継続カーソルを pageParam に格納します。
• アダプターには AbortSignal を渡し、プロジェクトの型付きエラー契約に従ってエラーを表現してください。リクエスト境界でスコープの欠落をガードします。enabled だけでは、非 null 断言を正当化する型の証明にはなりません。
• 既存の鮮度に関するデフォルトに従ってください。正規キーを使ってミューテーションを整合させます。所有する読み取りモデルでサーバーからの再読み込みが必要な場合に限り、無効化してください。楽観的更新のコールバックは、楽観的更新の契約がある場合にのみ追加します。その際は、競合する読み取りをキャンセルし、状態全体のスナップショットを取り、失敗時には復元してください。
• コンテキストは、サブツリー全体で共有する必要がある状態にのみ追加します。必須プロバイダーを前提とする null 許容パターンが適するコンテキストもあります。プロバイダーは、所有関係や更新頻度の必要性が実証されている場合にのみ分割してください。
• サーバー状態は Query で管理します。イベント駆動型のローカルデータには XState Store を使用します。明示的なライフサイクルモードやガードには、代わりにステートマシンが必要な場合があります。システムに非同期呼び出しがあるというだけでストアを導入してはいけません。
• サポート対象の操作は、バレルから明示的にエクスポートします。ディレクトリ構造をテストでそのまま再現するのではなく、変更した各不変条件を担当する既存のテストスイートを再利用してください。