diff --git a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/RecognizeDriverLicenseController.java b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/RecognizeDriverLicenseController.java index fe74153..559be82 100644 --- a/api-web/api-interface/src/main/java/com/heyu/api/controller/car/RecognizeDriverLicenseController.java +++ b/api-web/api-interface/src/main/java/com/heyu/api/controller/car/RecognizeDriverLicenseController.java @@ -20,28 +20,83 @@ import java.util.Map; /** * 驾驶证识别控制器 *

- * 对机动车驾驶证正页、副页及电子驾驶证正页进行结构化识别。 - * 校验、请求组装、结果封装及异常处理均在 Controller 层完成。 - *

- *

- * 接口路径：POST /driver/license/recognize - *

- *

- * 返回约定：进入平台识别链路（组装请求体之后）一律 {@code R.ok()}；若有异常则将详细提示写入 {@code msg}。 - * 仅入参校验失败时返回 {@code R.error()}（未调用平台识别、不计费）。 + * 能力说明：对机动车驾驶证正页、副页及电子驾驶证正页进行结构化识别， + * 底层对接百度智能云文字识别「驾驶证识别」能力，由本服务完成参数校验、请求转发与字段映射。 *

* + *

百度官方文档

+ * + * + *

本服务接口

+ * + * + *

请求参数（{@link DriverLicenseRecognizeRequest}）

+ * + * + * + * + * + * + * + * + *
字段必填说明
imageBase64与 imageUrl 二选一图片 Base64，需 urlencode；编码后≤4M；支持 jpg/jpeg/png/bmp；优先级高于 url
imageUrl与 imageBase64 二选一图片完整 URL，≤1024 字节；需公网可访问并关闭防盗链
side否，默认 face{@code face}/{@code front}：正页/电子证正页；{@code back}：副页。 + * 映射百度参数 {@code driving_license_side=front|back}
+ * + *

返回结构（统一包装 {@link R}）

+ * 
+ * {
+ *   "code": "200",           // 成功为 200；仅入参非法时为 400
+ *   "msg": "...",            // 成功默认文案；业务异常时写入详细提示（仍可能 code=200）
+ *   "traceId": "...",
+ *   "data": { ... }          // 见下方 data 结构，失败时可能为空对象
+ * }
+ *
+ *

返回约定（重要）：

+ * + * + *

data 结构（按 side 区分）

+ *

正页 / 电子证正页（{@link RecognizeDriverLicenseFaceResp}，side=face 或 front）：

+ * + *

副页（{@link RecognizeDriverLicenseBackResp}，side=back）：

+ * + * + *

字段与百度 {@code words_result} 中中文 key 的对应关系见 + * 官方返回示例。

+ * * @author heyu * @since 1.0.0 + * @see DriverLicenseRecognizeRequest + * @see RecognizeDriverLicenseFaceResp + * @see RecognizeDriverLicenseBackResp */ @Slf4j @RestController @RequestMapping("/driver/license") public class RecognizeDriverLicenseController extends BaseController { + /** 百度驾驶证识别 API 路径，完整地址见类注释 */ private static final String DRIVING_LICENSE_URI = "/rest/2.0/ocr/v1/driving_license"; - /** 平台错误码 → 对外原因说明（每条语义独立，便于客服判读） */ + /** 百度 error_code → 对外 msg 原因说明（日志与返回 msg 使用「平台」表述，注释可写百度） */ private static final Map PLATFORM_ERROR_HINTS = new HashMap<>(); static { @@ -63,6 +118,31 @@ public class RecognizeDriverLicenseController extends BaseController { PLATFORM_ERROR_HINTS.put("282000", "平台识别引擎内部异常，属短暂性故障，可间隔数秒后重试"); } + /** + * 驾驶证识别 + *

+ * 请求示例（form 表单）： + *

+ * 
+     * POST /driver/license/recognize
+     * Content-Type: application/x-www-form-urlencoded
+     *
+     * imageUrl=https://example.com/license.jpg&side=face
+     * // 或 imageBase64=xxx&side=back
+     *
+ *

+ * 成功示例（正页，data 为 {@link RecognizeDriverLicenseFaceResp}）： + *

+ * 
+     * { "code":"200", "msg":"成功", "data": { "licenseNumber":"...", "name":"...", "vehicleType":"C1", ... } }
+     *
+ *

+ * 已调用百度但识别异常时仍返回 code=200，msg 中带处置指引，data 可能为空对象。 + *

+ * + * @param request 驾驶证识别请求，字段见类注释「请求参数」 + * @return 正页/电子证正页返回 {@link RecognizeDriverLicenseFaceResp}；副页返回 {@link RecognizeDriverLicenseBackResp} + */ @EbAuthentication(tencent = ApiConstants.TENCENT_AUTH) @PostMapping("/recognize") public R recognize(DriverLicenseRecognizeRequest request) {