π BillingInvoice.cs Documentation
π Table of Contents
- π Overview & Purpose
- π Key Functional Areas
- π¦ Dependencies & Technologies
- ποΈ Data Model Details
- π Property Reference
- π§ Usage Examples
- π Entity Framework Configuration
- πΌοΈ UML Class Diagram
- π€ Best Practices & Recommendations
- π Conclusion
π Overview & Purpose
BillingInvoice.cs is a plain-old CLR object (POCO) that represents the Billing Invoice entity in the irby schema of the database. This class is used with Entity Framework (Code First) to map invoice data, such as charges, job details, customer information, and audit fields, into the BillingInvoice table.
Intended Use:
- Store and retrieve invoices for carriers.
- Keep track of audit trails (added/modified by & dates).
- Simplify billing queries in the application.
π Key Functional Areas
-
Database Mapping
- Maps the C# class to the
irby.BillingInvoicetable using[Table]. - Primary key defined by
[Key].
- Maps the C# class to the
-
Data Representation
- Holds invoice metadata (e.g.,
InvoiceYearMonth,CarrierId). - Stores contact info (
PhoneNumber,FirstName,LastName). - Includes financial data (
Charge,GeneralLedgerId).
- Holds invoice metadata (e.g.,
-
Audit Trails
- Tracks who added or modified the invoice.
- Stores timestamps (
AddedDate,ModifiedDate).
π¦ Dependencies & Technologies
| Technology / Package | Purpose |
|---|---|
System |
Base .NET types (e.g., Guid, DateTime, Decimal). |
System.ComponentModel.DataAnnotations |
Data validation & metadata (e.g., [Key], [Display]). |
System.ComponentModel.DataAnnotations.Schema |
Schema mapping (e.g., [Table]). |
| Entity Framework Core (EF Core) | ORM for database CRUD operations. |
ποΈ Data Model Details
using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
namespace IrbyImaging.DomainClasses
{
[Table("BillingInvoice", Schema = "irby")]
public class BillingInvoice
{
[Key]
public Guid Id { get; set; }
public Guid CarrierId { get; set; }
public string InvoiceYearMonth { get; set; }
public string PhoneNumber { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
public string JDENumber { get; set; }
public decimal Charge { get; set; }
public string JobNumber { get; set; }
public string JobName { get; set; }
public Guid GeneralLedgerId { get; set; }
public string FileName { get; set; }
public bool IsDeleted { get; set; }
[Display(Name = "Added By")]
public string AddedBy { get; set; }
[Display(Name = "Added Date")]
public DateTime AddedDate { get; set; }
[Display(Name = "Modified By")]
public string ModifiedBy { get; set; }
[Display(Name = "Modified Date")]
public DateTime ModifiedDate { get; set; }
// Denormalized / helper fields
public string CarrierName { get; set; }
public string EmployeeName { get; set; }
}
}
π Property Reference
| Property | Type | Description |
|---|---|---|
| Id | Guid |
Primary Key. Unique identifier for the invoice. |
| CarrierId | Guid |
Foreign key to the carrier entity. |
| InvoiceYearMonth | string |
Year and month of the invoice in YYYYMM format (e.g., "202203"). |
| PhoneNumber | string |
Customer or contact phone number. |
| FirstName | string |
Contactβs first name. |
| LastName | string |
Contactβs last name. |
| JDENumber | string |
External JDE system identifier. |
| Charge | decimal |
Invoice amount / charge. |
| JobNumber | string |
Internal job code. |
| JobName | string |
Descriptive name of the job. |
| GeneralLedgerId | Guid |
Ledger reference for financial integration. |
| FileName | string |
Attached invoice file name (if any). |
| IsDeleted | bool |
Soft-delete flag (true = deleted). |
| AddedBy | string |
Username or identifier who created the record. |
| AddedDate | DateTime |
Timestamp when the record was added. |
| ModifiedBy | string |
Username or identifier who last modified the record. |
| ModifiedDate | DateTime |
Timestamp of the last modification. |
| CarrierName | string |
(Denormalized) Carrier display name. |
| EmployeeName | string |
(Denormalized) Employee display name. |
π§ Usage Examples
1. Adding a New Invoice
var invoice = new BillingInvoice
{
Id = Guid.NewGuid(),
CarrierId = carrier.Id,
InvoiceYearMonth = "202204",
FirstName = "Jane",
LastName = "Doe",
PhoneNumber = "555-1234",
JDENumber = "JDE-7890",
Charge = 1500.75m,
JobNumber = "JOB-2022-04",
JobName = "Site Inspection",
GeneralLedgerId = glAccount.Id,
FileName = "Invoice_Apr_2022.pdf",
IsDeleted = false,
AddedBy = currentUser,
AddedDate = DateTime.UtcNow,
ModifiedBy = currentUser,
ModifiedDate = DateTime.UtcNow
};
dbContext.BillingInvoices.Add(invoice);
dbContext.SaveChanges();
2. Querying Invoices By Month & Carrier
var aprilInvoices = dbContext.BillingInvoices
.Where(inv => inv.CarrierId == carrier.Id
&& inv.InvoiceYearMonth == "202204"
&& !inv.IsDeleted)
.OrderBy(inv => inv.LastName)
.ToList();
π Entity Framework Configuration
-
Table Mapping:
[Table("BillingInvoice", Schema = "irby")] -
Primary Key:
[Key] public Guid Id { get; set; } -
Display Attributes:
- Used for UI frameworks (e.g., ASP.NET MVC) to render friendly labels.
- Example:
[Display(Name = "Added Date")] public DateTime AddedDate { get; set; }
πΌοΈ UML Class Diagram
+--------------------------------+
| BillingInvoice |
+--------------------------------+
| - Id : Guid |
| - CarrierId : Guid |
| - InvoiceYearMonth : string |
| - PhoneNumber : string |
| - FirstName : string |
| - LastName : string |
| - JDENumber : string |
| - Charge : decimal |
| - JobNumber : string |
| - JobName : string |
| - GeneralLedgerId : Guid |
| - FileName : string |
| - IsDeleted : bool |
| - AddedBy : string |
| - AddedDate : DateTime |
| - ModifiedBy : string |
| - ModifiedDate : DateTime |
| - CarrierName : string |
| - EmployeeName : string |
+--------------------------------+
π€ Best Practices & Recommendations
-
Soft Deletes:
- Utilize
IsDeletedto implement soft-delete. - Always filter out deleted records (
!IsDeleted) in queries.
- Utilize
-
Audit Trail:
- Automatically set
AddedDate/ModifiedDatevia EF Core interceptors. - Ensure
ModifiedByis updated on every save.
- Automatically set
-
Validation:
- Add
[Required]or[StringLength]attributes as needed to enforce data integrity.
- Add
-
Denormalized Fields:
CarrierNameandEmployeeNamehelp display human-readable values without joins.- Keep them in sync via triggers or application logic.
π Conclusion
The BillingInvoice class is a foundational data model in the Irby Imaging domain for handling billing and invoicing operations. It encapsulates all relevant invoice details, audit information, and mappings required by Entity Framework. By following the patterns demonstrated above, you can seamlessly perform CRUD operations, maintain data integrity, and extend the model with custom logic (validation, events, etc.) as business requirements evolve.
Happy Billing! π§Ύπ°