/*
 * Copyright (c) 2018-2999 广州市蓝海创新科技有限公司 All rights reserved.
 *
 * https://www.mall4j.com/
 *
 * 未经允许，不可做商业用途！
 *
 * 版权所有，侵权必究！
 */

package com.yami.shop.api.controller;

import com.google.common.collect.Maps;
import com.yami.shop.bean.app.param.SendSmsParam;
import com.yami.shop.bean.enums.SmsType;
import com.yami.shop.security.api.util.SecurityUtils;
import com.yami.shop.service.SmsLogService;
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.Operation;
import org.springframework.beans.factory.annotation.Autowired;
import com.yami.shop.common.response.ServerResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * 发送验证码相关的接口控制器类，主要负责处理发送验证码的业务逻辑，向外提供发送验证码的接口，
 * 通过调用SmsLogService的相关方法来实现验证码的发送，并返回相应的成功响应给客户端。
 *
 * @author lanhai
 */
@RestController
// 设置该控制器类对应的请求映射路径，后续类中的接口方法路径会基于此进行拼接，这里表明是与发送验证码相关接口所在的基础路径。
@RequestMapping("/p/sms")
// 使用 @Tag 注解为该控制器类添加标签说明，用于在 API 文档（如 Swagger 生成的文档）中对该类下的接口进行分类展示，这里表明是“发送验证码接口”相关的一组接口。
@Tag(name = "发送验证码接口")
public class SmsController {

    // 注入SmsLogService，用于处理与短信验证码相关的业务逻辑，例如实际发送短信、记录短信发送日志等操作。
    @Autowired
    private SmsLogService smsLogService;

    /**
     * 发送验证码接口方法，用于接收客户端发送的发送验证码请求，根据请求参数调用相关服务来发送验证码，并返回相应的响应结果给客户端。
     * 通过 @PostMapping 注解将该方法映射到 HTTP 的 POST 请求方式，请求路径为“/send”，意味着客户端需要通过发送POST请求到该路径来调用此发送验证码接口。
     * @Operation 注解用于在 API 文档中对该接口进行详细描述，这里的摘要（summary）和详细描述（description）都表明是发送验证码的功能，方便接口使用者了解接口用途。
     *
     * @param sendSmsParam 包含发送验证码相关参数的请求体对象，例如手机号码等信息，具体字段取决于SendSmsParam类的定义，这些参数将作为发送验证码的依据传递给服务层进行处理。
     * @return 返回一个表示操作成功的ServerResponseEntity对象，由于这里主要是执行发送验证码操作，没有需要返回的具体业务数据，所以返回的是Void类型的成功响应，告知客户端发送验证码请求已受理并处理。
     */
    @PostMapping("/send")
    @Operation(summary = "发送验证码", description = "用户的发送验证码")
    public ServerResponseEntity<Void> audit(@RequestBody SendSmsParam sendSmsParam) {
        // 通过SecurityUtils工具类获取当前登录用户的ID，可能用于记录短信发送与用户的关联关系，或者作为短信发送业务逻辑中的一部分验证等操作。
        String userId = SecurityUtils.getUser().getUserId();
        // 调用SmsLogService的sendSms方法来发送短信验证码，传入短信类型（这里指定为SmsType.VALID，表示验证类型的短信）、用户ID、手机号码以及一个空的Map（可能用于传递一些额外的短信发送配置参数等，目前为空）作为参数，进行短信发送操作。
        smsLogService.sendSms(SmsType.VALID, userId, sendSmsParam.getMobile(), Maps.newHashMap());

        return ServerResponseEntity.success();
    }
}