payservedb 8.3.5 → 8.3.6

package/src/models/invoice.js

@@ -1,388 +1,388 @@
-const mongoose = require("mongoose");
-
-const invoiceSchema = new mongoose.Schema(
-  {
-    invoiceNumber: {
-      type: String,
-      required: true,
-      unique: true,
-    },
-    accountNumber: {
-      type: String,
-      required: 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,
-    },
-    // NEW FIELD 1: Year-Month for easy filtering
-    yearMonth: {
-      type: String,
-      match: /^\d{4}-\d{2}$/, // Validates format like "2025-08"
-      index: true
-    },
-    // NEW FIELD 2: Simple notification tracking
-    notificationsSent: {
-      sms: {
-        type: Boolean,
-        default: false
-      },
-      email: {
-        type: Boolean,
-        default: false
-      },
-      attempts: {
-        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" }
-      }]
-    },
-    invoiceUrl: {
-      type: String,
-      default: null
-    },
-    // New fields for double entry accounts
-    invoiceDoubleEntryAccount: {
-      type: mongoose.Schema.Types.ObjectId,
-      ref: "GLAccountDoubleEntries",
-      required: false,
-    },
-    paymentDoubleEntryAccount: {
-      type: mongoose.Schema.Types.ObjectId,
-      ref: "GLAccountDoubleEntries",
-      required: false,
-    },
-    // GL account details for invoice entries
-    accountdebitedData: {
-      amount: { type: Number },
-      description: { type: String },
-      isActive: { type: Boolean, default: true }
-    },
-    accountcreditedData: {
-      amount: { type: Number },
-      description: { type: String },
-      isActive: { type: Boolean, default: true }
-    }
-  },
-  {
-    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 index for double entry accounts
-invoiceSchema.index({ invoiceDoubleEntryAccount: 1 });
-invoiceSchema.index({ paymentDoubleEntryAccount: 1 });
-// NEW INDEXES for new fields
-invoiceSchema.index({ yearMonth: 1 }); // For filtering by year-month
-invoiceSchema.index({ yearMonth: 1, status: 1 }); // Combined index for monthly reports
-invoiceSchema.index({ 'notificationsSent.sms': 1 }); // For finding SMS sent/not sent
-invoiceSchema.index({ 'notificationsSent.email': 1 }); // For finding email sent/not sent
-
-// 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 virtual populate for invoice double entry account
-invoiceSchema.virtual('invoiceDoubleEntry', {
-  ref: 'GLAccountDoubleEntries',
-  localField: 'invoiceDoubleEntryAccount',
-  foreignField: '_id',
-  justOne: true
-});
-
-// Add virtual populate for payment double entry account
-invoiceSchema.virtual('paymentDoubleEntry', {
-  ref: 'GLAccountDoubleEntries',
-  localField: 'paymentDoubleEntryAccount',
-  foreignField: '_id',
-  justOne: true
-});
-
-// 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
-  });
-};
-
-// NEW STATIC METHODS for new fields
-// Find invoices by year-month
-invoiceSchema.statics.findByYearMonth = function (yearMonth) {
-  return this.find({ yearMonth: yearMonth });
-};
-
-// Find invoices where notifications haven't been sent
-invoiceSchema.statics.findPendingNotifications = function (facilityId) {
-  return this.find({
-    'facility.id': facilityId,
-    status: { $in: ['Unpaid', 'Overdue'] },
-    $or: [
-      { 'notificationsSent.sms': false },
-      { 'notificationsSent.email': 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
-  }
-
-  // NEW: Auto-generate yearMonth from issueDate if not provided
-  if (!this.yearMonth && this.issueDate) {
-    const year = this.issueDate.getFullYear();
-    const month = String(this.issueDate.getMonth() + 1).padStart(2, '0');
-    this.yearMonth = `${year}-${month}`;
-  }
-
-  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
+    },
+    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,
+    },
+    // NEW FIELD 1: Year-Month for easy filtering
+    yearMonth: {
+      type: String,
+      match: /^\d{4}-\d{2}$/, // Validates format like "2025-08"
+      index: true
+    },
+    // NEW FIELD 2: Simple notification tracking
+    notificationsSent: {
+      sms: {
+        type: Boolean,
+        default: false
+      },
+      email: {
+        type: Boolean,
+        default: false
+      },
+      attempts: {
+        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" }
+      }]
+    },
+    invoiceUrl: {
+      type: String,
+      default: null
+    },
+    // New fields for double entry accounts
+    invoiceDoubleEntryAccount: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: "GLAccountDoubleEntries",
+      required: false,
+    },
+    paymentDoubleEntryAccount: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: "GLAccountDoubleEntries",
+      required: false,
+    },
+    // GL account details for invoice entries
+    accountdebitedData: {
+      amount: { type: Number },
+      description: { type: String },
+      isActive: { type: Boolean, default: true }
+    },
+    accountcreditedData: {
+      amount: { type: Number },
+      description: { type: String },
+      isActive: { type: Boolean, default: true }
+    }
+  },
+  {
+    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 index for double entry accounts
+invoiceSchema.index({ invoiceDoubleEntryAccount: 1 });
+invoiceSchema.index({ paymentDoubleEntryAccount: 1 });
+// NEW INDEXES for new fields
+invoiceSchema.index({ yearMonth: 1 }); // For filtering by year-month
+invoiceSchema.index({ yearMonth: 1, status: 1 }); // Combined index for monthly reports
+invoiceSchema.index({ 'notificationsSent.sms': 1 }); // For finding SMS sent/not sent
+invoiceSchema.index({ 'notificationsSent.email': 1 }); // For finding email sent/not sent
+
+// 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 virtual populate for invoice double entry account
+invoiceSchema.virtual('invoiceDoubleEntry', {
+  ref: 'GLAccountDoubleEntries',
+  localField: 'invoiceDoubleEntryAccount',
+  foreignField: '_id',
+  justOne: true
+});
+
+// Add virtual populate for payment double entry account
+invoiceSchema.virtual('paymentDoubleEntry', {
+  ref: 'GLAccountDoubleEntries',
+  localField: 'paymentDoubleEntryAccount',
+  foreignField: '_id',
+  justOne: true
+});
+
+// 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
+  });
+};
+
+// NEW STATIC METHODS for new fields
+// Find invoices by year-month
+invoiceSchema.statics.findByYearMonth = function (yearMonth) {
+  return this.find({ yearMonth: yearMonth });
+};
+
+// Find invoices where notifications haven't been sent
+invoiceSchema.statics.findPendingNotifications = function (facilityId) {
+  return this.find({
+    'facility.id': facilityId,
+    status: { $in: ['Unpaid', 'Overdue'] },
+    $or: [
+      { 'notificationsSent.sms': false },
+      { 'notificationsSent.email': 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
+  }
+
+  // NEW: Auto-generate yearMonth from issueDate if not provided
+  if (!this.yearMonth && this.issueDate) {
+    const year = this.issueDate.getFullYear();
+    const month = String(this.issueDate.getMonth() + 1).padStart(2, '0');
+    this.yearMonth = `${year}-${month}`;
+  }
+
+  next();
+});
+
+const Invoice = mongoose.model('Invoice', invoiceSchema);
+
 module.exports = Invoice;