<?php
declare(strict_types=1);

namespace addon\paycenter\library\contract;

use think\Response;

/**
 * 支付渠道契约。
 *
 * 新增渠道（如银联、PayPal）只需实现本接口并在 service\Payment::CHANNELS 登记，
 * 业务侧（应用市场等）一行都不用改。
 */
interface Channel
{
    /** 渠道标识：alipay / wechat */
    public function code(): string;

    /** 渠道中文名（后台展示 / 支付方式列表） */
    public function name(): string;

    /** 是否已配置商户参数（未配置时 methods() 不返回该渠道） */
    public function configured(): bool;

    /** 本渠道支持的场景 */
    public function scenes(): array;

    /**
     * 下单（拉起支付）
     *
     * @param array  $order ['trade_no','amount','subject','biz','biz_id','attach','openid'?]
     * @param string $scene web / wap / qr / h5 / mp / mini / app
     * @param array  $urls  ['notify' => 绝对回调地址, 'return' => 同步跳转地址]
     * @return array ['type' => form|qrcode|url|params, 'content' => mixed, 'trade_no' => string]
     */
    public function create(array $order, string $scene, array $urls): array;

    /**
     * 主动查单（回调丢失 / 用户跳回落地页时兜底）
     * @return array ['paid' => bool, 'amount' => float, 'gateway_no' => string]
     */
    public function query(string $tradeNo): array;

    /**
     * 解析并验签异步回调
     * @return array ['paid'=>bool,'trade_no'=>string,'amount'=>float,'gateway_no'=>string]
     */
    public function notify(): array;

    /** 给网关的应答（支付宝要 'success'，微信要 JSON {code:SUCCESS}） */
    public function ack(bool $ok = true): Response;

    /**
     * 退款
     * @return array ['ok'=>bool,'message'=>string]
     */
    public function refund(string $tradeNo, float $amount, float $total): array;
}