feat: persist detailed lines (#4202)

Author: turip

.agents/skills/charges/SKILL.md

@@ -35,7 +35,7 @@ Primary packages:
 
 `openmeter/billing/charges` is the root facade for charge operations.
 
-For charge-owned detailed lines, the shared invoice-agnostic base belongs in `openmeter/billing/models/stddetailedline`. Keep charge wrappers thin by adding only `charge_id` / `run_id`-style ownership fields around `stddetailedline.Base`, and reuse shared detailed-line base mapping helpers instead of duplicating the common field assembly in charge adapters.
+For charge-owned detailed lines, the shared invoice-agnostic base belongs in `openmeter/billing/models/stddetailedline`. Prefer using `type DetailedLine = stddetailedline.Base` in charge packages and keep ownership implicit through containment in the parent aggregate (`flatfee.Realizations` or `usagebased.RealizationRun`) rather than duplicating `charge_id` / `run_id` fields in the domain type. Reuse the shared detailed-line base mapping and create helpers instead of duplicating common field assembly in charge adapters.
 
 Charge-backed invoicing no longer relies on a charges-side `InvoicePendingLines(...)` wrapper. Billing owns invoice creation and dispatches gathering lines by `billing.LineEngineType`, while charge packages provide charge-specific line engines where needed.
 
@@ -73,6 +73,7 @@ Important types:
   - `CreditRealizations`
   - `AccruedUsage`
   - `Payment`
+  - `DetailedLines`
 - `flatfee.Intent.CalculateAmountAfterProration()` computes the prorated amount from `AmountBeforeProration`, `ServicePeriod/FullServicePeriod` ratio, and `ProRating` config, with currency-precision rounding
 - Charge-backed targets do not use invoice-style semantic proration or empty-period filtering; the charge stack materializes and prorates state itself, and the flat fee charge is responsible for omitting empty lines
 - `usagebased.Intent` carries `FeatureKey`, `Price`, `SettlementMode`, `InvoiceAt`, and `ServicePeriod`
@@ -86,6 +87,15 @@ Important types:
   - `CollectionEnd`
   - `MeterValue`
   - `Totals`
+- `usagebased.RealizationRun` can expand:
+  - `DetailedLines`
+
+Detailed-line expansion rules:
+
+- `meta.ExpandDetailedLines` is not standalone for charge reads; it requires `meta.ExpandRealizations`
+- usage-based detailed lines live under `RealizationRun.DetailedLines`
+- flat-fee detailed lines also live under `Charge.Realizations.DetailedLines`, not on the root charge
+- `mo.None()` means detailed lines were not expanded; present options mean expanded data, even when the underlying slice is nil/empty
 
 ## Billing Line Engines
 
@@ -99,7 +109,7 @@ Current engine values:
 
 Current implementations:
 
-- flat fee line engine: `openmeter/billing/charges/flatfee/lineengine`
+- flat fee line engine: `openmeter/billing/charges/flatfee/service/lineengine.go`
 - credit purchase line engine: `openmeter/billing/charges/creditpurchase/lineengine`
 - usage-based line engine: `openmeter/billing/charges/usagebased/service/lineengine.go`
 
@@ -112,6 +122,8 @@ Important rules:
 - charge test setups must also register those engines explicitly; keep this in `openmeter/billing/charges/testutils`
 - if a charge create path stamps a new `LineEngineType`, app wiring and charge test wiring must register a matching implementation in the same change
 - usage-based exposes its billing line engine from `usagebased.Service.GetLineEngine()`; register that returned engine instead of reusing the service type directly
+- flat-fee now follows the same pattern: `flatfee.Service.GetLineEngine()` returns the engine owned by the service package
+- because flat-fee owns its line engine, `flatfee/service.New(...)` requires a `rating.Service`; forgetting that dependency breaks app/test wiring with `rating service cannot be null`
 
 Operational consequence:
 

app/common/charges.go

@@ -13,7 +13,6 @@ import (
 	creditpurchaseservice "github.com/openmeterio/openmeter/openmeter/billing/charges/creditpurchase/service"
 	"github.com/openmeterio/openmeter/openmeter/billing/charges/flatfee"
 	flatfeeadapter "github.com/openmeterio/openmeter/openmeter/billing/charges/flatfee/adapter"
-	flatfeelineengine "github.com/openmeterio/openmeter/openmeter/billing/charges/flatfee/lineengine"
 	flatfeeservice "github.com/openmeterio/openmeter/openmeter/billing/charges/flatfee/service"
 	"github.com/openmeterio/openmeter/openmeter/billing/charges/lineage"
 	lineageadapter "github.com/openmeterio/openmeter/openmeter/billing/charges/lineage/adapter"
@@ -146,13 +145,15 @@ func NewChargesFlatFeeService(
 	lineageService lineage.Service,
 	metaAdapter meta.Adapter,
 	locker *lockr.Locker,
+	ratingService rating.Service,
 ) (flatfee.Service, error) {
 	flatFeeSvc, err := flatfeeservice.New(flatfeeservice.Config{
-		Adapter:     flatFeeAdapter,
-		Handler:     flatFeeHandler,
-		Lineage:     lineageService,
-		MetaAdapter: metaAdapter,
-		Locker:      locker,
+		Adapter:       flatFeeAdapter,
+		Handler:       flatFeeHandler,
+		Lineage:       lineageService,
+		MetaAdapter:   metaAdapter,
+		Locker:        locker,
+		RatingService: ratingService,
 	})
 	if err != nil {
 		return nil, fmt.Errorf("failed to create charges flat fee service: %w", err)
@@ -325,20 +326,12 @@ func newChargesRegistry(
 		return nil, err
 	}
 
-	flatFeeSvc, err := NewChargesFlatFeeService(flatFeeAdapter, flatFeeHandler, lineageService, metaAdapter, locker)
+	flatFeeSvc, err := NewChargesFlatFeeService(flatFeeAdapter, flatFeeHandler, lineageService, metaAdapter, locker, ratingService)
 	if err != nil {
 		return nil, err
 	}
 
-	flatFeeLineEngine, err := flatfeelineengine.New(flatfeelineengine.Config{
-		FlatFeeService: flatFeeSvc,
-		RatingService:  ratingService,
-	})
-	if err != nil {
-		return nil, fmt.Errorf("failed to create charges flat fee line engine: %w", err)
-	}
-
-	if err := billingService.RegisterLineEngine(flatFeeLineEngine); err != nil {
+	if err := billingService.RegisterLineEngine(flatFeeSvc.GetLineEngine()); err != nil {
 		return nil, fmt.Errorf("failed to register charges flat fee line engine: %w", err)
 	}
 

openmeter/billing/adapter/stdinvoicelinemapper.go

@@ -209,43 +209,16 @@ func (a *adapter) mapStandardInvoiceDetailedLineFromDB(dbLine *db.BillingInvoice
 }
 
 func (a *adapter) mapStandardInvoiceDetailedLineV2FromDB(dbLine *db.BillingStandardInvoiceDetailedLine) (billing.DetailedLine, error) {
-	creditsApplied := lo.FromPtr(dbLine.CreditsApplied)
-	if len(creditsApplied) == 0 {
-		creditsApplied = nil
-	}
-
 	detailedLineBase := billing.DetailedLineBase{
 		InvoiceID: dbLine.InvoiceID,
-		Base: stddetailedline.Base{
-			ManagedResource: models.NewManagedResource(models.ManagedResourceInput{
-				Namespace:   dbLine.Namespace,
-				ID:          dbLine.ID,
-				CreatedAt:   dbLine.CreatedAt.In(time.UTC),
-				UpdatedAt:   dbLine.UpdatedAt.In(time.UTC),
-				DeletedAt:   convert.TimePtrIn(dbLine.DeletedAt, time.UTC),
-				Name:        dbLine.Name,
-				Description: dbLine.Description,
-			}),
-			ChildUniqueReferenceID: dbLine.ChildUniqueReferenceID,
-			ServicePeriod: timeutil.ClosedPeriod{
-				From: dbLine.ServicePeriodStart.In(time.UTC),
-				To:   dbLine.ServicePeriodEnd.In(time.UTC),
-			},
-			PerUnitAmount:  dbLine.PerUnitAmount,
-			Quantity:       dbLine.Quantity,
-			Category:       dbLine.Category,
-			PaymentTerm:    dbLine.PaymentTerm,
-			Index:          dbLine.Index,
-			Currency:       dbLine.Currency,
-			CreditsApplied: creditsApplied,
-			TaxConfig: backfillTaxConfigReferences(
+		Base: stddetailedline.FromDB(
+			dbLine,
+			backfillTaxConfigReferences(
 				lo.EmptyableToPtr(dbLine.TaxConfig),
 				dbLine.TaxBehavior,
 				taxCodeFromDetailedLineV2Edge(dbLine),
 			),
-			Totals:      totals.FromDB(dbLine),
-			ExternalIDs: externalid.MapLineExternalIDFromDB(dbLine),
-		},
+		),
 	}
 
 	discounts, err := slicesx.MapWithErr(dbLine.Edges.AmountDiscounts, a.mapStandardInvoiceDetailedLineAmountDiscountFromDB)

openmeter/billing/adapter/stdinvoicelines.go

@@ -12,6 +12,7 @@ import (
 
 	"github.com/openmeterio/openmeter/openmeter/billing"
 	"github.com/openmeterio/openmeter/openmeter/billing/models/externalid"
+	"github.com/openmeterio/openmeter/openmeter/billing/models/stddetailedline"
 	"github.com/openmeterio/openmeter/openmeter/billing/models/totals"
 	"github.com/openmeterio/openmeter/openmeter/customer"
 	"github.com/openmeterio/openmeter/openmeter/ent/db"
@@ -421,22 +422,9 @@ func (a *adapter) upsertDetailedLinesV2(ctx context.Context, in detailedLineDiff
 				SetID(line.ID).
 				SetNamespace(line.Namespace).
 				SetInvoiceID(line.InvoiceID).
-				SetServicePeriodStart(line.ServicePeriod.From.In(time.UTC)).
-				SetServicePeriodEnd(line.ServicePeriod.To.In(time.UTC)).
-				SetParentLineID(lineWithParent.Parent.ID).
-				SetNillableDeletedAt(line.DeletedAt).
-				SetName(line.Name).
-				SetNillableDescription(line.Description).
-				SetCurrency(line.Currency).
-				SetQuantity(line.Quantity).
-				SetPerUnitAmount(line.PerUnitAmount).
-				SetChildUniqueReferenceID(line.ChildUniqueReferenceID).
-				SetCategory(line.Category).
-				SetPaymentTerm(line.PaymentTerm).
-				SetNillableIndex(line.Index)
+				SetParentLineID(lineWithParent.Parent.ID)
 
-			create = externalid.CreateLineExternalID(create, line.ExternalIDs)
-			create = totals.Set(create, line.Totals)
+			create = stddetailedline.Create(create, line.Base)
 
 			if len(line.CreditsApplied) > 0 {
 				create = create.SetCreditsApplied(&line.CreditsApplied)

openmeter/billing/charges/flatfee/adapter.go

@@ -17,6 +17,7 @@ import (
 
 type Adapter interface {
 	ChargeAdapter
+	ChargeDetailedLineAdapter
 	ChargeCreditAllocationAdapter
 	ChargeInvoicedUsageAdapter
 	ChargePaymentAdapter
@@ -32,6 +33,11 @@ type ChargeAdapter interface {
 	GetByID(ctx context.Context, id GetByIDInput) (Charge, error)
 }
 
+type ChargeDetailedLineAdapter interface {
+	UpsertDetailedLines(ctx context.Context, chargeID meta.ChargeID, lines DetailedLines) error
+	FetchDetailedLines(ctx context.Context, charge Charge) (Charge, error)
+}
+
 type ChargeInvoicedUsageAdapter interface {
 	CreateInvoicedUsage(ctx context.Context, chargeID meta.ChargeID, invoicedUsage invoicedusage.AccruedUsage) (invoicedusage.AccruedUsage, error)
 }
@@ -89,7 +95,7 @@ func (i GetByIDsInput) Validate() error {
 		}
 	}
 
-	if err := i.Expands.Validate(); err != nil {
+	if err := validateExpands(i.Expands); err != nil {
 		errs = append(errs, fmt.Errorf("expands: %w", err))
 	}
 
@@ -107,7 +113,7 @@ func (i GetByIDInput) Validate() error {
 		errs = append(errs, fmt.Errorf("charge ID: %w", err))
 	}
 
-	if err := i.Expands.Validate(); err != nil {
+	if err := validateExpands(i.Expands); err != nil {
 		errs = append(errs, fmt.Errorf("expands: %w", err))
 	}
 
@@ -134,3 +140,15 @@ func (i CreateChargesInput) Validate() error {
 
 	return models.NewNillableGenericValidationError(errors.Join(errs...))
 }
+
+func validateExpands(expands meta.Expands) error {
+	if err := expands.Validate(); err != nil {
+		return err
+	}
+
+	if expands.Has(meta.ExpandDetailedLines) && !expands.Has(meta.ExpandRealizations) {
+		return fmt.Errorf("%q requires %q", meta.ExpandDetailedLines, meta.ExpandRealizations)
+	}
+
+	return nil
+}

openmeter/billing/charges/flatfee/adapter/charge.go

@@ -195,6 +195,12 @@ func (a *adapter) GetByIDs(ctx context.Context, input flatfee.GetByIDsInput) ([]
 			return nil, err
 		}
 
+		if input.Expands.Has(meta.ExpandDetailedLines) {
+			return slicesx.MapWithErr(out, func(charge flatfee.Charge) (flatfee.Charge, error) {
+				return tx.FetchDetailedLines(ctx, charge)
+			})
+		}
+
 		return out, nil
 	})
 }
@@ -227,6 +233,10 @@ func (a *adapter) GetByID(ctx context.Context, input flatfee.GetByIDInput) (flat
 			return flatfee.Charge{}, err
 		}
 
+		if input.Expands.Has(meta.ExpandDetailedLines) {
+			return tx.FetchDetailedLines(ctx, charge)
+		}
+
 		return charge, nil
 	})
 }