Enhance API documentation and restructure routes for improved clarity

- Updated README.md to include comprehensive Swagger documentation details, highlighting new features and endpoint categories.
- Introduced a new router structure to streamline route registration for admin and public endpoints, enhancing maintainability.
- Updated health check endpoint documentation to reflect comprehensive server status information.
- Enhanced customer and company management routes with improved descriptions and examples in Swagger.
- Refactored customer and user handlers to remove obsolete route registrations, aligning with the new router structure.
- Improved response handling in customer and user services to utilize string IDs consistently.
- Updated validation rules and forms for customer management to support multiple company assignments.
- Enhanced logging practices across services to ensure better traceability and error handling.

internal/customer/repository.go

@@ -20,11 +20,13 @@ type Repository interface {
 	GetByRegistrationNumber(ctx context.Context, registrationNumber string) (*Customer, error)
 	GetByTaxID(ctx context.Context, taxID string) (*Customer, error)
 	GetByCompanyID(ctx context.Context, companyID string, limit, offset int) ([]*Customer, error)
+	GetByCompanyIDs(ctx context.Context, companyIDs []string, limit, offset int) ([]*Customer, error)
 	Update(ctx context.Context, customer *Customer) error
 	Delete(ctx context.Context, id string) error
 	List(ctx context.Context, limit, offset int) ([]*Customer, error)
 	Search(ctx context.Context, search string, customerType *string, status *string, companyID *string, industry *string, isVerified *bool, isCompliant *bool, language *string, currency *string, limit, offset int, sortBy, sortOrder string) ([]*Customer, error)
 	CountByCompanyID(ctx context.Context, companyID string) (int64, error)
+	CountByCompanyIDs(ctx context.Context, companyIDs []string) (int64, error)
 	CountByType(ctx context.Context, customerType CustomerType) (int64, error)
 	CountByStatus(ctx context.Context, status CustomerStatus) (int64, error)
 	UpdateStatus(ctx context.Context, id string, status CustomerStatus) error
@@ -46,7 +48,7 @@ func NewCustomerRepository(mongoManager *mongopkg.ConnectionManager, logger logg
 		*mongopkg.NewIndex("company_name_idx", bson.D{{Key: "company_name", Value: 1}}),
 		*mongopkg.NewIndex("registration_number_idx", bson.D{{Key: "registration_number", Value: 1}}),
 		*mongopkg.NewIndex("tax_id_idx", bson.D{{Key: "tax_id", Value: 1}}),
-		*mongopkg.NewIndex("company_id_idx", bson.D{{Key: "company_id", Value: 1}}),
+		*mongopkg.NewIndex("company_ids_idx", bson.D{{Key: "company_ids", Value: 1}}), // Index for CompanyIDs array
 		*mongopkg.NewIndex("type_idx", bson.D{{Key: "type", Value: 1}}),
 		*mongopkg.NewIndex("status_idx", bson.D{{Key: "status", Value: 1}}),
 		*mongopkg.NewIndex("industry_idx", bson.D{{Key: "industry", Value: 1}}),
@@ -245,6 +247,46 @@ func (r *customerRepository) GetByCompanyID(ctx context.Context, companyID strin
 	return customers, nil
 }
 
+// GetByCompanyIDs retrieves customers by multiple company IDs with pagination
+func (r *customerRepository) GetByCompanyIDs(ctx context.Context, companyIDs []string, limit, offset int) ([]*Customer, error) {
+	if len(companyIDs) == 0 {
+		return nil, errors.New("no company IDs provided")
+	}
+
+	// Build pagination
+	pagination := mongopkg.NewPaginationBuilder().
+		Limit(limit).
+		Skip(offset).
+		SortDesc("created_at").
+		Build()
+
+	// Filter by company IDs and active status
+	filter := bson.M{
+		"company_ids": bson.M{"$in": companyIDs},
+		"status":      bson.M{"$ne": CustomerStatusInactive},
+	}
+
+	// Use ORM to find customers
+	result, err := r.ormRepo.FindAll(ctx, filter, pagination)
+	if err != nil {
+		r.logger.Error("Failed to get customers by multiple company IDs", map[string]interface{}{
+			"error":       err.Error(),
+			"company_ids": companyIDs,
+			"limit":       limit,
+			"offset":      offset,
+		})
+		return nil, err
+	}
+
+	// Convert []Customer to []*Customer
+	customers := make([]*Customer, len(result.Items))
+	for i := range result.Items {
+		customers[i] = &result.Items[i]
+	}
+
+	return customers, nil
+}
+
 // Update updates a customer
 func (r *customerRepository) Update(ctx context.Context, customer *Customer) error {
 	// Set updated timestamp using Unix timestamp
@@ -424,6 +466,29 @@ func (r *customerRepository) CountByCompanyID(ctx context.Context, companyID str
 	return count, nil
 }
 
+// CountByCompanyIDs counts customers by multiple company IDs
+func (r *customerRepository) CountByCompanyIDs(ctx context.Context, companyIDs []string) (int64, error) {
+	if len(companyIDs) == 0 {
+		return 0, errors.New("no company IDs provided")
+	}
+
+	filter := bson.M{
+		"company_ids": bson.M{"$in": companyIDs},
+		"status":      bson.M{"$ne": CustomerStatusInactive},
+	}
+
+	count, err := r.ormRepo.Count(ctx, filter)
+	if err != nil {
+		r.logger.Error("Failed to count customers by multiple company IDs", map[string]interface{}{
+			"error":       err.Error(),
+			"company_ids": companyIDs,
+		})
+		return 0, err
+	}
+
+	return count, nil
+}
+
 // CountByType counts customers by type
 func (r *customerRepository) CountByType(ctx context.Context, customerType CustomerType) (int64, error) {
 	filter := bson.M{