package com.ylx.massage.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.ylx.common.core.domain.R;
import com.ylx.massage.domain.TRecharge;
import com.ylx.massage.domain.TWxUser;

import java.math.BigDecimal;
import java.util.Date;

/**
 * 充值记录服务接口
 * <p>
 * 提供充值记录管理、支付处理、退款等核心功能的业务接口。
 * 继承自 MyBatis-Plus 的 IService 接口，提供基础的 CRUD 操作。
 * </p>
 *
 * @author ylx
 * @version 1.0
 * @since 2024
 */
public interface TRechargeService extends IService<TRecharge> {

    /**
     * 处理用户充值请求
     * <p>
     * 创建充值记录并处理充值业务逻辑，包括充值金额验证、
     * 余额更新、充值记录保存等操作。
     * </p>
     *
     * @param recharge 充值记录实体，包含充值金额、用户ID等信息
     * @return 处理后的充值记录实体，包含生成的充值单号等信息
     */
    TRecharge recharge(TRecharge recharge);

    /**
     * 增加用户账户余额
     * <p>
     * 根据充值单号查找对应的充值记录，并将充值金额增加到用户账户余额中。
     * 通常在支付成功回调后调用此方法。
     * </p>
     *
     * @param rechargeNo 充值单号，用于唯一标识一笔充值订单
     * @return 更新后的充值记录实体
     */
    TRecharge increaseAmount(String rechargeNo);

    /**
     * 发起微信支付
     * <p>
     * 调用微信支付统一下单接口，生成支付参数返回给小程序端。
     * 小程序端根据返回的支付参数调起微信支付。
     * </p>
     *
     * @param setOutTradeNo 商户订单号，需保持唯一性
     * @param amount 支付金额，单位为元
     * @param openId 微信用户 OpenID，用于标识支付用户
     * @param description 商品描述，显示在支付详情页
     * @param attach 附加数据，在查询API和支付通知中原样返回，可作为自定义参数使用
     * @return R 支付参数结果对象，包含小程序支付所需的参数
     * @throws Exception 当微信支付接口调用失败时抛出异常
     */
    R getPay(String setOutTradeNo, BigDecimal amount, String openId, String description, String attach) throws Exception;

    /**
     * 退款接口
     * <p>
     * 此方法根据给定的退款编号、交易ID和原始交易订单号处理退款请求。
     * 调用微信退款接口进行退款操作。
     * </p>
     *
     * @param outRefundNo 商户系统内部的退款单号，对同一个退款单号多次提交退款请求，只退一次
     * @param transactionId 支付交易号，通过此交易号可以追溯交易支付时的信息
     * @param outTradeNo 商户系统内部的订单号，与transactionId不能同时为空
     * @param amount 退款金额，单位为元
     * @return String 如果退款成功，返回退款成功的标识字符串；如果失败，返回错误信息字符串
     */
    String refund(String outRefundNo, String transactionId, String outTradeNo, BigDecimal amount);

    /**
     * 统计指定技师的充值金额
     * <p>
     * 查询在指定时间范围内，特定技师的累计充值金额。
     * 可用于技师业绩统计、报表生成等场景。
     * </p>
     *
     * @param jsid 技师ID，用于标识具体的技师
     * @param startDate 统计开始日期
     * @param endDate 统计结束日期
     * @return 在指定时间范围内的累计充值金额
     */
    BigDecimal getRecharge(String jsid, Date startDate, Date endDate);

    /**
     * 关闭微信支付订单
     * <p>
     * 调用微信支付关单接口，关闭未支付订单的支付链路。
     * 如果订单从未唤起过支付（用户刚下单就取消），微信侧无订单，
     * 关单会返回特定错误码，此时忽略错误即可。
     * </p>
     *
     * @param outTradeNo 商户订单号
     * @return boolean 关闭成功返回true，失败返回false（特定错误码视为成功）
     */
    boolean closeWeChatOrder(String outTradeNo);

    int getLatestRechargeAmount(String openId, Date rechargeQueryTime);
}
