Assist_Design/docs/validation/bff-validation-migration.md

BFF Business Validation Migration to Domain

Investigation Summary

Found the following validator services in BFF:

1. ✅ MappingValidatorService - Already migrated to domain
2. ✅ OrderValidator - Already uses domain validation helpers
3. 🔄 InvoiceValidatorService - Has pure validation functions to migrate
4. ❌ OrderFulfillmentValidator - Pure infrastructure (DB/API calls)
5. ❌ SimValidationService - Pure infrastructure (DB lookups)

Candidates for Migration

1. Invoice Validation Functions → domain/billing/validation.ts

Source: apps/bff/src/modules/invoices/validators/invoice-validator.service.ts

Pure validation functions to migrate:

// Input validation (no dependencies)
- validateInvoiceId(invoiceId: number): ValidationResult
- validateUserId(userId: string): ValidationResult  
- validateWhmcsClientId(clientId: number): ValidationResult
- validatePaymentGateway(gatewayName: string): ValidationResult
- validateReturnUrl(returnUrl: string): ValidationResult
- validatePagination(options): ValidationResult
- validateGetInvoicesOptions(options): InvoiceValidationResult

Already in domain (correctly placed):

• INVOICE_PAGINATION constants ✅
• VALID_INVOICE_STATUSES ✅
• isValidInvoiceStatus() ✅
• sanitizePaginationLimit() ✅
• sanitizePaginationPage() ✅

2. Invoice Validation Result Type → domain/billing/contract.ts

Source: apps/bff/src/modules/invoices/types/invoice-service.types.ts

export interface InvoiceValidationResult {
  isValid: boolean;
  errors: string[];
}

Status Check: Orders & Subscriptions

Orders Validation ✅ Already good!

• Business rules already in domain/orders/validation.ts
• Helpers: getOrderTypeValidationError, hasSimServicePlan, etc.
• BFF only does infrastructure (DB, API calls, logging)

Subscriptions/SIM Validation ✅ Already good!

• SimValidationService is pure infrastructure (fetches from DB, checks subscription type)
• No pure business logic to extract

Migration Plan

Phase 1: Invoice Validation

1. Create packages/domain/billing/validation.ts with pure validation functions
2. Add InvoiceValidationResult to packages/domain/billing/contract.ts
3. Update packages/domain/billing/index.ts to export validation
4. Refactor InvoiceValidatorService to delegate to domain functions
5. Add logging wrapper (infrastructure concern) in BFF service

Phase 2: Common URL Validation

The validateReturnUrl() function is generic enough for domain/common/validation.ts:

export function validateUrl(url: string): ValidationResult {
  try {
    new URL(url);
    return { isValid: true, errors: [] };
  } catch {
    return { isValid: false, errors: ["Invalid URL format"] };
  }
}

Architecture Pattern (Confirmed Correct)

┌─────────────────────────────────────────────┐
│ Domain Layer (Pure Business Logic)         │
├─────────────────────────────────────────────┤
│ - domain/*/schema.ts (Zod schemas)          │
│ - domain/*/validation.ts (pure functions)   │
│ - domain/*/contract.ts (types)              │
│ - domain/common/validation.ts (helpers)     │
└─────────────────────────────────────────────┘
                    ↑
                    │ imports
                    │
┌─────────────────────────────────────────────┐
│ BFF Infrastructure Layer                    │
├─────────────────────────────────────────────┤
│ - *-validator.service.ts (thin wrappers)    │
│ - Database queries                          │
│ - HTTP/API calls                            │
│ - Logging                                   │
│ - Caching                                   │
│ - Error handling                            │
└─────────────────────────────────────────────┘

What Stays in BFF (Infrastructure)

These are correctly placed and should NOT be moved:

1. Database-dependent validation

   • validateUserMapping() - queries DB for mappings
   • validatePaymentMethod() - queries WHMCS API
   • validateSKUs() - queries Salesforce
   • validateInternetDuplication() - queries WHMCS for existing products
   • validateSimSubscription() - queries DB for subscription details

2. Service orchestration

   • validateCompleteOrder() - orchestrates multiple validations
   • validateFulfillmentRequest() - orchestrates SF + payment checks

3. Infrastructure types

   • InvoiceServiceStats (monitoring)
   • InvoiceHealthStatus (health checks)
   • MappingCacheKey, CachedMapping (caching)

Implementation Order

1. ✅ Common validation utilities (completed)
2. ✅ Mapping validation (completed)
3. 🔄 Next: Invoice validation functions
4. Document pattern in architecture guide