arolariu.Backend.Domain.Invoices.Services.Orchestration.InvoiceService
arolariu.Backend.Domain.Invoices
arolariu.Backend.Domain.Invoices.Services.Orchestration.InvoiceService Namespace
Classes
InvoiceOrchestrationService Class
The invoice orchestration service interface represents the orchestration service for the invoice domain.
public class InvoiceOrchestrationService : arolariu.Backend.Domain.Invoices.Services.Orchestration.InvoiceService.IInvoiceOrchestrationService
Inheritance System.Object 🡒 InvoiceOrchestrationService
Implements IInvoiceOrchestrationService
Constructors
InvoiceOrchestrationService(IInvoiceAnalysisFoundationService, IInvoiceStorageFoundationService, ILoggerFactory) Constructor
Constructor.
public InvoiceOrchestrationService(arolariu.Backend.Domain.Invoices.Services.Foundation.InvoiceAnalysis.IInvoiceAnalysisFoundationService invoiceAnalysisFoundationService, arolariu.Backend.Domain.Invoices.Services.Foundation.InvoiceStorage.IInvoiceStorageFoundationService invoiceStorageFoundationService, Microsoft.Extensions.Logging.ILoggerFactory loggerFactory);
Parameters
invoiceAnalysisFoundationService IInvoiceAnalysisFoundationService
invoiceStorageFoundationService IInvoiceStorageFoundationService
loggerFactory Microsoft.Extensions.Logging.ILoggerFactory
Methods
InvoiceOrchestrationService.AnalyzeInvoiceWithOptions(AnalysisOptions, Guid, Nullable<Guid>, CancellationToken) Method
Executes an analysis workflow for a specific invoice using the supplied option flags.
public System.Threading.Tasks.Task AnalyzeInvoiceWithOptions(arolariu.Backend.Domain.Invoices.DTOs.AnalysisOptions options, System.Guid invoiceIdentifier, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
options AnalysisOptions
Directive flags controlling which analysis / enrichment steps to perform (MUST NOT be null).
invoiceIdentifier System.Guid
Target invoice identifier (MUST reference an existing invoice).
userIdentifier System.Nullable<System.Guid>
Optional tenant / partition scope (enforced for ownership isolation).
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Implements AnalyzeInvoiceWithOptions(AnalysisOptions, Guid, Nullable<Guid>, CancellationToken)
Returns
System.Threading.Tasks.Task
Asynchronous task.
Exceptions
System.ArgumentNullException
Thrown if options is null.
System.InvalidOperationException
Thrown if invoice not found or fails pre-analysis invariants.
System.OperationCanceledException
Thrown if the operation is cancelled.
Remarks
Behavior: Orchestrates retrieval (if not already loaded downstream), validation, then delegates enrichment / classification steps to processing / foundation analysis components.
Side Effects: May update persisted invoice state if analysis results are persisted (future enhancement). Currently assumed to be synchronous; backlog: promote to async operation resource.
Idempotency: Re-running with identical inputs SHOULD yield semantically equivalent enrichment unless time‑variant data sources are consulted (e.g., external tax rates).
InvoiceOrchestrationService.CreateInvoiceObject(Invoice, Nullable<Guid>, CancellationToken) Method
Creates (persists) a new invoice aggregate via the underlying foundation storage service.
public System.Threading.Tasks.Task<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice> CreateInvoiceObject(arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice invoice, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
invoice Invoice
Fully initialized invoice aggregate to persist.
userIdentifier System.Nullable<System.Guid>
Optional tenant / partition scope.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Implements CreateInvoiceObject(Invoice, Nullable<Guid>, CancellationToken)
Returns
System.Threading.Tasks.Task<Invoice>
Persisted invoice aggregate (may contain persistence-generated fields).
Remarks
Workflow: Validate inbound aggregate → delegate to foundation storage → optionally trigger post-create hooks (future: events).
Failure Modes: Validation exceptions for invariant breaches; dependency / dependency validation exceptions surfaced from foundation layer and wrapped by implementation.
InvoiceOrchestrationService.DeleteInvoiceObject(Guid, Nullable<Guid>, CancellationToken) Method
Deletes (logical or physical depending on foundation strategy) a single invoice.
public System.Threading.Tasks.Task DeleteInvoiceObject(System.Guid identifier, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
identifier System.Guid
Invoice identifier.
userIdentifier System.Nullable<System.Guid>
Optional tenant / partition scope.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Implements DeleteInvoiceObject(Guid, Nullable<Guid>, CancellationToken)
Returns
System.Threading.Tasks.Task
Asynchronous task.
Remarks
Idempotency: Repeated calls yield stable terminal state.
Side Effects: No cascading delete in orchestration layer (future: explicit cascade policy / event emission).
InvoiceOrchestrationService.ReadAllInvoiceObjects(Guid, CancellationToken) Method
Retrieves all invoices for an optional partition scope.
public System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice>> ReadAllInvoiceObjects(System.Guid userIdentifier, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
userIdentifier System.Guid
Tenant / partition scope.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Implements ReadAllInvoiceObjects(Guid, CancellationToken)
Returns
System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<Invoice>>
Sequence of invoices (empty if none).
Remarks
Pagination: Not supported yet (backlog). Implementations SHOULD avoid unbounded materialization where possible.
InvoiceOrchestrationService.ReadInvoiceObject(Guid, Nullable<Guid>, CancellationToken) Method
Retrieves a single invoice aggregate by identifier.
public System.Threading.Tasks.Task<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice> ReadInvoiceObject(System.Guid identifier, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
identifier System.Guid
Invoice identifier.
userIdentifier System.Nullable<System.Guid>
Optional tenant / partition scope.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Implements ReadInvoiceObject(Guid, Nullable<Guid>, CancellationToken)
Returns
System.Threading.Tasks.Task<Invoice>
Invoice instance (null or exception if not found per implementation policy).
Remarks
Behavior: Delegates to foundation storage; may augment with orchestration-level caching or access policy enforcement in future.
InvoiceOrchestrationService.UpdateInvoiceObject(Invoice, Guid, Nullable<Guid>, CancellationToken) Method
Updates (replaces) an existing invoice aggregate.
public System.Threading.Tasks.Task<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice> UpdateInvoiceObject(arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice updatedInvoice, System.Guid invoiceIdentifier, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
updatedInvoice Invoice
Proposed new invoice state.
invoiceIdentifier System.Guid
Identifier of invoice being updated.
userIdentifier System.Nullable<System.Guid>
Optional tenant / partition scope.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Implements UpdateInvoiceObject(Invoice, Guid, Nullable<Guid>, CancellationToken)
Returns
System.Threading.Tasks.Task<Invoice>
Updated invoice instance.
Remarks
Validation: Ensures identifier consistency (argument id vs aggregate id if enforced) and domain invariants prior to persistence.
Concurrency: No ETag support yet; potential overwrite of concurrent updates (backlog: optimistic concurrency).
Interfaces
IInvoiceOrchestrationService Interface
Orchestration layer contract for coordinating invoice-related workflows across foundation services and (optionally) processing concerns.
public interface IInvoiceOrchestrationService
Derived
↳ InvoiceOrchestrationService
Remarks
Layer Role (The Standard): Orchestration services compose one or more foundation services, apply cross-cutting policies (validation sequencing, exception classification, retry / resilience hooks), and prepare data for upstream presentation layers. They MUST NOT contain raw persistence calls (delegated to foundation) nor heavy computational enrichment (delegated to processing).
Responsibilities:
- Sequence domain operations (e.g., validate → store → analyze) while maintaining clear transactional boundaries.
- Translate low-level dependency / validation exceptions into higher-order orchestration exceptions (per The Standard).
- Enforce partition / ownership rules by propagating or asserting
userIdentifier. - Invoke processing / analysis workflows when explicitly requested (e.g., AnalyzeInvoiceWithOptions).
Exclusions: No direct HTTP / transport awareness, no UI mapping, no persistence broker usage directly, no long-running state machines (those belong to a higher saga / workflow coordinator if introduced).
Idempotency: Read / delete operations are naturally idempotent; create and update operations SHOULD guard against duplicate or stale writes (future: optimistic concurrency tokens).
Error Strategy: Implementations SHOULD capture foundation exceptions and wrap them into orchestration-level exceptions to keep vertical layering separable for observability and policy (e.g., global exception middleware).
Methods
IInvoiceOrchestrationService.AnalyzeInvoiceWithOptions(AnalysisOptions, Guid, Nullable<Guid>, CancellationToken) Method
Executes an analysis workflow for a specific invoice using the supplied option flags.
System.Threading.Tasks.Task AnalyzeInvoiceWithOptions(arolariu.Backend.Domain.Invoices.DTOs.AnalysisOptions options, System.Guid invoiceIdentifier, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
options AnalysisOptions
Directive flags controlling which analysis / enrichment steps to perform (MUST NOT be null).
invoiceIdentifier System.Guid
Target invoice identifier (MUST reference an existing invoice).
userIdentifier System.Nullable<System.Guid>
Optional tenant / partition scope (enforced for ownership isolation).
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Returns
System.Threading.Tasks.Task
Asynchronous task.
Exceptions
System.ArgumentNullException
Thrown if options is null.
System.InvalidOperationException
Thrown if invoice not found or fails pre-analysis invariants.
System.OperationCanceledException
Thrown if the operation is cancelled.
Remarks
Behavior: Orchestrates retrieval (if not already loaded downstream), validation, then delegates enrichment / classification steps to processing / foundation analysis components.
Side Effects: May update persisted invoice state if analysis results are persisted (future enhancement). Currently assumed to be synchronous; backlog: promote to async operation resource.
Idempotency: Re-running with identical inputs SHOULD yield semantically equivalent enrichment unless time‑variant data sources are consulted (e.g., external tax rates).
IInvoiceOrchestrationService.CreateInvoiceObject(Invoice, Nullable<Guid>, CancellationToken) Method
Creates (persists) a new invoice aggregate via the underlying foundation storage service.
System.Threading.Tasks.Task<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice> CreateInvoiceObject(arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice invoice, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
invoice Invoice
Fully initialized invoice aggregate to persist.
userIdentifier System.Nullable<System.Guid>
Optional tenant / partition scope.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Returns
System.Threading.Tasks.Task<Invoice>
Persisted invoice aggregate (may contain persistence-generated fields).
Remarks
Workflow: Validate inbound aggregate → delegate to foundation storage → optionally trigger post-create hooks (future: events).
Failure Modes: Validation exceptions for invariant breaches; dependency / dependency validation exceptions surfaced from foundation layer and wrapped by implementation.
IInvoiceOrchestrationService.DeleteInvoiceObject(Guid, Nullable<Guid>, CancellationToken) Method
Deletes (logical or physical depending on foundation strategy) a single invoice.
System.Threading.Tasks.Task DeleteInvoiceObject(System.Guid identifier, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
identifier System.Guid
Invoice identifier.
userIdentifier System.Nullable<System.Guid>
Optional tenant / partition scope.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Returns
System.Threading.Tasks.Task
Asynchronous task.
Remarks
Idempotency: Repeated calls yield stable terminal state.
Side Effects: No cascading delete in orchestration layer (future: explicit cascade policy / event emission).
IInvoiceOrchestrationService.ReadAllInvoiceObjects(Guid, CancellationToken) Method
Retrieves all invoices for an optional partition scope.
System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice>> ReadAllInvoiceObjects(System.Guid userIdentifier, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
userIdentifier System.Guid
Tenant / partition scope.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Returns
System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<Invoice>>
Sequence of invoices (empty if none).
Remarks
Pagination: Not supported yet (backlog). Implementations SHOULD avoid unbounded materialization where possible.
IInvoiceOrchestrationService.ReadInvoiceObject(Guid, Nullable<Guid>, CancellationToken) Method
Retrieves a single invoice aggregate by identifier.
System.Threading.Tasks.Task<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice> ReadInvoiceObject(System.Guid identifier, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
identifier System.Guid
Invoice identifier.
userIdentifier System.Nullable<System.Guid>
Optional tenant / partition scope.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Returns
System.Threading.Tasks.Task<Invoice>
Invoice instance (null or exception if not found per implementation policy).
Remarks
Behavior: Delegates to foundation storage; may augment with orchestration-level caching or access policy enforcement in future.
IInvoiceOrchestrationService.UpdateInvoiceObject(Invoice, Guid, Nullable<Guid>, CancellationToken) Method
Updates (replaces) an existing invoice aggregate.
System.Threading.Tasks.Task<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice> UpdateInvoiceObject(arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice updatedInvoice, System.Guid invoiceIdentifier, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
updatedInvoice Invoice
Proposed new invoice state.
invoiceIdentifier System.Guid
Identifier of invoice being updated.
userIdentifier System.Nullable<System.Guid>
Optional tenant / partition scope.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Returns
System.Threading.Tasks.Task<Invoice>
Updated invoice instance.
Remarks
Validation: Ensures identifier consistency (argument id vs aggregate id if enforced) and domain invariants prior to persistence.
Concurrency: No ETag support yet; potential overwrite of concurrent updates (backlog: optimistic concurrency).