payservedb 9.6.0 → 9.6.2

package/src/models/propertyManagerContract.js

@@ -1,612 +1,612 @@
-const mongoose = require('mongoose');
-const Schema = mongoose.Schema;
-
-const PropertyManagerContractSchema = new Schema(
-    {
-        contractName: {
-            type: String,
-            required: [true, 'Contract name is required']
-        },
-        propertyManager: {
-            type: mongoose.Schema.Types.ObjectId,
-            ref: 'User', // References global User collection
-            required: [true, 'Property manager is required']
-        },
-        units: [{
-            type: mongoose.Schema.Types.ObjectId,
-            ref: 'Unit',
-            required: [true, 'At least one unit is required']
-        }],
-        customerId: {
-            type: mongoose.Schema.Types.ObjectId,
-            ref: 'Customer', // Can reference global or facility-specific Customer
-            required: [true, 'Customer ID is required']
-        },
-        facilityId: {
-            type: mongoose.Schema.Types.ObjectId,
-            ref: 'Facility',
-            required: [true, 'Facility ID is required']
-        },
-        // Lease term details
-        startDate: {
-            type: Date,
-            required: function() {
-                return this.status === 'Active';
-            }
-        },
-        endDate: {
-            type: Date,
-            required: function() {
-                return this.status === 'Active';
-            }
-        },
-        // Payment details - aligned with LeaseAgreement
-        paymentDueDate: {
-            type: Number,
-            required: function() {
-                return this.status === 'Active';
-            },
-            min: [1, 'Payment due date must be between 1 and 31'],
-            max: [31, 'Payment due date must be between 1 and 31']
-        },
-        frequency: {
-            type: String,
-            enum: ['Monthly', 'Quarterly', 'Annually'],
-            default: 'Monthly',
-            required: function() {
-                return this.status === 'Active';
-            }
-        },
-        nextInvoiceDate: { 
-            type: Date 
-        },
-        lastInvoiceDate: { 
-            type: Date 
-        },
-        autoSend: { 
-            type: Boolean, 
-            default: false 
-        },
-        balanceBroughtForward: {
-            type: Number,
-            default: 0
-        },
-        // Management fee
-        managementFee: {
-            type: {
-                type: String,
-                enum: ['percentage', 'amount'],
-                required: [true, 'Management fee type is required']
-            },
-            value: {
-                type: Number,
-                required: [true, 'Management fee value is required'],
-                min: [0, 'Management fee value cannot be negative'],
-                validate: {
-                    validator: function(value) {
-                        // If type is percentage, value should not exceed 100
-                        if (this.managementFee.type === 'percentage') {
-                            return value <= 100;
-                        }
-                        return true;
-                    },
-                    message: 'Management fee percentage cannot exceed 100%'
-                }
-            }
-        },
-        // Per-contract lease commission override — when set (value present)
-        // it takes precedence over the facility-wide
-        // PropertyManagementSettings default. Lease commission is the
-        // one-time fee earned when the property manager places a new
-        // tenant (first paid rent invoice).
-        leaseFee: {
-            type: {
-                type: String,
-                enum: ['percentage', 'amount']
-            },
-            value: {
-                type: Number,
-                min: [0, 'Lease commission value cannot be negative'],
-                validate: {
-                    validator: function (value) {
-                        if (this.leaseFee && this.leaseFee.type === 'percentage') {
-                            return value <= 100;
-                        }
-                        return true;
-                    },
-                    message: 'Lease commission percentage cannot exceed 100%'
-                }
-            }
-        },
-        // Currency for fixed-amount managementFee/leaseFee values above.
-        // Only meaningful when the fee type is 'amount' (percentage fees are
-        // currency-agnostic).
-        currencyId: {
-            type: mongoose.Schema.Types.ObjectId,
-            ref: 'Currency'
-        },
-        // Per-unit fee overrides. Each unit in `units` may have a different
-        // management/lease fee here; a unit with no entry here falls back to
-        // the contract-level managementFee/leaseFee/currencyId above. This is
-        // what lets one contract cover multiple units at different rates.
-        unitFees: [{
-            unitId: {
-                type: mongoose.Schema.Types.ObjectId,
-                ref: 'Unit',
-                required: true
-            },
-            managementFee: {
-                type: {
-                    type: String,
-                    enum: ['percentage', 'amount']
-                },
-                value: {
-                    type: Number,
-                    min: [0, 'Management fee value cannot be negative']
-                }
-            },
-            leaseFee: {
-                type: {
-                    type: String,
-                    enum: ['percentage', 'amount']
-                },
-                value: {
-                    type: Number,
-                    min: [0, 'Lease commission value cannot be negative']
-                }
-            },
-            currencyId: {
-                type: mongoose.Schema.Types.ObjectId,
-                ref: 'Currency'
-            }
-        }],
-        // GL Account configurations - updated to match sample data structure
-        invoiceDoubleEntryAccount: {
-            type: mongoose.Schema.Types.ObjectId,
-            ref: 'GLAccountDoubleEntries'
-        },
-        paymentDoubleEntryAccount: {
-            type: mongoose.Schema.Types.ObjectId,
-            ref: 'GLAccountDoubleEntries'
-        },
-        glAccounts: {
-            invoice: {
-                debit: {
-                    type: mongoose.Schema.Types.ObjectId,
-                    ref: 'GLAccount'
-                },
-                credit: {
-                    type: mongoose.Schema.Types.ObjectId,
-                    ref: 'GLAccount'
-                }
-            },
-            payment: {
-                debit: {
-                    type: mongoose.Schema.Types.ObjectId,
-                    ref: 'GLAccount'
-                },
-                credit: {
-                    type: mongoose.Schema.Types.ObjectId,
-                    ref: 'GLAccount'
-                }
-            }
-        },
-        status: {
-            type: String,
-            enum: ['Active', 'Inactive', 'Completed', 'Suspended', 'Terminated'],
-            // Contracts default Active on creation - billing eligibility is
-            // driven by lease existence, not contract status. Status is now
-            // a purely manual lifecycle field the property manager controls.
-            default: 'Active',
-            required: [true, 'Status is required']
-        },
-        createdBy: {
-            type: mongoose.Schema.Types.ObjectId,
-            ref: 'User' // References global User collection
-        },
-        // Additional fields for contract lifecycle management
-        suspensionReason: {
-            type: String
-        },
-        terminationReason: {
-            type: String
-        },
-        terminationDate: {
-            type: Date
-        },
-        completionDate: {
-            type: Date
-        }
-    },
-    {
-        timestamps: true,
-        // Ensure virtual fields are included in JSON output
-        toJSON: { virtuals: true },
-        toObject: { virtuals: true }
-    }
-);
-
-// Enhanced pre-save validation
-PropertyManagerContractSchema.pre('save', function (next) {
-    // Validate date range
-    if (this.startDate && this.endDate && this.startDate >= this.endDate) {
-        next(new Error('End date must be after start date'));
-        return;
-    }
-    
-    // Validate units array
-    if (!this.units || this.units.length === 0) {
-        next(new Error('At least one unit must be specified'));
-        return;
-    }
-    
-    // Validate management fee
-    if (!this.managementFee || !this.managementFee.type || this.managementFee.value === undefined) {
-        next(new Error('Management fee type and value are required'));
-        return;
-    }
-    
-    // Validate management fee percentage
-    if (this.managementFee.type === 'percentage' && this.managementFee.value > 100) {
-        next(new Error('Management fee percentage cannot exceed 100%'));
-        return;
-    }
-    
-    // Validate management fee value is non-negative
-    if (this.managementFee.value < 0) {
-        next(new Error('Management fee value cannot be negative'));
-        return;
-    }
-    
-    // Validate payment due date range
-    if (this.paymentDueDate && (this.paymentDueDate < 1 || this.paymentDueDate > 31)) {
-        next(new Error('Payment due date must be between 1 and 31'));
-        return;
-    }
-    
-    // Note: startDate/endDate/paymentDueDate/frequency are no longer
-    // required for Active status - contracts are always Active regardless
-    // of whether a lease has populated those fields yet. They remain
-    // required only for billing (see invoice_service's eligibility checks,
-    // which additionally require an active lease before generating an
-    // invoice).
-
-    next();
-});
-
-// Method to sync with lease data
-PropertyManagerContractSchema.methods.syncWithLeaseData = async function(leaseData) {
-    if (!leaseData) return;
-    
-    // Update contract fields from lease data
-    this.startDate = leaseData.leaseTerms?.startDate || this.startDate;
-    this.endDate = leaseData.leaseTerms?.endDate || this.endDate;
-    this.paymentDueDate = leaseData.financialTerms?.paymentDueDate || this.paymentDueDate;
-    this.balanceBroughtForward = leaseData.financialTerms?.balanceBroughtForward || this.balanceBroughtForward;
-    this.frequency = leaseData.billingCycle?.frequency || this.frequency;
-    this.autoSend = leaseData.billingCycle?.autoSend !== undefined ? leaseData.billingCycle.autoSend : this.autoSend;
-    this.nextInvoiceDate = leaseData.billingCycle?.nextInvoiceDate || this.nextInvoiceDate;
-    this.lastInvoiceDate = leaseData.billingCycle?.lastInvoiceDate || this.lastInvoiceDate;
-    
-    // Automatically activate contract if all required fields are present
-    if (this.startDate && this.endDate && this.paymentDueDate && this.frequency && this.status === 'Inactive') {
-        this.status = 'Active';
-    }
-    
-    return this.save();
-};
-
-// Method to check if contract can be activated
-PropertyManagerContractSchema.methods.canBeActivated = function() {
-    return !!(this.startDate && this.endDate && this.paymentDueDate && this.frequency);
-};
-
-// Method to get missing required fields
-PropertyManagerContractSchema.methods.getMissingRequiredFields = function() {
-    const requiredFields = ['startDate', 'endDate', 'paymentDueDate', 'frequency'];
-    return requiredFields.filter(field => !this[field]);
-};
-
-// Virtual for contract completion status
-PropertyManagerContractSchema.virtual('isComplete').get(function() {
-    return this.canBeActivated();
-});
-
-// Virtual for contract duration in days
-PropertyManagerContractSchema.virtual('durationInDays').get(function() {
-    if (!this.startDate || !this.endDate) return null;
-    const diffTime = Math.abs(this.endDate - this.startDate);
-    return Math.ceil(diffTime / (1000 * 60 * 60 * 24));
-});
-
-// Virtual for contract remaining days
-PropertyManagerContractSchema.virtual('remainingDays').get(function() {
-    if (!this.endDate) return null;
-    const now = new Date();
-    if (now > this.endDate) return 0;
-    const diffTime = Math.abs(this.endDate - now);
-    return Math.ceil(diffTime / (1000 * 60 * 60 * 24));
-});
-
-// Virtual for management fee display
-PropertyManagerContractSchema.virtual('managementFeeDisplay').get(function() {
-    if (!this.managementFee) return null;
-    
-    if (this.managementFee.type === 'percentage') {
-        return `${this.managementFee.value}%`;
-    } else {
-        return `$${this.managementFee.value.toLocaleString()}`;
-    }
-});
-
-// Indexes for better query performance
-PropertyManagerContractSchema.index({ customerId: 1, status: 1 });
-PropertyManagerContractSchema.index({ facilityId: 1, status: 1 });
-PropertyManagerContractSchema.index({ propertyManager: 1, facilityId: 1 });
-PropertyManagerContractSchema.index({ units: 1, status: 1 });
-PropertyManagerContractSchema.index({ nextInvoiceDate: 1, status: 1 });
-PropertyManagerContractSchema.index({ endDate: 1, status: 1 }); // For contract expiration queries
-PropertyManagerContractSchema.index({ 'managementFee.type': 1, 'managementFee.value': 1 }); // For fee analysis
-PropertyManagerContractSchema.index({ createdAt: -1 }); // For recent contracts
-PropertyManagerContractSchema.index({ startDate: 1, endDate: 1 }); // For date range queries
-
-// Compound indexes for common query patterns
-PropertyManagerContractSchema.index({ 
-    facilityId: 1, 
-    propertyManager: 1, 
-    status: 1 
-});
-
-PropertyManagerContractSchema.index({ 
-    facilityId: 1, 
-    customerId: 1, 
-    status: 1 
-});
-
-// Text index for searching contract names
-PropertyManagerContractSchema.index({ 
-    contractName: 'text' 
-});
-
-// Static methods for common queries
-PropertyManagerContractSchema.statics.findActiveContractsByFacility = function(facilityId) {
-    return this.find({
-        facilityId: facilityId,
-        status: 'Active'
-    }).populate('propertyManager', 'fullName email')
-      .populate('units', 'name unitType')
-      .populate('customerId', 'firstName lastName email');
-};
-
-PropertyManagerContractSchema.statics.findContractsByPropertyManager = function(propertyManagerId, facilityId) {
-    return this.find({
-        propertyManager: propertyManagerId,
-        facilityId: facilityId
-    }).populate('units', 'name unitType')
-      .populate('customerId', 'firstName lastName email')
-      .sort({ createdAt: -1 });
-};
-
-PropertyManagerContractSchema.statics.findExpiringContracts = function(facilityId, daysAhead = 30) {
-    const futureDate = new Date();
-    futureDate.setDate(futureDate.getDate() + daysAhead);
-    
-    return this.find({
-        facilityId: facilityId,
-        status: 'Active',
-        endDate: {
-            $gte: new Date(),
-            $lte: futureDate
-        }
-    }).populate('propertyManager', 'fullName email')
-      .populate('units', 'name unitType')
-      .populate('customerId', 'firstName lastName email')
-      .sort({ endDate: 1 });
-};
-
-PropertyManagerContractSchema.statics.findContractsRequiringInvoicing = function(facilityId) {
-    const today = new Date();
-    today.setHours(0, 0, 0, 0);
-    
-    return this.find({
-        facilityId: facilityId,
-        status: 'Active',
-        nextInvoiceDate: {
-            $lte: today
-        }
-    }).populate('propertyManager', 'fullName email')
-      .populate('units', 'name unitType')
-      .populate('customerId', 'firstName lastName email');
-};
-
-PropertyManagerContractSchema.statics.findContractsByFeeType = function(facilityId, feeType) {
-    return this.find({
-        facilityId: facilityId,
-        'managementFee.type': feeType
-    }).populate('propertyManager', 'fullName email')
-      .populate('units', 'name unitType')
-      .populate('customerId', 'firstName lastName email')
-      .sort({ 'managementFee.value': -1 });
-};
-
-PropertyManagerContractSchema.statics.getContractStatistics = function(facilityId) {
-    return this.aggregate([
-        {
-            $match: { facilityId: mongoose.Types.ObjectId(facilityId) }
-        },
-        {
-            $group: {
-                _id: '$status',
-                count: { $sum: 1 },
-                totalFeeValue: { $sum: '$managementFee.value' },
-                avgFeeValue: { $avg: '$managementFee.value' }
-            }
-        }
-    ]);
-};
-
-// Instance methods for contract management
-PropertyManagerContractSchema.methods.calculateNextInvoiceDate = function() {
-    if (!this.lastInvoiceDate && !this.startDate) return null;
-    
-    const baseDate = this.lastInvoiceDate || this.startDate;
-    const nextDate = new Date(baseDate);
-    
-    switch (this.frequency) {
-        case 'Monthly':
-            nextDate.setMonth(nextDate.getMonth() + 1);
-            break;
-        case 'Quarterly':
-            nextDate.setMonth(nextDate.getMonth() + 3);
-            break;
-        case 'Annually':
-            nextDate.setFullYear(nextDate.getFullYear() + 1);
-            break;
-        default:
-            nextDate.setMonth(nextDate.getMonth() + 1); // Default to monthly
-    }
-    
-    // Set to the payment due date of the month
-    if (this.paymentDueDate) {
-        const lastDayOfMonth = new Date(nextDate.getFullYear(), nextDate.getMonth() + 1, 0).getDate();
-        const dueDate = Math.min(this.paymentDueDate, lastDayOfMonth);
-        nextDate.setDate(dueDate);
-    }
-    
-    return nextDate;
-};
-
-PropertyManagerContractSchema.methods.updateInvoiceDates = async function(invoiceDate = new Date()) {
-    this.lastInvoiceDate = invoiceDate;
-    this.nextInvoiceDate = this.calculateNextInvoiceDate();
-    return this.save();
-};
-
-PropertyManagerContractSchema.methods.activateContract = async function() {
-    if (!this.canBeActivated()) {
-        throw new Error(`Cannot activate contract: missing required fields - ${this.getMissingRequiredFields().join(', ')}`);
-    }
-    
-    this.status = 'Active';
-    
-    // Set next invoice date if not already set
-    if (!this.nextInvoiceDate) {
-        this.nextInvoiceDate = this.calculateNextInvoiceDate();
-    }
-    
-    return this.save();
-};
-
-PropertyManagerContractSchema.methods.suspendContract = async function(reason) {
-    this.status = 'Suspended';
-    this.suspensionReason = reason;
-    return this.save();
-};
-
-PropertyManagerContractSchema.methods.terminateContract = async function(reason, terminationDate = new Date()) {
-    this.status = 'Terminated';
-    this.terminationReason = reason;
-    this.terminationDate = terminationDate;
-    return this.save();
-};
-
-PropertyManagerContractSchema.methods.completeContract = async function() {
-    this.status = 'Completed';
-    this.completionDate = new Date();
-    return this.save();
-};
-
-// Method to calculate management fee for a given amount
-PropertyManagerContractSchema.methods.calculateManagementFee = function(baseAmount) {
-    if (!this.managementFee) return 0;
-    
-    if (this.managementFee.type === 'percentage') {
-        return (baseAmount * this.managementFee.value) / 100;
-    } else {
-        return this.managementFee.value;
-    }
-};
-
-// Method to get contract summary
-PropertyManagerContractSchema.methods.getContractSummary = function() {
-    return {
-        id: this._id,
-        contractName: this.contractName,
-        status: this.status,
-        duration: this.durationInDays,
-        remainingDays: this.remainingDays,
-        managementFee: this.managementFeeDisplay,
-        frequency: this.frequency,
-        nextInvoiceDate: this.nextInvoiceDate,
-        isComplete: this.isComplete
-    };
-};
-
-// Pre-findOneAndUpdate middleware to maintain data integrity
-PropertyManagerContractSchema.pre(['findOneAndUpdate', 'updateOne', 'updateMany'], function() {
-    const update = this.getUpdate();
-    
-    // If status is being changed to Active, ensure required fields are present
-    if (update.$set && update.$set.status === 'Active') {
-        const requiredFields = ['startDate', 'endDate', 'paymentDueDate', 'frequency'];
-        // Note: We can't validate here because we don't have access to the full document
-        // Validation should be done in the application logic before calling update
-    }
-    
-    // Update the updatedAt field
-    if (update.$set) {
-        update.$set.updatedAt = new Date();
-    } else {
-        this.set({ updatedAt: new Date() });
-    }
-});
-
-// Post-save middleware for logging and notifications
-PropertyManagerContractSchema.post('save', function(doc) {
-    // Log contract creation/updates
-    console.log(`Property Manager Contract ${doc.isNew ? 'created' : 'updated'}: ${doc.contractName} (${doc._id})`);
-    
-    // Here you could add webhook calls, email notifications, etc.
-    // Example: notify property manager of contract status changes
-    if (this.isModified('status')) {
-        console.log(`Contract status changed to: ${doc.status}`);
-        // Add notification logic here
-    }
-    
-    // Log invoice date updates
-    if (this.isModified('nextInvoiceDate') || this.isModified('lastInvoiceDate')) {
-        console.log(`Invoice dates updated for contract: ${doc.contractName}`);
-    }
-});
-
-// Error handling for validation errors
-PropertyManagerContractSchema.post('save', function(error, doc, next) {
-    if (error.name === 'ValidationError') {
-        const messages = Object.values(error.errors).map(err => err.message);
-        next(new Error(`Contract validation failed: ${messages.join(', ')}`));
-    } else {
-        next(error);
-    }
-});
-
-// JSON transformation to remove sensitive data when returning to client
-PropertyManagerContractSchema.methods.toJSON = function() {
-    const contract = this.toObject();
-    
-    // Add computed fields
-    contract.isComplete = this.isComplete;
-    contract.canBeActivated = this.canBeActivated();
-    contract.missingRequiredFields = this.getMissingRequiredFields();
-    contract.durationInDays = this.durationInDays;
-    contract.remainingDays = this.remainingDays;
-    contract.managementFeeDisplay = this.managementFeeDisplay;
-    contract.contractSummary = this.getContractSummary();
-    
-    return contract;
-};
-
-// Export the schema
-module.exports = {
-    schema: PropertyManagerContractSchema,
-    name: 'PropertyManagerContract'
+const mongoose = require('mongoose');
+const Schema = mongoose.Schema;
+
+const PropertyManagerContractSchema = new Schema(
+    {
+        contractName: {
+            type: String,
+            required: [true, 'Contract name is required']
+        },
+        propertyManager: {
+            type: mongoose.Schema.Types.ObjectId,
+            ref: 'User', // References global User collection
+            required: [true, 'Property manager is required']
+        },
+        units: [{
+            type: mongoose.Schema.Types.ObjectId,
+            ref: 'Unit',
+            required: [true, 'At least one unit is required']
+        }],
+        customerId: {
+            type: mongoose.Schema.Types.ObjectId,
+            ref: 'Customer', // Can reference global or facility-specific Customer
+            required: [true, 'Customer ID is required']
+        },
+        facilityId: {
+            type: mongoose.Schema.Types.ObjectId,
+            ref: 'Facility',
+            required: [true, 'Facility ID is required']
+        },
+        // Lease term details
+        startDate: {
+            type: Date,
+            required: function() {
+                return this.status === 'Active';
+            }
+        },
+        endDate: {
+            type: Date,
+            required: function() {
+                return this.status === 'Active';
+            }
+        },
+        // Payment details - aligned with LeaseAgreement
+        paymentDueDate: {
+            type: Number,
+            required: function() {
+                return this.status === 'Active';
+            },
+            min: [1, 'Payment due date must be between 1 and 31'],
+            max: [31, 'Payment due date must be between 1 and 31']
+        },
+        frequency: {
+            type: String,
+            enum: ['Monthly', 'Quarterly', 'Annually'],
+            default: 'Monthly',
+            required: function() {
+                return this.status === 'Active';
+            }
+        },
+        nextInvoiceDate: { 
+            type: Date 
+        },
+        lastInvoiceDate: { 
+            type: Date 
+        },
+        autoSend: { 
+            type: Boolean, 
+            default: false 
+        },
+        balanceBroughtForward: {
+            type: Number,
+            default: 0
+        },
+        // Management fee
+        managementFee: {
+            type: {
+                type: String,
+                enum: ['percentage', 'amount'],
+                required: [true, 'Management fee type is required']
+            },
+            value: {
+                type: Number,
+                required: [true, 'Management fee value is required'],
+                min: [0, 'Management fee value cannot be negative'],
+                validate: {
+                    validator: function(value) {
+                        // If type is percentage, value should not exceed 100
+                        if (this.managementFee.type === 'percentage') {
+                            return value <= 100;
+                        }
+                        return true;
+                    },
+                    message: 'Management fee percentage cannot exceed 100%'
+                }
+            }
+        },
+        // Per-contract lease commission override — when set (value present)
+        // it takes precedence over the facility-wide
+        // PropertyManagementSettings default. Lease commission is the
+        // one-time fee earned when the property manager places a new
+        // tenant (first paid rent invoice).
+        leaseFee: {
+            type: {
+                type: String,
+                enum: ['percentage', 'amount']
+            },
+            value: {
+                type: Number,
+                min: [0, 'Lease commission value cannot be negative'],
+                validate: {
+                    validator: function (value) {
+                        if (this.leaseFee && this.leaseFee.type === 'percentage') {
+                            return value <= 100;
+                        }
+                        return true;
+                    },
+                    message: 'Lease commission percentage cannot exceed 100%'
+                }
+            }
+        },
+        // Currency for fixed-amount managementFee/leaseFee values above.
+        // Only meaningful when the fee type is 'amount' (percentage fees are
+        // currency-agnostic).
+        currencyId: {
+            type: mongoose.Schema.Types.ObjectId,
+            ref: 'Currency'
+        },
+        // Per-unit fee overrides. Each unit in `units` may have a different
+        // management/lease fee here; a unit with no entry here falls back to
+        // the contract-level managementFee/leaseFee/currencyId above. This is
+        // what lets one contract cover multiple units at different rates.
+        unitFees: [{
+            unitId: {
+                type: mongoose.Schema.Types.ObjectId,
+                ref: 'Unit',
+                required: true
+            },
+            managementFee: {
+                type: {
+                    type: String,
+                    enum: ['percentage', 'amount']
+                },
+                value: {
+                    type: Number,
+                    min: [0, 'Management fee value cannot be negative']
+                }
+            },
+            leaseFee: {
+                type: {
+                    type: String,
+                    enum: ['percentage', 'amount']
+                },
+                value: {
+                    type: Number,
+                    min: [0, 'Lease commission value cannot be negative']
+                }
+            },
+            currencyId: {
+                type: mongoose.Schema.Types.ObjectId,
+                ref: 'Currency'
+            }
+        }],
+        // GL Account configurations - updated to match sample data structure
+        invoiceDoubleEntryAccount: {
+            type: mongoose.Schema.Types.ObjectId,
+            ref: 'GLAccountDoubleEntries'
+        },
+        paymentDoubleEntryAccount: {
+            type: mongoose.Schema.Types.ObjectId,
+            ref: 'GLAccountDoubleEntries'
+        },
+        glAccounts: {
+            invoice: {
+                debit: {
+                    type: mongoose.Schema.Types.ObjectId,
+                    ref: 'GLAccount'
+                },
+                credit: {
+                    type: mongoose.Schema.Types.ObjectId,
+                    ref: 'GLAccount'
+                }
+            },
+            payment: {
+                debit: {
+                    type: mongoose.Schema.Types.ObjectId,
+                    ref: 'GLAccount'
+                },
+                credit: {
+                    type: mongoose.Schema.Types.ObjectId,
+                    ref: 'GLAccount'
+                }
+            }
+        },
+        status: {
+            type: String,
+            enum: ['Active', 'Inactive', 'Completed', 'Suspended', 'Terminated'],
+            // Contracts default Active on creation - billing eligibility is
+            // driven by lease existence, not contract status. Status is now
+            // a purely manual lifecycle field the property manager controls.
+            default: 'Active',
+            required: [true, 'Status is required']
+        },
+        createdBy: {
+            type: mongoose.Schema.Types.ObjectId,
+            ref: 'User' // References global User collection
+        },
+        // Additional fields for contract lifecycle management
+        suspensionReason: {
+            type: String
+        },
+        terminationReason: {
+            type: String
+        },
+        terminationDate: {
+            type: Date
+        },
+        completionDate: {
+            type: Date
+        }
+    },
+    {
+        timestamps: true,
+        // Ensure virtual fields are included in JSON output
+        toJSON: { virtuals: true },
+        toObject: { virtuals: true }
+    }
+);
+
+// Enhanced pre-save validation
+PropertyManagerContractSchema.pre('save', function (next) {
+    // Validate date range
+    if (this.startDate && this.endDate && this.startDate >= this.endDate) {
+        next(new Error('End date must be after start date'));
+        return;
+    }
+    
+    // Validate units array
+    if (!this.units || this.units.length === 0) {
+        next(new Error('At least one unit must be specified'));
+        return;
+    }
+    
+    // Validate management fee
+    if (!this.managementFee || !this.managementFee.type || this.managementFee.value === undefined) {
+        next(new Error('Management fee type and value are required'));
+        return;
+    }
+    
+    // Validate management fee percentage
+    if (this.managementFee.type === 'percentage' && this.managementFee.value > 100) {
+        next(new Error('Management fee percentage cannot exceed 100%'));
+        return;
+    }
+    
+    // Validate management fee value is non-negative
+    if (this.managementFee.value < 0) {
+        next(new Error('Management fee value cannot be negative'));
+        return;
+    }
+    
+    // Validate payment due date range
+    if (this.paymentDueDate && (this.paymentDueDate < 1 || this.paymentDueDate > 31)) {
+        next(new Error('Payment due date must be between 1 and 31'));
+        return;
+    }
+    
+    // Note: startDate/endDate/paymentDueDate/frequency are no longer
+    // required for Active status - contracts are always Active regardless
+    // of whether a lease has populated those fields yet. They remain
+    // required only for billing (see invoice_service's eligibility checks,
+    // which additionally require an active lease before generating an
+    // invoice).
+
+    next();
+});
+
+// Method to sync with lease data
+PropertyManagerContractSchema.methods.syncWithLeaseData = async function(leaseData) {
+    if (!leaseData) return;
+    
+    // Update contract fields from lease data
+    this.startDate = leaseData.leaseTerms?.startDate || this.startDate;
+    this.endDate = leaseData.leaseTerms?.endDate || this.endDate;
+    this.paymentDueDate = leaseData.financialTerms?.paymentDueDate || this.paymentDueDate;
+    this.balanceBroughtForward = leaseData.financialTerms?.balanceBroughtForward || this.balanceBroughtForward;
+    this.frequency = leaseData.billingCycle?.frequency || this.frequency;
+    this.autoSend = leaseData.billingCycle?.autoSend !== undefined ? leaseData.billingCycle.autoSend : this.autoSend;
+    this.nextInvoiceDate = leaseData.billingCycle?.nextInvoiceDate || this.nextInvoiceDate;
+    this.lastInvoiceDate = leaseData.billingCycle?.lastInvoiceDate || this.lastInvoiceDate;
+    
+    // Automatically activate contract if all required fields are present
+    if (this.startDate && this.endDate && this.paymentDueDate && this.frequency && this.status === 'Inactive') {
+        this.status = 'Active';
+    }
+    
+    return this.save();
+};
+
+// Method to check if contract can be activated
+PropertyManagerContractSchema.methods.canBeActivated = function() {
+    return !!(this.startDate && this.endDate && this.paymentDueDate && this.frequency);
+};
+
+// Method to get missing required fields
+PropertyManagerContractSchema.methods.getMissingRequiredFields = function() {
+    const requiredFields = ['startDate', 'endDate', 'paymentDueDate', 'frequency'];
+    return requiredFields.filter(field => !this[field]);
+};
+
+// Virtual for contract completion status
+PropertyManagerContractSchema.virtual('isComplete').get(function() {
+    return this.canBeActivated();
+});
+
+// Virtual for contract duration in days
+PropertyManagerContractSchema.virtual('durationInDays').get(function() {
+    if (!this.startDate || !this.endDate) return null;
+    const diffTime = Math.abs(this.endDate - this.startDate);
+    return Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+});
+
+// Virtual for contract remaining days
+PropertyManagerContractSchema.virtual('remainingDays').get(function() {
+    if (!this.endDate) return null;
+    const now = new Date();
+    if (now > this.endDate) return 0;
+    const diffTime = Math.abs(this.endDate - now);
+    return Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+});
+
+// Virtual for management fee display
+PropertyManagerContractSchema.virtual('managementFeeDisplay').get(function() {
+    if (!this.managementFee) return null;
+    
+    if (this.managementFee.type === 'percentage') {
+        return `${this.managementFee.value}%`;
+    } else {
+        return `$${this.managementFee.value.toLocaleString()}`;
+    }
+});
+
+// Indexes for better query performance
+PropertyManagerContractSchema.index({ customerId: 1, status: 1 });
+PropertyManagerContractSchema.index({ facilityId: 1, status: 1 });
+PropertyManagerContractSchema.index({ propertyManager: 1, facilityId: 1 });
+PropertyManagerContractSchema.index({ units: 1, status: 1 });
+PropertyManagerContractSchema.index({ nextInvoiceDate: 1, status: 1 });
+PropertyManagerContractSchema.index({ endDate: 1, status: 1 }); // For contract expiration queries
+PropertyManagerContractSchema.index({ 'managementFee.type': 1, 'managementFee.value': 1 }); // For fee analysis
+PropertyManagerContractSchema.index({ createdAt: -1 }); // For recent contracts
+PropertyManagerContractSchema.index({ startDate: 1, endDate: 1 }); // For date range queries
+
+// Compound indexes for common query patterns
+PropertyManagerContractSchema.index({ 
+    facilityId: 1, 
+    propertyManager: 1, 
+    status: 1 
+});
+
+PropertyManagerContractSchema.index({ 
+    facilityId: 1, 
+    customerId: 1, 
+    status: 1 
+});
+
+// Text index for searching contract names
+PropertyManagerContractSchema.index({ 
+    contractName: 'text' 
+});
+
+// Static methods for common queries
+PropertyManagerContractSchema.statics.findActiveContractsByFacility = function(facilityId) {
+    return this.find({
+        facilityId: facilityId,
+        status: 'Active'
+    }).populate('propertyManager', 'fullName email')
+      .populate('units', 'name unitType')
+      .populate('customerId', 'firstName lastName email');
+};
+
+PropertyManagerContractSchema.statics.findContractsByPropertyManager = function(propertyManagerId, facilityId) {
+    return this.find({
+        propertyManager: propertyManagerId,
+        facilityId: facilityId
+    }).populate('units', 'name unitType')
+      .populate('customerId', 'firstName lastName email')
+      .sort({ createdAt: -1 });
+};
+
+PropertyManagerContractSchema.statics.findExpiringContracts = function(facilityId, daysAhead = 30) {
+    const futureDate = new Date();
+    futureDate.setDate(futureDate.getDate() + daysAhead);
+    
+    return this.find({
+        facilityId: facilityId,
+        status: 'Active',
+        endDate: {
+            $gte: new Date(),
+            $lte: futureDate
+        }
+    }).populate('propertyManager', 'fullName email')
+      .populate('units', 'name unitType')
+      .populate('customerId', 'firstName lastName email')
+      .sort({ endDate: 1 });
+};
+
+PropertyManagerContractSchema.statics.findContractsRequiringInvoicing = function(facilityId) {
+    const today = new Date();
+    today.setHours(0, 0, 0, 0);
+    
+    return this.find({
+        facilityId: facilityId,
+        status: 'Active',
+        nextInvoiceDate: {
+            $lte: today
+        }
+    }).populate('propertyManager', 'fullName email')
+      .populate('units', 'name unitType')
+      .populate('customerId', 'firstName lastName email');
+};
+
+PropertyManagerContractSchema.statics.findContractsByFeeType = function(facilityId, feeType) {
+    return this.find({
+        facilityId: facilityId,
+        'managementFee.type': feeType
+    }).populate('propertyManager', 'fullName email')
+      .populate('units', 'name unitType')
+      .populate('customerId', 'firstName lastName email')
+      .sort({ 'managementFee.value': -1 });
+};
+
+PropertyManagerContractSchema.statics.getContractStatistics = function(facilityId) {
+    return this.aggregate([
+        {
+            $match: { facilityId: mongoose.Types.ObjectId(facilityId) }
+        },
+        {
+            $group: {
+                _id: '$status',
+                count: { $sum: 1 },
+                totalFeeValue: { $sum: '$managementFee.value' },
+                avgFeeValue: { $avg: '$managementFee.value' }
+            }
+        }
+    ]);
+};
+
+// Instance methods for contract management
+PropertyManagerContractSchema.methods.calculateNextInvoiceDate = function() {
+    if (!this.lastInvoiceDate && !this.startDate) return null;
+    
+    const baseDate = this.lastInvoiceDate || this.startDate;
+    const nextDate = new Date(baseDate);
+    
+    switch (this.frequency) {
+        case 'Monthly':
+            nextDate.setMonth(nextDate.getMonth() + 1);
+            break;
+        case 'Quarterly':
+            nextDate.setMonth(nextDate.getMonth() + 3);
+            break;
+        case 'Annually':
+            nextDate.setFullYear(nextDate.getFullYear() + 1);
+            break;
+        default:
+            nextDate.setMonth(nextDate.getMonth() + 1); // Default to monthly
+    }
+    
+    // Set to the payment due date of the month
+    if (this.paymentDueDate) {
+        const lastDayOfMonth = new Date(nextDate.getFullYear(), nextDate.getMonth() + 1, 0).getDate();
+        const dueDate = Math.min(this.paymentDueDate, lastDayOfMonth);
+        nextDate.setDate(dueDate);
+    }
+    
+    return nextDate;
+};
+
+PropertyManagerContractSchema.methods.updateInvoiceDates = async function(invoiceDate = new Date()) {
+    this.lastInvoiceDate = invoiceDate;
+    this.nextInvoiceDate = this.calculateNextInvoiceDate();
+    return this.save();
+};
+
+PropertyManagerContractSchema.methods.activateContract = async function() {
+    if (!this.canBeActivated()) {
+        throw new Error(`Cannot activate contract: missing required fields - ${this.getMissingRequiredFields().join(', ')}`);
+    }
+    
+    this.status = 'Active';
+    
+    // Set next invoice date if not already set
+    if (!this.nextInvoiceDate) {
+        this.nextInvoiceDate = this.calculateNextInvoiceDate();
+    }
+    
+    return this.save();
+};
+
+PropertyManagerContractSchema.methods.suspendContract = async function(reason) {
+    this.status = 'Suspended';
+    this.suspensionReason = reason;
+    return this.save();
+};
+
+PropertyManagerContractSchema.methods.terminateContract = async function(reason, terminationDate = new Date()) {
+    this.status = 'Terminated';
+    this.terminationReason = reason;
+    this.terminationDate = terminationDate;
+    return this.save();
+};
+
+PropertyManagerContractSchema.methods.completeContract = async function() {
+    this.status = 'Completed';
+    this.completionDate = new Date();
+    return this.save();
+};
+
+// Method to calculate management fee for a given amount
+PropertyManagerContractSchema.methods.calculateManagementFee = function(baseAmount) {
+    if (!this.managementFee) return 0;
+    
+    if (this.managementFee.type === 'percentage') {
+        return (baseAmount * this.managementFee.value) / 100;
+    } else {
+        return this.managementFee.value;
+    }
+};
+
+// Method to get contract summary
+PropertyManagerContractSchema.methods.getContractSummary = function() {
+    return {
+        id: this._id,
+        contractName: this.contractName,
+        status: this.status,
+        duration: this.durationInDays,
+        remainingDays: this.remainingDays,
+        managementFee: this.managementFeeDisplay,
+        frequency: this.frequency,
+        nextInvoiceDate: this.nextInvoiceDate,
+        isComplete: this.isComplete
+    };
+};
+
+// Pre-findOneAndUpdate middleware to maintain data integrity
+PropertyManagerContractSchema.pre(['findOneAndUpdate', 'updateOne', 'updateMany'], function() {
+    const update = this.getUpdate();
+    
+    // If status is being changed to Active, ensure required fields are present
+    if (update.$set && update.$set.status === 'Active') {
+        const requiredFields = ['startDate', 'endDate', 'paymentDueDate', 'frequency'];
+        // Note: We can't validate here because we don't have access to the full document
+        // Validation should be done in the application logic before calling update
+    }
+    
+    // Update the updatedAt field
+    if (update.$set) {
+        update.$set.updatedAt = new Date();
+    } else {
+        this.set({ updatedAt: new Date() });
+    }
+});
+
+// Post-save middleware for logging and notifications
+PropertyManagerContractSchema.post('save', function(doc) {
+    // Log contract creation/updates
+    console.log(`Property Manager Contract ${doc.isNew ? 'created' : 'updated'}: ${doc.contractName} (${doc._id})`);
+    
+    // Here you could add webhook calls, email notifications, etc.
+    // Example: notify property manager of contract status changes
+    if (this.isModified('status')) {
+        console.log(`Contract status changed to: ${doc.status}`);
+        // Add notification logic here
+    }
+    
+    // Log invoice date updates
+    if (this.isModified('nextInvoiceDate') || this.isModified('lastInvoiceDate')) {
+        console.log(`Invoice dates updated for contract: ${doc.contractName}`);
+    }
+});
+
+// Error handling for validation errors
+PropertyManagerContractSchema.post('save', function(error, doc, next) {
+    if (error.name === 'ValidationError') {
+        const messages = Object.values(error.errors).map(err => err.message);
+        next(new Error(`Contract validation failed: ${messages.join(', ')}`));
+    } else {
+        next(error);
+    }
+});
+
+// JSON transformation to remove sensitive data when returning to client
+PropertyManagerContractSchema.methods.toJSON = function() {
+    const contract = this.toObject();
+    
+    // Add computed fields
+    contract.isComplete = this.isComplete;
+    contract.canBeActivated = this.canBeActivated();
+    contract.missingRequiredFields = this.getMissingRequiredFields();
+    contract.durationInDays = this.durationInDays;
+    contract.remainingDays = this.remainingDays;
+    contract.managementFeeDisplay = this.managementFeeDisplay;
+    contract.contractSummary = this.getContractSummary();
+    
+    return contract;
+};
+
+// Export the schema
+module.exports = {
+    schema: PropertyManagerContractSchema,
+    name: 'PropertyManagerContract'
 };