Aller au contenu principal

Reclamation Processing Enhancement - Post-RBAC Epic

Epic Goal​

Enhance the existing reclamation system to provide comprehensive TF/CFE tax claim processing workflow with automated status transitions, approval processes, and integration with billing systems that leverage the newly implemented RBAC and authentication infrastructure for secure, tenant-aware operations.

Epic Description​

Current System Context (Post-RBAC Implementation):

  • Authentication: JWT-based authentication with role extraction implemented
  • Authorization: Role-based guards and security infrastructure in place
  • Core functionality: Basic CRUD operations for tax reclamations (TF/CFE), site association, status tracking, and statistics
  • Technology stack: NestJS controllers/services, Prisma ORM, PostgreSQL database, Swagger with Bearer auth
  • Integration points: Site (with Client and Cadastre), Facture, FacturePartenaire entities
  • Security patterns: JwtAuthGuard, RolesGuard, role-based endpoint protection, tenant-aware data access

Enhancement Details:

  • What's being added/changed: Complete reclamation workflow automation including status transition validation, approval processes, automated billing generation, and enhanced tracking capabilities
  • How it integrates: Extends existing ReclamationService methods, adds workflow endpoints to ReclamationController, leverages existing Site/Client/Facture relationships
  • Success criteria: Automated reclamation processing workflow operational, status transitions validated, billing integration working, existing functionality preserved

Stories​

  1. Story 1: Reclamation Status Workflow Automation

    • Implement business rules for status transitions (NOUVELLE → ACCEPTEE → FACTURATION)
    • Add status validation and automated progression based on business logic
    • Create status history tracking and audit trail with timestamps

  2. Story 2: Reclamation Approval & Review Process

    • Add approval workflow for reclamations requiring review
    • Implement approval routing based on reclamation amount and type (TF/CFE)
    • Create approval notifications and review dashboard functionality

  3. Story 3: Automated Billing Integration

    • Implement automatic facture creation when reclamation reaches FACTURATION status
    • Add billing calculation logic based on montantAttendu and degrevement data
    • Create billing reconciliation and partner invoice generation

Compatibility Requirements​

  • Existing APIs remain unchanged (GET /reclamations, POST /reclamations, GET /reclamations/site/:siteId)
  • 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 Site/Client/Facture relationships and reclamation statistics
  • Mitigation: All new features are additive, existing service methods preserved, comprehensive relationship and billing testing
  • 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 reclamation CRUD functionality verified through testing
  • Integration points with Site, Facture, FacturePartenaire working correctly
  • Swagger documentation updated appropriately
  • No regression in existing reclamation statistics and site-based queries

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: Site (N:1), Facture (1:N), FacturePartenaire (1:N), through Site: Client and Cadastre relationships
  • Existing patterns to follow: Controller/Service/DTO architecture, Prisma includes for complex relationships, JSON field usage for degrevement data, status enum handling
  • Critical compatibility requirements: Preserve existing API endpoints, maintain database relationship integrity, follow existing ReclamationType (TF/CFE) and ReclamationStatus enum patterns
  • Each story must include verification that existing reclamation functionality (CRUD, site queries, stats, billing relationships) remains intact

The epic should maintain system integrity while delivering comprehensive reclamation processing workflow automation."