Appearance
灵妙儿带你游西湖项目异常与容错策略
概述
本文定义项目在关键业务场景下的异常类型、用户提示与系统处理策略，用于指导客户端与服务端在异常、延迟、冲突和风控命中场景中的统一行为。
异常处理总表
| 异常类型 | 场景说明 | 用户提示 | 系统处理 |
|---|---|---|---|
| 网络异常 | 首页、列表、详情、下单时网络不可用 | 网络开小差了，请稍后重试 | 展示重试按钮，保留当前页面状态 |
| 登录失效 | token 过期或失效 | 登录状态已失效，请重新授权后继续 | 清理本地 token，拉起登录流程 |
| 重复提交 | 抽奖、打卡、下单、解锁频繁点击 | 请求处理中，请勿重复操作 | 使用幂等键和按钮 loading 拦截 |
| 并发冲突 | 库存/积分同时被多个请求扣减 | 数据已更新，请重新确认后再试 | 回滚事务，刷新最新数据 |
| 库存不足/名额不足 | 下单或抽奖时库存变化 | 商品库存不足，请重新选择 / 奖品已发完 | 返回业务错误码，客户端停留当前页 |
| 支付失败 | 用户取消支付或签名失败 | 支付未完成，可稍后到订单页继续支付 | 订单保留待支付状态 |
| 支付回调延迟 | 微信回调未及时到达 | 支付结果确认中，请稍后到订单页查看 | 订单详情页轮询或手动刷新 |
| 消息发送失败 | 系统消息或订阅消息发送失败 | 不额外打扰用户 | 核心业务先成功落库，消息失败进入补偿任务 |
| 数据不同步 | 打卡成功但页面未刷新、订单状态显示滞后 | 数据刷新中，请下拉重试 | 强制回源获取最新状态 |
| 用户越权操作 | 查看他人订单、修改他人地址 | 当前操作无权限 | 返回 A0002 并记录审计日志 |
| NFC 设备不支持 | 设备或微信版本不支持 NFC | 当前设备暂不支持 NFC 打卡 | 提供返回路径并记录设备信息 |
| 错误标签 | 触碰非当前景点/图鉴芯片 | 未识别到当前目标芯片，请重试 | 不落业务数据，仅记录失败日志 |
| 频控/反作弊命中 | 同一用户短时间内对同一景点/图鉴重复触发识别 | 操作过于频繁，请稍后再试 | 命中风控直接拒绝；返回 A0004；记录 userId、spotId/atlasId、uid、deviceModel、traceId 以便排查 |
处理原则
1. 用户体验优先
- 异常提示应简洁明确，避免暴露系统内部实现。
- 网络、支付回调延迟、数据不同步等可恢复问题，优先引导用户重试或刷新。
- 非核心失败场景（如消息发送失败）不额外打扰用户。
2. 业务一致性保障
- 重复提交通过幂等键和按钮
loading双重拦截。 - 并发扣减场景需执行事务回滚并刷新最新业务状态。
- 库存、名额、积分等强一致资源变更，统一通过业务错误码控制客户端行为。
3. 支付容错
- 支付失败时，订单应保留为待支付状态，支持用户后续继续支付。
- 支付回调延迟时，订单详情页应支持轮询或手动刷新确认最终状态。
4. 降级与补偿
- 消息发送失败不影响核心交易链路，采用先落库、后补偿策略。
- 页面状态异常或展示滞后时，客户端应执行强制回源获取最新状态。
5. 安全与审计
- 越权操作统一返回
A0002，并记录审计日志。 - 风控命中统一返回
A0004，并记录关键排查字段：userIdspotId/atlasIduiddeviceModeltraceId
重点场景说明
重复提交防护
适用于以下高频操作：
- 抽奖
- 打卡
- 下单
- 解锁
推荐措施：
- 前端按钮点击后进入
loading - 请求侧附带幂等键
- 服务端校验幂等状态，避免重复落单或重复发奖
NFC 场景异常处理
NFC 相关异常需重点区分：
- 设备不支持：设备能力或微信版本限制，需提供返回路径并记录设备信息。
- 错误标签：识别到非当前景点/图鉴芯片，不写入业务数据，只保留失败日志。
- 频控/反作弊命中：短时间重复识别直接拒绝，返回
A0004。
支付链路异常处理
支付链路中需要区分：
- 支付失败：用户取消、签名失败等，订单保留待支付。
- 支付回调延迟：支付结果未最终确认，前端展示“确认中”状态，并支持轮询或刷新。
错误码
| 错误码 | 含义 | 使用场景 |
|---|---|---|
A0002 | 无权限操作 | 查看他人订单、修改他人地址等越权行为 |
A0004 | 频控/反作弊命中 | 同一用户短时间重复触发景点/图鉴识别 |
落地建议
- 客户端统一封装异常提示与重试组件。
- 服务端统一定义业务错误码、幂等机制和审计日志格式。
- 支付、消息、NFC、库存扣减等核心链路需接入监控与告警。
- 风控命中日志需保留足够上下文，便于追踪作弊行为与问题排查。