提交修改
This commit is contained in:
quyixiao
parent
d58c9c9fd1
commit
6c2d38aa95
@ -20,28 +20,83 @@ import java.util.Map;
|
||||
/**
|
||||
* 驾驶证识别控制器
|
||||
* <p>
|
||||
* 对机动车驾驶证正页、副页及电子驾驶证正页进行结构化识别。
|
||||
* 校验、请求组装、结果封装及异常处理均在 Controller 层完成。
|
||||
* </p>
|
||||
* <p>
|
||||
* 接口路径：POST /driver/license/recognize
|
||||
* </p>
|
||||
* <p>
|
||||
* 返回约定：进入平台识别链路（组装请求体之后）一律 {@code R.ok()}；若有异常则将详细提示写入 {@code msg}。
|
||||
* 仅入参校验失败时返回 {@code R.error()}（未调用平台识别、不计费）。
|
||||
* 能力说明：对机动车驾驶证<strong>正页</strong>、<strong>副页</strong>及<strong>电子驾驶证正页</strong>进行结构化识别，
|
||||
* 底层对接百度智能云文字识别「驾驶证识别」能力，由本服务完成参数校验、请求转发与字段映射。
|
||||
* </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&side=face
|
||||
* // 或 imageBase64=xxx&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) {
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user