异步错误处理需分级记录、全链路透传trace_id、统一上报并支持状态可观测与自动化分析。致命错误立即中断并告警；可恢复错误记录重试上下文；用户感知错误存操作路径与前端截图；所有异步环节必须透传trace_id；自动化聚焦高频模式化问题，敏感路径强制人工介入；任务状态须暴露五态并实时可查。
异步执行出错，不能只靠日志“留个痕迹”就完事。关键是要让错误可定位、可归因、可收敛——记录不是目的，驱动改进才是。
错误必须分级记录
同一类异常在不同环节意义不同。比如网络超时：在任务初始化阶段可能意味着流程无法启动，属于致命问题；而在结果回传阶段，大概率只是临时抖动，适合重试。
- 致命错误：如 OCR 引擎加载失败、数据库连接池耗尽。需立即中断，记录完整堆栈、设备/环境信息、trace_id，并触发告警
- 可恢复错误：如 HTTP 429、磁盘空间不足、Tesseract 运行时崩溃。记录错误类型、当前重试次数、上下文快照（如请求参数、图片尺寸、语言包版本）
- 用户感知错误：如“未识别到文字”“格式不支持”。不记堆栈，但存操作路径（从点击到提示耗时）、前端截图缩略图（若合规）、用户所选语言和模式
所有异步链路必须透传 trace_id
一个 OCR 流程常跨越拍照 → 裁剪 → 上传 → 识别 → 结构化解析多个异步环节。若某层吞掉异常或丢失上下文，排查就变成盲人摸象。
- 每个 AsyncTask、协程、Promise 启动时生成或继承唯一 trace_id，并透传至下游调用（含 HTTP Header、MQ 消息头、DB 日志字段）
- catch 到异常后，必须调用统一上报方法（而非仅 Log.e），入参含 trace_id、阶段名、耗时、原始异常类名、业务上下文
- 前端轮询状态接口时，后端响应体中固定携带 error_code 和 user_message 字段，避免仅靠 HTTP 状态码判断成败
自动化分析要聚焦高频、可模式化的问题
不是所有错误都值得自动分析。优先覆盖结构清晰、上下文明确、修复路径固定的场景：
- 连续 3 次相同堆栈指纹 + 相同代码位置的失败，自动聚合标记为“疑似稳定缺陷”，推送至对应模块负责人
- HTTP 500 类错误且响应体含 “timeout” 或 “circuit breaker open”，自动关联熔断指标与下游服务健康状态
- JSON 解析失败、空指针访问、正则匹配超时等语言级错误，可尝试生成修复建议（如加非空校验、设超时阈值），但仅限 PR 形式，禁止自动合并
- 对敏感路径（如支付回调、权限校验、DB 写操作）的错误，强制人工介入，不触发任何自动分析动作
状态可观测是分析的前提
没有准确的状态流转，自动化分析就是无源之水。每个异步任务应暴露最小五个状态：PENDING → RUNNING → SUCCESS / FAILED / RETRYING，并支持按 trace_id 实时查询全链路。
- 任务启动前写入中央状态表（Redis 或轻量 DB），含唯一 ID、类型、超时时间、重试策略
- 执行中更新为 RUNNING 并记录开始时间；完成后更新终态、耗时、脱敏后的错误摘要
- 将状态变更同步推送到 Prometheus 等指标系统，用于触发熔断、容量预警或自动扩缩容
