+ * 对图片中的文档、卡证、票据等含文字的主体进行检测、分类， + * 可同时支持一张图片中多张主体的情况，返回每个主体的类别及位置信息。 + *
* - * 文件检测分类 + *
- * {
- * "imageBase64": "图像base64编码（与imageUrl二选一）",
- * "imageUrl": "图片完整URL（与imageBase64二选一）"
- * }
- *
+ * @param request 文档分类请求
+ * @return {@code Rdoc_classify 的 words_result 是 List 结构，不同于 OCR 识别的 Map 结构。
+ */ + @SuppressWarnings("unchecked") + private DocClassifyResp buildResp(Mapdoc_classify 的 words_result 是 List，与 OCR 识别的 Map 结构不同， + * 因此不能直接使用父类的 {@link #isWordsResultEmpty}。
+ */ + private boolean isClassifyResultEmpty(Mapdoc_classify 的 words_result 是 List 结构，与 OCR 识别的 Map 结构不同， + * 因此不能直接使用父类的 {@link #isAllStringFieldsBlank}（它只看顶层 String 字段）， + * 改为遍历每条 ItemResp 做反射判断。
+ */ + private boolean isAllItemsFieldsBlank(DocClassifyResp data) { + if (data == null || data.getItems() == null || data.getItems().isEmpty()) { + return true; + } + for (DocClassifyItemResp item : data.getItems()) { + if (!isAllStringFieldsBlank(item)) { + return false; + } + } + return true; + } + + private String formatHint(String category, String reason, String suggestion, String detail) { + StringBuilder sb = new StringBuilder(); + sb.append("【文档分类·").append(category).append("】").append(reason); + if (StringUtils.isNotBlank(detail)) { + sb.append("｜定位信息：").append(detail); + } + sb.append("｜处置指引：").append(suggestion); + return sb.toString(); + } + + /** 入参日志说明（不打印影像正文，只说类型与长度） */ + private String buildInputLogContext(DocClassifyRequest request, ResolvedImageInput imageInput) { + if (request == null) { + return "未收到请求体"; + } + String modeDesc = imageInput != null ? imageInput.getType().getDesc() : "影像未解析"; + int rawLen = imageInput != null + ? textLength(imageInput.getRawValue()) + : textLength(request.getImageUrlOrBase64()); + return String.format("%s，影像原始长度 %d 字符", modeDesc, rawLen); + } } diff --git a/api-web/api-interface/src/main/java/com/heyu/api/request/doc/DocClassifyRequest.java b/api-web/api-interface/src/main/java/com/heyu/api/request/doc/DocClassifyRequest.java new file mode 100644 index 0000000..e97138c --- /dev/null +++ b/api-web/api-interface/src/main/java/com/heyu/api/request/doc/DocClassifyRequest.java @@ -0,0 +1,28 @@ +package com.heyu.api.request.doc; + +import lombok.Data; + +/** + * 文档分类检测请求参数。 + *+ * 对外只暴露一个字段 {@code imageUrlOrBase64}， + * 服务端自动识别为 HTTP(S) 链接或 Base64 字符串。 + *
+ * + * @author zhengli + * @since 20260609_zl + */ +@Data +public class DocClassifyRequest { + + /** + * 影像入参（URL 或 Base64 二合一）： + *+ * 所有字段均为 String 类型，保证反射统计工具覆盖。 + * 字段与百度 doc_classify 接口返回的 words_result 数组元素一一对应。 + *
+ * + * @author zhengli + * @since 20260609_zl + */ +@Data +public class DocClassifyItemResp { + + /** + * 类别信息，当前可输出类别包括：卡证_身份证_正、卡证_银行卡、办公文档、表格 等 200+ 种。 + * 对应百度字段：type（string） + * 示例："卡证_银行卡" + */ + private String type; + + /** + * 分类置信度（0~1 之间的小数，字符串形式）。 + * 对应百度字段：probablity（float） + * 示例："0.9999860525" + */ + private String probability; + + /** + * 位置信息 — 表示定位位置的长方形左上顶点的垂直坐标（像素）。 + * 对应百度字段：location.top（uint32） + * 示例："1684" + */ + private String top; + + /** + * 位置信息 — 表示定位位置的长方形左上顶点的水平坐标（像素）。 + * 对应百度字段：location.left（uint32） + * 示例："300" + */ + private String left; + + /** + * 位置信息 — 表示定位位置的长方形的宽度（像素）。 + * 对应百度字段：location.width（uint32） + * 示例："2710" + */ + private String width; + + /** + * 位置信息 — 表示定位位置的长方形的高度（像素）。 + * 对应百度字段：location.height（uint32） + * 示例："1712" + */ + private String height; + +} diff --git a/api-web/api-interface/src/main/java/com/heyu/api/resp/doc/DocClassifyResp.java b/api-web/api-interface/src/main/java/com/heyu/api/resp/doc/DocClassifyResp.java index 2ad9a83..863251c 100644 --- a/api-web/api-interface/src/main/java/com/heyu/api/resp/doc/DocClassifyResp.java +++ b/api-web/api-interface/src/main/java/com/heyu/api/resp/doc/DocClassifyResp.java @@ -1,19 +1,33 @@ package com.heyu.api.resp.doc; - -import com.heyu.api.data.dto.BaseResp; import lombok.Data; -@Data -public class DocClassifyResp extends BaseResp { +import java.util.List; - /*** - * 分类置信度 +/** + * 文档分类检测响应。 + *+ * 对图片中的文档、卡证、票据等含文字的主体进行检测和分类， + * 返回每个主体的类别、置信度和位置信息。 + * 如图片中无文字内容，items 为空列表。 + *
+ * + * @author zhengli + * @since 20260609_zl + */ +@Data +public class DocClassifyResp { + + /** + * 分类结果列表；图片中无文字内容时为空列表。 + * 示例：[{type="卡证_银行卡", probability="0.9999860525", top="1684", left="300", width="2710", height="1712"}] */ - private Double probablity; - /*** - * 类别信息，当前可输出类别列表见下文「附录：类别列表」 - */ - private String type; + private List+ * 覆盖参数校验、上游异常、识别空结果、识别成功、兜底等必测场景。 + *
* * @author zhengli - * @since 20260531_zl + * @since 20260609_zl */ public class DocClassifyControllerTest extends ApiInterfaceApplicationTests { @Autowired private DocClassifyController docClassifyController; + // ===================== 参数校验场景 ===================== + /** + * 假设(Given): 不传任何请求参数 + * 当(When): 调用 classify 接口 + * 则(Then): 返回 code=200，data 不为 null，msg 含【文档分类·入参绑定失败】 + */ + @Test + void classifyRequestNullTest() { + // Act + R result = docClassifyController.recognize(null); + + // Assert + assertNotNull(result, "返回结果不能为空"); + assertEquals("200", result.getCode(), "接口应返回成功"); + assertNotNull(result.getData(), "data 不能为 null（defaultEmptyResp 生效）"); + assertTrue(result.getData() instanceof DocClassifyResp, "data 类型应为 DocClassifyResp"); + String msg = result.getMsg(); + assertNotNull(msg, "msg 不应为 null"); + assertTrue(msg.contains("【文档分类·入参绑定失败】"), "msg 应含入参绑定失败前缀"); + assertNoUpstreamPlatformName(msg, "msg"); + } + + /** + * 假设(Given): imageUrlOrBase64 为空字符串 + * 当(When): 调用 classify 接口 + * 则(Then): 返回 code=200，msg 含【文档分类·影像源缺失】 + */ + @Test + void classifyImageEmptyTest() { + // Arrange + DocClassifyRequest request = new DocClassifyRequest(); + request.setImageUrlOrBase64(""); + + // Act + R result = docClassifyController.recognize(request); + + // Assert + assertNotNull(result, "返回结果不能为空"); + assertEquals("200", result.getCode(), "接口应返回成功"); + assertNotNull(result.getData(), "data 不能为 null"); + String msg = result.getMsg(); + assertNotNull(msg, "msg 不应为 null"); + assertTrue(msg.contains("【文档分类·影像源缺失】"), "msg 应含影像源缺失前缀"); + assertNoUpstreamPlatformName(msg, "msg"); + } + + /** + * 假设(Given): imageUrlOrBase64 为非法 Base64 + * 当(When): 调用 classify 接口 + * 则(Then): 返回 code=200，msg 含分类错误信息 + */ + @Test + void classifyInvalidBase64Test() { + // Arrange + DocClassifyRequest request = new DocClassifyRequest(); + request.setImageUrlOrBase64("not_a_valid_base64!!!"); + + // Act + R result = docClassifyController.recognize(request); + + // Assert + assertNotNull(result, "返回结果不能为空"); + assertEquals("200", result.getCode(), "接口应返回成功"); + assertNotNull(result.getData(), "data 不能为 null"); + String msg = result.getMsg(); + assertNotNull(msg, "msg 不应为 null"); + assertTrue(msg.startsWith("【文档分类·"), "msg 应含文档分类前缀"); + assertNoUpstreamPlatformName(msg, "msg"); + } + + /** + * 假设(Given): imageUrlOrBase64 为非法 URL（ftp 协议） + * 当(When): 调用 classify 接口 + * 则(Then): 返回 code=200，msg 含链接协议无效 + */ + @Test + void classifyInvalidUrlProtocolTest() { + // Arrange + DocClassifyRequest request = new DocClassifyRequest(); + request.setImageUrlOrBase64("ftp://example.com/image.png"); + + // Act + R result = docClassifyController.recognize(request); + + // Assert + assertNotNull(result, "返回结果不能为空"); + assertEquals("200", result.getCode(), "接口应返回成功"); + assertNotNull(result.getData(), "data 不能为 null"); + String msg = result.getMsg(); + assertTrue(msg.contains("【文档分类·"), "msg 应含文档分类前缀"); + assertNoUpstreamPlatformName(msg, "msg"); + } + + // ===================== 识别成功场景 ===================== + + /** + * 假设(Given): 目标图片可访问，百度 API 可用 + * 当(When): 调用 classify 接口，传入图片 URL + * 则(Then): 返回 code=200，data 不为 null 且含分类结果 + */ @Test void classifyByUrlTest() { - // 1. 构造请求 - BDocClassifyRequest request = new BDocClassifyRequest(); - request.setImageUrl(TestConstant.TARGET_IMAGE_URL); + // Arrange + DocClassifyRequest request = new DocClassifyRequest(); + request.setImageUrlOrBase64(TestConstant.TARGET_IMAGE_URL); - // 2. 打印请求参数 - System.out.println("\n========== 请求参数 =========="); - System.out.println(JSON.toJSONString(request)); - System.out.println("=============================="); + // Act + R result = docClassifyController.recognize(request); - // 3. 调用本地 /doc/classify 接口 - R