升鲜宝 生鲜配送 供应链管理系统 SaaS 自动计费引擎核心接口清单

升鲜宝 SaaS 自动计费引擎核心接口清单 

目标：

🔥 分层清晰
🔥 支持订阅 + 用量 + 升级补差 + 自动续费
🔥 可重算 + 幂等 + 可审计
🔥 可插拔价格策略

结构风格：
遵循你升鲜宝 Spring Boot 单体 + 分域包结构

---

一、整体分层结构

 

saas ├── facade │ └── BillingFacade │ ├── service │ ├── PricingService │ ├── UsageService │ ├── InvoiceService │ ├── PaymentService │ ├── SubscriptionService │ └── EntitlementService │ ├── strategy │ ├── PricingStrategy │ ├── FixedPricingStrategy │ ├── PerUnitPricingStrategy │ └── TieredPricingStrategy │ ├── job │ ├── InvoiceGenerateJob │ ├── AutoRenewJob │ └── ExpireEnforcementJob │ └── model ├── InvoiceBuildContext ├── PricingResult ├── UsageSnapshot └── ProrationResult

---

二、1️⃣ BillingFacade（对外统一入口）

计费引擎总门面

 

public interface BillingFacade { /** * 构建账单（幂等） */ InvoiceBuildResult buildInvoice(Long tenantId, Long subscriptionId, Long periodStart, Long periodEnd); /** * 手动重算账单 */ InvoiceBuildResult rebuildInvoice(Long invoiceId); /** * 升级套餐（触发补差） */ ProrationResult upgradePlan(Long tenantId, Long subscriptionId, Long newPlanId); /** * 支付成功回调处理 */ void handlePaymentSuccess(String payNo); /** * 到期检查并冻结 */ void enforceExpiration(Long tenantId); }

---

三、2️⃣ PricingService（价格计算核心）

负责组件级金额计算

 

public interface PricingService { /** * 计算单个组件费用 */ PricingResult calculateComponent(ComponentContext context); /** * 计算阶梯费用 */ BigDecimal calculateTieredPrice(BigDecimal usageValue, List<PriceTier> tiers); /** * 计算按量单价 */ BigDecimal calculatePerUnitPrice(BigDecimal usageValue, BigDecimal unitPrice); /** * 计算固定费用 */ BigDecimal calculateFixedPrice(BigDecimal fixedPrice); /** * 计算升级补差 */ ProrationResult calculateProration(ProrationContext context); }

---

PricingResult

 

@Data public class PricingResult { private String componentCode; private BigDecimal quantity; private BigDecimal unitPrice; private BigDecimal amount; private Map<String, Object> metaData; }

---

四、3️⃣ UsageService（用量读取层）

所有用量来源统一入口

 

public interface UsageService { /** * 获取周期内累计用量 */ BigDecimal getSumUsage(Long tenantId, String meterCode, Long periodStart, Long periodEnd); /** * 获取周期内最大值（快照型） */ BigDecimal getMaxUsage(Long tenantId, String meterCode, Long periodStart, Long periodEnd); /** * 获取某一天用量 */ BigDecimal getDailyUsage(Long tenantId, String meterCode, Long statDate); }

---

五、4️⃣ InvoiceService（账单持久层）

负责落库 + 幂等 + 状态机

 

public interface InvoiceService { /** * 创建账单（带幂等校验） */ TenantInvoiceEntity createInvoice(InvoiceBuildContext context); /** * 写账单明细 */ void createInvoiceItems(Long invoiceId, List<PricingResult> pricingResults); /** * 更新账单状态 */ void updateInvoiceStatus(Long invoiceId, Integer status); /** * 标记已支付 */ void markInvoicePaid(Long invoiceId, BigDecimal paidAmount); /** * 查询待支付账单 */ List<TenantInvoiceEntity> findPendingInvoices(); /** * 根据 bizKey 查询 */ TenantInvoiceEntity findByBizKey(String invoiceBizKey); }

---

六、5️⃣ PaymentService（支付域）

 

public interface PaymentService { /** * 创建支付单 */ TenantPaymentEntity createPayment(Long tenantId, Long invoiceId, BigDecimal amount); /** * 处理支付回调 */ void handleCallback(PaymentCallbackDTO callback); /** * 校验支付签名 */ boolean verifySignature(PaymentCallbackDTO callback); /** * 查询支付状态 */ TenantPaymentEntity findByPayNo(String payNo); }

---

七、6️⃣ SubscriptionService

 

public interface SubscriptionService { TenantSubscriptionEntity getActiveSubscription(Long tenantId); void extendSubscription(Long subscriptionId, Long newEndTime); void upgradePlan(Long subscriptionId, Long newPlanId); boolean isExpired(Long subscriptionId); }

---

八、7️⃣ EntitlementService（授权快照）

 

public interface EntitlementService { /** * 刷新授权快照 */ void refreshSnapshot(Long tenantId); /** * 冻结授权 */ void freezeTenant(Long tenantId); /** * 解冻授权 */ void unfreezeTenant(Long tenantId); /** * 校验模块权限 */ boolean checkModuleEnabled(Long tenantId, String moduleCode); }

---

九、8️⃣ PricingStrategy（策略模式）

 

public interface PricingStrategy { BigDecimal calculate(ComponentContext context); }

---

FixedPricingStrategy

 

public class FixedPricingStrategy implements PricingStrategy { @Override public BigDecimal calculate(ComponentContext context) { return context.getFixedPrice(); } }

---

PerUnitPricingStrategy

 

public class PerUnitPricingStrategy implements PricingStrategy { @Override public BigDecimal calculate(ComponentContext context) { return context.getUsageValue() .multiply(context.getUnitPrice()) .setScale(2, RoundingMode.HALF_UP); } }

---

TieredPricingStrategy

 

public class TieredPricingStrategy implements PricingStrategy { @Override public BigDecimal calculate(ComponentContext context) { return TieredCalculator.calculate( context.getUsageValue(), context.getTiers() ); } }

---

十、核心流程调用关系图

 

BillingFacade ↓ SubscriptionService ↓ PricingService ↓ UsageService ↓ InvoiceService ↓ PaymentService ↓ EntitlementService

---

十一、账单构建标准流程（最终生产流程）

 

1️⃣ 读取订阅 2️⃣ 读取套餐 3️⃣ 遍历组件 4️⃣ 计算用量 5️⃣ 计算金额 6️⃣ 计算补差 7️⃣ 汇总金额 8️⃣ 写入 invoice 9️⃣ 写入 items 🔟 写入 calculation_log

---

十二、幂等保障点

模块	幂等方式
buildInvoice	invoice_biz_key 唯一
createPayment	pay_no 唯一
payment callback	pay_no 唯一
extendSubscription	乐观锁 version

---

十三、金额统一规范（升鲜宝标准）

• 金额 DECIMAL(18,2)

• 单价 DECIMAL(18,6)

• 统一 HALF_UP

• 所有中间运算 BigDecimal

---

十四、你现在已经具备

✅ 商业级计费核心结构
✅ 可插拔价格策略
✅ 可扩展用量模型
✅ 可重算架构
✅ 可冻结可解冻授权