mirror of
https://github.com/crmeb/CRMEB.git
synced 2026-10-28 21:40:50 +00:00
278 lines
11 KiB
PHP
278 lines
11 KiB
PHP
<?php
|
||
// +----------------------------------------------------------------------
|
||
// | CRMEB [ CRMEB赋能开发者，助力企业发展 ]
|
||
// +----------------------------------------------------------------------
|
||
// | Copyright (c) 2016~2026 https://www.crmeb.com All rights reserved.
|
||
// +----------------------------------------------------------------------
|
||
// | Author: CRMEB Team <admin@crmeb.com>
|
||
// +----------------------------------------------------------------------
|
||
declare(strict_types=1);
|
||
|
||
namespace crmeb\trade\mode;
|
||
|
||
/**
|
||
* 交易模式处理器接口
|
||
* 定义所有交易模式（即旧称"活动"）必须实现的方法
|
||
* 注意：此接口等同于旧版 ActivityHandlerInterface，仅命名空间变更
|
||
*/
|
||
interface TradeModeHandlerInterface
|
||
{
|
||
/**
|
||
* 获取交易模式标识
|
||
* @return string 例如：seckill, bargain, combination
|
||
*/
|
||
public function getType(): string;
|
||
|
||
/**
|
||
* 获取交易模式中文标签
|
||
* @return string 例如：秒杀, 砍价, 拼团
|
||
*/
|
||
public function getLabel(): string;
|
||
|
||
/**
|
||
* 检查商品是否参与该交易模式
|
||
* @param array $productIds 商品ID数组
|
||
* @return array 返回商品ID为key的数组，值为true/false
|
||
* 例如：[1 => true, 2 => false]
|
||
*/
|
||
public function getProductExist(array $productIds): array;
|
||
|
||
/**
|
||
* 检查单个商品是否参与该交易模式
|
||
* @param int $productId 商品ID
|
||
* @return bool
|
||
*/
|
||
public function isProductInActivity(int $productId): bool;
|
||
|
||
/**
|
||
* 获取商品的交易模式信息
|
||
* @param int $productId 商品ID
|
||
* @return array|null 交易模式信息，无则返回null
|
||
*/
|
||
public function getProductActivity(int $productId): ?array;
|
||
|
||
/**
|
||
* 获取交易模式ID列表
|
||
* @param array $productIds 商品ID数组，为空则获取所有
|
||
* @param array $field 需要返回的字段
|
||
* @return array 返回交易模式ID列表
|
||
*/
|
||
public function getActivityIdsList(array $productIds = [], array $field = []): array;
|
||
|
||
/**
|
||
* 获取交易模式价（活动价）
|
||
* 处理器根据规则返回商品在该交易模式下的价格、库存、限购等信息
|
||
* @param int $productId 中台商品ID
|
||
* @param string $skuUnique SKU唯一码
|
||
* @param int $activityId 交易模式ID
|
||
* @return array 返回价格信息
|
||
* [
|
||
* 'unit_price' => '10.00', // 单价（人民币），普通购买时使用
|
||
* 'total_price' => '20.00', // 总价（人民币）
|
||
* 'currency' => 'money', // 货币类型：money / integral
|
||
* 'currency_amount' => 0, // 当 currency=integral 时，表示积分数量
|
||
* 'stock' => 100, // 库存
|
||
* 'limit' => 1, // 每人限购，0表示不限购
|
||
* ]
|
||
*/
|
||
public function getActivityPrice(int $productId, string $skuUnique, int $activityId): array;
|
||
|
||
/**
|
||
* 校验订单是否满足交易模式规则
|
||
* @param int $productId 中台商品ID
|
||
* @param string $skuUnique SKU唯一码
|
||
* @param int $num 购买数量
|
||
* @param int $activityId 交易模式ID
|
||
* @param int $uid 用户ID
|
||
* @throws \crmeb\exceptions\ApiException 不满足时抛出异常
|
||
*/
|
||
public function validateOrder(int $productId, string $skuUnique, int $num, int $activityId, int $uid): void;
|
||
|
||
/**
|
||
* 获取订单 extra_info 中需要记录的交易模式信息
|
||
* @param int $activityId 交易模式ID
|
||
* @return array
|
||
*/
|
||
public function getOrderExtraInfo(int $activityId): array;
|
||
|
||
/**
|
||
* 获取该交易模式允许的支付方式
|
||
* @param int $activityId 交易模式ID
|
||
* @return array 空数组表示不限制，否则只允许指定方式
|
||
*/
|
||
public function getAllowedPayTypes(int $activityId): array;
|
||
|
||
/**
|
||
* 是否不需要真实货币支付（如积分兑换、0元砍价）
|
||
* @param int $activityId 交易模式ID
|
||
* @return bool
|
||
*/
|
||
public function isFreePay(int $activityId): bool;
|
||
|
||
/**
|
||
* 免费支付使用的支付方式标识
|
||
* isFreePay 返回 true 时生效，前端据此调用 orderPay 接口完成 0 元支付
|
||
* @param int $activityId 交易模式ID
|
||
* @return string 支付方式标识，默认 'free'
|
||
*/
|
||
public function getFreePayType(int $activityId): string;
|
||
|
||
/**
|
||
* 免费支付完成后的跳转地址
|
||
* 地址中可含 {order_no} 占位符，前端替换为实际订单号
|
||
* @param int $activityId 交易模式ID
|
||
* @return string 跳转地址，空字符串表示走默认收银台流程
|
||
*/
|
||
public function getPayRedirectUrl(int $activityId): string;
|
||
|
||
/**
|
||
* 创建订单前校验
|
||
* 例如：砍价是否已完成、预售是否开始、拼团是否可参与
|
||
* @param int $productId 中台商品ID
|
||
* @param string $skuUnique SKU唯一码
|
||
* @param int $num 购买数量
|
||
* @param int $activityId 交易模式ID
|
||
* @param int $uid 用户ID
|
||
*/
|
||
public function beforeCreateOrder(int $productId, string $skuUnique, int $num, int $activityId, int $uid): void;
|
||
|
||
/**
|
||
* 创建订单后回调
|
||
* 例如：拼团记录创建、砍价订单关联
|
||
* @param string $orderNo 订单号
|
||
* @param int $activityId 交易模式ID
|
||
* @param array $orderInfo 订单信息
|
||
*/
|
||
public function afterOrderCreate(string $orderNo, int $activityId, array $orderInfo): void;
|
||
|
||
/**
|
||
* 支付前校验
|
||
* 例如：秒杀是否还有库存、拼团是否未过期
|
||
* @param string $orderNo 订单号
|
||
* @param int $activityId 交易模式ID
|
||
* @param array $orderInfo 订单信息
|
||
*/
|
||
public function beforeOrderPay(string $orderNo, int $activityId, array $orderInfo): void;
|
||
|
||
/**
|
||
* 支付处理
|
||
* 例如：积分扣减、定金转正式订单
|
||
* @param string $orderNo 订单号
|
||
* @param int $activityId 交易模式ID
|
||
* @param array $orderInfo 订单信息
|
||
*/
|
||
public function onOrderPay(string $orderNo, int $activityId, array $orderInfo): void;
|
||
|
||
/**
|
||
* 支付成功后回调
|
||
* 例如：拼团状态推进、秒杀库存扣减、砍价状态更新
|
||
* @param string $orderNo 订单号
|
||
* @param int $activityId 交易模式ID
|
||
* @param array $orderInfo 订单信息
|
||
*/
|
||
public function afterOrderPay(string $orderNo, int $activityId, array $orderInfo): void;
|
||
|
||
/**
|
||
* 支付失败回调
|
||
* 用于回滚 onOrderPay 中已经执行的资源扣减（如积分、库存等）
|
||
* @param string $orderNo 订单号
|
||
* @param int $activityId 交易模式ID
|
||
* @param array $orderInfo 订单信息
|
||
*/
|
||
public function onOrderPayFail(string $orderNo, int $activityId, array $orderInfo): void;
|
||
|
||
/**
|
||
* 取消前校验
|
||
* @param string $orderNo 订单号
|
||
* @param int $activityId 交易模式ID
|
||
* @param array $orderInfo 订单信息
|
||
*/
|
||
public function beforeOrderCancel(string $orderNo, int $activityId, array $orderInfo): void;
|
||
|
||
/**
|
||
* 取消后回调
|
||
* 例如：返还积分、回滚库存
|
||
* @param string $orderNo 订单号
|
||
* @param int $activityId 交易模式ID
|
||
* @param array $orderInfo 订单信息
|
||
*/
|
||
public function afterOrderCancel(string $orderNo, int $activityId, array $orderInfo): void;
|
||
|
||
/**
|
||
* 退款前校验
|
||
* @param string $orderNo 订单号
|
||
* @param int $activityId 交易模式ID
|
||
* @param array $orderInfo 订单信息
|
||
*/
|
||
public function beforeOrderRefund(string $orderNo, int $activityId, array $orderInfo): void;
|
||
|
||
/**
|
||
* 退款后回调
|
||
* 例如：返还积分、回滚库存
|
||
* @param string $orderNo 订单号
|
||
* @param int $activityId 交易模式ID
|
||
* @param array $orderInfo 订单信息
|
||
*/
|
||
public function afterOrderRefund(string $orderNo, int $activityId, array $orderInfo): void;
|
||
|
||
/**
|
||
* 订单完成回调
|
||
* @param string $orderNo 订单号
|
||
* @param int $activityId 交易模式ID
|
||
* @param array $orderInfo 订单信息
|
||
*/
|
||
public function onOrderComplete(string $orderNo, int $activityId, array $orderInfo): void;
|
||
|
||
/**
|
||
* 获取订单详情扩展数据
|
||
* 例如：拼团显示团员列表、砍价显示砍价进度、积分显示消耗积分
|
||
* @param string $orderNo 订单号
|
||
* @param int $activityId 交易模式ID
|
||
* @param array $orderInfo 订单信息
|
||
* @return array
|
||
*/
|
||
public function getOrderDetailExtend(string $orderNo, int $activityId, array $orderInfo): array;
|
||
|
||
/**
|
||
* 获取交易模式专属按钮
|
||
* 例如：拼团显示"邀请好友"、砍价显示"继续砍价"
|
||
* @param string $orderNo 订单号
|
||
* @param int $activityId 交易模式ID
|
||
* @param array $orderInfo 订单信息
|
||
* @return array
|
||
*/
|
||
public function getActivityButtons(string $orderNo, int $activityId, array $orderInfo): array;
|
||
|
||
/**
|
||
* 获取旧版数字 type 协议
|
||
* 兼容购物车/下单接口的旧版数字交易类型（0=普通、1=秒杀、2=砍价、3=拼团、6=预售）
|
||
* 由 TradeModeRegistry::getByLegacyType() 用于将旧版数字 type 解析为交易模式处理器
|
||
* @return int 旧版数字 type，默认 0 表示普通购买
|
||
*/
|
||
public function getLegacyType(): int;
|
||
|
||
/**
|
||
* 是否为营销类交易模式（可参与活动）
|
||
* 基础交易模式（普通购买、会员购买等）返回 false，
|
||
* 营销活动（秒杀/砍价/拼团/积分等）返回 true，
|
||
* 商品列表「参与活动」标签、商品操作活动检查等场景仅针对营销类交易模式，
|
||
* 新增营销活动由 Handler 自行声明，无需改动调用方
|
||
* @return bool
|
||
*/
|
||
public function isMarketingActivity(): bool;
|
||
|
||
/**
|
||
* 购物车阶段库存校验（加购/立即购买时调用）
|
||
* 各交易模式在此校验活动有效性、限购数量与 SKU 库存，不满足时抛出 ApiException
|
||
* 返回空数组表示该交易模式不参与购物车校验，由调用方回退到普通购买逻辑
|
||
* @param int $uid 用户ID
|
||
* @param int $cartNum 购买数量
|
||
* @param string $unique SKU唯一码
|
||
* @param int $activityId 交易模式ID（秒杀/砍价/拼团活动ID，普通购买为0）
|
||
* @param int $productId 中台商品ID
|
||
* @return array 返回 [attrInfo, unique, productInfo, activityInfo]
|
||
* activityInfo 为交易模式附加信息（如砍价的 bargainUserInfo），无则为空数组
|
||
*/
|
||
public function checkCartStock(int $uid, int $cartNum, string $unique, int $activityId, int $productId): array;
|
||
}
|