agmission/Development/server/docs/archived/PARTNER_MODEL_SCHEMA_UPDATES.md

Partner Model Schema Updates

Summary of Changes

Updated the partner and customer models to properly establish partner relationships in the system.

Changes Made

1. Partner System User Schema (model/partner.js)

Added explicit partner field:

// Before: partnerId was inherited from base User schema (confusing)
// Links to AgMission entities - partnerId now comes from base User schema

// After: explicit partner reference
partner: { type: Schema.Types.ObjectId, ref: 'User', required: true }, // Reference to Partner organization

Benefits:

• Clear and explicit partner relationship
• Required field ensures data integrity
• Direct reference to Partner organization
• Better query performance and clarity

2. Customer Schema (model/customer.js)

Added partner field:

// Added to customer schema
partner: { type: Schema.Types.ObjectId, ref: 'User', required: false }, // Reference to Partner organization

Benefits:

• Customers can be associated with partner organizations
• Optional field allows for both partner and non-partner customers
• Direct relationship tracking
• Enables partner-specific customer operations

Schema Relationships

Current Structure:

Partner (User discriminator)
  ↑
  │ (partner reference)
  │
PartnerSystemUser (User discriminator)
  ↑
  │ (customerId reference)
  │
Customer (User discriminator)
  ↑
  │ (partner reference - new)
  │
Partner (closes the relationship circle)

Relationship Benefits:

1. Clear Partner Hierarchy: Partner → PartnerSystemUser → Customer
2. Bidirectional References: Customers can reference their partner organization
3. Data Integrity: Required partner in PartnerSystemUser ensures valid relationships
4. Query Flexibility: Can query from either direction (partner→customers or customer→partner)

Use Cases Enabled

1. Partner Customer Management

// Find all customers for a specific partner
const partnerCustomers = await Customer.find({ partner: partnerObjectId });

// Find partner for a specific customer
const customerPartner = await Customer.findById(customerId).populate('partner');

2. Partner System User Queries

// Find all system users for a partner
const partnerSystemUsers = await PartnerSystemUser.find({ partner: partnerObjectId });

// Find system user for a specific customer-partner combination
const systemUser = await PartnerSystemUser.findOne({ 
  partner: partnerObjectId, 
  customer: customerObjectId 
});

3. Partner Integration Workflows

// When processing partner data, easily identify relationships
const assignment = await JobAssign.findById(assignmentId)
  .populate({
    path: 'user',
    populate: { path: 'partner' }
  });
  
// Get partner system credentials for customer
const partnerUser = await PartnerSystemUser.findOne({
  partner: assignment.user.partner,
  customerId: assignment.user._id
});

Migration Considerations

Data Migration Scripts Needed:

1. Existing PartnerSystemUser Records: Update to include explicit partner field
2. Customer Records: Optionally set partner for existing partner customers
3. Index Updates: Add indexes on new partner fields for performance

Index Recommendations:

// Customer model
{ partner: 1 }
{ partner: 1, active: 1 }

// PartnerSystemUser model  
{ partner: 1, customer: 1 } // Composite unique index
{ partner: 1, active: 1 }

Validation Rules

PartnerSystemUser:

• partner is required (ensures valid partner relationship)
• customer is required (represents the applicator user)

Customer:

• partner is optional (supports both partner and direct customers)
• When set, must reference a valid Partner user type

Future Enhancements

1. Cascade Operations: Implement cascade delete/update operations
2. Partner-Specific Validation: Add partner-specific business rules
3. Multi-Partner Support: Allow customers to work with multiple partners
4. Partner Hierarchy: Support for partner sub-organizations
5. Permission Management: Role-based access within partner relationships

This update provides a solid foundation for partner relationship management while maintaining backward compatibility and enabling future partner integration features.