payservedb 9.2.8 → 9.3.0

package/src/models/power_invoice.js

@@ -1,367 +1,372 @@
-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,
-    },
-    // Unit reference — stored directly from PowerMeterAccount.unitId / PowerMeters.unitId
-    unitId: {
-      type: mongoose.Schema.Types.ObjectId,
-      ref: 'Unit',
-      default: null,
-    },
-    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
-    },
-
-    withholdingTaxPercentage: {
-      type: Number,
-      min: 0,
-      max: 100,
-      default: 0
-    },
-
-    // ── Biller Address ─────────────────────────────────────────────────────────
-    // Reference to the BillerAddress document configured in PowerMeterSettings.
-    // The sub-document below is a denormalised snapshot captured at invoice time.
-    billerAddressId: {
-      type: mongoose.Schema.Types.ObjectId,
-      ref: 'BillerAddress',
-      default: null,
-    },
-    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,
-      },
-    },
-
-    // ── Payment Methods ────────────────────────────────────────────────────────
-    // paymentMethods stores the IDs configured in PowerMeterSettings so the
-    // invoice knows which accounts/paybills are available for payment.
-    // paymentMethod (singular) records how this invoice was actually settled.
-    paymentMethods: {
-      mobilePayment: {
-        status: {
-          type: Boolean,
-          default: false,
-        },
-        // References the FacilityPaymentDetails (M-Pesa paybill) configured in settings
-        paymentId: {
-          type: mongoose.Schema.Types.ObjectId,
-          ref: 'FacilityPaymentDetails',
-          default: null,
-        },
-      },
-      bankPayment: {
-        status: {
-          type: Boolean,
-          default: false,
-        },
-        // References the BankDetails configured in settings
-        paymentId: {
-          type: mongoose.Schema.Types.ObjectId,
-          ref: 'BankDetails',
-          default: null,
-        },
-      },
-      cashPayment: {
-        status: {
-          type: Boolean,
-          default: false,
-        },
-      },
-    },
-    // How this invoice was actually paid (set during reconciliation)
-    paymentMethod: {
-      type: String,
-      enum: ['mobile', 'bank', 'cash', 'mixed'],
-      default: null,
-    },
-
-    // ── 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 ──────────────────────────────────────────────────────────
-    powerCharges: {
-      tariff: { type: String },
-      yearMonth: { type: String },
-      energyCharge: { type: Number, required: true, default: 0 },
-      fuelCostCharge: { type: Number, default: 0 },
-      forexAdjustment: { type: Number, default: 0 },
-      inflationAdjustment: { type: Number, default: 0 },
-      waterResourceManagementLevy: { type: Number, default: 0 },
-      energyRegulatoryLevy: { type: Number, default: 0 },
-      ruralElectrificationLevy: { type: Number, default: 0 },
-      powerFactorSurcharge: { type: Number, default: 0 },
-      valueAddedTax: { type: Number, default: 0 },
-      vatPercentage: { type: Number, default: 16 },
-      repPercentage: { type: Number, default: 5 },
-      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' },
-        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')) && this.powerCharges && !this.powerCharges.tariff) {
-    this.powerCharges.tariff = this.tariff;
-  }
-  if ((this.isNew || this.isModified('yearMonth')) && 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 {
-        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 });
-powerInvoiceSchema.index({ unitId: 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,
+    },
+    // Unit reference — stored directly from PowerMeterAccount.unitId / PowerMeters.unitId
+    unitId: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: 'Unit',
+      default: null,
+    },
+    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
+    },
+
+    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 ─────────────────────────────────────────────────────────
+    // Reference to the BillerAddress document configured in PowerMeterSettings.
+    // The sub-document below is a denormalised snapshot captured at invoice time.
+    billerAddressId: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: 'BillerAddress',
+      default: null,
+    },
+    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,
+      },
+    },
+
+    // ── Payment Methods ────────────────────────────────────────────────────────
+    // paymentMethods stores the IDs configured in PowerMeterSettings so the
+    // invoice knows which accounts/paybills are available for payment.
+    // paymentMethod (singular) records how this invoice was actually settled.
+    paymentMethods: {
+      mobilePayment: {
+        status: {
+          type: Boolean,
+          default: false,
+        },
+        // References the FacilityPaymentDetails (M-Pesa paybill) configured in settings
+        paymentId: {
+          type: mongoose.Schema.Types.ObjectId,
+          ref: 'FacilityPaymentDetails',
+          default: null,
+        },
+      },
+      bankPayment: {
+        status: {
+          type: Boolean,
+          default: false,
+        },
+        // References the BankDetails configured in settings
+        paymentId: {
+          type: mongoose.Schema.Types.ObjectId,
+          ref: 'BankDetails',
+          default: null,
+        },
+      },
+      cashPayment: {
+        status: {
+          type: Boolean,
+          default: false,
+        },
+      },
+    },
+    // How this invoice was actually paid (set during reconciliation)
+    paymentMethod: {
+      type: String,
+      enum: ['mobile', 'bank', 'cash', 'mixed'],
+      default: null,
+    },
+
+    // ── 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 ──────────────────────────────────────────────────────────
+    powerCharges: {
+      tariff: { type: String },
+      yearMonth: { type: String },
+      energyCharge: { type: Number, required: true, default: 0 },
+      fuelCostCharge: { type: Number, default: 0 },
+      forexAdjustment: { type: Number, default: 0 },
+      inflationAdjustment: { type: Number, default: 0 },
+      waterResourceManagementLevy: { type: Number, default: 0 },
+      energyRegulatoryLevy: { type: Number, default: 0 },
+      ruralElectrificationLevy: { type: Number, default: 0 },
+      powerFactorSurcharge: { type: Number, default: 0 },
+      valueAddedTax: { type: Number, default: 0 },
+      vatPercentage: { type: Number, default: 16 },
+      repPercentage: { type: Number, default: 5 },
+      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' },
+        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')) && this.powerCharges && !this.powerCharges.tariff) {
+    this.powerCharges.tariff = this.tariff;
+  }
+  if ((this.isNew || this.isModified('yearMonth')) && 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 {
+        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 });
+powerInvoiceSchema.index({ unitId: 1 });
+
+const PowerInvoice = mongoose.model('PowerInvoice', powerInvoiceSchema);
+
 module.exports = PowerInvoice;