Add #discounted_amount by adjustments

[mamhoff]

Summary

This adds the DiscountedAmount module to the promotion system. It is preparatory work to be able to calculate the discounted_amount for each discountable item depending on the current promotion lane, without taking into account adjustments/discounts from later lanes or discounts that are market for destruction.

This just adds methods, their use will be done in a subsequent PR.

Extracted from #6371 .

This introduces an Object to hold the current promotion lane while calculating, and adds a couple of methods in order to replace a couple of older methods.

New: discountable.discounted_amount. Will replace discountable.discountable_amount.
Rationale: When called from within the promotion system, these mean the same thing (we can only discount from what is still available to discount, and if there's previous discounts, the discountable amount is equal to the discounted amount). Also: discounted_amount is calculated from real adjustments, so it can be called from outside the promotion system, and the return value will make sense (it will be equal to total_before_tax unless someone adds manual adjustments somewhere. That's why this should stay public.

New: discountable.previous_lanes_discounts. Will replace discountable.current_discounts
Rationale: We need a different name for this as it returns an array of adjustments, rather than an array of SolidusPromotion::ItemDiscount objects. I could make this private, too, as it's only used from discounted_amount above.

New: discountable.current_lane_discounts. Replaces a local variable in the order discounter.
Rationale: We need to know which discounts are being currently added in the current lane so that we can mark those for destruction that we don't want. Here's where it will be used (draft PR): ea4cd30#diff-828a39d27bc67194ff2509c675bf0148420849b1fcafabe848605f4e2d81f085R69.

Checklist

Check out our PR guidelines for more details.

The following are mandatory for all PRs:

• I agree that my PR will be published under the same license as Solidus.
• I have written a thorough PR description.
• I have kept my commits small and atomic.
• I have localized any and all user-facing strings that I added to the source code.
• I have used clear, explanatory commit messages.

The following are not always needed:

• 📖 I have updated the README to account for my changes.
• 📑 I have documented new code with YARD.
• 🛣️ I have opened a PR to update the guides.
• ✅ I have added automated tests to cover my changes.
• 📸 I have attached screenshots to demo visual changes.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.48%. Comparing base (57e8ef9) to head (ff58cdd).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6379      +/-   ##
==========================================
+ Coverage   89.46%   89.48%   +0.02%     
==========================================
  Files         977      980       +3     
  Lines       20386    20427      +41     
==========================================
+ Hits        18238    18279      +41     
  Misses       2148     2148              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[tvdeyen]

This is very clever code, but honestly I am not very happy with this approach.

I would like to not mix in even more modules into already large objects (LineItem, Shipment, etc.) just for storing an in memory calculation.

That we now have a raise condition in a module so we are sure that we never call that public methods outside of the promotion run is a smell imo.

Maybe we can use some kind of object that holds the current state during calculation instead of the objects itself?

Would like to have some thoughts from other @solidusio/core-team members as well .

[mamhoff]

I would like to not mix in even more modules into already large objects (LineItem, Shipment, etc.) just for storing an in memory calculation.

That we now have a raise condition in a module so we are sure that we never call that public methods outside of the promotion run is a smell imo.

I've tried - hard, over many months - to use a specialized order object just for promotion calculation. However, in order to discount an order, it needs to be mutated, and I have not found a way to expose all of the order to calculators and conditions (because that's what the calling code expects) from an object that is another class than Spree::Order. I've tried inheriting from SimpleDelegator, I've even tried Refinements. ActiveRecord and Rails are not suited to that kind of programming, as much as I'd like them to be.

The goal of this work is to actually go closer to the real order object. To use adjustments/shipping rate discounts to store discounts, rather than the double bookkeeping we have now with discounts while calculating promotions, and adjustments outside of it.

A side requirement I have is to require as little change to conditions and calculators as possible, as many stores have many custom conditions and calculators.

[mamhoff]

I would like to not mix in even more modules into already large objects (LineItem, Shipment, etc.) just for storing an in memory calculation.

This work allows us to remove the SolidusPromotions::DiscountableAmount module from line item, shipment, and shipping rate, and with it four public methods. DiscountedAmount only needs two private methods (mostly because we don't need to add an in-memory discounts collection, and we don't need to manage these discounts from the outside).

The idea in #6371 is to store the results of all calculations on objects that we will ultimately store in the database.

[tvdeyen]

Nice. Some suggestions by @manleyac and me