Sorghum Calculator

# sorghum-calculator

**Repository Path**: cmeet/sorghum-calculator

## Basic Information

- **Project Name**: sorghum-calculator
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-19
- **Last Updated**: 2025-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# sorghum-calculator

中文 &nbsp; | &nbsp; [English](./README-EN.md)

<h1 align="center">Sorghum Calculator</h1>
<h3 align="center">基于Java的优惠组合最优价格计算器</h3>

<p align="center">
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202-blue" alt="license Apache 2.0"></a>
    <a href="#"><img src="https://img.shields.io/badge/version-1.0-green" alt="version 1.0"></a>
</p>

---

## 🚀 简介 | Intro

sorghum-calculator 是一个基于Java的优惠组合最优价格计算器。它可以通过智能算法计算出在多种优惠券、折扣等优惠组合下，能够获得的最优价格方案。适用于电商平台、购物网站等需要进行复杂价格计算的场景。

该框架基于Solon框架构建，通过多线程计算和智能筛选算法，大大简化了复杂优惠组合的价格计算问题。

## 🌈 特性 | Features

+ **智能计算**：自动计算多种优惠组合下的最优价格
+ **多线程支持**：支持单线程和多线程两种计算模式
+ **灵活配置**：支持多种优惠类型（折扣、满减、固定金额等）
+ **优惠规则**：支持设置优惠门槛、是否可叠加、是否排他等规则
+ **易于扩展**：模块化设计，易于添加新的优惠类型和计算规则

## 📦 模块说明

```
sorghum-calculator
├── site.sorghum.calculator.Discount           优惠实体类
├── site.sorghum.calculator.PriceEngine        价格计算引擎
└── site.sorghum.calculator.CalDemo            使用示例
```

### Discount 优惠类
表示一个优惠券或折扣规则，包含优惠名称、类型、计算方式等属性。

### PriceEngine 价格计算引擎
核心计算模块，负责生成优惠组合、计算最优价格等功能。

### CalDemo 使用示例
演示如何使用该计算器计算最优价格的示例代码。

## 🔧 使用示例

### 基本使用

```java
package site.sorghum.calculator;

import lombok.SneakyThrows;

import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.List;

public class CalDemo {
    @SneakyThrows
    public static void main(String[] args) {
        // 创建各种优惠
        List<Discount> discounts = new ArrayList<>();

        // 店铺折扣（可叠加）
        discounts.add(new Discount("D001",
                "店铺9折",
                "store_discount",
                "shop1",
                null,
                new BigDecimal("0.9"),
                null,
                true,
                false));
        discounts.add(new Discount("D002",
                "店铺满1000减50",
                "store_discount",
                "shop1",
                new BigDecimal("50"),
                null,
                new BigDecimal("1000"),
                true,
                false));

        // 平台满减券（不可叠加）
        discounts.add(new Discount("C001",
                "满500减100",
                "coupon",
                "platform",
                new BigDecimal("100"),
                null,
                new BigDecimal("500"),
                false,
                false));
        discounts.add(new Discount("C002",
                "满1000减300",
                "coupon",
                "platform",
                new BigDecimal("300"),
                null,
                new BigDecimal("1000"),
                false,
                false));

        // 会员专享券（排他）
        discounts.add(new Discount("M001",
                "会员8折",
                "member",
                "platform",
                null,
                new BigDecimal("0.8"),
                null,
                false,
                true));
        discounts.add(new Discount("M002",
                "会员满1000减200",
                "member",
                "platform",
                new BigDecimal("200"),
                null,
                new BigDecimal("1000"),
                false,
                true));

        // 计算最优价格
        PriceEngine priceEngine = new PriceEngine();
        BigDecimal originalPrice = new BigDecimal("1200");
        BigDecimal optimalPrice = priceEngine.calculateOptimalPrice(originalPrice, discounts);
        System.out.println("原始价格: " + originalPrice);
        System.out.println("最优价格: " + optimalPrice);
        priceEngine.shutdown();
    }
}
```

## 📚 详细说明

### 优惠类型

1. **折扣优惠**：通过设置[discountRate](site/sorghum/calculator/Discount.java#L18)属性实现按比例折扣
2. **固定金额减免**：通过设置[discountAmount](site/sorghum/calculator/Discount.java#L17)属性实现固定金额减免
3. **门槛优惠**：通过设置[threshold](site/sorghum/calculator/Discount.java#L19)属性实现满足门槛条件才可使用

### 优惠规则

1. **可叠加性**：通过[stackable](site/sorghum/calculator/Discount.java#L21)属性设置优惠是否可以与其他优惠叠加使用
2. **排他性**：通过[exclusive](site/sorghum/calculator/Discount.java#L22)属性设置优惠是否排他（排他优惠最多只能有一个生效）

### 计算模式

1. **单线程模式**：适用于优惠组合较少的场景，计算稳定可靠
2. **多线程模式**：适用于优惠组合复杂的场景，可通过系统属性`price.engine.multithreading=true`启用

## 🛠️ 自定义扩展

框架支持自定义扩展，只需继承或修改现有类：

```java
// 自定义价格计算引擎
public class CustomPriceEngine extends PriceEngine {
    // 重写或添加自定义方法
}
```

## 📄 许可证

sorghum-calculator使用Apache 2.0许可证。详情请参阅[LICENSE](LICENSE)文件。