feat(products): link fees to rate_card_rate and add product_item fee type

Fees produced by the new billing path need to reference the catalog rate that
generated them and a fee type identifying them as coming from a product item.

Add an optional rate_card_rate_id reference to fees (concurrent index,
unvalidated foreign key for a safe rollout) and append product_item to
Fee::FEE_TYPES. The existing fee types and billing path are untouched.

Author: rsempe

app/models/fee.rb

@@ -21,6 +21,7 @@ class Fee < ApplicationRecord
   belongs_to :organization
   belongs_to :billing_entity
   belongs_to :fixed_charge, -> { with_discarded }, optional: true
+  belongs_to :rate_card_rate, optional: true
 
   has_one :adjusted_fee, dependent: :nullify
   has_one :billable_metric, -> { with_discarded }, through: :charge
@@ -45,7 +46,7 @@ class Fee < ApplicationRecord
   monetize :unit_amount_cents, disable_validation: true, allow_nil: true, with_model_currency: :currency
 
   # TODO: Deprecate add_on type in the near future
-  FEE_TYPES = %i[charge add_on subscription credit commitment fixed_charge].freeze
+  FEE_TYPES = %i[charge add_on subscription credit commitment fixed_charge product_item].freeze
   PAYMENT_STATUS = %i[pending succeeded failed refunded].freeze
 
   enum :fee_type, FEE_TYPES
@@ -414,6 +415,7 @@ def to_date
 #  original_fee_id                     :uuid
 #  pay_in_advance_event_id             :uuid
 #  pay_in_advance_event_transaction_id :string
+#  rate_card_rate_id                   :uuid
 #  subscription_id                     :uuid
 #  true_up_parent_fee_id               :uuid
 #
@@ -435,6 +437,7 @@ def to_date
 #  index_fees_on_organization_id                       (organization_id)
 #  index_fees_on_original_fee_id                       (original_fee_id)
 #  index_fees_on_pay_in_advance_event_transaction_id   (pay_in_advance_event_transaction_id) WHERE (deleted_at IS NULL)
+#  index_fees_on_rate_card_rate_id                     (rate_card_rate_id)
 #  index_fees_on_subscription_id                       (subscription_id)
 #  index_fees_on_true_up_parent_fee_id                 (true_up_parent_fee_id)
 #
@@ -449,6 +452,7 @@ def to_date
 #  fk_rails_...  (invoice_id => invoices.id)
 #  fk_rails_...  (organization_id => organizations.id)
 #  fk_rails_...  (original_fee_id => fees.id)
+#  fk_rails_...  (rate_card_rate_id => rate_card_rates.id)
 #  fk_rails_...  (subscription_id => subscriptions.id)
 #  fk_rails_...  (true_up_parent_fee_id => fees.id)
 #

app/models/rate_card_rate.rb

@@ -33,6 +33,8 @@ class RateCardRate < ApplicationRecord
   belongs_to :organization
   belongs_to :rate_card
 
+  has_many :fees
+
   enum :rate_model, RATE_MODELS, validate: true
   enum :billing_interval_unit, BILLING_INTERVAL_UNITS, validate: true
 

db/migrate/20260604182138_add_rate_card_rate_to_fees.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class AddRateCardRateToFees < ActiveRecord::Migration[8.0]
+  disable_ddl_transaction!
+
+  def change
+    add_reference :fees, :rate_card_rate, type: :uuid, null: true, index: {algorithm: :concurrently}
+    add_foreign_key :fees, :rate_card_rates, column: :rate_card_rate_id, validate: false
+  end
+end

db/structure.sql

@@ -231,6 +231,7 @@ ALTER TABLE IF EXISTS ONLY public.payment_provider_customers DROP CONSTRAINT IF
 ALTER TABLE IF EXISTS ONLY public.wallets DROP CONSTRAINT IF EXISTS fk_rails_4ff087c52e;
 ALTER TABLE IF EXISTS ONLY public.rate_cards DROP CONSTRAINT IF EXISTS fk_rails_4f7ffc3e03;
 ALTER TABLE IF EXISTS ONLY public.order_forms DROP CONSTRAINT IF EXISTS fk_rails_4ed54bfec0;
+ALTER TABLE IF EXISTS ONLY public.fees DROP CONSTRAINT IF EXISTS fk_rails_4cadfc14f3;
 ALTER TABLE IF EXISTS ONLY public.product_item_filter_values DROP CONSTRAINT IF EXISTS fk_rails_4b395cde98;
 ALTER TABLE IF EXISTS ONLY public.billing_entities DROP CONSTRAINT IF EXISTS fk_rails_4aa58496c3;
 ALTER TABLE IF EXISTS ONLY public.recurring_transaction_rules_invoice_custom_sections DROP CONSTRAINT IF EXISTS fk_rails_49fcc221b0;
@@ -689,6 +690,7 @@ DROP INDEX IF EXISTS public.index_fees_taxes_on_fee_id_and_tax_id;
 DROP INDEX IF EXISTS public.index_fees_taxes_on_fee_id;
 DROP INDEX IF EXISTS public.index_fees_on_true_up_parent_fee_id;
 DROP INDEX IF EXISTS public.index_fees_on_subscription_id;
+DROP INDEX IF EXISTS public.index_fees_on_rate_card_rate_id;
 DROP INDEX IF EXISTS public.index_fees_on_pay_in_advance_event_transaction_id;
 DROP INDEX IF EXISTS public.index_fees_on_original_fee_id;
 DROP INDEX IF EXISTS public.index_fees_on_organization_id;
@@ -3438,7 +3440,8 @@ CREATE TABLE public.fees (
     precise_credit_notes_amount_cents numeric(30,5) DEFAULT 0.0 NOT NULL,
     fixed_charge_id uuid,
     duplicated_in_advance boolean DEFAULT false,
-    original_fee_id uuid
+    original_fee_id uuid,
+    rate_card_rate_id uuid
 );
 
 
@@ -8637,6 +8640,13 @@ CREATE INDEX index_fees_on_original_fee_id ON public.fees USING btree (original_
 CREATE INDEX index_fees_on_pay_in_advance_event_transaction_id ON public.fees USING btree (pay_in_advance_event_transaction_id) WHERE (deleted_at IS NULL);
 
 
+--
+-- Name: index_fees_on_rate_card_rate_id; Type: INDEX; Schema: public; Owner: -
+--
+
+CREATE INDEX index_fees_on_rate_card_rate_id ON public.fees USING btree (rate_card_rate_id);
+
+
 --
 -- Name: index_fees_on_subscription_id; Type: INDEX; Schema: public; Owner: -
 --
@@ -11849,6 +11859,22 @@ ALTER TABLE ONLY public.billing_entities
     ADD CONSTRAINT fk_rails_4aa58496c3 FOREIGN KEY (applied_dunning_campaign_id) REFERENCES public.dunning_campaigns(id) ON DELETE SET NULL;
 
 
+--
+-- Name: product_item_filter_values fk_rails_4b395cde98; Type: FK CONSTRAINT; Schema: public; Owner: -
+--
+
+ALTER TABLE ONLY public.product_item_filter_values
+    ADD CONSTRAINT fk_rails_4b395cde98 FOREIGN KEY (billable_metric_filter_id) REFERENCES public.billable_metric_filters(id);
+
+
+--
+-- Name: fees fk_rails_4cadfc14f3; Type: FK CONSTRAINT; Schema: public; Owner: -
+--
+
+ALTER TABLE ONLY public.fees
+    ADD CONSTRAINT fk_rails_4cadfc14f3 FOREIGN KEY (rate_card_rate_id) REFERENCES public.rate_card_rates(id) NOT VALID;
+
+
 --
 -- Name: order_forms fk_rails_4ed54bfec0; Type: FK CONSTRAINT; Schema: public; Owner: -
 --
@@ -13637,6 +13663,7 @@ INSERT INTO "schema_migrations" (version) VALUES
 ('20260609161044'),
 ('20260608111837'),
 ('20260608074112'),
+('20260604182138'),
 ('20260604181958'),
 ('20260604181826'),
 ('20260604181654'),

schema.graphql

@@ -8,6 +8,7 @@
   it { is_expected.to belong_to(:add_on).optional }
   it { is_expected.to belong_to(:charge).optional }
   it { is_expected.to belong_to(:fixed_charge).optional }
+  it { is_expected.to belong_to(:rate_card_rate).optional }
   it { is_expected.to have_many(:presentation_breakdowns) }
   it { is_expected.to have_one(:fixed_charge_add_on).through(:fixed_charge) }
   it { is_expected.to have_one(:adjusted_fee).dependent(:nullify) }