- 构建者：可扩展促销规则与外部服务
*/
public final class ShoppingCart {
// 基础配置
private final Currency currency; // 购物车货币（单一）
private final MathContext mathContext; // 金额计算精度
private final RoundingMode roundingMode; // 金额舍入规则
private final int moneyScale; // 金额小数位（通常 2）
private final Clock clock; // 可注入时钟，便于测试
// 聚合内数据
private final List items; // 购物项集合
private final List discountStrategies; // 折扣策略链
private ShippingPolicy shippingPolicy; // 运费策略
private final Set couponCodes; // 已应用优惠券（去重）
private BigDecimal subtotalCache; // 小计缓存（派生）
private boolean subtotalDirty; // 缓存失效标记
private Instant updatedAt; // 最近更新时间
private String idempotencyKey; // 幂等键（结算/下单防重）
// 外部协作者（策略/服务）
private final InventoryPolicy inventoryPolicy; // 库存/最小购买校验策略
private final CouponValidator couponValidator; // 优惠券校验器
private final PaymentPreparation paymentPreparation; // 支付前准备（可与支付网关协作）
// ======================= 构造与构建者 =======================
private ShoppingCart(Builder b) {
Objects.requireNonNull(b.currency, "currency required");
this.currency = b.currency;
this.mathContext = b.mathContext != null ? b.mathContext : MathContext.DECIMAL64;
this.roundingMode = b.roundingMode != null ? b.roundingMode : RoundingMode.HALF_UP;
this.moneyScale = b.moneyScale > 0 ? b.moneyScale : 2;
this.clock = b.clock != null ? b.clock : Clock.systemUTC();
this.items = new ArrayList<>();
if (b.initialItems != null) {
for (CartItem it : b.initialItems) {
// 防止不同货币：单价不含币种，视为与购物车币种一致
addItem(it.getSkuId(), it.getTitle(), it.getUnitPrice(), it.getQty(), it.getAttrs());
}
}
this.discountStrategies = new ArrayList<>(b.discountStrategies != null ? b.discountStrategies : Collections.emptyList());
this.shippingPolicy = Objects.requireNonNullElseGet(b.shippingPolicy, () -> new FreeShippingThresholdPolicy(Money.zero(currency), Money.zero(currency)));
this.couponCodes = new LinkedHashSet<>(b.initialCoupons != null ? b.initialCoupons : Collections.emptySet());
this.inventoryPolicy = Objects.requireNonNullElseGet(b.inventoryPolicy, NoopInventoryPolicy::new);
this.couponValidator = Objects.requireNonNullElseGet(b.couponValidator, () -> CouponValidationResult.invalid("no validator"));
this.paymentPreparation = Objects.requireNonNullElseGet(b.paymentPreparation, NoopPaymentPreparation::new);
this.subtotalCache = BigDecimal.ZERO.setScale(moneyScale, roundingMode);
this.subtotalDirty = true;
this.updatedAt = clock.instant();
this.idempotencyKey = b.idempotencyKey;
}
public static Builder builder() {
return new Builder();
}
// ======================= 聚合根操作 =======================
/**
-
若已存在同款（skuId + attrs 相同）则合并数量；价格以最新为准。
*/
public synchronized void addItem(String skuId, String title, BigDecimal unitPrice, int qty, Map<String, String> attrs) {
requireNonBlank(skuId, "skuId");
requireNonBlank(title, "title");
Objects.requireNonNull(unitPrice, "unitPrice");
if (qty <= 0) throw new IllegalArgumentException("qty must be > 0");
Map<String, String> safeAttrs = attrs == null ? Collections.emptyMap() : new TreeMap<>(attrs);
BigDecimal normalizedPrice = normalizeAmount(unitPrice);
Optional existing = findItem(skuId, safeAttrs);
int newQty = qty;
if (existing.isPresent()) {
CartItem item = existing.get();
newQty = Math.addExact(item.getQty(), qty);
// 库存与最小购买校验
validateQtyRules(skuId, safeAttrs, newQty);
// 合并：更新数量与价格
item.setQty(newQty);
item.setUnitPrice(normalizedPrice);
} else {
// 校验
validateQtyRules(skuId, safeAttrs, qty);
items.add(new CartItem(skuId, title, normalizedPrice, qty, safeAttrs));
}
markDirty();
}
/**
- 按 SKU 移除购物项（移除该 SKU 的所有变体）。
*/
public synchronized void removeItem(String skuId) {
requireNonBlank(skuId, "skuId");
boolean removed = items.removeIf(i -> i.getSkuId().equals(skuId));
if (removed) {
markDirty();
}
}
/**
- 调整指定 SKU 的数量（如果存在多个变体，全部调整为该数量；如需变体级别，可扩展重载）。
- qty <= 0 则移除该 SKU。
*/
public synchronized void changeQty(String skuId, int qty) {
requireNonBlank(skuId, "skuId");
if (qty <= 0) {
removeItem(skuId);
return;
}
boolean any = false;
for (CartItem it : items) {
if (it.getSkuId().equals(skuId)) {
validateQtyRules(it.getSkuId(), it.getAttrs(), qty);
it.setQty(qty);
any = true;
}
}
if (!any) {
throw new NoSuchElementException("SKU not in cart: " + skuId);
}
markDirty();
}
/**
- 应用优惠券：验证有效期、可叠加性与适用范围后记录。
- 返回是否成功应用（重复添加返回 false）。
*/
public synchronized boolean applyCoupon(String code) {
requireNonBlank(code, "coupon code");
if (couponCodes.contains(code)) {
return false; // 去重
}
CouponValidationResult result = couponValidator.validate(code, this, Collections.unmodifiableSet(couponCodes));
if (!result.isValid()) {
return false;
}
// 可叠加性由策略链在计算折扣时综合判断；此处仅记录
couponCodes.add(code);
touch();
return true;
}
/**
- 计算应付总额：subtotal + shipping(估算) - discount。
- 注意：如需地址敏感的运费，请使用 calculateTotal(Address)。
*/
public synchronized Money calculateTotal() {
return calculateTotal(null);
}
/**
- 计算应付总额（地址可选）。
*/
public synchronized Money calculateTotal(Address shippingAddress) {
Money subtotal = getSubtotalMoney();
Money shipping = shippingPolicy.estimate(this, Optional.ofNullable(shippingAddress));
Money discount = calculateDiscounts(subtotal, shipping, shippingAddress);
Money total = subtotal.add(shipping).subtract(discount);
if (total.isNegative()) {
total = Money.zero(currency);
}
return total;
}
/**
-
结算：生成订单草案、锁定库存并返回应付信息。
-
-
- 返回应付金额、运费、折扣、已用优惠券与库存锁定凭证等
*/
public synchronized CheckoutResult checkout(PaymentGateway gateway, Address shippingAddress) {
Objects.requireNonNull(gateway, "PaymentGateway required");
Objects.requireNonNull(shippingAddress, "shipping address required");
if (items.isEmpty()) {
throw new IllegalStateException("cart is empty");
}
// 1) 计算金额
Money subtotal = getSubtotalMoney();
Money shipping = shippingPolicy.estimate(this, Optional.of(shippingAddress));
Money discount = calculateDiscounts(subtotal, shipping, shippingAddress);
Money totalPayable = subtotal.add(shipping).subtract(discount);
if (totalPayable.isNegative()) totalPayable = Money.zero(currency);
// 2) 锁定库存
String reservationToken = inventoryPolicy.reserve(items);
// 3) 准备支付（可用于创建支付意图等）
String idem = getOrGenerateIdempotencyKey();
PaymentPreparation.PreparedPayment prepared = paymentPreparation.prepare(totalPayable, idem, shippingAddress);
PaymentGateway.PaymentIntent intent = gateway.createPaymentIntent(totalPayable, idem, prepared);
// 4) 生成 CheckoutResult
CheckoutResult result = new CheckoutResult(
UUID.randomUUID().toString(), // orderDraftId
subtotal, shipping, discount, totalPayable,
Collections.unmodifiableList(new ArrayList<>(items)),
Collections.unmodifiableSet(new LinkedHashSet<>(couponCodes)),
reservationToken,
intent.intentId(),
intent.raw()
);
touch(); // 更新更新时间
return result;
}
/**
- 清空购物车与派生缓存。
*/
public synchronized void clear() {
items.clear();
couponCodes.clear();
subtotalCache = Money.zero(currency).amount();
subtotalDirty = true;
touch();
}
public static Builder builder(Currency currency) {
return new Builder().currency(currency);
}
// ======================= 内部计算/校验 =======================
private Optional findItem(String skuId, Map<String, String> attrs) {
for (CartItem it : items) {
if (it.getSkuId().equals(skuId) && it.getAttrs().equals(attrs)) {
return Optional.of(it);
}
}
return Optional.empty();
}
private void validateQtyRules(String skuId, Map<String, String> attrs, int qty) {
if (qty < 1) throw new IllegalArgumentException("min qty is 1");
int max = inventoryPolicy.getMaxPurchasable(skuId, attrs);
if (qty > max) {
throw new IllegalArgumentException("qty exceeds available limit: " + max);
}
}
private Money calculateDiscounts(Money subtotal, Money shipping, Address shippingAddress) {
if (discountStrategies.isEmpty()) return Money.zero(currency);
DiscountContext ctx = new DiscountContext(
currency, mathContext, roundingMode, moneyScale,
Collections.unmodifiableSet(couponCodes),
subtotal, shipping, Optional.ofNullable(shippingAddress));
Money totalDiscount = Money.zero(currency);
for (DiscountStrategy strategy : discountStrategies) {
Discount d = strategy.apply(this, ctx);
if (d == null || d.amount() == null) continue;
Money delta = d.amount();
if (!delta.currency().equals(currency)) {
throw new IllegalStateException("discount currency mismatch");
}
if (delta.isNegative()) continue; // 保护，不支持负折扣
totalDiscount = totalDiscount.add(delta);
}
// 折扣不得超过 subtotal + shipping
Money cap = subtotal.add(shipping);
if (totalDiscount.gt(cap)) totalDiscount = cap;
return totalDiscount;
}
private Money getSubtotalMoney() {
BigDecimal amt = getSubtotalAmount();
return Money.of(amt, currency, moneyScale, roundingMode);
}
private BigDecimal getSubtotalAmount() {
if (subtotalDirty) {
BigDecimal sum = BigDecimal.ZERO.setScale(moneyScale, roundingMode);
for (CartItem it : items) {
BigDecimal line = it.getUnitPrice().multiply(BigDecimal.valueOf(it.getQty()), mathContext);
line = line.setScale(moneyScale, roundingMode);
sum = sum.add(line, mathContext).setScale(moneyScale, roundingMode);
}
subtotalCache = sum;
subtotalDirty = false;
}
return subtotalCache;
}
private void markDirty() {
subtotalDirty = true;
touch();
}
private void touch() {
updatedAt = clock.instant();
}
private BigDecimal normalizeAmount(BigDecimal amount) {
return amount.setScale(moneyScale, roundingMode);
}
private static void requireNonBlank(String s, String name) {
if (s == null || s.trim().isEmpty()) throw new IllegalArgumentException(name + " required");
}
private String getOrGenerateIdempotencyKey() {
if (idempotencyKey == null || idempotencyKey.isBlank()) {
idempotencyKey = "cart-" + UUID.randomUUID();
}
return idempotencyKey;
}
// ======================= 对外可读属性（只读视图） =======================
public Currency getCurrency() { return currency; }
public List getItems() { return Collections.unmodifiableList(items); }
public List getDiscountStrategies() { return Collections.unmodifiableList(discountStrategies); }
public ShippingPolicy getShippingPolicy() { return shippingPolicy; }
public Set getCouponCodes() { return Collections.unmodifiableSet(couponCodes); }
public BigDecimal getSubtotal() { return getSubtotalAmount(); }
public Instant getUpdatedAt() { return updatedAt; }
public String getIdempotencyKey() { return idempotencyKey; }
// 可选：动态更换运费策略（例如结算时基于地址）
public synchronized void setShippingPolicy(ShippingPolicy shippingPolicy) {
this.shippingPolicy = Objects.requireNonNull(shippingPolicy);
touch();
}
public synchronized void setIdempotencyKey(String idempotencyKey) {
this.idempotencyKey = idempotencyKey;
touch();
}
// ======================= 嵌套类型：值对象/策略/接口 =======================
public static final class CartItem {
private final String skuId;
private final String title;
private BigDecimal unitPrice; // 与购物车货币一致
private int qty;
private final Map<String, String> attrs;
CartItem(String skuId, String title, BigDecimal unitPrice, int qty, Map<String, String> attrs) {
this.skuId = skuId;
this.title = title;
this.unitPrice = unitPrice;
this.qty = qty;
this.attrs = Collections.unmodifiableMap(new TreeMap<>(attrs));
}
public String getSkuId() { return skuId; }
public String getTitle() { return title; }
public BigDecimal getUnitPrice() { return unitPrice; }
public int getQty() { return qty; }
public Map<String, String> getAttrs() { return attrs; }
void setUnitPrice(BigDecimal unitPrice) {
this.unitPrice = unitPrice;
}
void setQty(int qty) {
this.qty = qty;
}
@Override
public String toString() {
return "CartItem{" +
"skuId='" + skuId + '\'' +
", title='" + title + '\'' +
", unitPrice=" + unitPrice +
", qty=" + qty +
", attrs=" + attrs +
'}';
}
}
public record Money(BigDecimal amount, Currency currency) {
public static Money of(BigDecimal amount, Currency currency, int scale, RoundingMode rm) {
return new Money(amount.setScale(scale, rm), currency);
}
public static Money zero(Currency c) {
return new Money(BigDecimal.ZERO.setScale(2, RoundingMode.HALF_UP), c);
}
public Money add(Money other) {
requireSameCurrency(other);
return new Money(amount.add(other.amount), currency);
}
public Money subtract(Money other) {
requireSameCurrency(other);
return new Money(amount.subtract(other.amount), currency);
}
public boolean isNegative() { return amount.signum() < 0; }
public boolean gt(Money other) { requireSameCurrency(other); return amount.compareTo(other.amount) > 0; }
private void requireSameCurrency(Money other) {
if (!currency.equals(other.currency)) throw new IllegalArgumentException("currency mismatch");
}
public BigDecimal amount() { return amount; } // alias
}
public interface DiscountStrategy {
Discount apply(ShoppingCart cart, DiscountContext ctx);
}
public static final class DiscountContext {
public final Currency currency;
public final MathContext mathContext;
public final RoundingMode roundingMode;
public final int moneyScale;
public final Set couponCodes;
public final Money subtotal;
public final Money shipping;
public final Optional shippingAddress;
public DiscountContext(Currency currency,
MathContext mathContext,
RoundingMode roundingMode,
int moneyScale,
Set<String> couponCodes,
Money subtotal,
Money shipping,
Optional<Address> shippingAddress) {
this.currency = currency;
this.mathContext = mathContext;
this.roundingMode = roundingMode;
this.moneyScale = moneyScale;
this.couponCodes = couponCodes;
this.subtotal = subtotal;
this.shipping = shipping;
this.shippingAddress = shippingAddress;
}
public Money money(BigDecimal amt) {
return Money.of(amt, currency, moneyScale, roundingMode);
}
}
public record Discount(Money amount, String reason, Map<String, Object> meta) {
public static Discount of(Money amount, String reason) {
return new Discount(amount, reason, Collections.emptyMap());
}
}
public interface ShippingPolicy {
Money estimate(ShoppingCart cart, Optional
shippingAddress);
}
/**
-
示例运费策略：满额包邮，否则固定运费；可根据区域差异化（演示结构）。
*/
public static final class FreeShippingThresholdPolicy implements ShippingPolicy {
private final Money threshold;
private final Money baseFee;
public FreeShippingThresholdPolicy(Money threshold, Money baseFee) {
this.threshold = threshold;
this.baseFee = baseFee;
}
@Override
public Money estimate(ShoppingCart cart, Optional
shippingAddress) {
Money subtotal = cart.getSubtotalMoney();
if (!subtotal.currency().equals(threshold.currency)) {
throw new IllegalStateException("currency mismatch in shipping policy");
}
// 区域差异示意：海外加收 50%
boolean overseas = shippingAddress.map(a -> !"CN".equalsIgnoreCase(a.country())).orElse(false);
if (subtotal.amount().compareTo(threshold.amount) >= 0) {
return Money.of(BigDecimal.ZERO, threshold.currency, 2, RoundingMode.HALF_UP);
}
Money fee = baseFee;
if (overseas) {
BigDecimal up = fee.amount().multiply(BigDecimal.valueOf(1.5));
fee = Money.of(up, fee.currency(), 2, RoundingMode.HALF_UP);
}
return fee;
}
}
public interface CouponValidator {
CouponValidationResult validate(String code, ShoppingCart cart, Set existingCodes);
}
public interface CouponValidationResult extends CouponValidator {
boolean isValid();
String reason();
static CouponValidationResult ok() {
return new CouponValidationResult() {
public boolean isValid() { return true; }
public String reason() { return "OK"; }
@Override public CouponValidationResult validate(String code, ShoppingCart cart, Set<String> existingCodes) { return this; }
};
}
static CouponValidationResult invalid(String reason) {
return new CouponValidationResult() {
public boolean isValid() { return false; }
public String reason() { return reason; }
@Override public CouponValidationResult validate(String code, ShoppingCart cart, Set<String> existingCodes) { return this; }
};
}
}
public interface InventoryPolicy {
int getMaxPurchasable(String skuId, Map<String, String> attrs);
String reserve(List items);
}
public static final class NoopInventoryPolicy implements InventoryPolicy {
@Override public int getMaxPurchasable(String skuId, Map<String, String> attrs) { return Integer.MAX_VALUE / 4; }
@Override public String reserve(List items) { return "noop-reservation-" + UUID.randomUUID(); }
}
public interface PaymentPreparation {
PreparedPayment prepare(Money total, String idempotencyKey, Address shippingAddress);
record PreparedPayment(Map<String, Object> meta) {}
}
public static final class NoopPaymentPreparation implements PaymentPreparation {
@Override public PreparedPayment prepare(Money total, String idempotencyKey, Address shippingAddress) {
return new PreparedPayment(Map.of("prepared", true));
}
}
public interface PaymentGateway {
PaymentIntent createPaymentIntent(Money amount, String idempotencyKey, PaymentPreparation.PreparedPayment prepared);
record PaymentIntent(String intentId, Map<String, Object> raw) {}
}
public record Address(String country, String region, String city, String postcode, String addressLine) {}
public static final class CheckoutResult {
private final String orderDraftId;
private final Money subtotal;
private final Money shipping;
private final Money discount;
private final Money totalPayable;
private final List lineItems;
private final Set appliedCoupons;
private final String inventoryReservationToken;
private final String paymentIntentId;
private final Map<String, Object> paymentRaw;
public CheckoutResult(String orderDraftId,
Money subtotal,
Money shipping,
Money discount,
Money totalPayable,
List<CartItem> lineItems,
Set<String> appliedCoupons,
String inventoryReservationToken,
String paymentIntentId,
Map<String, Object> paymentRaw) {
this.orderDraftId = orderDraftId;
this.subtotal = subtotal;
this.shipping = shipping;
this.discount = discount;
this.totalPayable = totalPayable;
this.lineItems = lineItems;
this.appliedCoupons = appliedCoupons;
this.inventoryReservationToken = inventoryReservationToken;
this.paymentIntentId = paymentIntentId;
this.paymentRaw = paymentRaw;
}
public String orderDraftId() { return orderDraftId; }
public Money subtotal() { return subtotal; }
public Money shipping() { return shipping; }
public Money discount() { return discount; }
public Money totalPayable() { return totalPayable; }
public List<CartItem> lineItems() { return lineItems; }
public Set<String> appliedCoupons() { return appliedCoupons; }
public String inventoryReservationToken() { return inventoryReservationToken; }
public String paymentIntentId() { return paymentIntentId; }
public Map<String, Object> paymentRaw() { return paymentRaw; }
}
// ======================= 构建者 =======================
public static final class Builder {
private Currency currency;
private List initialItems;
private List discountStrategies;
private ShippingPolicy shippingPolicy;
private Set initialCoupons;
private InventoryPolicy inventoryPolicy;
private CouponValidator couponValidator;
private PaymentPreparation paymentPreparation;
private MathContext mathContext;
private RoundingMode roundingMode;
private int moneyScale = 2;
private Clock clock;
private String idempotencyKey;
public Builder currency(Currency currency) { this.currency = currency; return this; }
public Builder items(List<CartItem> items) { this.initialItems = items; return this; }
public Builder discountStrategies(List<DiscountStrategy> strategies) { this.discountStrategies = strategies; return this; }
public Builder addDiscountStrategy(DiscountStrategy s) {
if (this.discountStrategies == null) this.discountStrategies = new ArrayList<>();
this.discountStrategies.add(s);
return this;
}
public Builder shippingPolicy(ShippingPolicy policy) { this.shippingPolicy = policy; return this; }
public Builder coupons(Set<String> coupons) { this.initialCoupons = coupons; return this; }
public Builder inventoryPolicy(InventoryPolicy policy) { this.inventoryPolicy = policy; return this; }
public Builder couponValidator(CouponValidator validator) { this.couponValidator = validator; return this; }
public Builder paymentPreparation(PaymentPreparation prep) { this.paymentPreparation = prep; return this; }
public Builder mathContext(MathContext mc) { this.mathContext = mc; return this; }
public Builder roundingMode(RoundingMode rm) { this.roundingMode = rm; return this; }
public Builder moneyScale(int scale) { this.moneyScale = scale; return this; }
public Builder clock(Clock clock) { this.clock = clock; return this; }
public Builder idempotencyKey(String key) { this.idempotencyKey = key; return this; }
public ShoppingCart build() {
return new ShoppingCart(this);
}
}
// ======================= 示例折扣策略（可选） =======================
/**
-
示例：满减策略。满 X 减 Y，不可为负。
*/
public static final class FullReductionStrategy implements DiscountStrategy {
private final Money threshold;
private final Money reduction;
public FullReductionStrategy(Money threshold, Money reduction) {
this.threshold = threshold;
this.reduction = reduction;
if (!threshold.currency.equals(reduction.currency)) {
throw new IllegalArgumentException("currency mismatch in FullReductionStrategy");
}
}
@Override
public Discount apply(ShoppingCart cart, DiscountContext ctx) {
if (!ctx.subtotal.currency().equals(threshold.currency)) return null;
if (ctx.subtotal.amount().compareTo(threshold.amount) >= 0) {
return Discount.of(Money.of(reduction.amount, reduction.currency, ctx.moneyScale, ctx.roundingMode), "满减");
}
return null;
}
}
/**
-
示例：会员折扣（百分比）。
*/
public static final class MemberPercentageOffStrategy implements DiscountStrategy {
private final BigDecimal percent; // 0.05 表示 5%
public MemberPercentageOffStrategy(BigDecimal percent) {
if (percent == null || percent.compareTo(BigDecimal.ZERO) <= 0) {
throw new IllegalArgumentException("percent must be > 0");
}
this.percent = percent;
}
@Override
public Discount apply(ShoppingCart cart, DiscountContext ctx) {
BigDecimal amt = ctx.subtotal.amount().multiply(percent, ctx.mathContext);
amt = amt.setScale(ctx.moneyScale, ctx.roundingMode);
if (amt.signum() <= 0) return null;
return Discount.of(ctx.money(amt), "会员折扣");
}
}
/**
- 示例：优惠券策略（基于已应用 couponCodes，简单演示）。
*/
public static final class CouponDiscountStrategy implements DiscountStrategy {
@Override
public Discount apply(ShoppingCart cart, DiscountContext ctx) {
if (ctx.couponCodes.isEmpty()) return null;
// 简单规则演示：SAVE10 -> 减 10；SAVE20 -> 满 100 减 20；不可为负
BigDecimal total = BigDecimal.ZERO;
boolean save10 = ctx.couponCodes.contains("SAVE10");
boolean save20 = ctx.couponCodes.contains("SAVE20");
if (save10) total = total.add(BigDecimal.TEN);
if (save20 && ctx.subtotal.amount().compareTo(new BigDecimal("100.00")) >= 0) {
total = total.add(new BigDecimal("20.00"));
}
if (total.signum() <= 0) return null;
return Discount.of(ctx.money(total), "优惠券");
}
}
}
