Aller au contenu principal

Billing & Partners Management Enhancement - Brownfield Epic

Epic Goal​

Enhance the existing billing and partner invoice system to provide comprehensive financial management with automated invoice generation, partner commission calculation, and payment tracking that seamlessly extends the current NestJS/Prisma architecture.

Epic Description​

Existing System Context:

  • Current functionality: Basic CRUD operations for invoices (Facture) and partner invoices (FacturePartenaire) with status tracking and financial calculations
  • Technology stack: NestJS controllers/services, Prisma ORM, PostgreSQL database, Swagger documentation
  • Integration points: Reclamation (N:1), Client through Reclamation, ApporteurAffaire partner relationships
  • Existing patterns: Controller/Service architecture, DTO validation, status enum handling, financial field management

Enhancement Details:

  • What's being added/changed: Complete billing workflow automation including invoice generation from reclamations, partner commission calculation, payment reconciliation, and financial reporting capabilities
  • How it integrates: Extends existing FactureService and FacturePartenaireService methods, adds workflow endpoints, leverages existing Reclamation/Client/ApporteurAffaire relationships
  • Success criteria: Automated billing workflow operational, partner commissions calculated accurately, payment tracking functional, existing functionality preserved

Stories​

  1. Story 1: Automated Invoice Generation & Management

    • Implement automatic invoice creation from reclamation FACTURATION status
    • Add invoice numbering system and calculation logic for totals (HT, TTC, degrevement)
    • Create invoice status workflow and payment tracking functionality

  2. Story 2: Partner Commission & Invoice Automation

    • Implement automated partner invoice generation based on client invoices
    • Add commission calculation logic based on ApporteurAffaire relationships
    • Create partner payment reconciliation and tracking system

  3. Story 3: Financial Reporting & Payment Management

    • Add comprehensive financial reporting for invoices and partner payments
    • Implement payment reconciliation workflows and aging reports
    • Create financial dashboard with revenue tracking and outstanding balances

Compatibility Requirements​

  • Existing APIs remain unchanged (GET /invoices, POST /invoices, GET /partner-invoices)
  • Database schema changes are backward compatible (additive fields only)
  • UI changes follow existing Swagger documentation patterns
  • Performance impact is minimal (optimized queries with existing includes)

Risk Mitigation​

  • Primary Risk: Breaking existing Reclamation/Client relationships and financial calculation integrity
  • Mitigation: All new features are additive, existing service methods preserved, comprehensive financial calculation testing and validation
  • Rollback Plan: Database migrations are reversible, new workflow endpoints can be disabled via feature flags, existing CRUD functionality isolated

Definition of Done​

  • All stories completed with acceptance criteria met
  • Existing invoice CRUD functionality verified through testing
  • Integration points with Reclamation, Client, ApporteurAffaire working correctly
  • Swagger documentation updated appropriately
  • No regression in existing financial calculations and status management

Story Manager Handoff​

"Please develop detailed user stories for this brownfield epic. Key considerations:

  • This is an enhancement to an existing system running NestJS/Prisma/PostgreSQL
  • Integration points: Reclamation (N:1), Client through Reclamation, ApporteurAffaire for partner relationships
  • Existing patterns to follow: Controller/Service/DTO architecture, FactureStatus and FacturePartenaireStatus enum handling, financial field calculations (totalHt, totalTtc, etc.)
  • Critical compatibility requirements: Preserve existing API endpoints, maintain database relationship integrity, follow existing status enum patterns (A_FACTURER, FACTUREE, REGLEE, etc.)
  • Each story must include verification that existing billing functionality (CRUD, financial calculations, status tracking, partner relationships) remains intact

The epic should maintain system integrity while delivering comprehensive billing and partner financial management workflow automation."