税收系统（开发者指南）

QuickShop 的税收系统允许服主与开发者定义交易税收的计算、分配及拓展方式。

在 6.2.0.11，完全重写后的税收系统提供如下内容：

• 灵活的 TaxManager
• 可插入的 TaxProvider 支持
• 渐进式税收
• 税收指向（商店拥有者、交互玩家，或兼顾两者）
• 对第三方拓展的自定义扩展能力

本教程将会引导你在代码层面使用税收系统。

---

概览

税收系统由三个主要部分组成：

TaxManager
负责处理税务的计算与执行。

TaxProvider
决定税值的计算方式。

Taxates
表示交易的计算税收结果。

该系统旨在允许自定义提供方注册与使用，而不修改现有核心逻辑。

---

获取 TaxManager 实例

为了使用税收系统，你需要先从 ShopManager 返回 TaxManager。

ShopManager manager = api.getShopManager();
TaxManager taxManager = manager.taxManager();

获取后，你可以：

• 获取当前税收配置
• 注册自定义税务提供方
• 计算税值
• 挂钩税务相关事件

---

税收系统如何工作

在商店交易中：

1. 确定基本价格。

2. TaxManager 选择要使用的 TaxProvider。

3. TaxProvider 计算当前收取的税。

4. 产生一个 TaxRates 对象。

5. 系统将税应用于：

   • 店主
   • 参与交互的玩家
   • 或者双方兼顾（取决于配置）

这样的结构就可以在不修改交易逻辑的情况下改变税收行为。

---

TaxProvider

TaxProvider 决定税值的计算方式。

创建你自己的税务提供方可以实现：

• 渐进式税收门槛
• 固定百分比税
• 条件税收规则
• 基于区域的税收
• 基于等级的税收
• 基于时间的税收

提供方的最小示例：

public class MyCustomTaxProvider implements TaxProvider {

    @Override
    public TaxRates calculateTax(TaxContext context) {

        double basePrice = context.getPrice();

        double taxAmount = basePrice * 0.05; // 5% 固定税额

        return new TaxRates()
                .ownerTax(taxAmount)
                .buyerTax(0.0);
    }
}

然后注册：

taxManager.provider(new MyCustomTaxProvider());

注册后，你的提供方就可以用于计算税收。

---

TaxRates

TaxRates 是计算税率的结果。

它通常包含：

• 所有者税金额
• 买方税金额
• 税收总影响
• 元数据（若适用）

交易系统读取税率，并据此使用折扣。

---

渐进式税收

内置的系统支持渐进式税收结构。

这允许服务器管理员基于这些情况调整税收：

• 玩家余额
• 店主余额
• 设定的税收门槛

示例配置概念：

• 0-10000 余额 → 1% 的税收
• 10000–100000 → 2% 的税收
• 100000+ → 3% 的税收

开发者可以在 TaxProvider 中拓展或覆盖逻辑。

---

指定税

新税收系统允许针对这些对象收税：

• 店主
• 参与交互的玩家
• 两者

这是通过配置控制的，但自定义提供方可以通过调整税率输出覆盖分配逻辑。

示例：

return new TaxRates()
        .ownerTax(basePrice * 0.02)
        .buyerTax(basePrice * 0.01);

---

注册自定义 TaxProvider

替换或拓展税收逻辑：

ShopManager manager = api.getShopManager();
TaxManager taxManager = manager.taxManager();

taxManager.provider(new MyCustomTaxProvider());

一次只能注册一个主要提供方。 若需要多个提供方，请在自定义提供方中实现内部授权。

---

税收事件

税收系统与事件系统相结合。

使用的现代事件如下：

ShopEnhancedTaxEvent

代替旧版税收事件，提供改进的内容，包括：

• 交易构造器参考
• TaxRates 对象
• 直到最终执行前都可修改

你可以监听事件，并动态修改税收行为：

@EventHandler
public void onTax(ShopEnhancedTaxEvent event) {

    TaxRates rates = event.getTaxRates();

    // 例如：对 VIP 玩家降低税率
    if (event.getOwner().hasPermission("vip.tax.discount")) {
        rates.ownerTax(rates.getOwnerTax() * 0.5);
    }
}

---

最佳做法

让税收计算保持轻量化。

避免：

• calculateTax 内的大量数据库查询
• 阻止网络调用
• 耗时较长的计算

如果需要复杂逻辑，请在计算执行路径之外预先缓存数据。

确保不返回负数税收，除非有必要。

在进行修改之前，记得验证最终数量。

除非有意覆写，否则需要尊重原配置结构。

---

示例完整实现

public class ExampleTaxAddon {

    public void register(QuickShopAPI api) {

        ShopManager manager = api.getShopManager();
        TaxManager taxManager = manager.taxManager();

        taxManager.provider(new MyCustomTaxProvider());
    }
}

---

总结

新的税收系统旨在：

• 灵活
• 扩展性
• 分离备受关注的内容
• 未来的扩展

通过获取：

ShopManager manager = api.getShopManager();
TaxManager taxManager = manager.taxManager();

你可以完全控制 QuickShop 在交易时计算与应用税收的方式。