🏗️ Main System Flow Implementation Guide

📋 Overview

This guide provides complete implementation details for integrating the main system workflows with Partner Services APIs. It covers all user journeys from partner selection to shipment assignment with detailed code examples.

Implementation Coverage: 85% (Current) → 100% (Post Phase 3.8)
User Flows Covered: Partner Setup, Zone Management, Shipment Assignment
Performance Target: <2s page load, <200ms API responses

🎯 Main System User Journeys

Journey 1: Partner Setup Flow

Main System Login → Partner Panel → Select Partner → Configure Data

Journey 2: Zone Management Flow

Zone Management → Fetch All Data → Create/Update Operations

Journey 3: Shipment Assignment Flow

Create Shipment → Assign Courier Partner → Partner Selection → Final Charges

🔄 Flow 1: Partner Setup & Configuration

Step 1: Partner Panel Initialization

javascript

class PartnerSetupFlow {
  constructor(client) {
    this.client = client;
    this.cache = new Map();
  }

  // Initialize partner panel with all available partners
  async initializePartnerPanel() {
    try {
      console.log("🚀 Initializing partner panel...");

      // Phase 1: Load all partners (after P3.8.1 implementation)
      const partners = await this.loadAllPartners();

      // Phase 2: Load partner configurations
      const configurations = await this.loadPartnerConfigurations(partners);

      // Phase 3: Build partner selection UI
      const panelData = this.buildPartnerPanelData(partners, configurations);

      console.log(
        `✅ Partner panel initialized with ${partners.length} partners`
      );
      return panelData;
    } catch (error) {
      console.error("❌ Partner panel initialization failed:", error);
      throw new Error("Failed to initialize partner panel");
    }
  }

  // Load all partners with basic info
  async loadAllPartners() {
    try {
      // 🔥 CRITICAL: This API will be available after P3.8.1
      const response = await this.client.makeRequest(
        "GET",
        "/partners/bulk-data"
      );

      return response.data.partners.map((partner) => ({
        partnerId: partner.partnerId,
        name: partner.name,
        status: partner.status,
        operationalStatus: partner.availability?.isAvailable || false,
        zones: partner.zones?.length || 0,
        services: partner.services?.length || 0,
        lastUpdated: partner.lastUpdated,
      }));
    } catch (error) {
      console.warn(
        "⚠️ Bulk partner API not available, falling back to individual calls"
      );
      return await this.loadPartnersIndividually();
    }
  }

  // Fallback method for current implementation
  async loadPartnersIndividually() {
    // This is a workaround until P3.8.1 is implemented
    const knownPartners = await this.getKnownPartnerIds();
    const partners = [];

    for (const partnerId of knownPartners) {
      try {
        const partnerData = await this.client.makeRequest(
          "GET",
          `/partners/comprehensive-data?format=minimal`
        );

        partners.push({
          partnerId,
          name: partnerData.data.partner?.name || partnerId,
          status: partnerData.success ? "ACTIVE" : "INACTIVE",
          zones: partnerData.data.zones?.total || 0,
          services: partnerData.data.services?.total || 0,
        });
      } catch (error) {
        console.warn(`⚠️ Failed to load partner ${partnerId}:`, error.message);
      }
    }

    return partners;
  }

  // Build partner panel UI data
  buildPartnerPanelData(partners, configurations = {}) {
    return {
      partners: partners.map((partner) => ({
        ...partner,
        configuration: configurations[partner.partnerId] || null,
        actions: {
          configure: `/partners/${partner.partnerId}/configure`,
          zones: `/partners/${partner.partnerId}/zones`,
          services: `/partners/${partner.partnerId}/services`,
          charges: `/partners/${partner.partnerId}/charges`,
          discounts: `/partners/${partner.partnerId}/discounts`,
        },
      })),
      summary: {
        total: partners.length,
        active: partners.filter((p) => p.status === "ACTIVE").length,
        operational: partners.filter((p) => p.operationalStatus).length,
      },
      actions: {
        refresh: "/partners/refresh",
        bulkConfigure: "/partners/bulk-configure",
      },
    };
  }
}

Step 2: Partner Selection & Data Fetching

javascript

// When user selects a partner from the panel
async function selectPartner(partnerId) {
  try {
    console.log(`🎯 Selected partner: ${partnerId}`);

    // Fetch comprehensive partner data
    const partnerData = await client.makeRequest(
      "GET",
      `/partners/comprehensive-data?format=standard&includeStatistics=true`
    );

    console.log("📊 Partner Data Summary:");
    console.log(`Zones: ${partnerData.data.zones?.total || 0}`);
    console.log(
      `Packages: ${partnerData.data.packages?.packageCharges?.total || 0}`
    );
    console.log(
      `Services: ${partnerData.data.services?.serviceTypes?.total || 0}`
    );
    console.log(
      `Charges: ${partnerData.data.charges?.customerCharges?.total || 0}`
    );
    console.log(
      `Discounts: ${partnerData.data.discounts?.discounts?.total || 0}`
    );

    // Cache partner data for quick access
    sessionStorage.setItem(`partner_${partnerId}`, JSON.stringify(partnerData));

    return {
      partnerId,
      data: partnerData.data,
      configurationStatus: assessConfigurationCompleteness(partnerData.data),
      nextActions: getRecommendedActions(partnerData.data),
    };
  } catch (error) {
    console.error(`❌ Failed to fetch partner ${partnerId} data:`, error);
    throw error;
  }
}

// Assess configuration completeness
function assessConfigurationCompleteness(data) {
  const checks = {
    zones: data.zones?.total > 0,
    packages: data.packages?.packageCharges?.total > 0,
    services: data.services?.serviceTypes?.total > 0,
    charges: data.charges?.customerCharges?.total > 0,
    discounts: data.discounts?.discounts?.total > 0,
  };

  const completed = Object.values(checks).filter(Boolean).length;
  const total = Object.keys(checks).length;

  return {
    percentage: Math.round((completed / total) * 100),
    completed,
    total,
    checks,
    isComplete: completed === total,
  };
}

Step 3: Zone Configuration Workflow

javascript

// 7-step zone creation process
class ZoneConfigurationFlow {
  constructor(client, partnerId) {
    this.client = client;
    this.partnerId = partnerId;
    this.zoneData = {
      basic: {},
      geographical: {},
      services: {},
    };
  }

  // Step 1: Basic zone information
  async setBasicInformation(zoneInfo) {
    this.zoneData.basic = {
      name: zoneInfo.name,
      description: zoneInfo.description,
      status: zoneInfo.status || true,
    };

    console.log("✅ Zone basic information set");
    return this.zoneData.basic;
  }

  // Step 2: State selection
  async selectStates(stateIds) {
    try {
      // Validate states exist
      const states = await this.client.makeRequest("GET", "/pincodes/states");
      const validStates = stateIds.filter((id) =>
        states.data.some((state) => state.id === id)
      );

      this.zoneData.geographical.states = validStates;
      console.log(`✅ Selected ${validStates.length} states`);

      return validStates;
    } catch (error) {
      console.error("❌ State selection failed:", error);
      throw error;
    }
  }

  // Step 3: City selection (dependent on states)
  async selectCities(cityIds) {
    try {
      const selectedStates = this.zoneData.geographical.states;
      if (!selectedStates?.length) {
        throw new Error("Please select states first");
      }

      // Get cities for selected states
      const cities = await this.client.makeRequest(
        "GET",
        `/pincodes/cities?stateIds=${selectedStates.join(",")}`
      );

      const validCities = cityIds.filter((id) =>
        cities.data.some((city) => city.id === id)
      );

      this.zoneData.geographical.cities = validCities;
      console.log(`✅ Selected ${validCities.length} cities`);

      return validCities;
    } catch (error) {
      console.error("❌ City selection failed:", error);
      throw error;
    }
  }

  // Step 4: Area selection (dependent on cities)
  async selectAreas(areaIds) {
    try {
      const selectedCities = this.zoneData.geographical.cities;
      if (!selectedCities?.length) {
        throw new Error("Please select cities first");
      }

      // Get areas for selected cities
      const areas = await this.client.makeRequest(
        "GET",
        `/pincodes/areas?cityIds=${selectedCities.join(",")}`
      );

      const validAreas = areaIds.filter((id) =>
        areas.data.some((area) => area.id === id)
      );

      this.zoneData.geographical.areas = validAreas;
      console.log(`✅ Selected ${validAreas.length} areas`);

      return validAreas;
    } catch (error) {
      console.error("❌ Area selection failed:", error);
      throw error;
    }
  }

  // Step 5: Pincode selection (dependent on areas)
  async selectPincodes(pincodes) {
    try {
      const selectedAreas = this.zoneData.geographical.areas;
      if (!selectedAreas?.length) {
        throw new Error("Please select areas first");
      }

      // Get pincodes for selected areas
      const availablePincodes = await this.client.makeRequest(
        "GET",
        `/pincodes?areaIds=${selectedAreas.join(",")}`
      );

      const validPincodes = pincodes.filter((pincode) =>
        availablePincodes.data.some((p) => p.pincode === pincode)
      );

      this.zoneData.geographical.pincodes = validPincodes;
      console.log(`✅ Selected ${validPincodes.length} pincodes`);

      return validPincodes;
    } catch (error) {
      console.error("❌ Pincode selection failed:", error);
      throw error;
    }
  }

  // Step 6: Service configuration
  async configureServices(serviceConfigs) {
    try {
      // Validate service types
      const availableServices = await this.client.makeRequest(
        "GET",
        "/service-types"
      );

      const validServices = serviceConfigs.filter((config) =>
        availableServices.data.some(
          (service) => service.id === config.serviceTypeId
        )
      );

      this.zoneData.services = validServices;
      console.log(`✅ Configured ${validServices.length} services`);

      return validServices;
    } catch (error) {
      console.error("❌ Service configuration failed:", error);
      throw error;
    }
  }

  // Step 7: Create zone with all configurations
  async createZone() {
    try {
      const zoneRequest = {
        name: this.zoneData.basic.name,
        description: this.zoneData.basic.description,
        status: this.zoneData.basic.status,
        geographical: {
          states: this.zoneData.geographical.states,
          cities: this.zoneData.geographical.cities || [],
          areas: this.zoneData.geographical.areas || [],
          pincodes: this.zoneData.geographical.pincodes || [],
        },
        services: this.zoneData.services.map((service) => ({
          serviceTypeId: service.serviceTypeId,
          isAvailable: service.isAvailable,
          baseCharge: service.baseCharge || 0,
          customCharges: service.customCharges || {},
          additionalInfo: service.additionalInfo || {},
        })),
      };

      const result = await this.client.makeRequest(
        "POST",
        "/zones",
        zoneRequest
      );

      console.log("🎉 Zone created successfully!");
      console.log(`Zone ID: ${result.data.id}`);
      console.log(`Zone Name: ${result.data.name}`);

      return result.data;
    } catch (error) {
      console.error("❌ Zone creation failed:", error);
      throw error;
    }
  }

  // Get current configuration status
  getConfigurationStatus() {
    return {
      step1_basic: !!this.zoneData.basic.name,
      step2_states: !!this.zoneData.geographical.states?.length,
      step3_cities: !!this.zoneData.geographical.cities?.length,
      step4_areas: !!this.zoneData.geographical.areas?.length,
      step5_pincodes: !!this.zoneData.geographical.pincodes?.length,
      step6_services: !!this.zoneData.services?.length,
      readyToCreate: this.isReadyToCreate(),
    };
  }

  isReadyToCreate() {
    return !!(
      this.zoneData.basic.name &&
      this.zoneData.geographical.states?.length &&
      this.zoneData.services?.length
    );
  }
}

🔄 Flow 2: Zone Management Operations

Fetch All Data for Management

javascript

class ZoneManagementFlow {
  constructor(client) {
    this.client = client;
  }

  // Fetch all zones for management interface
  async fetchAllZones(filters = {}) {
    try {
      const queryParams = new URLSearchParams({
        page: filters.page || 1,
        limit: filters.limit || 50,
        sortBy: filters.sortBy || "name",
        sortOrder: filters.sortOrder || "asc",
        includeStats: true,
        ...filters,
      });

      const zones = await this.client.makeRequest(
        "GET",
        `/zones?${queryParams}`
      );

      console.log(`📍 Loaded ${zones.data.length} zones`);
      return this.enrichZoneData(zones.data);
    } catch (error) {
      console.error("❌ Failed to fetch zones:", error);
      throw error;
    }
  }

  // Fetch all packages for management
  async fetchAllPackages(filters = {}) {
    try {
      const packages = await this.client.makeRequest(
        "GET",
        `/packages/charges?${new URLSearchParams(filters)}`
      );

      console.log(`📦 Loaded ${packages.data.length} packages`);
      return packages.data;
    } catch (error) {
      console.error("❌ Failed to fetch packages:", error);
      throw error;
    }
  }

  // Fetch all services for management
  async fetchAllServices(filters = {}) {
    try {
      const services = await this.client.makeRequest(
        "GET",
        `/service-types?${new URLSearchParams(filters)}`
      );

      console.log(`🔧 Loaded ${services.data.length} services`);
      return services.data;
    } catch (error) {
      console.error("❌ Failed to fetch services:", error);
      throw error;
    }
  }

  // Fetch all charges for management
  async fetchAllCharges(filters = {}) {
    try {
      const charges = await this.client.makeRequest(
        "GET",
        `/customer-charges?${new URLSearchParams(filters)}`
      );

      console.log(`💰 Loaded ${charges.data.length} charges`);
      return charges.data;
    } catch (error) {
      console.error("❌ Failed to fetch charges:", error);
      throw error;
    }
  }

  // Fetch all discounts for management
  async fetchAllDiscounts(filters = {}) {
    try {
      const discounts = await this.client.makeRequest(
        "GET",
        `/discounts?${new URLSearchParams(filters)}`
      );

      console.log(`🎯 Loaded ${discounts.data.length} discounts`);
      return discounts.data;
    } catch (error) {
      console.error("❌ Failed to fetch discounts:", error);
      throw error;
    }
  }

  // Load complete management dashboard data
  async loadManagementDashboard() {
    try {
      console.log("📊 Loading management dashboard...");

      const [zones, packages, services, charges, discounts] = await Promise.all(
        [
          this.fetchAllZones({ limit: 100 }),
          this.fetchAllPackages({ limit: 100 }),
          this.fetchAllServices({ limit: 100 }),
          this.fetchAllCharges({ limit: 100 }),
          this.fetchAllDiscounts({ limit: 100 }),
        ]
      );

      const dashboard = {
        zones: {
          data: zones,
          total: zones.length,
          active: zones.filter((z) => z.status).length,
        },
        packages: {
          data: packages,
          total: packages.length,
          active: packages.filter((p) => p.status).length,
        },
        services: {
          data: services,
          total: services.length,
          active: services.filter((s) => s.status === "ACTIVE").length,
        },
        charges: {
          data: charges,
          total: charges.length,
          active: charges.filter((c) => c.status).length,
        },
        discounts: {
          data: discounts,
          total: discounts.length,
          active: discounts.filter((d) => d.status).length,
        },
        summary: {
          totalConfigurations:
            zones.length +
            packages.length +
            services.length +
            charges.length +
            discounts.length,
          lastUpdated: new Date().toISOString(),
        },
      };

      console.log("✅ Management dashboard loaded successfully");
      return dashboard;
    } catch (error) {
      console.error("❌ Management dashboard loading failed:", error);
      throw error;
    }
  }

  // Enrich zone data with additional information
  enrichZoneData(zones) {
    return zones.map((zone) => ({
      ...zone,
      coverage: {
        states: zone._count?.zoneStates || 0,
        cities: zone._count?.zoneCities || 0,
        areas: zone._count?.zoneAreas || 0,
        pincodes: zone._count?.zonePincodes || 0,
      },
      services: {
        total: zone.serviceTypes?.length || 0,
        active: zone.serviceTypes?.filter((s) => s.isAvailable).length || 0,
      },
      healthScore: this.calculateZoneHealthScore(zone),
    }));
  }

  // Calculate zone health score
  calculateZoneHealthScore(zone) {
    let score = 0;

    // Basic configuration (30%)
    if (zone.name && zone.description) score += 30;

    // Geographical coverage (40%)
    const coverage = zone._count || {};
    if (coverage.zoneStates > 0) score += 10;
    if (coverage.zoneCities > 0) score += 10;
    if (coverage.zonePincodes > 0) score += 20;

    // Service configuration (30%)
    const services = zone.serviceTypes || [];
    if (services.length > 0) score += 15;
    if (services.some((s) => s.isAvailable)) score += 15;

    return Math.min(score, 100);
  }
}

🔄 Flow 3: Shipment Assignment Workflow

Complete Shipment Assignment Implementation

javascript

class ShipmentAssignmentFlow {
  constructor(client) {
    this.client = client;
  }

  // Main shipment assignment workflow
  async assignCourierPartner(shipmentDetails) {
    try {
      console.log("📦 Starting shipment assignment workflow...");

      // Step 1: Validate shipment details
      this.validateShipmentDetails(shipmentDetails);

      // Step 2: Find available partners
      const availablePartners = await this.findAvailablePartners(
        shipmentDetails
      );

      if (availablePartners.length === 0) {
        throw new Error("No available partners found for this shipment");
      }

      // Step 3: Calculate charges for each partner
      const partnersWithCharges = await this.calculateChargesForPartners(
        availablePartners,
        shipmentDetails
      );

      // Step 4: Rank partners (after P3.8.3 implementation)
      const rankedPartners = await this.rankPartners(
        partnersWithCharges,
        shipmentDetails
      );

      // Step 5: Present options to user
      const partnerOptions = this.formatPartnerOptions(rankedPartners);

      console.log(`✅ Found ${partnerOptions.length} available partners`);
      return {
        shipmentDetails,
        partnerOptions,
        recommendedPartner: partnerOptions[0], // Highest ranked
        metadata: {
          searchCriteria: shipmentDetails,
          evaluatedPartners: availablePartners.length,
          availablePartners: partnerOptions.length,
          timestamp: new Date().toISOString(),
        },
      };
    } catch (error) {
      console.error("❌ Shipment assignment failed:", error);
      throw error;
    }
  }

  // Find all available partners for shipment
  async findAvailablePartners(shipmentDetails) {
    try {
      // 🔥 CRITICAL: After P3.8.1, use bulk partner availability
      try {
        const bulkAvailability = await this.client.makeRequest(
          "POST",
          "/partners/bulk-availability",
          { shipmentDetails }
        );

        return bulkAvailability.data.availablePartners;
      } catch (error) {
        console.warn(
          "⚠️ Bulk availability API not available, using individual checks"
        );
        return await this.findAvailablePartnersIndividually(shipmentDetails);
      }
    } catch (error) {
      console.error("❌ Failed to find available partners:", error);
      throw error;
    }
  }

  // Fallback method for individual partner checks
  async findAvailablePartnersIndividually(shipmentDetails) {
    const knownPartners = await this.getKnownPartnerIds();
    const availablePartners = [];

    for (const partnerId of knownPartners) {
      try {
        // Switch partner context for each check
        const partnerClient = new PartnerServicesClient({
          ...this.client.config,
          partnerId,
        });

        const availability = await partnerClient.makeRequest(
          "POST",
          "/partners/availability/check",
          shipmentDetails
        );

        if (availability.data.isAvailable) {
          availablePartners.push({
            partnerId,
            availability: availability.data,
          });
        }
      } catch (error) {
        console.warn(`⚠️ Availability check failed for partner ${partnerId}`);
      }
    }

    return availablePartners;
  }

  // Calculate charges for all available partners
  async calculateChargesForPartners(partners, shipmentDetails) {
    const partnersWithCharges = [];

    for (const partner of partners) {
      try {
        const partnerClient = new PartnerServicesClient({
          ...this.client.config,
          partnerId: partner.partnerId,
        });

        const charges = await partnerClient.makeRequest(
          "POST",
          "/shipments/calculate-charges",
          {
            partnerId: partner.partnerId,
            ...shipmentDetails,
          }
        );

        if (charges.data.available) {
          partnersWithCharges.push({
            ...partner,
            charges: charges.data.charges,
            breakdown: charges.data.breakdown,
            calculationId: charges.data.calculationId,
          });
        }
      } catch (error) {
        console.warn(
          `⚠️ Charge calculation failed for partner ${partner.partnerId}`
        );
      }
    }

    return partnersWithCharges;
  }

  // Rank partners by multiple criteria
  async rankPartners(partners, shipmentDetails) {
    try {
      // 🔥 CRITICAL: After P3.8.3, use ranking API
      try {
        const rankingRequest = {
          shipmentDetails,
          partners: partners.map((p) => ({
            partnerId: p.partnerId,
            charges: p.charges,
          })),
          rankingCriteria: {
            priorityWeights: {
              cost: 0.4,
              speed: 0.3,
              reliability: 0.3,
            },
          },
        };

        const ranking = await this.client.makeRequest(
          "POST",
          "/shipment-assignment/rank-partners",
          rankingRequest
        );

        return ranking.data.rankings;
      } catch (error) {
        console.warn("⚠️ Ranking API not available, using local ranking");
        return this.rankPartnersLocally(partners);
      }
    } catch (error) {
      console.error("❌ Partner ranking failed:", error);
      return partners; // Return unranked if ranking fails
    }
  }

  // Local ranking fallback
  rankPartnersLocally(partners) {
    return partners
      .map((partner) => ({
        ...partner,
        score: this.calculateLocalScore(partner),
      }))
      .sort((a, b) => b.score - a.score);
  }

  // Calculate local ranking score
  calculateLocalScore(partner) {
    let score = 0;

    // Cost factor (40%) - lower cost = higher score
    const totalAmount = partner.charges.totalAmount;
    const costScore = Math.max(0, 100 - totalAmount / 10); // Adjust scaling as needed
    score += costScore * 0.4;

    // Availability confidence (30%)
    const confidence = partner.availability.confidence || 50;
    score += confidence * 0.3;

    // Service coverage (30%)
    const serviceScore = partner.availability.services?.coverage || 50;
    score += serviceScore * 0.3;

    return Math.round(score);
  }

  // Format partner options for UI display
  formatPartnerOptions(rankedPartners) {
    return rankedPartners.map((partner, index) => ({
      rank: index + 1,
      partnerId: partner.partnerId,
      score: partner.score,
      charges: {
        total: partner.charges.totalAmount,
        subtotal: partner.charges.subtotal,
        breakdown: {
          weightCharge: partner.charges.weightCharge,
          distanceCharge: partner.charges.distanceCharge,
          fscCharge: partner.charges.fscCharge,
          codCharge: partner.charges.codCharge,
          discountAmount: partner.charges.discountAmount,
          gstAmount: partner.charges.gstAmount,
        },
      },
      availability: {
        confidence: partner.availability.confidence,
        services: partner.availability.services.matched,
        coverage: partner.availability.coverage,
      },
      estimatedDelivery: partner.estimatedDelivery || "2-3 days",
      recommended: index === 0,
      actions: {
        select: `/shipments/assign/${partner.partnerId}`,
        details: `/partners/${partner.partnerId}/details`,
        charges: `/shipments/charges/${partner.calculationId}`,
      },
    }));
  }

  // Validate shipment details
  validateShipmentDetails(details) {
    const required = ["pickupPincode", "deliveryPincode", "weight"];
    const missing = required.filter((field) => !details[field]);

    if (missing.length > 0) {
      throw new Error(`Missing required fields: ${missing.join(", ")}`);
    }

    if (!/^\d{6}$/.test(details.pickupPincode)) {
      throw new Error("Invalid pickup pincode format");
    }

    if (!/^\d{6}$/.test(details.deliveryPincode)) {
      throw new Error("Invalid delivery pincode format");
    }

    if (details.weight <= 0 || details.weight > 50000) {
      throw new Error("Weight must be between 1g and 50kg");
    }
  }

  // Final partner selection and assignment
  async selectPartner(partnerId, shipmentDetails) {
    try {
      const assignmentRequest = {
        shipmentDetails: {
          ...shipmentDetails,
          assignedPartnerId: partnerId,
        },
        assignmentPreferences: {
          assignmentStrategy: "MANUAL_SELECTION",
          selectedPartner: partnerId,
        },
        options: {
          includeChargeEstimate: true,
          includeTransitTime: true,
          createAssignmentRecord: true,
        },
      };

      const assignment = await this.client.makeRequest(
        "POST",
        "/shipment-assignment/assign",
        assignmentRequest
      );

      console.log("🎉 Partner selected and assignment created!");
      console.log(`Assignment ID: ${assignment.data.assignment.assignmentId}`);

      return assignment.data;
    } catch (error) {
      console.error("❌ Partner selection failed:", error);
      throw error;
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307

📊 Performance Optimization

Caching Strategy for Main System

javascript

class MainSystemCache {
  constructor() {
    this.cache = new Map();
    this.cacheExpiry = new Map();
  }

  // Cache partner data with TTL
  cachePartnerData(partnerId, data, ttlMinutes = 30) {
    const key = `partner_${partnerId}`;
    const expiry = Date.now() + ttlMinutes * 60 * 1000;

    this.cache.set(key, data);
    this.cacheExpiry.set(key, expiry);

    console.log(
      `💾 Cached partner ${partnerId} data for ${ttlMinutes} minutes`
    );
  }

  // Get cached partner data
  getCachedPartnerData(partnerId) {
    const key = `partner_${partnerId}`;
    const expiry = this.cacheExpiry.get(key);

    if (expiry && Date.now() < expiry) {
      console.log(`⚡ Using cached data for partner ${partnerId}`);
      return this.cache.get(key);
    }

    // Expired or not found
    this.cache.delete(key);
    this.cacheExpiry.delete(key);
    return null;
  }

  // Cache charge calculations
  cacheChargeCalculation(shipmentHash, charges, ttlMinutes = 15) {
    const key = `charges_${shipmentHash}`;
    const expiry = Date.now() + ttlMinutes * 60 * 1000;

    this.cache.set(key, charges);
    this.cacheExpiry.set(key, expiry);

    console.log(`💾 Cached charge calculation for ${ttlMinutes} minutes`);
  }

  // Generate shipment hash for caching
  generateShipmentHash(shipmentDetails) {
    const hashString = [
      shipmentDetails.partnerId,
      shipmentDetails.pickupPincode,
      shipmentDetails.deliveryPincode,
      shipmentDetails.weight,
      shipmentDetails.shipmentType,
      shipmentDetails.paymentType,
    ].join("|");

    return btoa(hashString).replace(/[^a-zA-Z0-9]/g, "");
  }
}

✅ Complete Integration Example

javascript

// Complete main system integration example
class MainSystemIntegration {
  constructor(config) {
    this.client = new PartnerServicesClient(config);
    this.cache = new MainSystemCache();
    this.setupFlow = new PartnerSetupFlow(this.client);
    this.managementFlow = new ZoneManagementFlow(this.client);
    this.assignmentFlow = new ShipmentAssignmentFlow(this.client);
  }

  // Initialize main system with partner services
  async initialize() {
    try {
      console.log("🚀 Initializing main system integration...");

      // Test connectivity
      await this.client.makeRequest("GET", "/health");

      // Load partner panel
      const partnerPanel = await this.setupFlow.initializePartnerPanel();

      // Load management dashboard
      const managementDashboard =
        await this.managementFlow.loadManagementDashboard();

      console.log("✅ Main system integration initialized successfully");

      return {
        partnerPanel,
        managementDashboard,
        status: "READY",
      };
    } catch (error) {
      console.error("❌ Main system integration failed:", error);
      throw error;
    }
  }

  // Complete shipment workflow
  async processShipment(shipmentDetails) {
    try {
      // Step 1: Assign courier partner
      const assignmentOptions = await this.assignmentFlow.assignCourierPartner(
        shipmentDetails
      );

      // Return options for user selection
      return assignmentOptions;
    } catch (error) {
      console.error("❌ Shipment processing failed:", error);
      throw error;
    }
  }

  // Finalize shipment assignment
  async finalizeShipment(partnerId, shipmentDetails) {
    try {
      const assignment = await this.assignmentFlow.selectPartner(
        partnerId,
        shipmentDetails
      );

      // Cache the successful assignment
      this.cache.cacheChargeCalculation(
        this.cache.generateShipmentHash(shipmentDetails),
        assignment.charges,
        60 // 1 hour cache for completed assignments
      );

      return assignment;
    } catch (error) {
      console.error("❌ Shipment finalization failed:", error);
      throw error;
    }
  }
}

// Usage example
const mainSystem = new MainSystemIntegration(API_CONFIG);

// Initialize system
mainSystem.initialize().then((data) => {
  console.log("🎉 Main system ready!");
});

// Process a shipment
const shipment = {
  pickupPincode: "110001",
  deliveryPincode: "400001",
  weight: 2500,
  shipmentType: "B2C",
  paymentType: "COD",
  declaredValue: 3500,
};

mainSystem
  .processShipment(shipment)
  .then((options) => {
    console.log("📦 Shipment options ready for selection");

    // User selects the recommended partner
    const selectedPartner = options.recommendedPartner.partnerId;

    // Finalize assignment
    return mainSystem.finalizeShipment(selectedPartner, shipment);
  })
  .then((assignment) => {
    console.log("✅ Shipment assigned successfully!");
    console.log(`Assignment ID: ${assignment.assignment.assignmentId}`);
  });

🎯 Next Steps

Partner Setup - Advanced partner configuration
Shipment Assignment Integration - Detailed assignment workflows
API Examples - Complete request/response examples
Error Handling - Robust error management

This guide provides 85% implementation coverage. The remaining 15% will be available after Phase 3.8 completion.

🏗️ Main System Flow Implementation Guide ​

📋 Overview ​

🎯 Main System User Journeys ​

Journey 1: Partner Setup Flow ​

Journey 2: Zone Management Flow ​

Journey 3: Shipment Assignment Flow ​

🔄 Flow 1: Partner Setup & Configuration ​

Step 1: Partner Panel Initialization ​

Step 2: Partner Selection & Data Fetching ​

Step 3: Zone Configuration Workflow ​

🔄 Flow 2: Zone Management Operations ​

Fetch All Data for Management ​

🔄 Flow 3: Shipment Assignment Workflow ​

Complete Shipment Assignment Implementation ​

📊 Performance Optimization ​

Caching Strategy for Main System ​

✅ Complete Integration Example ​

🎯 Next Steps ​

🏗️ Main System Flow Implementation Guide

📋 Overview

🎯 Main System User Journeys

Journey 1: Partner Setup Flow

Journey 2: Zone Management Flow

Journey 3: Shipment Assignment Flow

🔄 Flow 1: Partner Setup & Configuration

Step 1: Partner Panel Initialization

Step 2: Partner Selection & Data Fetching

Step 3: Zone Configuration Workflow

🔄 Flow 2: Zone Management Operations

Fetch All Data for Management

🔄 Flow 3: Shipment Assignment Workflow

Complete Shipment Assignment Implementation

📊 Performance Optimization

Caching Strategy for Main System

✅ Complete Integration Example

🎯 Next Steps