implement-frontend

实现前端

当仓库已采用以下技术栈时，应用此技能：

• React + TypeScript + Next.js
• React Hook Form + Zod
• React Query 或 Connect Query
• Proto 生成的 API 类型（如有）

如果本地约定不同，请遵循现有项目规范，只应用可迁移的原则。

核心工作流

1. 编辑前划分职责边界。
   • 仅在组件中处理渲染相关事项。
   • 在 hooks 中处理数据获取、映射和业务规则。
   • 将服务端状态保存在查询缓存中，将表单状态保存在 RHF 中，并使用 useState 管理仅用于 UI 的状态。
2. 使用严格类型和明确映射来实现。
   • 避免使用 any、as any 和忽略指令等类型逃逸方式。
   • 在映射器中将 API 模型映射为 UI 模型，而不是直接进行类型断言。
3. 完成前验证可靠性和 UX。
   • 覆盖加载、错误和空状态。
   • 当可能发生竞态时，为异步工作添加取消和清理逻辑。
   • 保持键盘可访问性和焦点行为。

不可妥协的检查项

• 移除重复状态和 useEffect 同步循环。
• 不要在渲染组件中处理 API 调用和业务逻辑。
• 只使受影响的查询键失效或更新。
• 只使用可安全回滚的乐观更新。
• 移除 console.*、debugger、无用代码和未使用的导入。

技术栈约束

• 如果仓库使用 RHF + Zod，请使用 createZodResolver；避免使用 zodResolver(schema as any)。
• 如果使用 RHF，避免将整个 form 对象放入依赖数组。
• 如果使用 proto 契约，请将 proto 到 UI 的转换放在专用的映射器文件中（例如 utils/proto-mappers.ts）。

参考资料

• 使用 react-patterns.md 了解表单、hooks、状态归属、查询用法和可访问性。
• 使用 typescript-patterns.md 了解类型规范、proto 类型和代码组织。