payservedb 4.9.2 → 4.9.4

package/src/models/invoice.js

@@ -1,277 +1,292 @@
-const mongoose = require("mongoose");
-
-const invoiceSchema = new mongoose.Schema(
-  {
-    invoiceNumber: {
-      type: String,
-      required: true,
-      unique: true,
-    },
-    accountNumber: {
-      type: String,
-      required: true,
-      unique: true,
-    },
-    client: {
-      clientId: {
-        type: mongoose.Schema.Types.ObjectId,
-        ref: "Customer",
-        required: true,
-      },
-      firstName: {
-        type: String,
-        required: true
-      },
-      lastName: {
-        type: String,
-        required: true
-      }
-    },
-    facility: {
-      id: {
-        type: mongoose.Schema.Types.ObjectId,
-        ref: "Facility",
-        required: true,
-      },
-      name: {
-        type: String,
-        required: true
-      }
-    },
-    unit: {
-      id: { type: mongoose.Schema.Types.ObjectId, ref: "Unit", required: true },
-      name: { type: String, required: true },
-    },
-    currency: {
-      id: {
-        type: mongoose.Schema.Types.ObjectId,
-        ref: "Currency",
-        required: true
-      },
-      name: {
-        type: String,
-        required: true
-      },
-      code: {
-        type: String,
-        required: true,
-        uppercase: true,
-        minlength: 3,
-        maxlength: 3
-      }
-    },
-    items: [
-      {
-        description: { type: String, required: true },
-        quantity: { type: Number, required: true, min: 1 },
-        unitPrice: { type: Number, required: true, min: 0 },
-      },
-    ],
-    subTotal: {
-      type: Number,
-      required: true,
-    },
-    tax: {
-      type: Number,
-      required: true,
-    },
-    totalAmount: {
-      type: Number,
-      required: true,
-    },
-    amountPaid: {
-      type: Number,
-      default: 0,
-      min: 0,
-    },
-    // Mark as deprecated, keep for backward compatibility
-    overpay: {
-      type: Number,
-      default: 0,
-      min: 0,
-      deprecated: true
-    },
-    issueDate: {
-      type: Date,
-      required: true,
-    },
-    dueDate: {
-      type: Date,
-      required: true,
-    },
-    status: {
-      type: String,
-      required: true,
-      enum: ["Unpaid", "Pending", "Paid", "Overdue", "Cancelled", "Partially Paid"],
-    },
-    penalty: {
-      type: Number,
-      default: 0,
-    },
-    whatFor: {
-      invoiceType: { type: String, required: true },
-      description: { type: String },
-    },
-    invoiceNote: {
-      type: String,
-      default: null,
-    },
-    // Enhanced balanceBroughtForward field
-    // Positive values = customer owes money
-    // Negative values = credit (previously tracked in overpay field)
-    balanceBroughtForward: {
-      type: Number,
-      default: 0,
-    },
-    lastReminderSent: Date,
-    reminderHistory: [
-      {
-        sentAt: Date,
-        reminderId: mongoose.Schema.Types.ObjectId,
-        notificationTypes: [String],
-      },
-    ],
-    reconciliationHistory: [{
-      date: { type: Date, required: true },
-      amount: { type: Number, required: true },
-      type: {
-        type: String,
-        enum: ['payment', 'cash', 'cheque', 'bank-transfer', 'mpesa-transfer', 'overpay-transfer', 'balance-deduction', 'overpay-received', 'credit-forward', 'debit-forward'],
-        required: true
-      },
-      sourceInvoice: String,
-      destinationInvoice: String,
-      paymentReference: String,
-      paymentCompletion: String,
-      remainingBalance: Number,
-      notes: String,
-      exchangeRate: {
-        type: Number,
-        default: 1  // For cross-currency reconciliations
-      },
-      originalCurrency: {
-        code: String,  // Original currency code if different from invoice currency
-        amount: Number // Amount in original currency
-      }
-    }],
-    paymentDetails: {
-      paymentStatus: { type: String, required: true },
-      paymentMethod: { type: String },
-      paymentDate: { type: Date },
-      transactionId: { type: String },
-    },
-    // New field to track when an invoice has been viewed
-    viewStatus: {
-      isOpened: { type: Boolean, default: false },
-      openedAt: { type: Date, default: null },
-      openedBy: {
-        facilityId: { type: mongoose.Schema.Types.ObjectId, ref: "Facility" },
-        userId: { type: mongoose.Schema.Types.ObjectId, ref: "User" },
-        userRole: { type: String }
-      },
-      viewHistory: [{
-        viewedAt: { type: Date, required: true },
-        facilityId: { type: mongoose.Schema.Types.ObjectId, ref: "Facility" },
-        userId: { type: mongoose.Schema.Types.ObjectId, ref: "User" }
-      }]
-    }
-  },
-  {
-    timestamps: true,
-  }
-);
-
-// Add indexes for frequently queried fields
-invoiceSchema.index({ accountNumber: 1 });
-invoiceSchema.index({ status: 1 });
-invoiceSchema.index({ 'client.clientId': 1, status: 1 });
-invoiceSchema.index({ 'reconciliationHistory.paymentReference': 1 });
-invoiceSchema.index({ issueDate: -1 });
-invoiceSchema.index({ 'currency.code': 1 }); // Add index for currency code
-invoiceSchema.index({ 'currency.id': 1 }); // Add index for currency ID
-invoiceSchema.index({ 'currency.code': 1, 'client.clientId': 1, status: 1 }); // Compound index for currency-based queries
-invoiceSchema.index({ 'client.clientId': 1, balanceBroughtForward: 1 }); // Add index for finding invoices with credit balances
-invoiceSchema.index({ 'viewStatus.isOpened': 1 }); // Add index for view status
-invoiceSchema.index({ 'viewStatus.openedBy.facilityId': 1 }); // Add index for facility view tracking
-
-// Add virtual field for calculating balance
-invoiceSchema.virtual('calculatedBalance').get(function () {
-  const baseBalance = this.totalAmount - (this.amountPaid || 0);
-
-  // Add positive balanceBroughtForward (customer owes money)
-  if (this.balanceBroughtForward > 0) {
-    return baseBalance + this.balanceBroughtForward;
-  }
-
-  // Subtract negative balanceBroughtForward (credit)
-  return baseBalance;
-});
-
-// Add virtual field for credit balance
-invoiceSchema.virtual('creditBalance').get(function () {
-  return this.balanceBroughtForward < 0 ? Math.abs(this.balanceBroughtForward) : 0;
-});
-
-// Getter for compatible overpay field
-invoiceSchema.virtual('effectiveOverpay').get(function () {
-  return this.balanceBroughtForward < 0 ? Math.abs(this.balanceBroughtForward) : 0;
-});
-
-// Add method for currency conversion if needed
-invoiceSchema.methods.convertAmount = function (amount, fromCurrency, toCurrency, exchangeRate) {
-  if (fromCurrency === toCurrency) {
-    return amount;
-  }
-  return amount * exchangeRate;
-};
-
-// Add static method to find invoices by currency
-invoiceSchema.statics.findByCurrency = function (currencyCode) {
-  return this.find({ 'currency.code': currencyCode.toUpperCase() });
-};
-
-// Add static method to find invoices with credit balance
-invoiceSchema.statics.findWithCreditBalance = function (clientId) {
-  return this.find({
-    'client.clientId': clientId,
-    'balanceBroughtForward': { $lt: 0 }
-  }).sort({ updatedAt: -1 });
-};
-
-// Add static method to calculate totals by currency
-invoiceSchema.statics.calculateTotalsByCurrency = function (query = {}) {
-  return this.aggregate([
-    { $match: query },
-    {
-      $group: {
-        _id: '$currency.code',
-        totalAmount: { $sum: '$totalAmount' },
-        totalPaid: { $sum: '$amountPaid' },
-        count: { $sum: 1 }
-      }
-    }
-  ]);
-};
-
-// New static method to find all unviewed invoices
-invoiceSchema.statics.findUnviewedInvoices = function (facilityId) {
-  return this.find({
-    'facility.id': facilityId,
-    'viewStatus.isOpened': false
-  });
-};
-
-// Pre-save middleware to ensure overpay and balanceBroughtForward stay in sync during transition
-invoiceSchema.pre('save', function (next) {
-  // If balanceBroughtForward is negative (credit), sync with overpay for backwards compatibility
-  if (this.balanceBroughtForward < 0) {
-    this.overpay = Math.abs(this.balanceBroughtForward);
-  } else {
-    this.overpay = 0; // No overpay if there's no negative balance
-  }
-  next();
-});
-
-const Invoice = mongoose.model('Invoice', invoiceSchema);
-
+const mongoose = require("mongoose");
+
+const invoiceSchema = new mongoose.Schema(
+  {
+    invoiceNumber: {
+      type: String,
+      required: true,
+      unique: true,
+    },
+    accountNumber: {
+      type: String,
+      required: true,
+      unique: true,
+    },
+    client: {
+      clientId: {
+        type: mongoose.Schema.Types.ObjectId,
+        ref: "Customer",
+        required: true,
+      },
+      firstName: {
+        type: String,
+        required: true
+      },
+      lastName: {
+        type: String,
+        required: true
+      }
+    },
+    facility: {
+      id: {
+        type: mongoose.Schema.Types.ObjectId,
+        ref: "Facility",
+        required: true,
+      },
+      name: {
+        type: String,
+        required: true
+      }
+    },
+    unit: {
+      id: { type: mongoose.Schema.Types.ObjectId, ref: "Unit", required: true },
+      name: { type: String, required: true },
+    },
+    currency: {
+      id: {
+        type: mongoose.Schema.Types.ObjectId,
+        ref: "Currency",
+        required: true
+      },
+      name: {
+        type: String,
+        required: true
+      },
+      code: {
+        type: String,
+        required: true,
+        uppercase: true,
+        minlength: 3,
+        maxlength: 3
+      }
+    },
+    items: [
+      {
+        description: { type: String, required: true },
+        quantity: { type: Number, required: true, min: 1 },
+        unitPrice: { type: Number, required: true, min: 0 },
+      },
+    ],
+    subTotal: {
+      type: Number,
+      required: true,
+    },
+    tax: {
+      type: Number,
+      required: true,
+    },
+    totalAmount: {
+      type: Number,
+      required: true,
+    },
+    amountPaid: {
+      type: Number,
+      default: 0,
+      min: 0,
+    },
+    // Mark as deprecated, keep for backward compatibility
+    overpay: {
+      type: Number,
+      default: 0,
+      min: 0,
+      deprecated: true
+    },
+    issueDate: {
+      type: Date,
+      required: true,
+    },
+    dueDate: {
+      type: Date,
+      required: true,
+    },
+    status: {
+      type: String,
+      required: true,
+      enum: ["Unpaid", "Pending", "Paid", "Overdue", "Cancelled", "Partially Paid", "Void"],
+    },
+    penalty: {
+      type: Number,
+      default: 0,
+    },
+    whatFor: {
+      invoiceType: { type: String, required: true },
+      description: { type: String },
+    },
+    invoiceNote: {
+      type: String,
+      default: null,
+    },
+    balanceBroughtForward: {
+      type: Number,
+      default: 0,
+    },
+    voidMetadata: {
+      voidedBy: {
+        userId: { type: mongoose.Schema.Types.ObjectId, ref: "User" },
+        name: { type: String },
+        role: { type: String }
+      },
+      voidedAt: { type: Date },
+      reason: { type: String }
+    },
+    cancelMetadata: {
+      cancelledBy: {
+        userId: { type: mongoose.Schema.Types.ObjectId, ref: "User" },
+        name: { type: String },
+        role: { type: String }
+      },
+      cancelledAt: { type: Date },
+      reason: { type: String }
+    },
+    lastReminderSent: Date,
+    reminderHistory: [
+      {
+        sentAt: Date,
+        reminderId: mongoose.Schema.Types.ObjectId,
+        notificationTypes: [String],
+      },
+    ],
+    reconciliationHistory: [{
+      date: { type: Date, required: true },
+      amount: { type: Number, required: true },
+      type: {
+        type: String,
+        enum: ['payment', 'cash', 'cheque', 'bank-transfer', 'mpesa-transfer', 'overpay-transfer', 'balance-deduction', 'overpay-received', 'credit-forward', 'debit-forward'],
+        required: true
+      },
+      sourceInvoice: String,
+      destinationInvoice: String,
+      paymentReference: String,
+      paymentCompletion: String,
+      remainingBalance: Number,
+      notes: String,
+      exchangeRate: {
+        type: Number,
+        default: 1  // For cross-currency reconciliations
+      },
+      originalCurrency: {
+        code: String,  // Original currency code if different from invoice currency
+        amount: Number // Amount in original currency
+      }
+    }],
+    paymentDetails: {
+      paymentStatus: { type: String, required: true },
+      paymentMethod: { type: String },
+      paymentDate: { type: Date },
+      transactionId: { type: String },
+    },
+    // New field to track when an invoice has been viewed
+    viewStatus: {
+      isOpened: { type: Boolean, default: false },
+      openedAt: { type: Date, default: null },
+      openedBy: {
+        facilityId: { type: mongoose.Schema.Types.ObjectId, ref: "Facility" },
+        userId: { type: mongoose.Schema.Types.ObjectId, ref: "User" },
+        userRole: { type: String }
+      },
+      viewHistory: [{
+        viewedAt: { type: Date, required: true },
+        facilityId: { type: mongoose.Schema.Types.ObjectId, ref: "Facility" },
+        userId: { type: mongoose.Schema.Types.ObjectId, ref: "User" }
+      }]
+    }
+  },
+  {
+    timestamps: true,
+  }
+);
+
+// Add indexes for frequently queried fields
+invoiceSchema.index({ accountNumber: 1 });
+invoiceSchema.index({ status: 1 });
+invoiceSchema.index({ 'client.clientId': 1, status: 1 });
+invoiceSchema.index({ 'reconciliationHistory.paymentReference': 1 });
+invoiceSchema.index({ issueDate: -1 });
+invoiceSchema.index({ 'currency.code': 1 }); // Add index for currency code
+invoiceSchema.index({ 'currency.id': 1 }); // Add index for currency ID
+invoiceSchema.index({ 'currency.code': 1, 'client.clientId': 1, status: 1 }); // Compound index for currency-based queries
+invoiceSchema.index({ 'client.clientId': 1, balanceBroughtForward: 1 }); // Add index for finding invoices with credit balances
+invoiceSchema.index({ 'viewStatus.isOpened': 1 }); // Add index for view status
+invoiceSchema.index({ 'viewStatus.openedBy.facilityId': 1 }); // Add index for facility view tracking
+
+// Add virtual field for calculating balance
+invoiceSchema.virtual('calculatedBalance').get(function () {
+  const baseBalance = this.totalAmount - (this.amountPaid || 0);
+
+  // Add positive balanceBroughtForward (customer owes money)
+  if (this.balanceBroughtForward > 0) {
+    return baseBalance + this.balanceBroughtForward;
+  }
+
+  // Subtract negative balanceBroughtForward (credit)
+  return baseBalance;
+});
+
+// Add virtual field for credit balance
+invoiceSchema.virtual('creditBalance').get(function () {
+  return this.balanceBroughtForward < 0 ? Math.abs(this.balanceBroughtForward) : 0;
+});
+
+// Getter for compatible overpay field
+invoiceSchema.virtual('effectiveOverpay').get(function () {
+  return this.balanceBroughtForward < 0 ? Math.abs(this.balanceBroughtForward) : 0;
+});
+
+// Add method for currency conversion if needed
+invoiceSchema.methods.convertAmount = function (amount, fromCurrency, toCurrency, exchangeRate) {
+  if (fromCurrency === toCurrency) {
+    return amount;
+  }
+  return amount * exchangeRate;
+};
+
+// Add static method to find invoices by currency
+invoiceSchema.statics.findByCurrency = function (currencyCode) {
+  return this.find({ 'currency.code': currencyCode.toUpperCase() });
+};
+
+// Add static method to find invoices with credit balance
+invoiceSchema.statics.findWithCreditBalance = function (clientId) {
+  return this.find({
+    'client.clientId': clientId,
+    'balanceBroughtForward': { $lt: 0 }
+  }).sort({ updatedAt: -1 });
+};
+
+// Add static method to calculate totals by currency
+invoiceSchema.statics.calculateTotalsByCurrency = function (query = {}) {
+  return this.aggregate([
+    { $match: query },
+    {
+      $group: {
+        _id: '$currency.code',
+        totalAmount: { $sum: '$totalAmount' },
+        totalPaid: { $sum: '$amountPaid' },
+        count: { $sum: 1 }
+      }
+    }
+  ]);
+};
+
+// New static method to find all unviewed invoices
+invoiceSchema.statics.findUnviewedInvoices = function (facilityId) {
+  return this.find({
+    'facility.id': facilityId,
+    'viewStatus.isOpened': false
+  });
+};
+
+// Pre-save middleware to ensure overpay and balanceBroughtForward stay in sync during transition
+invoiceSchema.pre('save', function (next) {
+  // If balanceBroughtForward is negative (credit), sync with overpay for backwards compatibility
+  if (this.balanceBroughtForward < 0) {
+    this.overpay = Math.abs(this.balanceBroughtForward);
+  } else {
+    this.overpay = 0; // No overpay if there's no negative balance
+  }
+  next();
+});
+
+const Invoice = mongoose.model('Invoice', invoiceSchema);
+
 module.exports = Invoice;