异步任务错误需分层处理：致命错误立即中断并告警；可恢复错误记录上下文并重试；用户感知错误提供具体可操作提示；全程透传trace_id，统一上报与提示入口，重试与降级策略明确。
异步任务出错时，不能只靠后台打日志就完事——用户需要知道“发生了什么”，系统需要知道“怎么修”。关键在于把错误信息分层处理：对开发者要精准可追溯，对用户要友好可操作。
错误必须分级记录
同一类错误在不同场景下严重性不同。比如网络超时，在 OCR 初始化阶段是致命错误（无法启动识别），但在结果上传阶段只是临时失败（可重试）。建议按三级划分：
- 致命错误：如相机初始化失败、OCR 引擎加载失败。立即中断流程，记录完整堆栈、设备型号、Android 版本、任务 ID，并触发告警
- 可恢复错误：如网络不可达、存储满、Tesseract 运行时异常。记录错误类型、重试次数、前后上下文（如当前图片尺寸、语言包版本）
- 用户感知错误：如“识别结果为空”“未检测到文字区域”。不记堆栈，但存用户操作路径（从点击拍照到提示耗时多少秒）、截图缩略图（若合规允许）
用户提示要具体、可行动
避免出现“操作失败”“未知错误”这类无效提示。每条提示需包含三个要素：问题是什么、为什么发生、用户现在能做什么。
- 相机初始化失败 → “无法打开摄像头。请检查是否被其他应用占用，或重启设备后重试。”
- 语言包下载失败 → “网络连接不可用，无法加载中文识别支持。请检查 Wi-Fi 或移动数据，稍后点击‘重试’。”
- 识别结果为空 → “未在图片中找到清晰文字。建议调整拍摄角度、确保光线充足，或尝试手动框选区域。”
所有提示通过统一入口（如 CaptureActivity.showErrorMessage()）弹出，禁止直接 Toast 或 Log.e 混用。
异步链路中错误不丢失
一个 OCR 流程常跨多个异步环节（拍照 → 裁剪 → 上传 → 识别 → 解析），错误容易在某一层被吞掉。必须做到：
- 每个 AsyncTask 或协程启动时绑定唯一 trace_id，并透传至下游调用
- catch 到异常后，不只打印日志，还要调用统一上报方法（含 trace_id、阶段名、耗时、原始异常类名）
- 前端轮询状态接口时，后端响应体中必须携带 error_code 和 user_message 字段，而非仅靠 HTTP 状态码判断
重试与降级要有明确边界
不是所有错误都该重试，也不是所有失败都要暴露给用户。设计时需预设策略：
- 网络类错误：最多重试 2 次，间隔 1s、2s（指数退避），第三次失败则降级为本地缓存识别（如有）或提示离线模式
- 资源类错误（如内存溢出、存储满）：不重试，直接提示并引导清理空间或切换到轻量模式
- 识别质量类错误（置信度低于阈值、结果乱码率高）：不报错，而是静默返回空结果 + 埋点，后续用于模型优化，用户侧无感知
错误处理不是兜底，而是有策略的分流。记录和提示，本质都是为了更快定位根因、更少打扰用户。
