package com.heyu.api.controller.qrcode;

import com.heyu.api.baidu.handle.common.BQrCodeHandle;
import com.heyu.api.baidu.request.common.BQrcodeReconizeRequest;
import com.heyu.api.baidu.response.common.BQrcodeReconizeResp;
import com.heyu.api.controller.BaseController;
import com.heyu.api.data.annotation.CacheResult;
import com.heyu.api.data.annotation.NotIntercept;
import com.heyu.api.data.utils.ApiR;
import com.heyu.api.data.utils.R;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * 二维码识别控制器
 * <p>
 * 基于百度 QR Code API，提供二维码/条形码的识别和解析能力。
 * 支持图片 URL 或 Base64 编码两种方式传入图片，自动识别并解析二维码内容。
 * </p>
 * <p>
 * 核心功能：
 * <ul>
 *   <li>二维码识别：支持 QR Code、DataMatrix、PDF417 等格式</li>
 *   <li>条形码识别：支持 EAN-13、EAN-8、Code128 等常见格式</li>
 *   <li>多码检测：单张图片包含多个二维码时全部识别</li>
 *   <li>位置定位：返回二维码在图片中的坐标位置</li>
 * </ul>
 * </p>
 * <p>
 * 适用场景：
 * <ul>
 *   <li>支付扫码：识别微信、支付宝等收款码</li>
 *   <li>票务验证：识别门票、优惠券二维码</li>
 *   <li>信息采集：扫描产品包装、证件上的二维码</li>
 *   <li>链接跳转：识别网址二维码并解析目标 URL</li>
 * </ul>
 * </p>
 * <p>
 * 接口路径：/qrcode/recognize
 * </p>
 *
 * @author heyu
 * @since 1.0.0
 */
@Slf4j
@RestController
@RequestMapping("/qrcode")
@NotIntercept
public class RecognizeQrCodeController extends BaseController {

    @Autowired
    private BQrCodeHandle bqrCodeHandle;

    /**
     * 二维码识别接口
     * <p>
     * 接收图片（URL 或 Base64），调用百度 QR Code API 进行识别和解析。
     * 启用结果缓存，相同图片的识别结果会被缓存以提升响应速度。
     * </p>
     *
     * @param request 二维码识别请求参数，包含以下字段（任选其一）：
     *                - imageBase64：图片 Base64 编码
     *                - imageUrl：图片 URL
     * @return 二维码识别结果，包含二维码内容、类型、位置坐标等信息
     */
    @RequestMapping("/recognize")
    @CacheResult
    public R recognize(BQrcodeReconizeRequest request) {
        ApiR<BQrcodeReconizeResp> bR = bqrCodeHandle.handle(request);
        if (bR.isSuccess()) {
            return R.ok().setData(bR.getData());
        }
        return R.error(bR.getErrorMsg());
    }
}
