payservedb 9.2.3 → 9.2.4

package/src/models/water_invoice.js

@@ -1,363 +1,397 @@
-const mongoose = require('mongoose');
-
-const waterInvoiceSchema = new mongoose.Schema(
-  {
-    // Basic identifiers
-    invoiceNumber: {
-      type: String,
-      required: true,
-      unique: true
-    },
-    accountNumber: {
-      type: String,
-      required: true
-    },
-    unitName: {
-      type: String,
-      required: true,
-    },
-    yearMonth: {
-      type: String,
-      required: true,
-    },
-    facilityId: {
-      type: mongoose.Schema.Types.ObjectId,
-      required: true
-    },
-    customerId: {
-      type: mongoose.Schema.Types.ObjectId,
-      required: true
-    },
-    billingType: {
-      type: String,
-      enum: ['postpaid'],
-    },
-    balanceBroughtForward: {
-      type: Number,
-      default: 0
-    },
-
-    paymentMethods: {
-      mobilePayment: {
-        status: {
-          type: Boolean,
-          default: false
-        },
-        paymentId: {
-          type: mongoose.Schema.Types.ObjectId,
-          ref: 'FacilityPaymentDetails'
-        }
-      },
-      bankPayment: {
-        status: {
-          type: Boolean,
-          default: false
-        },
-        paymentId: {
-          type: mongoose.Schema.Types.ObjectId,
-          ref: 'BankDetails'
-        }
-      },
-      cashPayment: {
-        status: {
-          type: Boolean,
-          default: false
-        }
-      }
-    },
-    paymentMethod: {
-      type: String,
-      enum: ['mobile', 'bank', 'cash', 'mixed'],
-      default: null
-    },
-    withholdingTaxes: [
-      {
-        name: { type: String, required: true },       // e.g. "withholding"
-        percentage: { type: Number, required: true }, // e.g. 5
-        amount: { type: Number, required: true },     // e.g. 50 (subTotal * percentage / 100)
-      },
-    ],
-    totalWithholdingTax: {
-      type: Number,
-      default: 0,
-    },
-
-    // Biller Address Information
-    billerAddress: {
-      name: {
-        type: String,
-        required: [true, "Biller name is required"],
-        trim: true,
-        minlength: [1, "Biller name must be at least 1 character long"],
-      },
-      email: {
-        type: String,
-        required: [true, "Biller email is required"],
-        trim: true,
-        lowercase: true,
-        validate: {
-          validator: function (v) {
-            return /^\w+([\.-]?\w+)@\w+([\.-]?\w+)(\.\w{2,3})+$/.test(v);
-          },
-          message: "Please enter a valid email address"
-        }
-      },
-      phone: {
-        type: String,
-        required: [true, "Biller phone is required"],
-        trim: true,
-      },
-      address: {
-        type: String,
-        required: [true, "Biller address is required"],
-        trim: true,
-      },
-      city: {
-        type: String,
-        required: [true, "Biller city is required"],
-        trim: true,
-      }
-    },
-
-    // Dates
-    dateIssued: {
-      type: Date,
-      default: Date.now
-    },
-    dueDate: {
-      type: Date,
-      required: true
-    },
-
-    // Meter & Consumption Details
-    meterNumber: {
-      type: String,
-      required: true
-    },
-    meterReadings: {
-      previousReading: {
-        type: Number,
-        required: true
-      },
-      currentReading: {
-        type: Number,
-        required: true
-      },
-      usage: {
-        type: Number,
-        required: true,
-      }
-    },
-    consumptionPeriod: {
-      startDate: {
-        type: Date,
-        required: true
-      },
-      endDate: {
-        type: Date,
-        required: true
-      }
-    },
-
-    // Charges
-    charges: {
-      waterCharge: {
-        type: Number,
-        required: true
-      },
-      sewerCharge: {
-        type: Number,
-        default: 0
-      },
-      tax: {
-        type: Number,
-        default: 0
-      },
-      fixedCharge: {
-        type: Number,
-        default: 0
-      },
-      totalMonthlyBill: {
-        type: Number,
-        required: true
-      }
-    },
-    amountPaid: {
-      type: Number,
-      default: 0
-    },
-    imageUrl: { type: String, trim: true },
-
-    // Invoice Note & Status
-    invoiceNote: {
-      type: String,
-      default: 'Payment is due within 10 days'
-    },
-    status: {
-      type: String,
-      required: true,
-      enum: ['Pending', 'Paid', 'Partially Paid', 'Cancelled', 'Overdue', 'Unpaid'],
-      default: 'Unpaid'
-    },
-
-    // Currency Info
-    currency: {
-      id: {
-        type: mongoose.Schema.Types.ObjectId
-      },
-      name: {
-        type: String,
-        default: 'Kenyan Shilling'
-      },
-      code: {
-        type: String,
-        default: 'KES'
-      },
-      symbol: {
-        type: String,
-        default: 'KSh'
-      }
-    },
-    notificationsSent: {
-      type: {
-        sms: {
-          type: Boolean,
-          default: false
-        },
-        email: {
-          type: Boolean,
-          default: false
-        },
-        sentAt: {
-          type: Date,
-          default: null
-        },
-        lastAttempt: {
-          type: Date,
-          default: null
-        },
-        attempts: {
-          type: Number,
-          default: 0
-        },
-        smsDetails: {
-          type: {
-            success: Boolean,
-            error: String,
-            sentAt: Date,
-            phoneNumber: String
-          },
-          default: null
-        },
-        emailDetails: {
-          type: {
-            success: Boolean,
-            error: String,
-            sentAt: Date,
-            emailAddress: String
-          },
-          default: null
-        }
-      },
-      default: {
-        sms: false,
-        email: false,
-        sentAt: null,
-        lastAttempt: null,
-        attempts: 0,
-        smsDetails: null,
-        emailDetails: null
-      }
-    },
-
-    // Payment & Reconciliation
-    reconciliationHistory: [
-      {
-        date: {
-          type: Date,
-          default: Date.now
-        },
-        amount: {
-          type: Number,
-          required: true
-        },
-        type: {
-          type: String,
-          default: 'Manual'
-        },
-        paymentReference: {
-          type: String
-        },
-        paymentCompletion: {
-          type: String,
-          default: 'Completed'
-        },
-        sourceInvoice: {
-          type: String
-        },
-        destinationInvoice: {
-          type: String
-        },
-        notes: {
-          type: String
-        },
-        remainingBalance: {
-          type: Number
-        }
-      }
-    ],
-  },
-  {
-    timestamps: true
-  }
-);
-
-// Pre-save middleware to update payment method status and primary payment method
-waterInvoiceSchema.pre('save', function (next) {
-  // Handle due date and status
-  if (this.isModified('dueDate') || this.isNew) {
-    const today = new Date();
-    if (this.dueDate < today && this.status === 'Pending') {
-      this.status = 'Overdue';
-    }
-  }
-
-  // Update payment method status based on reconciliation history
-  if (this.isModified('reconciliationHistory') || this.isNew) {
-    if (this.reconciliationHistory && this.reconciliationHistory.length > 0) {
-      const latestPayment = this.reconciliationHistory[this.reconciliationHistory.length - 1];
-      const paymentType = latestPayment.type?.toLowerCase();
-
-      // Initialize paymentMethods if not exists
-      if (!this.paymentMethods) {
-        this.paymentMethods = {
-          mobilePayment: { status: false },
-          bankPayment: { status: false },
-          cashPayment: { status: false }
-        };
-      }
-
-      // Update payment method status based on payment type
-      if (paymentType && (paymentType.includes('mobile') || paymentType.includes('mpesa') || paymentType.includes('m-pesa'))) {
-        this.paymentMethods.mobilePayment.status = true;
-        this.primaryPaymentMethod = 'mobile';
-      } else if (paymentType && paymentType.includes('bank')) {
-        this.paymentMethods.bankPayment.status = true;
-        this.primaryPaymentMethod = 'bank';
-      } else if (paymentType && paymentType.includes('cash')) {
-        this.paymentMethods.cashPayment.status = true;
-        this.primaryPaymentMethod = 'cash';
-      } else {
-        // Default to cash for manual or unspecified payments
-        this.paymentMethods.cashPayment.status = true;
-        this.primaryPaymentMethod = 'cash';
-      }
-    }
-  }
-
-  next();
-});
-
-const WaterInvoice = mongoose.model('WaterInvoice', waterInvoiceSchema);
-
+const mongoose = require('mongoose');
+
+const waterInvoiceSchema = new mongoose.Schema(
+  {
+    // Basic identifiers
+    invoiceNumber: {
+      type: String,
+      required: true,
+      unique: true
+    },
+    accountNumber: {
+      type: String,
+      required: true // static on the meter — always present, customer or not
+    },
+    unitId: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: 'Unit',
+      default: null
+    },
+    unitName: {
+      type: String,
+      required: true,
+    },
+    yearMonth: {
+      type: String,
+      required: true,
+    },
+    facilityId: {
+      type: mongoose.Schema.Types.ObjectId,
+      required: true
+    },
+
+    // Customer is now OPTIONAL — a meter can be billed with no active tenant
+    customerId: {
+      type: mongoose.Schema.Types.ObjectId,
+      required: false,
+      default: null
+    },
+    hasActiveCustomer: {
+      type: Boolean,
+      default: true
+    },
+
+    billingType: {
+      type: String,
+      enum: ['postpaid'],
+    },
+    balanceBroughtForward: {
+      type: Number,
+      default: 0
+    },
+
+    // Tracks WHY the balance was carried forward the way it was —
+    // critical for audit trail when tenants move in/out of a unit.
+    balanceSource: {
+      type: String,
+      enum: ['customer', 'unit', 'reset-new-tenant', 'none', 'error'],
+      default: 'none'
+    },
+
+    // If a tenant changed and there was an outstanding balance from the
+    // PREVIOUS tenant, it is NOT carried onto the new tenant's invoice.
+    // It's recorded here instead so it isn't silently lost, and can be
+    // picked up by a separate collections/reconciliation process.
+    unresolvedPriorBalance: {
+      type: Number,
+      default: 0
+    },
+    unresolvedPriorCustomerId: {
+      type: mongoose.Schema.Types.ObjectId,
+      default: null
+    },
+
+    paymentMethods: {
+      mobilePayment: {
+        status: {
+          type: Boolean,
+          default: false
+        },
+        paymentId: {
+          type: mongoose.Schema.Types.ObjectId,
+          ref: 'FacilityPaymentDetails'
+        }
+      },
+      bankPayment: {
+        status: {
+          type: Boolean,
+          default: false
+        },
+        paymentId: {
+          type: mongoose.Schema.Types.ObjectId,
+          ref: 'BankDetails'
+        }
+      },
+      cashPayment: {
+        status: {
+          type: Boolean,
+          default: false
+        }
+      }
+    },
+    paymentMethod: {
+      type: String,
+      enum: ['mobile', 'bank', 'cash', 'mixed'],
+      default: null
+    },
+    withholdingTaxes: [
+      {
+        name: { type: String, required: true },       // e.g. "withholding"
+        percentage: { type: Number, required: true }, // e.g. 5
+        amount: { type: Number, required: true },     // e.g. 50 (subTotal * percentage / 100)
+      },
+    ],
+    totalWithholdingTax: {
+      type: Number,
+      default: 0,
+    },
+
+    // Biller Address Information
+    billerAddress: {
+      name: {
+        type: String,
+        required: [true, "Biller name is required"],
+        trim: true,
+        minlength: [1, "Biller name must be at least 1 character long"],
+      },
+      email: {
+        type: String,
+        required: [true, "Biller email is required"],
+        trim: true,
+        lowercase: true,
+        validate: {
+          validator: function (v) {
+            return /^\w+([\.-]?\w+)@\w+([\.-]?\w+)(\.\w{2,3})+$/.test(v);
+          },
+          message: "Please enter a valid email address"
+        }
+      },
+      phone: {
+        type: String,
+        required: [true, "Biller phone is required"],
+        trim: true,
+      },
+      address: {
+        type: String,
+        required: [true, "Biller address is required"],
+        trim: true,
+      },
+      city: {
+        type: String,
+        required: [true, "Biller city is required"],
+        trim: true,
+      }
+    },
+
+    // Dates
+    dateIssued: {
+      type: Date,
+      default: Date.now
+    },
+    dueDate: {
+      type: Date,
+      required: true
+    },
+
+    // Meter & Consumption Details
+    meterNumber: {
+      type: String,
+      required: true
+    },
+    meterReadings: {
+      previousReading: {
+        type: Number,
+        required: true
+      },
+      currentReading: {
+        type: Number,
+        required: true
+      },
+      usage: {
+        type: Number,
+        required: true,
+      }
+    },
+    consumptionPeriod: {
+      startDate: {
+        type: Date,
+        required: true
+      },
+      endDate: {
+        type: Date,
+        required: true
+      }
+    },
+
+    // Charges
+    charges: {
+      waterCharge: {
+        type: Number,
+        required: true
+      },
+      sewerCharge: {
+        type: Number,
+        default: 0
+      },
+      tax: {
+        type: Number,
+        default: 0
+      },
+      fixedCharge: {
+        type: Number,
+        default: 0
+      },
+      totalMonthlyBill: {
+        type: Number,
+        required: true
+      }
+    },
+    amountPaid: {
+      type: Number,
+      default: 0
+    },
+    imageUrl: { type: String, trim: true },
+
+    // Invoice Note & Status
+    invoiceNote: {
+      type: String,
+      default: 'Payment is due within 10 days'
+    },
+    status: {
+      type: String,
+      required: true,
+      enum: ['Pending', 'Paid', 'Partially Paid', 'Cancelled', 'Overdue', 'Unpaid'],
+      default: 'Unpaid'
+    },
+
+    // Currency Info
+    currency: {
+      id: {
+        type: mongoose.Schema.Types.ObjectId
+      },
+      name: {
+        type: String,
+        default: 'Kenyan Shilling'
+      },
+      code: {
+        type: String,
+        default: 'KES'
+      },
+      symbol: {
+        type: String,
+        default: 'KSh'
+      }
+    },
+    notificationsSent: {
+      type: {
+        sms: {
+          type: Boolean,
+          default: false
+        },
+        email: {
+          type: Boolean,
+          default: false
+        },
+        sentAt: {
+          type: Date,
+          default: null
+        },
+        lastAttempt: {
+          type: Date,
+          default: null
+        },
+        attempts: {
+          type: Number,
+          default: 0
+        },
+        smsDetails: {
+          type: {
+            success: Boolean,
+            error: String,
+            sentAt: Date,
+            phoneNumber: String
+          },
+          default: null
+        },
+        emailDetails: {
+          type: {
+            success: Boolean,
+            error: String,
+            sentAt: Date,
+            emailAddress: String
+          },
+          default: null
+        }
+      },
+      default: {
+        sms: false,
+        email: false,
+        sentAt: null,
+        lastAttempt: null,
+        attempts: 0,
+        smsDetails: null,
+        emailDetails: null
+      }
+    },
+
+    // Payment & Reconciliation
+    reconciliationHistory: [
+      {
+        date: {
+          type: Date,
+          default: Date.now
+        },
+        amount: {
+          type: Number,
+          required: true
+        },
+        type: {
+          type: String,
+          default: 'Manual'
+        },
+        paymentReference: {
+          type: String
+        },
+        paymentCompletion: {
+          type: String,
+          default: 'Completed'
+        },
+        sourceInvoice: {
+          type: String
+        },
+        destinationInvoice: {
+          type: String
+        },
+        notes: {
+          type: String
+        },
+        remainingBalance: {
+          type: Number
+        }
+      }
+    ],
+  },
+  {
+    timestamps: true
+  }
+);
+
+// Pre-save middleware to update payment method status and primary payment method
+waterInvoiceSchema.pre('save', function (next) {
+  // Handle due date and status
+  if (this.isModified('dueDate') || this.isNew) {
+    const today = new Date();
+    if (this.dueDate < today && this.status === 'Pending') {
+      this.status = 'Overdue';
+    }
+  }
+
+  // Update payment method status based on reconciliation history
+  if (this.isModified('reconciliationHistory') || this.isNew) {
+    if (this.reconciliationHistory && this.reconciliationHistory.length > 0) {
+      const latestPayment = this.reconciliationHistory[this.reconciliationHistory.length - 1];
+      const paymentType = latestPayment.type?.toLowerCase();
+
+      // Initialize paymentMethods if not exists
+      if (!this.paymentMethods) {
+        this.paymentMethods = {
+          mobilePayment: { status: false },
+          bankPayment: { status: false },
+          cashPayment: { status: false }
+        };
+      }
+
+      // Update payment method status based on payment type
+      if (paymentType && (paymentType.includes('mobile') || paymentType.includes('mpesa') || paymentType.includes('m-pesa'))) {
+        this.paymentMethods.mobilePayment.status = true;
+        this.primaryPaymentMethod = 'mobile';
+      } else if (paymentType && paymentType.includes('bank')) {
+        this.paymentMethods.bankPayment.status = true;
+        this.primaryPaymentMethod = 'bank';
+      } else if (paymentType && paymentType.includes('cash')) {
+        this.paymentMethods.cashPayment.status = true;
+        this.primaryPaymentMethod = 'cash';
+      } else {
+        // Default to cash for manual or unspecified payments
+        this.paymentMethods.cashPayment.status = true;
+        this.primaryPaymentMethod = 'cash';
+      }
+    }
+  }
+
+  next();
+});
+
+const WaterInvoice = mongoose.model('WaterInvoice', waterInvoiceSchema);
+
 module.exports = WaterInvoice;