错误处理和UX解释

1）为什么这很重要

• 解释发生了什么，接下来该怎么做，
• 保存输入的数据并防止丢失进度,
• 给出安全的重复或替代路径,
• 保持可用状态（SR/键盘）,不透露额外内容。

2）错误类型（用于接口）

1.数据验证（4xx client）：空白/错误字段、格式、长度、规则冲突。
2.业务规则：限制，地理限制，KYC/KYB，双打，不可用插槽。
3.权利/永久化：角色，获得资源，年龄限制。
4.网络/服务器：定时,离线,5xx,拥塞,利率限制。
5.冲突/状态：409/412（数据更改），比赛，锁定。
6.资源缺失：404/410,已删除/已迁移。
7.支付和风险：银行/PSP拒绝，反欺诈和责任游戏限制。

3）频道和显示级别

规则：不要把关键藏在烤面包/hover中。用户观看的地方，消息也在那里。

4）文桉撰写错误

结构：原因→后果→行动。
语气：诚实，中立，无过错。
具体：指定字段/条件,避免代码和堆栈。
按钮操作：重复、更改地图、重置过滤器、打开聊天。
敏感数据：不显示（PAN掩码,个人属性）。

示例

好： "付款没有通过：银行拒绝了交易。尝试另一种方法或稍后重复。"

不好： "错误500。 出事了

好吧： "白天支出的限制已经达到。设置新的限制或明天尝试。"

好： "文件太大（最大25 MB）。吞噬或下载多个文件。"

5）行为和重点（A11y）

将错误输出到焦点上下文中：将焦点转移到第一个错误字段。
生活区域："role="status""（polite）用于信息，'role="alert""（assertive）-用于关键。
可见的"：focus-visible"，≥ AA的对比，颜色替代品（图标/文本）。
消息通过"aria-describedby"绑定到字段。

html
<label for = "pwd "> Password </label>
<input id="pwd" name="password" aria-describedby="pwd-err" aria-invalid="true">
<p id = "pwd-err" role = "alert"> Minimum 8 characters </p>

6）Retrai，backoff和idempority

如果有成功的机会（网络故障，5xx，利率限制），则提供重播。
指数反向1-2-4-8 s，尝试限制，可理解的"重复"按钮。
关键交易（利率/付款）：强制性Idempotency-Key →排除双打。
回滚乐观更新-清晰的视觉回报+解释。

js async function retry(fn, attempts=3){
let wait=1000; for(let i=0; i<attempts; i++){
try{ return await fn(); }catch(e){ if(i===attempts-1) throw e; await new Promise(r=>setTimeout(r,wait)); wait=2; }
}
}

7）离线，定时和部分内容

离线：我们显示"无连接"横幅、腰果访问（只读）、同步队列。
Taymauts：UI-taymaut（3-5 s）→"等待确认……"状态，安全重播/取消。
部分成功：保持成功；标记"不同步"。

8）冲突与竞争

409/412：数据已过时。提供"更新"并显示diff（发生了什么变化）。
锁定：通知谁持有设备,以及多长时间,"请求访问"按钮。

9） UI模板样本

html
<div class="banner banner--error" role="alert">
<strong> Connection failed. </strong> Shows cached data.
<button class =" btn btn--ghost" id = "retry "> Retry </button>
</div>

html
<div role="alertdialog" aria-labelledby="err-title" aria-describedby="err-desc">
<h2 id = "err-title "> Session expired </h2>
<p id = "err-desc "> Sign in again to continue. </p>
<button class = "btn "> Sign in </button>
<button class =" btn btn--ghost"> Home </button>
</div>

tsx function Fallback({ id, onRetry }: { id: string; onRetry: ()=>void }) {
return (
<div role="alert" className="banner banner--error">
<strong> We couldn't load the page. </strong>
<div> Try again. Код: <code>{id}</code> <button onClick={()=>navigator. clipboard. writeText (id)}> Copy </button> </div>
<button onClick = {onRetry}> Retry </button>
</div>
);
}

10）错误令牌（设计系统）

json
{
"error": {
"tones": { "danger": "#", "warning": "#", "info": "#" },
"aria": { "polite": true, "assertive": true },
"timing": { "toastMs": 3500, "retryBackoffMs": [1000,2000,4000] },
"layout": { "fieldGap": 8, "bannerIcon": 20 }
}
}

css
.banner--error { background: var(--bg-danger); color: var(--on-danger); padding: 12px 16px; border-radius: 12px; }
.field-error { color: var(--role-danger); margin-top: 6px; font-size:.875rem; }

11）安全和隐私

我们不会输出堆栈路径、内部ID、DB路径。
我们掩盖敏感值（地图、文档）。
消息不应提示攻击者（例如，帐户存在）。
要支持-ID相关性而不是零件。

json
{"level":"error","event":"payment_fail","correlation_id":"c-8f1...","user_id":"u-","route":"/pay","psp_code":"DO_NOT_EXPOSE_TO_USER"}

12）度量与控制

错误发生时的INP和长期任务份额（错误不应"挂起"UI）。
Retry success rate,错误1000操作,恢复前时间。
CTR在"帮助/聊天"上，被遗弃的表格百分比。
热图：现场错误最常见的地方。

13） QA支票清单

可用性

• 重点关注第一个错误的领域；"aria-describedby"/"aria-invalid"展出。
• 关键信息是'role='alert'；AA ≥对比。

行为

• 表格数据不会因错误而丢失。
• 有一个可以理解的"Retry"和正确的背景。
• 离线模式/kesh工作；看到的横幅。

文桉撰写

• 原因→行动；没有技术术语和指控。
• 文本是本地化的，并且不会打破网格。

安全性

• 没有PII/秘密泄漏；我们只显示安全代码/ID。
• 用于关键操作的幂等性。

14） iGaming的细节

• UI立即记录了"忙碌"；延迟时>3 c-"等待确认……"
• 失误：诚实状态（"市场关闭"，"系数改变"）+安全的"回归"。
• 排除双重出价的偶数键。

• 区分"银行/PSP故障"与"服务器故障"。第一个是"选择其他方法"，第二个是"Retry"。
• KYC/AML透明步骤；链接"为什么需要？».

• 语气有爱心，没有压力。"达到极限-暂停或更新极限。"
• 没有耀斑/霓虹灯；AAA对比，SR可用性。

• 明确解释限制,并提供"熟悉规则/支持"。

15）反模式

"出了问题"，没有行动和背景。
错误后重置表格。
在敬酒中隐藏关键的3秒钟。
只有没有文本/图标的颜色。
无休止的撤退，没有取消的可能性。
显示内部代码/堆栈跟踪。

16）设计系统中的文档

Компоненты: `FieldError`, `FormError`, `PageBanner`, `AlertDialog`, `ErrorBoundary`.

音调/对比/时间令牌，a11 y预设和ARIA示例。
具有文本模板的典型脚本映射（验证，网络，权利，支付）。
"Do/Do n't"：带有故障/成功度量的实际前后屏幕。

简短摘要

让错误易于理解和管理：以人性化的语言说话，保留输入的数据，提供安全的重播和替代品，尊重可用性和隐私。然后，即使是不合时宜的情况也保持信任，并且不会中断用户的路径-尤其是在关键的投注和支付情况下。