管线层实操：收件箱从报错到自愈

2026年7月12日 · 系统架构系列第二篇 · 爱普纳杰专利所

上篇讲了管线-Agent-数据库三层架构。这篇落地：管线层最典型的场景——收件箱入库异常——怎么从红色报错变成自动自愈。

改前 vs 改后

❌ 改前

打开 CNPTES → 收件箱 → 红色报错
「Expecting value: line 1 column 1」
不知道哪个文件失败、为什么失败
只能点「手动提取入库」→ 又失败
循环：报错 → 无处理 → 堆积

✅ 改后

打开 CNPTES → 收件箱 → 「3条待处理」
点击查看：2条已自动重试成功，1条待确认
每条有 error_type + 原始文件路径
异常文件自动写入 failed_queue
循环：报错 → 自动重试 → 自愈或升级

核心设计：一张表 + 三段逻辑

failed_queue 表

CREATE TABLE failed_queue (
    id INT AUTO_INCREMENT PRIMARY KEY,
    source VARCHAR(64)     — 'inbox' / 'ocr'
    original_file VARCHAR(512)  — 原始文件路径
    error_type VARCHAR(128) — 'json_parse' / 'ocr_fail' / 'encoding'
    error_detail TEXT       — 完整报错信息
    retry_count INT DEFAULT 0  — 已重试 ≤ 3
    max_retries INT DEFAULT 3
    status ENUM('pending','retrying','resolved','escalated')
    created_at DATETIME
);

设计要点：不改造原有入库逻辑，只在失败路径上加一行 INSERT。

三段处理逻辑

阶段	动作	触发
① 捕获	入库失败时，不报错退出，而是 `INSERT INTO failed_queue`	每次入库异常
② 重试	Cron 每 30 分钟扫描 `pending` 记录，retry_count+1，重新执行入库	定时任务
③ 升级	retry_count ≥ 3 次仍失败 → status='escalated' → 通知管网的人	3 次重试后

为什么是 3 次，不是无限重试

三个原因：

可重试的错误会在前 2 次解决——JSON 解析失败通常因为文件正在写入、OCR 服务暂时不可用这类瞬时问题
3 次还失败，说明不是瞬时问题——可能是文件本身损坏、编码格式不支持、系统 Bug
避免死循环消耗资源——无限重试会把 CPU 和磁盘 IO 耗在无法修复的文件上

管线层的核心原则：能自动处理的决不升级，该升级的决不拖延。

实际效果

指标	改前	改后
异常发现	人工打开收件箱才能看到	Cron 主动扫描，异常即时入库
处理方式	手动「提取入库」反复尝试	系统自动重试，你只处理 escalated
追溯能力	无记录，靠记忆	每条的 error_type + error_detail + 原始文件路径
人工介入	每一条都要看	只看 escalated（约 10-20% 的异常）

和三层架构的关系

这是管线层的典型实现——

管线负责发现：Cron 定时扫描，捕获异常并写入队列
Agent 负责判断：escalated 后由 Agent 判断是文件问题还是系统 Bug，通知对应的人
数据库负责关联：failed_queue 和 agent_audit_log 双表联动，异常有来源、处理有记录

下期预告

Agent 层实操：核销匹配怎么从 0 做到自动匹配率 80%

↗ 系列第一弹：三层架构设计原则

📐 本文是「管线-Agent-数据库」系列第二篇。
第一篇：三层架构设计原则｜第三篇：Agent层实操（即将发布）