用途
backend-error-handling 是一个用于全栈应用的后端错误处理技能，帮助开发者实现分层的错误处理模式，包括错误边界、toast 提示以及统一的 API 错误结构。它适用于以下场景：为新增功能添加错误处理、改善错误的用户体验、标准化错误响应、调试错误传播、添加错误监控。
该技能的自由度标注为 MIXED：选择在哪一层处理以及使用什么消息属于高自由度；而检查已有类型与错误边界的探测步骤属于低自由度，需要严格按给定命令执行。
主要能力
技能围绕错误处理的分层展开：
- UI 层：错误边界、表单校验错误、toast 通知。
- 应用层：Server Action 错误、API 路由错误、业务逻辑错误。
- 数据层：数据库错误、Zod 校验错误、外部 API 错误。
核心原则是：每个错误都在能够命名它的最低层被捕获，并以 ActionResult 或类型化的 API 错误向上传递，绝不把原始 throw 直接抛给 UI。
技能提供标准错误类型设计：一个 AppError { code, message, details? }，其中 code 是机器可读的，message 是用户安全的。ActionResult<T> 是基于 success 的可辨识联合，不允许返回 { data, error } 两者都可选的结构。错误码包括 VALIDATION_ERROR、NOT_FOUND、UNAUTHORIZED、FORBIDDEN、CONFLICT、RATE_LIMITED、INTERNAL_ERROR。
技能还覆盖多个具体实现层面：Server Action 错误处理（safeParse FormData、检查会话、映射已知错误如 Prisma P2002 → CONFLICT、记录未知错误并返回通用 INTERNAL_ERROR）、React 19+ 表单错误显示（useActionState、useFormStatus、useOptimistic、aria-invalid 与 aria-describedby）、React 错误边界（app/error.tsx 与 app/global-error.tsx）、API 路由错误处理（统一的 { error: { code, message, details? } } 响应体）、TanStack Query 错误处理（queryFn/mutationFn 中抛出服务器消息、401/403 不重试、onSuccess 失效查询键并 toast.success、onError 触发 toast.error）以及可复用的 ErrorState UI 组件。
使用方式
技能强调在添加任何错误处理之前，先检查项目中已有的实现，并给出了具体的探测命令：
- 检查已有错误类型：rg "type.*Error|interface.*Error" --type ts；rg "ActionResult|ApiError" --type ts
- 检查已有错误边界：ls -la app/error.tsx app/global-error.tsx；rg "ErrorBoundary" --type tsx
- 检查已有错误工具：rg "formatError|handleError|reportError" --type ts；ls -la src/lib/errors* src/lib/error* 2>/dev/null
- 检查既有错误响应模式：rg "success: false|error:" src/features/*/server/ --type ts | head -10
技能给出了一个推理流程：观察（已有错误类型、边界、ActionResult / ApiError）→ 解读（缺失层 vs 结构不一致 vs 被吞掉的 catch）→ 分类（复用已有 / 扩展错误码 / 添加边界 / 仅 toast）→ 严重性排序（变更操作上未处理的 500 优先于缺失的 toast）。
技能还提供了一个完整示例：观察到 createUser 抛出 Prisma P2002，UI 显示空白 catch，ActionResult 已存在于 types/errors.ts；解读为已知冲突未映射、没有字段或 toast 路径；分类为复用 ActionResult + CONFLICT、toast 消息、不添加第二个错误类型；验证为重复邮箱返回 { success: false, error: { code: 'CONFLICT' } } 并显示表单提示。
在报告前，技能要求进行自我审查：是否在添加类型前搜索过 ActionResult / ApiError / error.tsx；是否用户安全（INTERNAL_ERROR 保持通用，客户端消息不含 PII）；是否分层（边界 + action result + toast，而非仅 toast）；归属是否正确（仅规划的可观测性审计 → plan-error-handling；实时 Sentry 分诊 → debug-sentry-monitor）。
适用场景
适用于使用 Server Actions、API 路由、React 错误边界与 TanStack Query 的全栈应用，尤其是需要统一错误响应结构、改善错误提示体验、调试错误传播链路或接入错误监控的项目。
限制
技能本身标注为 plan-only（仅规划），不直接执行运行时操作。错误边界只能捕获渲染错误，异步与事件错误需通过 ActionResult 或 TanStack Query 处理。技能中引用的 references/server-patterns.md 与 references/ui-patterns.md 等完整代码示例未在给定资料中提供。