πŸ“„ BillingInvoice.cs Documentation


πŸ“‘ Table of Contents

  1. πŸ“ Overview & Purpose
  2. πŸ”‘ Key Functional Areas
  3. πŸ“¦ Dependencies & Technologies
  4. πŸ—‚οΈ Data Model Details
  5. πŸ“‹ Property Reference
  6. πŸ”§ Usage Examples
  7. πŸ“ˆ Entity Framework Configuration
  8. πŸ–ΌοΈ UML Class Diagram
  9. πŸ€” Best Practices & Recommendations
  10. πŸš€ 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.BillingInvoice table using [Table].
    • Primary key defined by [Key].
  • Data Representation

    • Holds invoice metadata (e.g., InvoiceYearMonth, CarrierId).
    • Stores contact info (PhoneNumber, FirstName, LastName).
    • Includes financial data (Charge, GeneralLedgerId).
  • 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 IsDeleted to implement soft-delete.
    • Always filter out deleted records (!IsDeleted) in queries.
  • Audit Trail:

    • Automatically set AddedDate/ModifiedDate via EF Core interceptors.
    • Ensure ModifiedBy is updated on every save.
  • Validation:

    • Add [Required] or [StringLength] attributes as needed to enforce data integrity.
  • Denormalized Fields:

    • CarrierName and EmployeeName help 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! πŸ§ΎπŸ’°