Storefront local cache bypass

背景

Storefront では production / staging / preview と local で求めるキャッシュ挙動が異なる。production 系では公開 GET や public CMS データの shared cache を使って配信効率を上げたいが、local では UI・導線・表示内容の検証を最優先し、キャッシュ由来の見え方のズレを避ける必要がある。

合意事項

1. local / mock では shared cache を使わない
2. 公開 GET の Cache-Control / CDN-Cache-Control / Cloudflare-CDN-Cache-Control は no-store を返す。
3. revalidation metadata を付けた shared fetch は local / mock では無効化し、 no-store を優先する。
4. production / staging / preview は既存の shared cache 方針を維持する
5. 公開 CMS / tracking / metadata など、認証非依存で意図的に revalidate を付けた fetch は shared cache を使ってよい。
6. 公開 GET の edge cache opt-in も production 系でのみ有効にする。
7. private / 認証依存レスポンスは全環境で no-store を維持する
8. /commerce/shop-api、/api/customer-hierarchy、/api/auth-bypass、health 系、revalidate endpoint などは引き続き no-store。
9. local の client-side cache も極力避ける
10. ブラウザ側の navigation / asset cache は local / mock では stale window を極力持たない。
11. クライアント側の GraphQL 状態は TanStack Query を正本とし、local / mock では staleTime を短くしつつ invalidateQueries を優先して最新表示に寄せる。

実装ガイド

• local 例外は画面ごとに散らさず、Storefront 共通 helper に集約する。
• public catalog query を cross-request cache したい場合は、Cookie / Authorization 非依存であることを明示できる取得経路を別途用意する。
• PUBLIC_VENDURE_FETCH_OPTIONS が Cookie を送る可能性を前提に、public cache 追加時はセッション混入を必ず点検する。