Aller au contenu principal

User Story: Partner Commission & Invoice Automation - Billing & Partners Epic

Story Overview​

Story ID: BILL-002
Story Type: Brownfield Enhancement
Epic: Billing & Partners Management Enhancement
Priority: High
Estimated Effort: 21 story points

User Story Statement:
As a financial administrator, I want an automated partner commission and invoice system that generates partner invoices based on client invoices with accurate commission calculations using ApporteurAffaire relationships, comprehensive payment reconciliation, and seamless integration with the invoice generation workflow so that partner billing processes are streamlined, financially accurate, and maintain complete audit trails while preserving existing partner invoice functionality.

Business Context​

Current State Analysis​

  • Existing System: Manual partner invoice creation through FacturePartenaireService with basic CRUD operations
  • Technology Stack: NestJS/Prisma with established FacturePartenaire model and FacturePartenaireStatus enum
  • Integration Points: FacturePartenaire ↔ Client/Site/Reclamation/ApporteurAffaire relationships, existing commission field in ApporteurAffaire
  • Existing Patterns: Controller/Service architecture, findByPartnerId() method, getPartnerInvoiceStats(), status enum handling (A_REGLER, EN_ATTENTE, REGLEE, N_A)

Enhancement Goals​

  • Automate partner invoice generation triggered by client invoice creation from Story 1
  • Implement sophisticated commission calculation engine based on ApporteurAffaire commission rates
  • Create comprehensive partner payment reconciliation and tracking system
  • Establish automated commission accuracy validation and monitoring
  • Integrate seamlessly with Invoice Generation from Story 1 workflow
  • Maintain complete backward compatibility with existing partner invoice APIs

Acceptance Criteria​

AC1: Automated Partner Invoice Generation Trigger​

Given a client invoice (Facture) has been created from reclamation at FACTURATION status
When the invoice includes ApporteurAffaire relationships via Site/Reclamation
Then the system should:

  • Automatically detect client invoice creation events from Story 1 automation
  • Identify all ApporteurAffaire relationships connected to the invoice through Site/Reclamation chains
  • Generate corresponding FacturePartenaire records for each partner relationship
  • Set initial status to A_REGLER with proper date timestamps
  • Link partner invoices to client invoice through reclamation relationship
  • Calculate commission amounts using ApporteurAffaire.commission rate
  • Preserve existing FacturePartenaire model fields (montantHtClient, montantHt, numeroDossier, numeroFactureClient)
  • Log partner invoice creation events with complete audit trail

AC2: Commission Calculation Engine​

Given client invoice financial data and ApporteurAffaire commission rates
When calculating partner commission amounts
Then the system should:

  • Extract client invoice totals (totalHt, totalTtc) from linked Facture records
  • Apply ApporteurAffaire.commission percentage to client invoice amounts
  • Calculate montantHtClient as client invoice totalHt for reference tracking
  • Calculate montantHt as commission amount (montantHtClient × commission percentage)
  • Handle multiple partners per invoice with proportional commission distribution
  • Support different commission structures (flat rate, tiered percentages, fixed amounts)
  • Validate commission calculations with cross-reference to ApporteurAffaire settings
  • Handle edge cases: zero commissions, maximum commission caps, minimum thresholds
  • Provide commission calculation audit trail with step-by-step breakdown

AC3: Partner Invoice Numbering and Reference System​

Given partner invoice generation requirements
When creating partner invoices
Then the system should:

  • Generate unique numeroDossier with format PART_YYYY_MM_NNNNNN (6-digit sequence)
  • Set numeroFactureClient to reference the originating client invoice number
  • Maintain relationship integrity between client and partner invoice numbering
  • Support manual dossier number override with validation checks
  • Handle concurrent partner invoice creation with collision prevention
  • Provide partner invoice reference tracking and lookup capabilities
  • Integrate with existing sequential numbering patterns from Story 1

AC4: Partner Payment Reconciliation System​

Given partner invoice payment management needs
When processing partner invoice payments
Then the system should:

  • Track dateReglement automatically when status changes to REGLEE
  • Support partner payment status workflow: A_REGLER → EN_ATTENTE → REGLEE
  • Calculate partner payment periods and aging reports for outstanding invoices
  • Generate partner-specific payment reconciliation reports with commission breakdown
  • Handle payment method tracking and reference number storage in facture field
  • Integrate with existing getPartnerInvoiceStats() method for enhanced reporting
  • Provide overdue partner invoice identification and notification triggers
  • Support bulk partner payment processing with transaction safety

AC5: Integration with Client Invoice Generation Workflow​

Given the automated invoice generation from Story 1
When client invoices are automatically created from reclamations
Then the system should:

  • Listen for client invoice creation events via event-driven architecture
  • Automatically trigger partner invoice generation in the same transaction context
  • Validate ApporteurAffaire relationships before generating partner invoices
  • Handle batch processing for multiple client invoices with partner relationships
  • Support manual partner invoice generation override with proper authorization
  • Maintain transaction integrity between client and partner invoice creation
  • Preserve existing findByClientId() and findByPartnerId() functionality with enhanced data
  • Handle rollback scenarios when partner invoice generation fails

AC6: Partner Commission Accuracy Monitoring​

Given financial accuracy requirements for partner commissions
When partner invoices are generated and processed
Then the system should:

  • Implement automated validation of commission calculation accuracy
  • Cross-reference partner invoice amounts with ApporteurAffaire commission settings
  • Monitor for commission calculation anomalies and trigger alerts
  • Provide commission reconciliation reports comparing calculated vs actual amounts
  • Support commission audit trails with complete calculation history
  • Handle commission rate changes with proper versioning and effective date tracking
  • Generate partner commission summary reports for financial compliance
  • Validate total commission amounts against client invoice totals for consistency

Technical Implementation Details​

Database Schema Enhancements​

Backward Compatible Additions:

  • Add partnerSequenceNumber field to FacturePartenaire model for sequential tracking
  • Add commissionRate field to capture applied commission percentage at generation time
  • Add calculationAuditLog JSON field for commission calculation transparency
  • Add paymentReference and paymentMethod optional fields for payment tracking
  • Create MonthlyPartnerSequence table for concurrent sequence management
  • Add linkedClientInvoiceId field to maintain explicit client invoice relationship

Service Layer Enhancements​

Existing Methods to Preserve:

  • All current FacturePartenaireService methods (create, findAll, findOne, update, remove, findByClientId, findByPartnerId, getPartnerInvoiceStats)
  • Existing include patterns and relationship loading
  • Current status enum handling for FacturePartenaireStatus

New Service Methods:

  • generatePartnerInvoicesFromClientInvoice(clientInvoiceId) - Core automation method
  • calculateCommissionAmounts(clientInvoice, apporteurAffaire) - Commission calculation engine
  • generatePartnerSequentialNumber() - Advanced numbering system
  • updatePartnerInvoiceStatus(id, newStatus, paymentDetails) - Workflow management
  • getPartnerInvoicesByStatusWorkflow() - Status-based filtering
  • generatePartnerPaymentReconciliationReport() - Financial reconciliation
  • validateCommissionAccuracy(partnerId, periodStart, periodEnd) - Accuracy monitoring
  • getCommissionAuditTrail(partnerInvoiceId) - Commission calculation transparency

API Endpoints​

Preserve Existing:

  • GET /factures-partenaires (enhanced with workflow filters)
  • POST /factures-partenaires (maintained for manual creation)
  • GET /factures-partenaires/:id (enhanced with commission audit)
  • PATCH /factures-partenaires/:id (enhanced status workflow validation)
  • DELETE /factures-partenaires/:id (maintained with cascade checks)
  • GET /factures-partenaires/client/:clientId (enhanced with commission data)
  • GET /factures-partenaires/partner/:partnerId (enhanced with payment tracking)

New Endpoints:

  • POST /factures-partenaires/generate-from-client-invoice/:clientInvoiceId
  • PATCH /factures-partenaires/:id/status (dedicated status workflow endpoint)
  • GET /factures-partenaires/by-status-workflow
  • GET /factures-partenaires/payment-reconciliation
  • GET /factures-partenaires/commission-accuracy-report
  • GET /factures-partenaires/:id/commission-audit
  • POST /factures-partenaires/bulk-payment-update

Integration with Story 1 (Invoice Generation)​

Event-Driven Architecture:

  • Subscribe to client invoice creation events from FactureService
  • Implement asynchronous partner invoice generation to avoid blocking client invoice workflow
  • Handle transaction coordination between client and partner invoice creation
  • Provide fallback mechanisms for partner invoice generation failures
  • Support manual trigger for partner invoice generation from existing client invoices

Test Automation Requirements​

Partner Invoice Generation Test Suite​

Automated Test Coverage:

  • Unit Tests: Commission calculation accuracy, partner invoice sequential numbering, status workflow validation
  • Integration Tests: Client-to-partner invoice automation, ApporteurAffaire relationship resolution, transaction integrity
  • End-to-End Tests: Complete partner invoice lifecycle from client invoice creation to partner payment reconciliation

Commission Calculation Validation​

Test Scenarios:

  • Standard commission percentage calculations (5%, 10%, 15%, 20%)
  • Complex commission structures with tiered rates based on amount thresholds
  • Multiple partners per client invoice with proportional distribution
  • Edge cases: zero commissions, 100% commissions, fractional percentage calculations
  • Commission rate changes during invoice generation periods
  • Cross-validation between commission calculations and ApporteurAffaire settings
  • Rounding precision handling for financial accuracy

Partner Invoice Integration Tests​

Comprehensive Coverage:

  • Automatic partner invoice generation triggered by client invoice creation
  • ApporteurAffaire relationship resolution through Site/Reclamation chains
  • Transaction rollback scenarios when partner generation fails
  • Bulk client invoice processing with multiple partner relationships
  • Manual partner invoice generation overrides with authorization validation
  • Commission accuracy monitoring with automated alert generation

Payment Reconciliation Tests​

Financial Workflow Validation:

  • Partner payment status workflow transitions with business rule validation
  • Payment tracking integration with external payment systems
  • Aging report accuracy for overdue partner invoices
  • Bulk payment processing with transaction safety guarantees
  • Payment reconciliation report accuracy with commission breakdown verification
  • Integration with existing financial reporting systems

Performance and Concurrency Tests​

System Stress Testing:

  • Concurrent partner invoice generation under high client invoice volume
  • Commission calculation performance with large partner networks
  • Database transaction integrity under concurrent payment updates
  • Memory usage optimization for bulk partner invoice processing
  • API response time maintenance during peak partner invoice generation periods

Evolution Tracking & Audit Trail​

Partner Invoice Lifecycle Audit​

Comprehensive Tracking:

  • Partner invoice creation events with source client invoice details and ApporteurAffaire relationships
  • All status changes with timestamps, user attribution, and business justification
  • Commission calculation audit log with step-by-step breakdown and rate application
  • Payment tracking with method, reference, and reconciliation data
  • System-generated vs manual partner invoice differentiation
  • Commission rate changes with effective date tracking and version history

Commission Accuracy Audit​

Financial Accountability Measures:

  • Complete commission calculation transparency with input data preservation
  • Cross-reference validation between partner invoice amounts and ApporteurAffaire commission settings
  • Payment reconciliation audit trail with bank reference integration and partner confirmation
  • Month-end closing procedures with partner invoice sequence validation
  • Commission accuracy monitoring with automated variance detection and alerting
  • Regulatory compliance reporting for partner financial audit requirements

Partner Relationship Audit​

Business Relationship Tracking:

  • ApporteurAffaire relationship history with client assignment tracking
  • Commission rate evolution over time with business justification
  • Partner invoice volume and payment patterns analysis
  • Integration audit trail between client invoices and partner commission generation
  • Partner payment behavior analytics for relationship management
  • Compliance tracking for partner contract terms and commission agreements

Performance & Monitoring​

System Health Tracking:

  • Partner invoice generation performance metrics and response time monitoring
  • Commission calculation accuracy validation with automated cross-checks
  • Partner payment reconciliation workflow efficiency tracking
  • ApporteurAffaire relationship resolution performance analysis
  • Error rate monitoring with automated alerting for critical partner billing issues
  • Financial accuracy monitoring with variance detection and correction workflows

Risk Mitigation & Rollback Plan​

Primary Risks & Mitigations​

  • Commission Calculation Errors: Multi-level validation with audit logging, cross-reference checks, and rollback capabilities
  • Partner Invoice Generation Failures: Transaction-safe generation with rollback support, async processing with retry mechanisms
  • ApporteurAffaire Relationship Integrity: Comprehensive relationship validation before invoice generation, cascade handling for relationship changes
  • Performance Impact on Client Invoice Generation: Asynchronous partner invoice processing, optimized queries with existing include patterns
  • Backward Compatibility with Partner APIs: All existing endpoints preserved with enhanced functionality transparently added

Rollback Strategy​

  • Database Migrations: All schema changes are additive and reversible with data preservation
  • Feature Toggles: Partner invoice automation can be disabled via configuration without impacting manual processes
  • API Compatibility: Existing partner invoice endpoints maintain identical behavior with optional enhancements
  • Commission Recalculation: Complete audit trail enables precise commission correction and partner invoice regeneration
  • Transaction Integrity: Client invoice generation workflow isolated from partner invoice failures

Definition of Done​

Functional Completeness​

  • All acceptance criteria met with comprehensive test validation
  • Existing partner invoice CRUD functionality verified through automated regression testing
  • Commission calculation accuracy validated with precision testing and edge case coverage
  • Partner invoice numbering system stress-tested under concurrent load scenarios
  • Integration with Story 1 client invoice generation validated end-to-end

Technical Quality​

  • NestJS service architecture patterns followed with proper dependency injection
  • Prisma ORM integration maintained with enhanced ApporteurAffaire relationship handling
  • Swagger documentation updated with new endpoints and enhanced existing documentation
  • Error handling comprehensive with proper HTTP status codes and user-friendly messages
  • Transaction management implemented for client-partner invoice coordination

Integration & Compatibility​

  • Client invoice workflow integration seamless with automated partner invoice generation
  • Existing Client/Site/Reclamation/ApporteurAffaire relationships preserved and enhanced
  • FacturePartenaireStatus enum integration maintained with enhanced workflow support
  • Performance benchmarks met with no degradation in existing partner operations
  • Event-driven architecture implemented for loose coupling with client invoice generation

Financial Accuracy & Compliance​

  • Commission calculation engine validated with financial precision requirements
  • Payment reconciliation system accurate with complete audit trails
  • Partner invoice financial reporting exportable and compliant with regulations
  • Commission accuracy monitoring operational with automated variance detection
  • Multi-level financial validation implemented with cross-check capabilities

Monitoring & Audit​

  • Complete partner invoice lifecycle audit trail implementation
  • Commission calculation transparency with regulatory compliance readiness
  • Partner payment reconciliation reports accurate and exportable
  • System monitoring implemented with alerting for critical partner billing errors
  • Evolution tracking enabled for future partner financial management enhancements

Story Manager Handoff​

"This brownfield enhancement story delivers automated partner commission and invoice generation while maintaining complete system integrity and seamless integration with Story 1. Key implementation considerations:

  • Backward Compatibility Priority: All existing FacturePartenaireService methods and API endpoints remain unchanged with transparent enhancements
  • Financial Accuracy Critical: Multi-level commission calculation validation ensures accuracy with comprehensive audit trails and ApporteurAffaire rate compliance
  • Integration Seamless: Event-driven architecture enables automatic partner invoice generation from client invoices without blocking primary billing workflow
  • Commission Transparency: Complete calculation audit trails and accuracy monitoring meet partner financial relationship requirements
  • Transaction Safety: Atomic operations ensure client and partner invoice consistency with proper rollback handling
  • Partner Relationship Integrity: ApporteurAffaire relationship validation and evolution tracking maintain business relationship accuracy

The implementation extends existing NestJS/Prisma patterns, integrates seamlessly with Story 1 invoice generation, and prepares comprehensive partner financial management for Story 3 in the billing epic."