统一佣金计算与下单结算方案

引擎只返回金额和来源，不判断数据库中的实时剩余预算。正式结算时，CommissionPostingService 对引擎输出的营销明细执行原子核销；核销失败只移除对应营销行，不改变其他金额，也不在业务模块重新计算。

完整计算示例

以下均为 minor 单位：订单金额 = 1,000,000、平台佣金 = 180,000、佣金基数上限 40%、技术服务费 10%、买家分成 70%、直接邀请人按买家返现的 20%。

基础分配 买家基础返现 + 直接邀请佣金 = 136,080 ≤ 净佣金；买家总返现超过 佣金基数 的 1,440 来自独立营销预算，符合资金边界。

默认分成规则按 countryCode + productType + cpsTier 匹配。CPS 阶梯按 minCpsBps/maxCpsBps 匹配，每档各自携带并必填 technicalServiceFeeBps、buyerShareBps 和 directShareBps（无全局回落，缺字段的档会被拒绝发布），本身不直接产生金额。

默认 CPS 阶梯

record ProductCommissionSplitOverride(
    Integer buyerShareBps,
    Integer directShareBps
) {}

COUPON_CASHBACK

完成时间筛出所有有效且适用本单的返现券，逐张通过统一引擎计算，选择金额最高的一张；金额相同时依次选择到期时间最早、券 ID 字典序最小的记录。预览不核销，正式结算在事务内锁定并核销。

REBATE_FUND

返佣基金只支付给买家。正式结算时余额或总预算不足，本单整条 REBATE_FUND 跳过，不按剩余额度部分发放，也不影响其他佣金行。

ACTIVITY_CASHBACK

确定性幂等键

活动预算必须维护可原子更新的 usedAmountMinor，通过“当前已用 + 本次金额不超过总预算”的条件更新抢占。禁止在结算时临时汇总历史记录后再判断，否则并发订单会超发。

退款不重新运行佣金计算引擎。Pending 冲正必须引用原佣金记录和原钱包账本；只有原规则定义为可恢复且仍能安全恢复的营销资源才退回。

统一应用接口

CommissionCalculationResult preview(CommissionPreviewCommand command);
CommissionCalculationResult settle(String orderId);
RefundHandlingResult handleRefund(String orderId, String platformRefundId);

核心引擎参考实现（Java 17）

public final class CommissionCalculationEngine {

    public CommissionCalculationResult calculate(ResolvedCommissionContext context) {
        validate(context);

        if (!context.productType().commissionable()
                || context.gmvMinor() == 0
                || context.platformCommissionMinor() == 0) {
            return CommissionCalculationResult.zero(context);
        }

        long actualCpsBps = multiplyDivide(
                context.platformCommissionMinor(), 10_000, context.gmvMinor());
        CommissionSplit split = context.splitRule().resolve(
                context.productType(), actualCpsBps, context.productOverride());

        long commissionBaseMinor = Math.min(
                context.platformCommissionMinor(),
                multiplyBps(context.gmvMinor(), context.maxCommissionBaseBps()));
        long technicalFeeMinor =
                multiplyBps(commissionBaseMinor, split.technicalServiceFeeBps());
        long netCommissionMinor = commissionBaseMinor - technicalFeeMinor;
        long userCashbackMinor =
                multiplyBps(netCommissionMinor, split.buyerShareBps());
        long directCommissionMinor = context.directInviterEligible()
                ? multiplyBps(userCashbackMinor, split.directShareBps())
                : 0;

        if (userCashbackMinor + directCommissionMinor > netCommissionMinor) {
            throw new InvalidCommissionConfigurationException(
                    "USER_CASHBACK + DIRECT_COMMISSION exceeds net commission");
        }

        CommissionLine userCashback = CommissionLine.userCashback(
                context.orderId(), context.buyerUserId(), userCashbackMinor);
        Optional<CommissionLine> directCommission =
                directCommissionMinor == 0
                        ? Optional.empty()
                        : Optional.of(CommissionLine.direct(
                                context.orderId(),
                                context.directInviterUserId(),
                                directCommissionMinor));

        Optional<CommissionLine> coupon = context.coupons().stream()
                .map(candidate -> calculateCoupon(candidate, userCashbackMinor))
                .sorted(CommissionLine.bestCouponFirst())
                .findFirst();
        Optional<CommissionLine> rebateFund = context.rebateFund()
                .map(candidate -> calculateRebateFund(candidate, userCashbackMinor));
        List<CommissionLine> activities = context.activities().stream()
                .map(candidate -> calculateActivity(candidate, userCashbackMinor))
                .filter(line -> line.amountMinor() > 0)
                .toList();

        return CommissionCalculationResult.of(
                actualCpsBps,
                commissionBaseMinor,
                technicalFeeMinor,
                netCommissionMinor,
                split,
                userCashback,
                directCommission,
                coupon,
                rebateFund,
                activities);
    }

    private long multiplyBps(long amountMinor, int bps) {
        return Math.multiplyExact(amountMinor, bps) / 10_000;
    }

    private long multiplyDivide(long value, long multiplier, long divisor) {
        return Math.multiplyExact(value, multiplier) / divisor;
    }
}

生产实现应继续使用项目统一的金额溢出处理；Java 17 获取列表首项使用 get(0)，不能使用更高版本才提供的 getFirst()。

必要数据字段