react-frontend

React 前端

实现前先验证：对于 App Router 模式、React 19 API 或特定版本的行为，编写代码前请查阅最新文档（如果可以，使用 Context7 query-docs；否则通过网络搜索查阅框架的官方文档）。训练数据可能滞后于当前版本。

工作规则

• 在渲染期间保留派生状态，并在事件处理程序中处理用户操作；使用 effect 与外部系统同步。
• 为异步工作设定生命周期和取消策略；将失败状态与待处理状态、空数据状态分别表示。
• 将缓存键与请求身份绑定。 当服务端会话状态先发生变化时，租户范围的键可能收到另一个租户的响应。在上下文切换期间，保持请求范围与缓存身份一致。使用已挂载的消费者、进行中的请求和失败的重新获取来验证隔离性。
• 隐藏交互区域时保留焦点，并在真实浏览器中测试键盘导航。
• 验证并授权每个公开的服务端操作；跨越服务端／客户端边界时只传递必要字段。
• 衡量性能变化，并测试用户可见的行为，而不只是类型检查。

Effects 决策树

Effects 是应急出口；大多数逻辑都不应使用 effects。

需求	解决方案
根据 props／state 派生值	在渲染期间计算（开销较大时使用 useMemo）
props 变化时重置状态	在组件上使用 key prop
响应用户事件	事件处理程序
通知父组件状态变化	在事件处理程序中调用 onChange，或使用完全受控的组件
一系列状态更新	在一个事件处理程序中计算所有下一状态
与外部系统同步	带清理逻辑的 effect

Effect 规则：

• 切勿抑制 linter；应修正代码
• 使用 updater 函数（setItems(prev => [...prev, item])）移除状态依赖
• 将对象／函数移入 effects，以稳定依赖项
• 对非响应式值使用 useEffectEvent（例如连接 effect 中的主题）
• 订阅、连接和监听器始终要返回清理函数
• 取消数据获取（根据具体情况选择）：对 fetch 使用 AbortController；对不可取消的 promise 使用 ignore 标记。使用 React Query 时，将查询函数的 signal 传递给传输层，例如 queryFn: ({ signal }) => fetch(url, { signal })。如果不使用该 signal，已不再需要的查询仍可能完成并填充缓存；不要将此行为描述为传输层取消。
• 请求完成不等于初始化完成。 只有在应用可用数据，或确认成功的最终空结果后，才消耗一次性初始化锁存状态。在同一次挂载中测试先返回空结果、后返回有数据的情况。验证后续重新获取不会覆盖用户编辑。

规范

• 简单优先：每项改动都应尽可能简单，并将影响限制在最少代码范围内
• 只修改必要内容；避免引入无关改动
• 不要采用取巧的权宜方案：如果修复方式感觉不妥，就退一步，实施干净的解决方案
• 添加新抽象前，先确认至少有 3 处会用到它

参考资料

• testing.md：组件、hook 和 mock 测试示例
• e2e-testing.md：Playwright E2E 模式

验证

• TypeScript 编译无错误
• 新代码中没有被抑制的 lint 规则（eslint-disable、@ts-ignore）
• 未手动覆盖 useEffect 依赖数组
• React 19+ 项目中不使用 forwardRef（直接使用 ref prop）

特定任务参考文档

在实现或审查相应行为之前，请阅读相关参考文档：

• 有关组件类型、状态归属、异步竞争、焦点或缓存查询行为：components-and-state.md。
• 有关性能、React API、Next.js 边界或缓存：rendering-and-frameworks.md。
• 有关 Tailwind CSS：工具类、@theme 令牌、CVA/tailwind-variants、暗色模式、从 v3 迁移到 v4，或溢出与 hidden 陷阱：tailwind.md。
• 有关组件、Hook、浏览器或集成测试的变更：test-selection.md。
• 有关同步 JSON 本地化文件或审查翻译：locale-synchronization.md。

适用于相应主题的现有专门参考文档：

• tailwind.md 中的 Tailwind 详细内容：tailwind-configuration.md、tailwind-v3-to-v4.md、tailwind-class-composition.md、tailwind-component-patterns.md、tailwind-layout-patterns.md。