import { Module } from '@nestjs/common';

import { TypeOrmModule } from '@nestjs/typeorm';
import { CacheModule } from '@nestjs/cache-manager';
import { VisaCommissionReceivedController } from './visa-commission-received.controller';
import { VisaCommissionReceivedService } from './visa-commission-received.service';
import { VisaServiceMasterEntity } from 'src/entities/VisaServiceMaster.entity';
import { CollegeEntity } from 'src/entities/College.entity';
import { MasteragentEntity } from 'src/entities/Masteragent.entity';
import { CountryEntity } from 'src/entities/Country.entity';
import { VcmInstituteCommissionEnquiryEntity } from 'src/entities/VcmInstituteCommissionEnquiry.entity';
import { VcmMasterAgentCommissionEnquiryEntity } from 'src/entities/VcmMasterAgentCommissionEnquiry.entity';
import { VmsVisaCasesEntity } from 'src/entities/VmsVisaCases.entity';
import { CourseMasterIntakeYearsEntity } from 'src/entities/CourseMasterIntakeYears.entity';
import { VcmCommissionContractInstancesEntity } from 'src/entities/VcmCommissionContractInstances.entity';
import { VcmCommissionReceivedEntity } from 'src/entities/VcmCommissionReceived.entity';
import { FileService } from 'src/services/file.service';
import { VcmCommissionReceivedDetailsEntity } from 'src/entities/VcmCommissionReceivedDetails.entity';

/**
 * VisaCommissionReceivedModule - Feature module for commission received tracking
 *
 * This module encapsulates all components related to tracking and managing
 * commission payments that have been actually received from institutes and master agents.
 * It represents the financial reconciliation and payment tracking phase of the
 * commission management lifecycle.
 *
 * Business Domain: Commission Payment Tracking & Reconciliation System
 * - Tracks actual commission payments received from partners
 * - Manages payment proofs and documentation
 * - Handles financial reconciliation between expected and received amounts
 * - Supports audit trails for payment verification
 * - Provides comprehensive reporting on commission receipts
 *
 * Module Characteristics:
 * - 10 entity integrations covering commission receipt tracking
 * - File service integration for payment proof documentation
 * - Caching for performance optimization
 * - Dual workflow support (institute vs master agent payments)
 * - Comprehensive filtering and reporting capabilities
 *
 * Architecture: Service-oriented with focus on financial tracking
 * - Primary entity: Commission received records
 * - Supporting entities: Visa cases, contracts, intake years
 * - File management for payment documentation
 * - Comprehensive query capabilities for financial reporting
 */
@Module({
  /**
   * controllers - Array of controllers that handle HTTP requests
   *
   * VisaCommissionReceivedController: Provides comprehensive commission received management
   * - 15+ endpoints for tracking received commission payments
   * - File attachment management for payment proofs and receipts
   * - Comprehensive filtering for payment tracking and reconciliation
   * - Reference data endpoints for filter dropdowns
   * - Attachment management for payment documentation
   */
  controllers: [VisaCommissionReceivedController],

  /**
   * providers - Injectable services available within this module
   *
   * 1. VisaCommissionReceivedService: Core business logic for commission received tracking
   *    - Complex payment tracking and reconciliation
   *    - Multi-entity joins for comprehensive payment reporting
   *    - Financial transaction validation and verification
   *    - Integration with 10 different entity repositories
   *    - Attachment management for payment documentation
   *
   * 2. FileService: Shared service for file operations
   *    - Handles file uploads, storage, and retrieval for payment proofs
   *    - Manates payment documentation (bank statements, receipts, screenshots)
   *    - Provides file validation and security checks
   *    - Essential for audit trail and compliance verification
   */
  providers: [VisaCommissionReceivedService, FileService],

  /**
   * imports - External modules and dependencies required by this module
   *
   * 1. CacheModule.register(): Configures the caching system
   *    - Provides in-memory caching for frequently accessed data
   *    - Important for reference data (countries, institutes, payment modes)
   *    - Reduces database load for filter dropdown population
   *    - Improves response times for payment tracking queries
   *
   * 2. TypeOrmModule.forFeature([...]): Registers 10 entities with TypeORM
   *    - Creates repositories for each entity that can be injected into services
   *    - Enables complex queries across multiple related entities
   *    - Supports transaction management for financial operations
   *    - Facilitates comprehensive payment tracking and reconciliation
   */
  imports: [
    CacheModule.register(), // Default cache configuration for performance optimization

    /**
     * TypeOrmModule.forFeature with 10 related entities:
     * This represents a comprehensive commission payment tracking system
     * organized into logical groups:
     */
    TypeOrmModule.forFeature([
      // ==================== CORE COMMISSION ENQUIRY ENTITIES (FOR REFERENCE) ====================
      /**
       * 1. VcmInstituteCommissionEnquiryEntity (Institute Commission Enquiry - Reference)
       *    - Original commission enquiries sent to institutes
       *    - Used for reconciliation between expected and received commissions
       *    - Reference for commission calculation and verification
       *    - Links received payments to original enquiries
       */
      VcmInstituteCommissionEnquiryEntity,

      /**
       * 2. VcmMasterAgentCommissionEnquiryEntity (Master Agent Commission Enquiry - Reference)
       *    - Original commission enquiries sent to master agents
       *    - Reference for agent commission reconciliation
       *    - Used to track which enquiries have been paid
       *    - Links agent payments to original enquiries
       */
      VcmMasterAgentCommissionEnquiryEntity,

      // ==================== REFERENCE AND SUPPORTING ENTITIES ====================
      /**
       * 3. VisaServiceMasterEntity (Visa Service Reference)
       *    - Visa service types and products
       *    - Used for categorizing commission payments by visa type
       *    - Examples: Student Visa, Work Visa, Tourist Visa
       *    - Service-specific payment tracking and reporting
       */
      VisaServiceMasterEntity,

      /**
       * 4. MasteragentEntity (Master Agent Reference)
       *    - Master/primary agents or partners
       *    - Agent details, payment terms, contact information
       *    - Used for agent-specific payment tracking
       *    - Agent hierarchy and relationship management
       */
      MasteragentEntity,

      /**
       * 5. CountryEntity (Country Reference)
       *    - Global country data
       *    - Used for client nationality-based payment tracking
       *    - Country-specific payment processing and reporting
       *    - Multi-currency payment support
       */
      CountryEntity,

      /**
       * 6. CollegeEntity (Educational Institute Reference)
       *    - Educational institutions/colleges/universities
       *    - Institute details, payment terms, contact information
       *    - Used for institute-specific payment tracking
       *    - Institute hierarchy and campus relationships
       */
      CollegeEntity,

      // ==================== VISA CASE AND CONTRACT ENTITIES ====================
      /**
       * 7. VmsVisaCasesEntity (Visa Case Management)
       *    - Individual visa application cases
       *    - Links commission payments to specific student cases
       *    - Contains case status, dates, and financial information
       *    - Used for per-case commission payment tracking
       */
      VmsVisaCasesEntity,

      /**
       * 8. CourseMasterIntakeYearsEntity (Academic Intake Reference)
       *    - Academic intake periods and years
       *    - Used for payment tracking by academic intake
       *    - Supports seasonal payment analysis and reporting
       *    - Intake-specific payment patterns and trends
       */
      CourseMasterIntakeYearsEntity,

      /**
       * 9. VcmCommissionContractInstancesEntity (Commission Contract Details)
       *    - Specific commission contract tiers and structures
       *    - Contains commission rates, percentages, amounts
       *    - Used to verify received payments against contract terms
       *    - Supports tiered commission payment validation
       */
      VcmCommissionContractInstancesEntity,

      // ==================== CORE COMMISSION RECEIVED ENTITIES ====================
      /**
       * 10. VcmCommissionReceivedEntity (Main Commission Received Record)
       *     - Primary entity for tracking received commission payments
       *     - Stores payment metadata: dates, amounts, payment modes
       *     - Contains bank account information and payment references
       *     - Supports attachment management for payment proofs
       *     - Example: "XYZ University - Commission Payment - $10,000"
       */
      VcmCommissionReceivedEntity,

      /**
       * 11. VcmCommissionReceivedDetailsEntity (Commission Received Line Items)
       *     - Detailed line items for received commission payments
       *     - Contains per-case payment details and amounts
       *     - Links received payments to specific visa cases
       *     - Used for detailed payment reconciliation and reporting
       *     - Supports currency conversion and amount tracking
       */
      VcmCommissionReceivedDetailsEntity,
    ]),
  ],
})
export class VisaCommissionReceivedModule {}
