用途：帮助在 React 项目中正确实现 TanStack Query 的 mutation，尤其是乐观更新（optimistic update）流程，避免常见的竞态与回滚错误。
主要能力：
- 决策是否真的需要乐观更新；不需要时直接走简单失效（invalidation）路径。
- 梳理 mutation 四个回调顺序：onMutate → API 调用 → onSuccess 或 onError → onSettled。
- 强调关键顺序：必须先 await queryClient.cancelQueries({ queryKey }) 取消在途查询，再 getQueryData 做快照，否则后台 refetch 可能覆盖乐观状态。
- onMutate 必须返回快照对象（如 { previousData }），作为 context 传给 onError 与 onSettled，否则无法回滚。
- 回滚放在 onError，缓存失效放在 onSettled，保证失败时缓存不会长期陈旧。
- 提供列表新增、列表就地更新、无乐观更新的删除、单资源更新等实现模式。
- 临时 ID 建议用 crypto.randomUUID()，避免 Date.now() 在快速操作下不唯一。
- 逐项加载状态：用 isPending 配合 variables?.id === item.id 判断某一行是否在提交。
- 错误状态用 reset() 清除；触发元素可加 disabled={isPending} 防止重复提交，因为 mutation 不做去重。
使用方式：按阶段执行——先发现（是否需要乐观更新、query key、列表还是单条、是否需要逐项加载），再实现回调，最后输出完整 mutation hook，包含类型化 context 与失效策略说明。
适用场景：React + TanStack Query 的增删改交互、需要即时 UI 反馈的表单与列表。
限制：资料未提供具体安装命令、版本要求、平台或收费信息；示例为 TypeScript 代码片段，需结合项目实际 API 与类型调整。