Webアプリケーションアーキテクチャ
最初に web-craft を読んでください。タスクに必要な参照のみをロードしてください。キットとフレームワークのアダプターは、選択したキットとフレームワークのものだけをロードします。
マップ
| トピック | 参照先 |
|---|---|
| サーバーコンポーネント vs クライアントコンポーネント、BFF、環境変数とシークレットの境界 | references/server-client.md |
| APIレイヤー、エラーモデル、状態の所有権、フォーム、楽観的UI、URL状態 | references/data-forms.md |
| ローディング、エラー、not-found境界、リトライ、オフライン、スケルトンのタイミング | references/states.md |
| i18n: レジストリ、解決、URL、カタログ、フォーマット、バックエンドヘッダー | references/i18n.md |
| RTL、論理プロパティ、方向性アイコン、ポータル | references/rtl.md |
| 認証、認可、XSS、CSRF、クッキー、キャッシュの分離、個人データ | references/auth-security.md |
| テーマ: ユーザー設定 vs 適用テーマ、システム変更、フラッシュ防止 | references/theming.md |
| 公開ページのSEO | references/seo.md |
| GEO: AI検索・アシスタントでの可視性 | references/geo.md |
| Next.js App Router アダプター | references/fw-next.md |
| React + Vite アダプター | references/fw-vite.md |
| shadcn/ui アダプター | references/kit-shadcn.md |
| Ant Design アダプター | references/kit-antd.md |
| Material UI アダプター | references/kit-mui.md |
| node-craft（または任意のOpenAPI）バックエンドとの連携 | references/node-craft-contract.md |
| 公式ソースとレビュー日 | references/sources.md |
すべてに適用されるルール
- 必要性に基づく境界。 コンポーネントは、インタラクティブ性、ブラウザAPI、またはクライアント状態を必要とするからクライアントコンポーネントになるのであって、デフォルトでそうなるわけではありません。インタラクティブなアイランドは小さく保ちます。サーバー専用コード、ORMクライアント、またはシークレットをクライアントコードにインポートしないでください。公開環境変数はシークレットではありません。
- 単一のAPIレイヤー。 1つのfetchクライアント、安定したコードとステータスでキー指定される1つの型付きエラーモデル、1つの認証動作。機能が独自のfetchやリトライを構築することはありません。サーバーデータはクエリ/キャッシュレイヤーに、グローバルクライアント状態は小さなストアまたはコンテキストに、フォーム状態はフォームツールに、ローカルUI状態はコンポーネントに保持します。モックソースは設定によって開発とテストのために切り替えられ、機能を編集して切り替えることはありません。信頼できないレスポンスは実行時にパースされます。
- フォーム。 プロジェクトに別のツールがない限り、react-hook-form + Zod。
mode: 'onTouched'、reValidateMode: 'onChange'、最初のエラーへのフォーカスとスクロール、setErrorによるサーバーフィールドエラー、エラー後も値は保持、二重送信はブロック。サーバーがバリデーションの権威であり続けます。 - 状態には境界があります。 ルートレベルのローディングとエラー境界、加えてデータがストリームされる場所にはローカルのSuspense。1つのウィジェットが失敗してもページ全体が空白になることはありません。
- i18nはアーキテクチャです。 本物のエンジン、ロケールレジストリ（BCP 47タグ、方向、カタログ、表示名）、特に指定がない限り英語フォールバック、サーバー上のリクエストスコープのロケール、サーバーとクライアントで同じ初期ロケール、ロケールと名前空間ごとにロードされるカタログ、アプリケーションロケールからマッピングされるキットと日付ロケール。
- セキュリティはサーバーサイド。 バックエンドでの認可。レンダリングするHTMLはすべてサニタイズします。クッキーセッションにはCSRF保護が必要です。個人を特定できるレスポンスは共有キャッシュに決して入れません。ロケールやユーザーに依存するレスポンスはキャッシュキーを変化させます。
- 公開ページは見つけやすい。 サーバーでレンダリングされるロケール正しいメタデータ、言語ごとの正規URL、実際の対応ページのみに対するhreflang代替、サイトマップ、表示されるコンテンツと一致する構造化データ。GEOはここから始まります：インデックス可能で引用可能なコンテンツと明示的なAIクローラーポリシー。ランキングや引用の保証はありません。
- キットはラップされるのではなく、適用されます。 テーマとトークンはプロダクトのデザイン決定から来ます。キットコンポーネントをラップするのは、繰り返されるプロダクトの振る舞いのため、またはAPIをピン留めするためだけです。キット独自のトランジションの上に、別のアニメーションシステムを積み重ねないでください。
完了条件
web-craft を適用 → 完了。加えて：クライアントバンドルにシークレットやサーバー専用モジュールが含まれていないこと；異なるロケールまたは異なるユーザーによる2つの同時リクエストがデータを混在させないこと；最初のレンダリングが正しい言語とテーマで行われること；主張されているすべてのキット/フレームワークの組み合わせが実際にチェックされたこと。