kknongchang_2506/app/Module/OpenAPI/Handlers/Transfer/TransferInHandler.php

<?php

namespace App\Module\OpenAPI\Handlers\Transfer;

use App\Module\OpenAPI\Handlers\BaseHandler;
use App\Module\OpenAPI\Enums\SCOPE_TYPE;
use App\Module\Transfer\Services\TransferService;
use App\Module\Transfer\Validations\TransferInValidation;
use Illuminate\Http\JsonResponse;

/**
 * 转入处理器
 * 处理外部应用向用户转入资金的请求
 */
class TransferInHandler extends BaseHandler
{
    /**
     * 获取所需权限范围
     * 
     * @return array
     */
    public function getRequiredScopes(): array
    {
        return [SCOPE_TYPE::TRANSFER_IN];
    }

    /**
     * 处理转入请求
     * 
     * @param array $data 请求数据
     * @param array $context 上下文信息
     * @return JsonResponse
     */
    public function handle(array $data, array $context = []): JsonResponse
    {
        try {
            // 验证权限
            if (!$this->validatePermissions($context['app']->scopes ?? [], $context)) {
                return $this->errorResponse('权限不足', null, 403);
            }

            // 添加应用ID到数据中
            $data['transfer_app_id'] = $context['app']->id ?? null;
            if (!$data['transfer_app_id']) {
                return $this->errorResponse('应用ID缺失', null, 400);
            }

            // 验证请求数据
            $validation = new TransferInValidation($data);
            if (!$validation->validate()) {
                return $this->errorResponse('数据验证失败', $validation->getErrors(), 422);
            }

            // 获取验证后的数据
            $validatedData = $validation->getValidatedData();

            // 调用Transfer服务创建转入订单
            $result = TransferService::createTransferIn(
                transferAppId: $validatedData['transfer_app_id'],
                userId: $validatedData['user_id'],
                businessId: $validatedData['business_id'],
                amount: $validatedData['amount'],
                outUserId: $validatedData['out_user_id'] ?? null,
                remark: $validatedData['remark'] ?? null,
                callbackData: $validatedData['callback_data'] ?? []
            );

            if (is_string($result)) {
                // 返回错误信息
                return $this->errorResponse($result, null, 400);
            }

            // 记录操作日志
            $this->logAction('transfer.in.create', [
                'order_id' => $result->id,
                'business_id' => $result->out_order_id,
                'amount' => $result->out_amount,
                'user_id' => $result->user_id
            ], $context);

            // 返回成功响应
            return $this->successResponse('转入订单创建成功', [
                'order_id' => $result->id,
                'business_id' => $result->out_order_id,
                'amount' => $result->out_amount,
                'internal_amount' => $result->amount,
                'exchange_rate' => $result->exchange_rate,
                'status' => $result->status->value,
                'status_text' => $result->status->getDescription(),
                'created_at' => $result->created_at->toISOString()
            ]);

        } catch (\Exception $e) {
            // 记录错误日志
            $this->logError('transfer.in.error', $e, $context);

            return $this->errorResponse('转入处理失败', [
                'error' => $e->getMessage()
            ], 500);
        }
    }

    /**
     * 获取Handler描述
     * 
     * @return string
     */
    public function getDescription(): string
    {
        return '处理外部应用向用户转入资金的请求';
    }

    /**
     * 获取请求参数说明
     * 
     * @return array
     */
    public function getRequestParameters(): array
    {
        return [
            'business_id' => [
                'type' => 'string',
                'required' => true,
                'description' => '外部业务订单ID，用于防重复提交'
            ],
            'user_id' => [
                'type' => 'integer',
                'required' => true,
                'description' => '目标用户ID'
            ],
            'amount' => [
                'type' => 'string',
                'required' => true,
                'description' => '转入金额（外部应用金额）'
            ],
            'out_user_id' => [
                'type' => 'string',
                'required' => false,
                'description' => '外部用户ID（可选）'
            ],
            'remark' => [
                'type' => 'string',
                'required' => false,
                'description' => '备注信息'
            ],
            'callback_data' => [
                'type' => 'object',
                'required' => false,
                'description' => '回调数据，将在回调时原样返回'
            ]
        ];
    }

    /**
     * 获取响应参数说明
     * 
     * @return array
     */
    public function getResponseParameters(): array
    {
        return [
            'order_id' => [
                'type' => 'integer',
                'description' => '内部订单ID'
            ],
            'business_id' => [
                'type' => 'string',
                'description' => '外部业务订单ID'
            ],
            'amount' => [
                'type' => 'string',
                'description' => '外部金额'
            ],
            'internal_amount' => [
                'type' => 'string',
                'description' => '内部金额（按汇率转换后）'
            ],
            'exchange_rate' => [
                'type' => 'string',
                'description' => '使用的汇率'
            ],
            'status' => [
                'type' => 'integer',
                'description' => '订单状态值'
            ],
            'status_text' => [
                'type' => 'string',
                'description' => '订单状态描述'
            ],
            'created_at' => [
                'type' => 'string',
                'description' => '创建时间（ISO格式）'
            ]
        ];
    }
}