diff --git a/OpheliasOasis/Models/Transaction.cs b/OpheliasOasis/Models/Transaction.cs index 14c6b8c..70e8d2b 100644 --- a/OpheliasOasis/Models/Transaction.cs +++ b/OpheliasOasis/Models/Transaction.cs @@ -5,6 +5,45 @@ namespace Ophelias.Models { internal class Transaction { + /* + * This class is related to a specific reservation, however, + * the correlation is not two ways as a transaction is a + * member of the reservation but not the other way around. + * Reservations are related to transactions by their ID. + * The transaction class is comprised of the following: + * + * Id + * Unique identifier + * + * Rate + * The base rate set for the transaction + * + * Owed + * The total amount a user owes + * + * Penalty + * This is a legacy item but exists for future functionality where penalty amounts + * may be set + * + * Multiplier + * The fee multiplier based on reservation status or type, see TxFunctions + * + * RefundAmount + * The amount to be refunded, currently a legacy item that remained for potential + * future use + * + * AmountPaid + * The amount of money paid by a guest + * + * PayBy + * The date a transaction should be paid by at the latest + * + * LastPaid + * The date a payment was last made + * + * PaidOn + * The date the transaction was paid off (when Owed = AmountPaid) + */ internal int Id; internal double Rate; internal double Owed; @@ -20,10 +59,15 @@ namespace Ophelias.Models double Multiplier, DateTime PayBy, DateTime? LastPaid = null, DateTime? PaidOn = null, double RefundAmount = 0, double Penalty = 0, double AmountPaid = 0) { + /* + * Creates a new transaction based on the assumption it never existed before. + * This constructor will create a new transaction in the database and return + * the ID from the database insertion. + */ int Id; - using (Database Manager = new()) + using (Database Manager = new()) // Create a new connection to the database { - using (SQLiteCommand cmd = Manager.con.CreateCommand()) + using (SQLiteCommand cmd = Manager.con.CreateCommand()) // Creates a new command that will be executed in the database { cmd.CommandText = "INSERT INTO transactions (Rate, Owed, Penalty, Multiplier, RefundAmount, AmountPaid, PayBy, LastPaid, PaidOn) " + "VALUES (@Rate, @Owed, @Penalty, @Multiplier, @RefundAmount, @AmountPaid, @PayBy, @LastPaid, @PaidOn)"; @@ -54,10 +98,9 @@ namespace Ophelias.Models cmd.Parameters.AddWithValue("@PaidOn", PaidOn); } - //cmd.CommandText = QueryBuilder.CreateTransaction(Rate, Owed, Multiplier, PayBy, Refund: RefundAmount, Penalty: Penalty, LastPaid: LastPaid, PaidOn: PaidOn); cmd.ExecuteNonQuery(); } - Id = (int)Manager.con.LastInsertRowId; + Id = (int)Manager.con.LastInsertRowId; // Sets the ID based on the ID returned by database insertion } this.Id = Id; this.Rate = Rate; @@ -74,6 +117,9 @@ namespace Ophelias.Models double Multiplier, DateTime PayBy, DateTime? LastPaid = null, DateTime? PaidOn = null, double RefundAmount = 0, double Penalty = 0, double AmountPaid = 0) { + /* + * Creates a new instance of transaction based on an existing transaction. + */ this.Id = Id; this.Rate = Rate; this.Owed = Owed; @@ -88,12 +134,17 @@ namespace Ophelias.Models internal void UpdateTransactionFees(double Rate, double Multiplier, DateTime PayBy) { + /* + * This function is used in conjunction with Reservation's UpdateReservation function + * typically as this function updates a transaction with the new fees and PayBy date. + * These changes are stored on the existing model and written out to the database. + */ this.Rate = Rate; this.Multiplier = Multiplier; this.PayBy = PayBy; using Database Manager = new(); using SQLiteCommand cmd = Manager.con.CreateCommand(); - string? query = QueryBuilder.UpdateTransaction(Id: Id, Rate: this.Rate, Multiplier: this.Multiplier, PayBy: this.PayBy); + string? query = QueryBuilder.UpdateTransaction(Id: Id, Rate: this.Rate, Multiplier: this.Multiplier, PayBy: this.PayBy); // Query string with parameters if (query == null) { @@ -109,6 +160,21 @@ namespace Ophelias.Models } internal PaymentStatus Pay(double Amount, string cc) { + /* + * This function attempts to make a payment based on the amount specified + * and if a creditcard exists. While we should be checking if the card is + * expired here, there are other systems further up the stack that prevent + * that from happening. Changes in the future would benefit us if we implement it + * down the line. Outside of that specific design, this class will return + * a payment status based on various conditions such as attempts to pay $0 or less, + * paying an already paid transaction and so forth. See the PaymentStatus enum for + * all the types which use self-explanatory names. Assuming payment is succesful, + * the AmountPaid is updated and the PaidOn date is set. These changes are then reflected + * to the database. Currently there is a refund parameter, however, it has not been + * implemented since refunds were not called for in the original design spec. + */ + + // Series of checks to prevent payment on certain conditions if (string.IsNullOrEmpty(cc)) { return PaymentStatus.MissingCreditCard; @@ -124,19 +190,19 @@ namespace Ophelias.Models LastPaid = DateTime.Now; AmountPaid += Amount; - if (Owed - AmountPaid < 0) + if (Owed - AmountPaid < 0) // Calulates the refund amount if applicable { RefundAmount = Math.Abs(Owed - Amount); } - if (Owed - AmountPaid <= 0) + if (Owed - AmountPaid <= 0) // Sets the paid by date { PaidOn = DateTime.Now; } - using Database Manager = new(); - using SQLiteCommand cmd = Manager.con.CreateCommand(); - string? query = QueryBuilder.UpdateTransaction(Id: Id, Refund: RefundAmount, AmountPaid: AmountPaid, LastPaid: LastPaid, PaidOn: PaidOn); + using Database Manager = new(); // Opens a new database connection + using SQLiteCommand cmd = Manager.con.CreateCommand(); // Creates a new command that will be executed in the database + string? query = QueryBuilder.UpdateTransaction(Id: Id, Refund: RefundAmount, AmountPaid: AmountPaid, LastPaid: LastPaid, PaidOn: PaidOn); // Query string with parameters if (query == null) { @@ -156,11 +222,16 @@ namespace Ophelias.Models } internal void Refund() { - AmountPaid -= RefundAmount; + /* + * This function is unused, however, it exists for when refund functionality becomes + * supported. As for the functionality, this sets the refund amount in the database and + * zeros it out as if it has been refunded. There is no payment system so changes are + * heavily simplified compared to real world scenarios. + */ RefundAmount = 0; - using Database Manager = new(); - using SQLiteCommand cmd = Manager.con.CreateCommand(); - string? query = QueryBuilder.UpdateTransaction(Id: Id, Refund: RefundAmount); + using Database Manager = new(); // Creates a new database connection + using SQLiteCommand cmd = Manager.con.CreateCommand(); // Creates a new command that will be executed in the database + string? query = QueryBuilder.UpdateTransaction(Id: Id, Refund: RefundAmount); // Query string with parameters if (query == null) { @@ -176,23 +247,37 @@ namespace Ophelias.Models internal static class TxFunctions { + /* + * This class is a set of functions that are not specifically + * tied to the Transaction class, but are closely related. + * This class is typically called upon for specific functions + * or information such as fee multipliers. + */ internal static double ConventionalFee = 1.0; internal static double PrepaidFee = 0.75; internal static double SixtyDayFee = 0.85; internal static double Changed = 1.1; internal static double IncentiveFee(DateTime Start, DateTime End) { + /* + * This returns the incentive fee if the hotel is operating + * at an occupancy of 60% or less. If so the fee mutltiplier + * is 80% else 100%. + */ int thirtyDayOcc; (thirtyDayOcc, _) = Hotel.AvgOccupancySpan(Start, End); if ((double)(thirtyDayOcc / 45.0) <= 0.6) { return 0.80; } - return 1.0; } internal static DateTime GetPayByDate(ReservationType Type, DateTime StartDate, DateTime EndDate) { + /* + * This class reports the date a reservation should be paid on + * at the latest based on the reservation type. + */ switch (Type) { case ReservationType.Conventional: return EndDate; @@ -204,12 +289,13 @@ namespace Ophelias.Models } internal static double CalculateOwed(double Rate, int Days, double Multiplier) { - return Math.Round(Rate * Days * Multiplier); + // Calculates the amount owed rounded to two decimals + return Math.Round(Rate * Days * Multiplier, 2); } } - internal enum PaymentStatus + internal enum PaymentStatus // Represents numerical values as words { SuccessfulPayment, AlreadyPaid,