Mica Ppocr Custom Parser

mica-ppocr 自定义结构化解析器

把 PP-OCRv6 检测出的散落文字框（List<PPOcrV6Result>），按"标签定位 + 位置匹配 + 正则兜底"的策略， 组织成业务字段对象（继承 BaseStructuredResult 的 POJO）。

模块路径：mica-ppocr-structured/src/main/java/net/dreamlu/mica/ai/ppocr/structured/parser/

1. 何时用本 skill

用户提出以下任何需求时,先加载本 skill：

• "加一个 XX 证件 / 票据 / 卡证的结构化解析"
• "新加一个 parser,识别 XX 业务字段"
• "把 OCR 散落文字组织成业务字段"
• "在 mica-ppocr 里写个自定义解析器"
• 看到 mica-ppocr-structured/.../parser/<new-biz>/ 这样的目录或被要求"参考 VehicleLicenseParser"

不要用本 skill 处理：

• 纯 OCR 推理（不改字段）→ 走 PPOcrV6Engine 即可,不需要结构化层
• 模型训练/字典扩充 → 走 PP-OCRv6 模型侧
• 非 mica-ppocr 项目 → 不适用

2. 三层骨架先认清楚

LabelMatcher 是 @UtilityClass 静态方法集合,不绑定任何具体业务,所有解析器共享同一套语义。

3. 新增一个解析器,5 步走

3.1 创建包

在 mica-ppocr-structured/src/main/java/net/dreamlu/mica/ai/ppocr/structured/parser/<biz>/ 下新增 2~3 个文件：

<biz>/
├── <Biz>Parser.java        # 继承 BaseStructuredParser<<Biz>Result>
├── <Biz>Result.java        # 继承 BaseStructuredResult
└── <Biz>Side.java          # 可选:有正反面/多版面时

包名小写 + 业务名（参考 vehicle/、idcard/、invoice/、train/）。

3.2 写 Result

@Data
@EqualsAndHashCode(callSuper = true)
public class InvoiceResult extends BaseStructuredResult {
    private String invoiceCode;     // 发票代码
    private String invoiceNo;       // 发票号码
    private String invoiceDate;     // 开票日期
    private BigDecimal amount;      // 价税合计
    // ... 业务字段
}

要点：

• 必须 @Data + @EqualsAndHashCode(callSuper = true) —— rawResults 和 fieldBoxes 在父类
• 字段名（key）要和后续 LabelMatcher.applyFieldBox(result, "fieldName", match) 一致
• 业务字段值允许为 null（OCR 失败/字段缺失）,不要用基本类型

3.3 写 Parser（核心）

@Slf4j
public class InvoiceParser extends BaseStructuredParser<InvoiceResult> {

    // 1) 正则常量（业务相关）
    private static final Pattern INVOICE_CODE_PATTERN = Pattern.compile("^\\d{8,12}$");

    public InvoiceParser(PPOcrV6Engine engine) {
        super(engine);  // engine 可为 null:仅当只调 parseResults(List) 时
    }

    @Override
    public InvoiceResult parseResults(List<PPOcrV6Result> results) {
        InvoiceResult r = new InvoiceResult();
        r.setRawResults(new ArrayList<>(results));  // 必填:供调用方做可视化

        // 2) 逐字段填值
        LabeledMatch codeMatch = parseInvoiceCode(results);
        r.setInvoiceCode(codeMatch.value());
        LabelMatcher.applyFieldBox(r, "invoiceCode", codeMatch);

        // ... 其他字段
        return r;
    }
}

模板四件套：

1. 构造器接 PPOcrV6Engine,转给 super(engine)
2. parseResults 入口：new Result → setRawResults(new ArrayList<>(results)) → 填字段 → return
3. 每个字段返回 LabeledMatch(值 + 匹配框),用 LabelMatcher.applyFieldBox 回填 fieldBoxes
4. 解析失败/未命中 → 字段值允许 null,打 log.warn(不要 System.out.println)

3.4 选 LabelMatcher 模式（按业务复杂度）

返回风格选择：

• 老代码/简单场景 → matchValue(...) -> String（一行搞定）
• 新代码/需要回填 fieldBoxes → matchValueWithBox(...) -> LabeledMatch,后续 LabelMatcher.applyFieldBox(result, "fieldName", match)

3.5 注册到 Spring Boot（如果用户用了 starter）

在 mica-ppocr-spring-boot-starter/src/main/java/net/dreamlu/mica/ai/ppocr/autoconfigure/StructuredParserAutoConfiguration.java：

1. 新增 @Bean（参考现有 8 个）
2. 把它加到 ppocrTemplate(...) 方法签名 + 构造器调用 + null 校验里
3. 在 PPOcrTemplate 同步新增：字段、@Getter 方法、构造器参数、null 校验

整套有 4 个文件要改（只要用户走 Spring Boot）：

Solon / 非 Spring 用户只需前 2 个文件,自行 new XxxParser(engine) 即可。

4. 7 个常用模式（按场景选）

模式 A：标准左标签 + 右值（行驶证、驾驶证、营业执照）

参考：VehicleLicenseParser、DriverLicenseParser、BusinessLicenseParser

LabeledMatch m = LabelMatcher.matchValueWithBox(results, "号牌号码");
r.setPlateNo(m.value());
LabelMatcher.applyFieldBox(r, "plateNo", m);

模式 B：标签 + 正则兜底（身份证号、发票号、车牌）

参考：VehicleLicenseParser 的 plateNo/vin/issueDate

LabeledMatch m = LabelMatcher.labelOrFallbackWithBox(
    LabelMatcher.matchValueWithBox(results, "车辆识别代号"),
    results, VIN_PATTERN, "VIN", false /* last=false 取首个 */);

模式 C：纯正则兜底（无标签,卡号、手机号）

参考：BankCardParser#parseCardNumber、BankCardParser#parseHolderName

String cardNo = LabelMatcher.matchPattern(results, CARD_NUMBER_PATTERN, false);

模式 D：合并框剥值（OCR 把标签和值识别成一框）

参考：VehicleLicenseParser#parseIdNumber、InvoiceParser#findInvoiceCode

• 合并框 "公民身份号码362503..." → 用 matchValueFromPrefix
• 合并框 "No14641426" → 自己写 extractor：

String no = LabelMatcher.matchSubstring(results, text -> {
    if (!text.startsWith("No")) return null;
    Matcher m = INVOICE_NO_PATTERN.matcher(text.substring(2));
    return m.find() ? m.group() : null;
});

模式 E：跨行字段（住址、经营范围、备注）

参考：IdCardParser#parseAddress、LabelMatcher.collectMultiLineRight

要点：合并框首行 + 后续 y 重叠右侧框按 y 升序拼接,中间空格分隔,最后用 replaceAll("\\s+", "") 去噪。

模式 F：版面/区域判定（身份证正反面、发票购销方）

参考：IdCardParser#detectSide、InvoiceParser#parseParty（用 imgMidY 分上下半区）

// 1) 用特征标签判定（先反后正:反面字少,OCR 不易误识）
boolean isBack = LabelMatcher.findLabelBox(results, "签发机关") != null;
if (isBack) { ... }

// 2) 用 y 中位数分上下区
int imgMidY = computeImageMidY(results);

模式 G：多 label 互斥分配（金额行多 label 抢同一值）

参考：LabelMatcher.assignExclusiveValues、LabelMatcher.LabelDef

适用于"金额/总金额/小计"等 label 同行且都指向同一右侧值。

5. 必须遵守的约定

命名

• 包名：单数业务名（vehicle / idcard / invoice / train / taxi / bankcard / driver / business）
• 类名：<业务名 PascalCase>Parser / <业务名 PascalCase>Result / IdCardSide（多版面时）
• 字段名：业务术语,首字母小写驼峰（plateNo / vin / issueDate / invoiceCode）

日志

• 命中分支打 log.debug(不要 info,正常路径不打日志)
• 失败/兜底打 log.warn("身份证解析:未匹配到身份证号")
• 不要用 System.out.println / System.err.println

防御性

• LabelMatcher.matchValueWithBox 返回的可能是 LabeledMatch.textOnly(null),先判 hasValue() 再用
• 正则匹配优先 find()(应对合并框),全等校验才用 matches()
• r.setRawResults(new ArrayList<>(results)) —— 必须用 new ArrayList 包一层,避免外部修改影响