Metanaka Feature Firestore API Boundary

Firestore を共有状態の正とする feature では、frontend client から Firestore へ直接書き込まない。 Firestore SDK を使う frontend adapter は読み取り専用にし、書き込み操作は backend API を認証付き HTTP request で呼ぶ。

Boundary

• Firestore adapter には onSnapshot、getDoc、getDocs などの購読/スナップショット取得だけを置く。
• setDoc、updateDoc、runTransaction、writeBatch、deleteDoc などの Firestore 書き込み API を frontend feature code から呼ばない。
• review では frontend feature code からの Firestore write を critical な境界違反として扱う。
• 作成、参加、設定更新、状態遷移、投票、集計、結果確定など共有状態を変更する操作は useNuxtApp().$authApi.requestApi 経由で backend API を呼ぶ。
• endpoint、method、body は、その操作を所有する useXxx composable に置き、useXxx の unit test で固定する。
• composable は $authApi.requestApi の Result を受け取り、pending guard、server error key、画面固有の遷移を扱う。
• Security Rules は client write を許可せず、backend は Admin SDK など trusted boundary 経由で書き込む。

例:

const result = await useNuxtApp().$authApi.requestApi<VoteResponse>(
  `/rooms/${roomId}/votes`,
  {
    method: "POST",
    body: { targetPlayerId },
  },
)

unit test では endpoint、method、body と、pending guard / server error handling を useXxx の public contract として確認する。

Data Policy

• 共有状態には、表示文言ではなく安定した key や ID を保存する。
• locale 別の表示名や翻訳文字列は frontend の表示境界で解決する。
• 結果表示前に公開してはいけない secret、role、vote target は公開ドキュメントへ保存しない。
• 公開ドキュメントとは、client が Security Rules で読める room / round / vote summary などの document を指す。結果表示前に公開してよいのは、人数や進行状態など秘密を推測できない集計値に限る。