payservedb 8.9.8 → 9.0.0

package/src/models/power_invoice.js

@@ -1,471 +1,471 @@
-const mongoose = require('mongoose');
-
-const powerInvoiceSchema = 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,
-      // Format: "YYYY-MM" e.g. "2025-03"
-    },
-    facilityId: {
-      type: mongoose.Schema.Types.ObjectId,
-      required: true,
-    },
-    customerId: {
-      type: mongoose.Schema.Types.ObjectId,
-      required: true,
-    },
-    billingType: {
-      type: String,
-      enum: ['postpaid'],
-      default: 'postpaid',
-    },
-    balanceBroughtForward: {
-      type: Number,
-      default: 0,
-      // Positive = arrears carried forward; Negative = credit from overpayment
-    },
-
-    // ── Payment Methods ────────────────────────────────────────────────────────
-    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,
-    },
-
-    // ── Biller Address ─────────────────────────────────────────────────────────
-    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,
-        trim: true,
-        lowercase: true,
-        validate: {
-          validator: function (v) {
-            return !v || /^\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,
-        trim: true,
-      },
-    },
-
-    // ── Dates ──────────────────────────────────────────────────────────────────
-    dateIssued: {
-      type: Date,
-      default: Date.now,
-    },
-    dueDate: {
-      type: Date,
-      required: true,
-    },
-
-    // ── Customer Info (denormalised snapshot) ──────────────────────────────────
-    CustomerInfo: {
-      fullName: {
-        type: String,
-        required: true,
-        trim: true,
-      },
-    },
-
-    // ── Meter & Consumption ────────────────────────────────────────────────────
-    meterNumber: {
-      type: String,
-      required: true,
-    },
-    tariff: {
-      type: String,
-      required: true,
-      // e.g. "Domestic Lifeline", "Domestic Ordinary 1", "Domestic Ordinary 2",
-      //      "Commercial Low Voltage", "Industrial Low Voltage"
-    },
-    meterReadings: {
-      previousReading: {
-        type: Number,
-        required: true,
-      },
-      currentReading: {
-        type: Number,
-        required: true,
-      },
-      usage: {
-        type: Number,
-        required: true,
-        // kWh consumed = currentReading - previousReading
-      },
-    },
-    consumptionPeriod: {
-      startDate: {
-        type: Date,
-        required: true,
-      },
-      endDate: {
-        type: Date,
-        required: true,
-      },
-    },
-
-    // ── Power Charges ──────────────────────────────────────────────────────────
-    // All monetary values are in the invoice currency (default KES).
-    powerCharges: {
-      tariff: {
-        type: String,
-        // Mirror of the top-level tariff field; stored here for invoice snapshot
-      },
-      yearMonth: {
-        type: String,
-        // Mirror of the top-level yearMonth; stored for historical rate lookups
-      },
-
-      // Core energy charge based on units consumed and applicable tariff block
-      energyCharge: {
-        type: Number,
-        required: true,
-        default: 0,
-      },
-
-      // Fuel Cost Charge (FCC) – passed through from EPRA-approved fuel levy
-      fuelCostCharge: {
-        type: Number,
-        default: 0,
-      },
-
-      // Foreign Exchange Fluctuation Adjustment
-      forexAdjustment: {
-        type: Number,
-        default: 0,
-      },
-
-      // Inflation Adjustment Charge
-      inflationAdjustment: {
-        type: Number,
-        default: 0,
-      },
-
-      // Water Resource Management Levy (WRML)
-      waterResourceManagementLevy: {
-        type: Number,
-        default: 0,
-      },
-
-      // Energy Regulatory Levy (ERL)
-      energyRegulatoryLevy: {
-        type: Number,
-        default: 0,
-      },
-
-      // Rural Electrification & Renewable Energy Levy (REL)
-      ruralElectrificationLevy: {
-        type: Number,
-        default: 0,
-      },
-
-      // Power Factor Surcharge (applied to commercial/industrial customers only)
-      powerFactorSurcharge: {
-        type: Number,
-        default: 0,
-      },
-
-      // Value Added Tax amount
-      valueAddedTax: {
-        type: Number,
-        default: 0,
-      },
-
-      // VAT rate applied (%) – captured at time of billing; typically 16
-      vatPercentage: {
-        type: Number,
-        default: 16,
-      },
-
-      // Rural Electrification Programme levy percentage (%) – typically 5
-      repPercentage: {
-        type: Number,
-        default: 5,
-      },
-
-      // Grand total = sum of all charges above
-      totalCharge: {
-        type: Number,
-        required: true,
-      },
-    },
-
-    // ── Payment & Reconciliation ───────────────────────────────────────────────
-    amountPaid: {
-      type: Number,
-      default: 0,
-    },
-
-    // ── 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',
-    },
-
-    // ── View / Read Status 
-    viewStatus: {
-      isOpened: {
-        type: Boolean,
-        default: false,
-      },
-      openedAt: {
-        type: Date,
-        default: null,
-      },
-    },
-
-    // ── Currency 
-    currency: {
-      id: {
-        type: mongoose.Schema.Types.ObjectId,
-      },
-      name: {
-        type: String,
-        default: 'Kenyan Shilling',
-      },
-      code: {
-        type: String,
-        default: 'KES',
-      },
-      symbol: {
-        type: String,
-        default: 'KSh',
-      },
-    },
-
-    // ── Notification Tracking 
-    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,
-      },
-    },
-
-    //   Reconciliation History 
-    reconciliationHistory: [
-      {
-        date: {
-          type: Date,
-          default: Date.now,
-        },
-        amount: {
-          type: Number,
-          required: true,
-        },
-        type: {
-          type: String,
-          default: 'Manual',
-          // e.g. 'Manual', 'M-Pesa', 'Bank Transfer', 'Cash'
-        },
-        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
-
-powerInvoiceSchema.pre('save', function (next) {
-  // 1. Auto-mark overdue
-  if (this.isModified('dueDate') || this.isNew) {
-    const today = new Date();
-    if (this.dueDate < today && this.status === 'Pending') {
-      this.status = 'Overdue';
-    }
-  }
-
-  // 2. Sync powerCharges snapshot fields with top-level fields
-  if (this.isNew || this.isModified('tariff')) {
-    if (this.powerCharges && !this.powerCharges.tariff) {
-      this.powerCharges.tariff = this.tariff;
-    }
-  }
-  if (this.isNew || this.isModified('yearMonth')) {
-    if (this.powerCharges && !this.powerCharges.yearMonth) {
-      this.powerCharges.yearMonth = this.yearMonth;
-    }
-  }
-
-  // 3. Update payment method flags from 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();
-
-      if (!this.paymentMethods) {
-        this.paymentMethods = {
-          mobilePayment: { status: false },
-          bankPayment: { status: false },
-          cashPayment: { status: false },
-        };
-      }
-
-      if (
-        paymentType &&
-        (paymentType.includes('mobile') ||
-          paymentType.includes('mpesa') ||
-          paymentType.includes('m-pesa'))
-      ) {
-        this.paymentMethods.mobilePayment.status = true;
-        this.paymentMethod = 'mobile';
-      } else if (paymentType && paymentType.includes('bank')) {
-        this.paymentMethods.bankPayment.status = true;
-        this.paymentMethod = 'bank';
-      } else if (paymentType && paymentType.includes('cash')) {
-        this.paymentMethods.cashPayment.status = true;
-        this.paymentMethod = 'cash';
-      } else {
-        // Default: treat unspecified / manual payments as cash
-        this.paymentMethods.cashPayment.status = true;
-        this.paymentMethod = 'cash';
-      }
-    }
-  }
-
-  next();
-});
-
-// Indexes 
-powerInvoiceSchema.index({ facilityId: 1, yearMonth: -1 });
-powerInvoiceSchema.index({ customerId: 1 });
-powerInvoiceSchema.index({ status: 1 });
-powerInvoiceSchema.index({ meterNumber: 1 });
-powerInvoiceSchema.index({ accountNumber: 1 });
-
-const PowerInvoice = mongoose.model('PowerInvoice', powerInvoiceSchema);
-
+const mongoose = require('mongoose');
+
+const powerInvoiceSchema = 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,
+      // Format: "YYYY-MM" e.g. "2025-03"
+    },
+    facilityId: {
+      type: mongoose.Schema.Types.ObjectId,
+      required: true,
+    },
+    customerId: {
+      type: mongoose.Schema.Types.ObjectId,
+      required: true,
+    },
+    billingType: {
+      type: String,
+      enum: ['postpaid'],
+      default: 'postpaid',
+    },
+    balanceBroughtForward: {
+      type: Number,
+      default: 0,
+      // Positive = arrears carried forward; Negative = credit from overpayment
+    },
+
+    // ── Payment Methods ────────────────────────────────────────────────────────
+    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,
+    },
+
+    // ── Biller Address ─────────────────────────────────────────────────────────
+    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,
+        trim: true,
+        lowercase: true,
+        validate: {
+          validator: function (v) {
+            return !v || /^\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,
+        trim: true,
+      },
+    },
+
+    // ── Dates ──────────────────────────────────────────────────────────────────
+    dateIssued: {
+      type: Date,
+      default: Date.now,
+    },
+    dueDate: {
+      type: Date,
+      required: true,
+    },
+
+    // ── Customer Info (denormalised snapshot) ──────────────────────────────────
+    CustomerInfo: {
+      fullName: {
+        type: String,
+        required: true,
+        trim: true,
+      },
+    },
+
+    // ── Meter & Consumption ────────────────────────────────────────────────────
+    meterNumber: {
+      type: String,
+      required: true,
+    },
+    tariff: {
+      type: String,
+      required: true,
+      // e.g. "Domestic Lifeline", "Domestic Ordinary 1", "Domestic Ordinary 2",
+      //      "Commercial Low Voltage", "Industrial Low Voltage"
+    },
+    meterReadings: {
+      previousReading: {
+        type: Number,
+        required: true,
+      },
+      currentReading: {
+        type: Number,
+        required: true,
+      },
+      usage: {
+        type: Number,
+        required: true,
+        // kWh consumed = currentReading - previousReading
+      },
+    },
+    consumptionPeriod: {
+      startDate: {
+        type: Date,
+        required: true,
+      },
+      endDate: {
+        type: Date,
+        required: true,
+      },
+    },
+
+    // ── Power Charges ──────────────────────────────────────────────────────────
+    // All monetary values are in the invoice currency (default KES).
+    powerCharges: {
+      tariff: {
+        type: String,
+        // Mirror of the top-level tariff field; stored here for invoice snapshot
+      },
+      yearMonth: {
+        type: String,
+        // Mirror of the top-level yearMonth; stored for historical rate lookups
+      },
+
+      // Core energy charge based on units consumed and applicable tariff block
+      energyCharge: {
+        type: Number,
+        required: true,
+        default: 0,
+      },
+
+      // Fuel Cost Charge (FCC) – passed through from EPRA-approved fuel levy
+      fuelCostCharge: {
+        type: Number,
+        default: 0,
+      },
+
+      // Foreign Exchange Fluctuation Adjustment
+      forexAdjustment: {
+        type: Number,
+        default: 0,
+      },
+
+      // Inflation Adjustment Charge
+      inflationAdjustment: {
+        type: Number,
+        default: 0,
+      },
+
+      // Water Resource Management Levy (WRML)
+      waterResourceManagementLevy: {
+        type: Number,
+        default: 0,
+      },
+
+      // Energy Regulatory Levy (ERL)
+      energyRegulatoryLevy: {
+        type: Number,
+        default: 0,
+      },
+
+      // Rural Electrification & Renewable Energy Levy (REL)
+      ruralElectrificationLevy: {
+        type: Number,
+        default: 0,
+      },
+
+      // Power Factor Surcharge (applied to commercial/industrial customers only)
+      powerFactorSurcharge: {
+        type: Number,
+        default: 0,
+      },
+
+      // Value Added Tax amount
+      valueAddedTax: {
+        type: Number,
+        default: 0,
+      },
+
+      // VAT rate applied (%) – captured at time of billing; typically 16
+      vatPercentage: {
+        type: Number,
+        default: 16,
+      },
+
+      // Rural Electrification Programme levy percentage (%) – typically 5
+      repPercentage: {
+        type: Number,
+        default: 5,
+      },
+
+      // Grand total = sum of all charges above
+      totalCharge: {
+        type: Number,
+        required: true,
+      },
+    },
+
+    // ── Payment & Reconciliation ───────────────────────────────────────────────
+    amountPaid: {
+      type: Number,
+      default: 0,
+    },
+
+    // ── 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',
+    },
+
+    // ── View / Read Status 
+    viewStatus: {
+      isOpened: {
+        type: Boolean,
+        default: false,
+      },
+      openedAt: {
+        type: Date,
+        default: null,
+      },
+    },
+
+    // ── Currency 
+    currency: {
+      id: {
+        type: mongoose.Schema.Types.ObjectId,
+      },
+      name: {
+        type: String,
+        default: 'Kenyan Shilling',
+      },
+      code: {
+        type: String,
+        default: 'KES',
+      },
+      symbol: {
+        type: String,
+        default: 'KSh',
+      },
+    },
+
+    // ── Notification Tracking 
+    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,
+      },
+    },
+
+    //   Reconciliation History 
+    reconciliationHistory: [
+      {
+        date: {
+          type: Date,
+          default: Date.now,
+        },
+        amount: {
+          type: Number,
+          required: true,
+        },
+        type: {
+          type: String,
+          default: 'Manual',
+          // e.g. 'Manual', 'M-Pesa', 'Bank Transfer', 'Cash'
+        },
+        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
+
+powerInvoiceSchema.pre('save', function (next) {
+  // 1. Auto-mark overdue
+  if (this.isModified('dueDate') || this.isNew) {
+    const today = new Date();
+    if (this.dueDate < today && this.status === 'Pending') {
+      this.status = 'Overdue';
+    }
+  }
+
+  // 2. Sync powerCharges snapshot fields with top-level fields
+  if (this.isNew || this.isModified('tariff')) {
+    if (this.powerCharges && !this.powerCharges.tariff) {
+      this.powerCharges.tariff = this.tariff;
+    }
+  }
+  if (this.isNew || this.isModified('yearMonth')) {
+    if (this.powerCharges && !this.powerCharges.yearMonth) {
+      this.powerCharges.yearMonth = this.yearMonth;
+    }
+  }
+
+  // 3. Update payment method flags from 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();
+
+      if (!this.paymentMethods) {
+        this.paymentMethods = {
+          mobilePayment: { status: false },
+          bankPayment: { status: false },
+          cashPayment: { status: false },
+        };
+      }
+
+      if (
+        paymentType &&
+        (paymentType.includes('mobile') ||
+          paymentType.includes('mpesa') ||
+          paymentType.includes('m-pesa'))
+      ) {
+        this.paymentMethods.mobilePayment.status = true;
+        this.paymentMethod = 'mobile';
+      } else if (paymentType && paymentType.includes('bank')) {
+        this.paymentMethods.bankPayment.status = true;
+        this.paymentMethod = 'bank';
+      } else if (paymentType && paymentType.includes('cash')) {
+        this.paymentMethods.cashPayment.status = true;
+        this.paymentMethod = 'cash';
+      } else {
+        // Default: treat unspecified / manual payments as cash
+        this.paymentMethods.cashPayment.status = true;
+        this.paymentMethod = 'cash';
+      }
+    }
+  }
+
+  next();
+});
+
+// Indexes 
+powerInvoiceSchema.index({ facilityId: 1, yearMonth: -1 });
+powerInvoiceSchema.index({ customerId: 1 });
+powerInvoiceSchema.index({ status: 1 });
+powerInvoiceSchema.index({ meterNumber: 1 });
+powerInvoiceSchema.index({ accountNumber: 1 });
+
+const PowerInvoice = mongoose.model('PowerInvoice', powerInvoiceSchema);
+
 module.exports = PowerInvoice;