error-handling-recovery

错误处理与恢复

将每次失败都变成一条明确的前进路径：找出应用可能失败的每种情况，为其提供具体、面向用户的提示文案、恰当的展示位置，以及至少一种恢复操作。**首要原则：绝不责怪用户，也绝不让他们陷入死胡同——每种错误状态都必须提供脱困方法。**交付一份错误状态矩阵，涵盖各种失败模式，以及已实现的组件和提示文案，而不只是消息撰写指南。

适用场景 / 不适用场景

适用于：错误提示文案、验证体验、网络 / 离线故障处理、权限拒绝和 404 页面、恢复工作流、优雅降级、错误无障碍设计。

以下实际需求应改由其他技能处理：

• 从源头避免等待 / 故障（将重试作为性能优化，以及乐观更新回滚机制）→ skills/frontend-design/performance-optimization
• 异步生命周期中加载的部分（骨架屏、加载动画、空状态）→ skills/frontend-design/loading-states——此技能负责处理加载失败后的情况
• 错误动画时机 → skills/frontend-design/interaction-physics
• 超出错误界面范围的完整无障碍审计 → skills/frontend-design/accessibility-excellence

步骤 0 — 检查代码库，然后只询问尚未明确的信息

1. 搜集现有错误界面：搜索 catch、.catch(、onError、错误状态变量、toast.error、alert(、错误边界组件，以及 "error"、"failed"、"wrong"、"invalid" 等字符串字面量。收集实际的提示文案——当前文案就是改进前的基准。
2. 梳理应用中存在的失败类别：表单（验证）、API 调用（网络 / 服务器）、需身份验证的资源（权限）、路由（404），以及任何特定于业务的情况（付款被拒、配额限制、文件类型不受支持）。
3. 找出缺失项：静默吞掉错误的 catch 代码块、没有错误分支的 fetch、仅将边框标红的表单、未在独立区域周围设置错误边界的情况，以及未处理离线状态的情况。
4. 检查无障碍支持：搜索 role="alert"、aria-live、aria-invalid、aria-describedby。缺少这些内容时，应自动列为修复项。

仅在无法推断时，集中询问用户一次：要指向哪个支持渠道（电子邮件 / 帮助中心——系统错误提示需要此信息），以及是否存在需要格外谨慎处理恢复流程的高风险操作（付款、破坏性操作）。如果无法确定，请使用占位支持链接，注明这一点，然后继续。

工作流

1. 构建错误状态矩阵

针对步骤 0 中发现的每种失败模式，填写一行：失败模式 → 用户当时正在做什么 → 提示文案（发生了什么 / 原因 / 怎么做）→ 展示位置 → 恢复操作 → 无障碍支持。该矩阵既是审查交付物，也是实现清单。

2. 按四部分结构撰写每条提示文案

1. 发生了什么——使用具体、通俗的语言（“此电子邮件已被使用”，而不是“输入无效”）
2. 原因——用一句话说明背景，避免术语（绝不要向用户展示“CORS policy violation”）
3. 怎么做——提供明确的下一步操作
4. 如何获取帮助——系统错误应提供支持渠道；如果后端提供了错误 / 参考 ID，也应一并提供

文案规则：绝不责怪用户（将“您输入了无效的……”改为“请输入……”）；明确说明如何修正，而不只是告知规则；只有当应用确实会保留用户数据时，才能在提示文案中承诺会保留数据——除非确实如此，否则绝不要声称“我们已保存您的工作”。

3. 按故障类别决定呈现位置和恢复方式

类别	呈现位置	时机	恢复方式
验证	字段内联显示，紧邻字段	失焦或提交时——输入尚未完成时，绝不在每次击键后显示；修正后立即清除	提供修正指导；如果有快捷方式，则提供快捷入口（“改为登录”）
网络	区块级状态或提示消息；如果整个视图加载失败，则显示完整状态	失败时	重试按钮；保留已输入的数据；如果支持，则允许离线继续
权限	显示完整状态，替换被阻止的内容	加载或操作时	解释原因，并提供“申请访问权限”或联系负责人的途径
系统/5xx	区块或页面状态	失败时	重试、联系支持团队以及错误 ID
404	专用页面	路由访问时	搜索和指向关键目的地的链接

分支规则：

• 内联、模态框还是页面： 与字段相关 → 内联；流程中途出现阻断性、高风险故障（支付被拒）→ 通过模态框恢复；整个资源不可用 → 完整页面/区块状态。仅当故障与用户当前关注内容无关时才使用提示消息——绝不用提示消息显示表单验证错误。
• 自动重试还是手动重试： 幂等读取操作可以采用退避策略自动重试；变更操作只能由用户明确触发重试（绝不能悄悄重新提交付款或帖子）。
• 降级处理，不要崩溃： 功能不可用时应禁用并说明原因，而不是隐藏或导致崩溃。将彼此独立的 UI 区域封装在错误边界中，避免单点故障使整个页面变空白。

4. 实现时内置无障碍支持

• 动态错误通过 role="alert"（阻断任务的错误）或 aria-live="polite"（后台错误）播报。
• 字段：设置 aria-invalid="true"，并通过 aria-describedby 指向消息元素。
• 提交失败时，将焦点移到第一个无效字段，或移到可链接到每个错误的错误摘要。
• 每个指示器都要同时使用图标、文本和颜色——绝不能只用颜色。
• 每种类别和恢复模式的规范标记/CSS 均见 references/patterns.md — 编写代码时请阅读。

5. 验证

触发每种故障（无效输入、在开发者工具中断开网络、通过错误端点触发 500、访问未知路由），并确认：消息在正确位置显示，恢复操作有效，已输入的数据得以保留，屏幕阅读器播报生效（或相应接线已就位），且不会静默失败。

必需的输出格式

交付以下两项：

1. 代码 — 实现错误组件、文案字符串、错误边界和无障碍接线，并按照应用现有的组件和样式规范进行修改。

2. 错误状态矩阵（Markdown）：

## Error-state matrix
| # | Failure mode | Class | Message (final copy) | Placement | Recovery | A11y | Status |
| 1 | Signup email taken | validation | "Email already in use…" | inline under field | "Sign in instead" link | aria-invalid + describedby + role=alert | implemented |
| 2 | Feed fetch fails | network | "We couldn't load your feed…" | section state | Retry | polite live region | implemented |
| 3 | Card declined | system | "Your card was declined…" | modal | Try again / other method | alertdialog, focus trapped | implemented |

## Silent failures fixed
| Location | Was | Now |

## Copy changes
| Before | After |

## Assumptions
[Support contact used, failure modes you could not reproduce, etc.]

质量标准（交付前检查）

• 矩阵中的每一行都有恢复操作——没有任何死胡同
• 任何消息都不归咎于用户；不向用户显示原始技术术语（堆栈跟踪、状态代码、CORS）
• 每条消息都说明该怎么做，而不只是说明出了什么问题
• 在失焦/提交时触发验证，修正后清除；不因每次击键而反复提示
• 错误显示在原因附近（没有缺少字段链接的孤立错误摘要）
• 所有指示器都使用图标/文本和颜色，绝不只用颜色
• 已实现 role="alert"/aria-live、aria-invalid、aria-describedby 和焦点管理
• 修改过的代码中，没有任何 catch 块会在不向用户提示或记录结果的情况下吞掉错误
• 变更操作绝不自动重试；修改过的流程会在故障发生后保留用户数据

严格禁止：不要承诺应用无法提供的恢复能力（例如，没有持久化时却声称“您的工作已保存”）；对于不可逆操作或支付失败，不要使用幽默；不要添加会向开发者隐藏实际错误的错误 UI——保留控制台/遥测日志。

集成

• skills/frontend-design/loading-states → 为你提供错误和空状态的布局位置；你需要将其扩展为完整的消息和恢复方案。加载→错误的转换应复用同一个布局位置。
• skills/frontend-design/performance-optimization → 该技能中的乐观 UI 回滚需要你在后台同步失败时提供失败 toast/消息。
• skills/frontend-design/component-architecture → 提供你要添加错误变体的表单/输入组件；在该处添加 ErrorState 作为共享组件。
• skills/frontend-design/accessibility-excellence ← 审核你的实时区域和焦点行为；从一开始就按其标准构建。

参考资料

• references/patterns.md — 不佳→良好的消息改写、各类失败（验证、网络、权限、系统、404）的完整标记、行内/模态/渐进式恢复模式、优雅降级片段、错误样式 CSS，以及无障碍布线代码块。编写组件和文案时请阅读。