kknongchang_2506/app/Module/Point/Logic/User.php

<?php

namespace App\Module\Point\Logic;

use App\Module\Point\Enums\LOG_TYPE;
use App\Module\Point\Models\PointLogModel;
use App\Module\Point\Models\PointModel;

/**
 * 用户积分操作逻辑类
 *
 * 处理用户积分的增减操作，专注于整数积分处理
 * 包括积分变更和日志记录
 */
class User
{
    /**
     * 处理用户积分操作
     *
     * @param int $userId 用户ID
     * @param int $pointId 积分类型ID
     * @param int $amount 积分数量（正数为增加，负数为减少）
     * @param LOG_TYPE $logType 日志类型
     * @param string $operateId 操作ID
     * @param string $remark 备注
     * @return bool|string 成功返回true，失败返回错误信息
     */
    public static function handle(int $userId, int $pointId, int $amount, LOG_TYPE $logType, string $operateId, string $remark)
    {
        if ($amount == 0) {
            return '积分数量不能为0';
        }

        # 获取当前积分余额
        $beforeBalance = PointModel::getBalance($userId, $pointId);

        # 计算操作后余额
        $laterBalance = $beforeBalance + $amount;

        # 检查余额是否足够（减少积分时）
        if ($amount < 0 && $beforeBalance < abs($amount)) {
            return '积分余额不足';
        }

        # 检查操作后余额不能为负数
        if ($laterBalance < 0) {
            return '操作后积分余额不能为负数';
        }

        # 执行积分变更
        if ($amount > 0) {
            # 增加积分
            $result = PointModel::inc($userId, $pointId, $amount);
        } else {
            # 减少积分
            $result = PointModel::dec($userId, $pointId, abs($amount));
        }

        if ($result !== true) {
            return is_string($result) ? $result : '积分操作失败';
        }

        # 记录日志
        $logResult = PointLogModel::createLog(
            $userId,
            $pointId,
            $amount,
            $logType,
            $operateId,
            $remark,
            $beforeBalance,
            $laterBalance
        );

        if (!$logResult) {
            return '积分日志记录失败';
        }

        return true;
    }

    /**
     * 批量处理用户积分操作
     *
     * @param array $operations 操作数组，每个元素包含用户ID、积分类型ID、数量等信息
     * @param LOG_TYPE $logType 日志类型
     * @param string $operateId 操作ID
     * @param string $remark 备注
     * @return array 处理结果数组
     */
    public static function batchHandle(array $operations, LOG_TYPE $logType, string $operateId, string $remark): array
    {
        $results = [];
        
        foreach ($operations as $index => $operation) {
            if (!isset($operation['user_id'], $operation['point_id'], $operation['amount'])) {
                $results[$index] = '操作参数不完整';
                continue;
            }

            $result = self::handle(
                $operation['user_id'],
                $operation['point_id'],
                $operation['amount'],
                $logType,
                $operateId,
                $remark
            );

            $results[$index] = $result;
        }

        return $results;
    }

    /**
     * 检查用户积分余额
     *
     * @param int $userId 用户ID
     * @param int $pointId 积分类型ID
     * @param int $amount 需要检查的积分数量
     * @return bool|string 余额足够返回true，不足返回错误信息
     */
    public static function checkBalance(int $userId, int $pointId, int $amount): bool|string
    {
        if ($amount <= 0) {
            return '检查数量必须大于0';
        }

        $balance = PointModel::getBalance($userId, $pointId);
        
        if ($balance < $amount) {
            return "积分余额不足，当前余额：{$balance}，需要：{$amount}";
        }

        return true;
    }

    /**
     * 获取用户积分账户信息
     *
     * @param int $userId 用户ID
     * @param int|null $pointId 积分类型ID（可选，为空则获取所有）
     * @return array 积分账户信息数组
     */
    public static function getAccountInfo(int $userId, ?int $pointId = null): array
    {
        if ($pointId !== null) {
            $account = PointModel::getAccount($userId, $pointId);
            return $account ? [
                'user_id' => $account->user_id,
                'point_id' => $account->point_id,
                'balance' => $account->balance,
                'create_time' => $account->create_time,
                'update_time' => $account->update_time,
            ] : [];
        }

        $accounts = PointModel::userAccount($userId);
        $result = [];
        
        foreach ($accounts as $account) {
            $result[] = [
                'user_id' => $account->user_id,
                'point_id' => $account->point_id,
                'balance' => $account->balance,
                'create_time' => $account->create_time,
                'update_time' => $account->update_time,
            ];
        }

        return $result;
    }

    /**
     * 冻结用户积分
     *
     * @param int $userId 用户ID
     * @param int $pointId 积分类型ID
     * @param int $amount 冻结积分数量
     * @param string $operateId 操作ID
     * @param string $remark 备注
     * @return bool|string 成功返回true，失败返回错误信息
     */
    public static function freeze(int $userId, int $pointId, int $amount, string $operateId, string $remark)
    {
        return self::handle($userId, $pointId, -$amount, LOG_TYPE::FREEZE, $operateId, $remark);
    }

    /**
     * 解冻用户积分
     *
     * @param int $userId 用户ID
     * @param int $pointId 积分类型ID
     * @param int $amount 解冻积分数量
     * @param string $operateId 操作ID
     * @param string $remark 备注
     * @return bool|string 成功返回true，失败返回错误信息
     */
    public static function unfreeze(int $userId, int $pointId, int $amount, string $operateId, string $remark)
    {
        return self::handle($userId, $pointId, $amount, LOG_TYPE::UNFREEZE, $operateId, $remark);
    }

    /**
     * 退还用户积分
     *
     * @param int $userId 用户ID
     * @param int $pointId 积分类型ID
     * @param int $amount 退还积分数量
     * @param string $operateId 操作ID
     * @param string $remark 备注
     * @return bool|string 成功返回true，失败返回错误信息
     */
    public static function refund(int $userId, int $pointId, int $amount, string $operateId, string $remark)
    {
        return self::handle($userId, $pointId, $amount, LOG_TYPE::REFUND, $operateId, $remark);
    }

    /**
     * 扣除用户积分
     *
     * @param int $userId 用户ID
     * @param int $pointId 积分类型ID
     * @param int $amount 扣除积分数量
     * @param string $operateId 操作ID
     * @param string $remark 备注
     * @return bool|string 成功返回true，失败返回错误信息
     */
    public static function deduct(int $userId, int $pointId, int $amount, string $operateId, string $remark)
    {
        return self::handle($userId, $pointId, -$amount, LOG_TYPE::DEDUCT, $operateId, $remark);
    }
}