frontend-server-state-tanstack-query

使用TanStack Query处理考勤数据。固定queryKey设计、无限/分页、mutation、乐观更新、错误/重试、缓存失效等操作。关键词：TanStack Query、queryKey、mutation、重试、缓存

SKILL.md

--- frontmatter

name: frontend-server-state-tanstack-query
description: 'TanStack Query を使って勤怠データを扱う。queryKey設計、infinite/pagination、mutation、楽観更新、エラー/リトライ、キャッシュ無効化の運用を固定する。キーワード: TanStack Query, queryKey, mutation, retry, cache'
license: MIT

TanStack Query Skill

目的

「どこで取得して、どこで更新して、いつ再取得するか」を統一する。

標準パターン

•QueryKeyは docs/frontend-data-contract.md が正
•一覧：ページング/無限スクロールのどちらかに統一（docsに明記）
•Mutation：成功時は invalidate か setQueryData で整合性を取る
•失敗時：ユーザーに短いメッセージ＋詳細ログ

勤怠でよくある実装指針

•打刻：mutation → 該当日の time_entries を即更新（setQueryData）→ 背後で invalidate
•月次申請：status を更新 → approvals と time_entries（該当月）を invalidate
•5分間隔反映が許容なら、refetchInterval は “必要な画面だけ” に限定

必須アウトプット

•queryKey一覧（timeEntries/approvals/employees）
•主要mutation（clockIn/clockOut/submit/approve/reject）のinvalidate方針
•429/一時失敗時のリトライ方針

依頼例

•「time_entries の queryKey と invalidate 設計を決めたい」
•「打刻は楽観更新したい。UI/データ整合性の設計を出して」

References

•docs/frontend-data-contract.md