fullstack-workflow

此技能为在 Inbox Zero 生态系统中构建全栈功能的开发人员提供了一套完整的架构模式。它强制执行严格的关注点分离，确保整个代码库的一致性，同时简化从数据获取到 UI 变更的开发周期。通过利用服务器动作 (Server Actions) 进行变更和 SWR 进行客户端状态管理等既定模式，此工作流程减少了错误并提高了应用程序的可维护性。它非常适合正在处理复杂 Next.js 项目并需要可靠模板进行高效数据操作的软件工程师。

• 标准化数据流：使用 GET API 路由进行只读数据操作，并封装 withAuth 或 withEmailAccount 中间件以确保安全性。

• 变更操作：利用 next-safe-action 定义类型安全的服务器动作，配备用于输入验证的 Zod 结构与用于监控的 Sentry metadata。

• 客户端优化：实现 SWR 钩子，实现高效的前端数据获取与缓存处理。

• 表单管理：整合 React Hook Form 与 zodResolver，确保在调用服务器动作前进行严格的客户端验证。

• 错误处理：内置自定义错误提示工具，可优雅地管理并向终端用户呈现操作错误。

• 构建新功能时务必遵循结构：先定义验证结构 (schema)，然后定义服务器动作，接着是 API 路由，最后是对应的 SWR 钩子。

• 确保所有 API 路由均受现有中间件保护，以维持对电子邮件帐户和用户上下文的安全访问。

• 使用现有的 action clients (例如 actionClient) 以确保正确的上下文 (userId 或 emailAccountId) 被注入到每个变更操作中。

• 通过定义返回类型 (使用 Awaited<ReturnType<typeof getData>>) 来利用类型推论，从而获得完整的 IDE 支持与运行期安全性。

• 保持逻辑分离；将业务逻辑保留在服务器动作中，并将 UI 状态逻辑保留在自定义 React 钩子中。