提交修改

api-web/api-interface/src/main/java/com/heyu/api/controller/car/RecognizeDriverLicenseController.java

@@ -20,28 +20,83 @@ import java.util.Map;
 /**
  * 驾驶证识别控制器
  * <p>
- * 对机动车驾驶证正页、副页及电子驾驶证正页进行结构化识别。
+ * 能力说明：对机动车驾驶证<strong>正页</strong>、<strong>副页</strong>及<strong>电子驾驶证正页</strong>进行结构化识别，
- * 校验、请求组装、结果封装及异常处理均在 Controller 层完成。
+ * 底层对接百度智能云文字识别「驾驶证识别」能力，由本服务完成参数校验、请求转发与字段映射。
- * </p>
- * <p>
- * 接口路径：POST /driver/license/recognize
- * </p>
- * <p>
- * 返回约定：进入平台识别链路（组装请求体之后）一律 {@code R.ok()}；若有异常则将详细提示写入 {@code msg}。
- * 仅入参校验失败时返回 {@code R.error()}（未调用平台识别、不计费）。
  * </p>
  *
+ * <h3>百度官方文档</h3>
+ * <ul>
+ *   <li>产品文档：<a href="https://cloud.baidu.com/doc/OCR/s/Vk3h7xzz7">驾驶证识别</a></li>
+ *   <li>接口地址：{@code POST https://aip.baidubce.com/rest/2.0/ocr/v1/driving_license}</li>
+ * </ul>
+ *
+ * <h3>本服务接口</h3>
+ * <ul>
+ *   <li>路径：{@code POST /driver/license/recognize}</li>
+ *   <li>Content-Type：{@code application/x-www-form-urlencoded}</li>
+ *   <li>鉴权：{@link EbAuthentication}（Tencent 鉴权头，见项目网关配置）</li>
+ * </ul>
+ *
+ * <h3>请求参数（{@link DriverLicenseRecognizeRequest}）</h3>
+ * <table>
+ *   <tr><th>字段</th><th>必填</th><th>说明</th></tr>
+ *   <tr><td>imageBase64</td><td>与 imageUrl 二选一</td>
+ *       <td>图片 Base64，需 urlencode；编码后≤4M；支持 jpg/jpeg/png/bmp；优先级高于 url</td></tr>
+ *   <tr><td>imageUrl</td><td>与 imageBase64 二选一</td>
+ *       <td>图片完整 URL，≤1024 字节；需公网可访问并关闭防盗链</td></tr>
+ *   <tr><td>side</td><td>否，默认 face</td>
+ *       <td>{@code face}/{@code front}：正页/电子证正页；{@code back}：副页。
+ *           映射百度参数 {@code driving_license_side=front|back}</td></tr>
+ * </table>
+ *
+ * <h3>返回结构（统一包装 {@link R}）</h3>
+ * <pre>
+ * {
+ *   "code": "200",           // 成功为 200；仅入参非法时为 400
+ *   "msg": "...",            // 成功默认文案；业务异常时写入详细提示（仍可能 code=200）
+ *   "traceId": "...",
+ *   "data": { ... }          // 见下方 data 结构，失败时可能为空对象
+ * }
+ * </pre>
+ * <p><b>返回约定（重要）：</b></p>
+ * <ul>
+ *   <li>入参校验失败：{@code R.error()}，<strong>未调用百度、不计费</strong></li>
+ *   <li>已调用百度识别链路：一律 {@code R.ok()}；若图片/平台/识别异常，将说明写入 {@code msg}，
+ *       {@code data} 可能为空或字段不全（对外不暴露「百度」字样，日志内可排查）</li>
+ * </ul>
+ *
+ * <h3>data 结构（按 side 区分）</h3>
+ * <p><b>正页 / 电子证正页</b>（{@link RecognizeDriverLicenseFaceResp}，side=face 或 front）：</p>
+ * <ul>
+ *   <li>纸质正页常见字段：licenseNumber 证号、name 姓名、gender 性别、nationality 国籍、
+ *       birthDate 出生日期、issueDate 初次领证日期、vehicleType 准驾车型、startDate 有效起始日期、
+ *       endDate 失效日期、address 住址、issueUnit 发证单位</li>
+ *   <li>电子驾驶证正页额外：accumulatedPoints 累积记分、status 状态、archiveNumber 档案编号、
+ *       generateTime 生成时间、currentTime 当前时间、barcodeNumber 条形码下编号</li>
+ * </ul>
+ * <p><b>副页</b>（{@link RecognizeDriverLicenseBackResp}，side=back）：</p>
+ * <ul>
+ *   <li>name 姓名、record 记录、cardNumber 证号、archiveNumber 档案编号</li>
+ * </ul>
+ *
+ * <p>字段与百度 {@code words_result} 中中文 key 的对应关系见
+ * <a href="https://cloud.baidu.com/doc/OCR/s/Vk3h7xzz7">官方返回示例</a>。</p>
+ *
  * @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<String, String> PLATFORM_ERROR_HINTS = new HashMap<>();
 
     static {
@@ -63,6 +118,31 @@ public class RecognizeDriverLicenseController extends BaseController {
         PLATFORM_ERROR_HINTS.put("282000", "平台识别引擎内部异常，属短暂性故障，可间隔数秒后重试");
     }
 
+    /**
+     * 驾驶证识别
+     * <p>
+     * 请求示例（form 表单）：
+     * </p>
+     * <pre>
+     * POST /driver/license/recognize
+     * Content-Type: application/x-www-form-urlencoded
+     *
+     * imageUrl=https://example.com/license.jpg&amp;side=face
+     * // 或 imageBase64=xxx&amp;side=back
+     * </pre>
+     * <p>
+     * 成功示例（正页，data 为 {@link RecognizeDriverLicenseFaceResp}）：
+     * </p>
+     * <pre>
+     * { "code":"200", "msg":"成功", "data": { "licenseNumber":"...", "name":"...", "vehicleType":"C1", ... } }
+     * </pre>
+     * <p>
+     * 已调用百度但识别异常时仍返回 code=200，msg 中带处置指引，data 可能为空对象。
+     * </p>
+     *
+     * @param request 驾驶证识别请求，字段见类注释「请求参数」
+     * @return 正页/电子证正页返回 {@link RecognizeDriverLicenseFaceResp}；副页返回 {@link RecognizeDriverLicenseBackResp}
+     */
     @EbAuthentication(tencent = ApiConstants.TENCENT_AUTH)
     @PostMapping("/recognize")
     public R recognize(DriverLicenseRecognizeRequest request) {