Reclamation Status Workflow Automation - Brownfield User Story

Story Overview

Epic: Reclamation Processing Enhancement
Story: Story 1 - Reclamation Status Workflow Automation
Story Type: Enhancement (Brownfield)
Priority: High
Estimated Effort: 13 story points

User Story

As a tax reclamation processor
I want to have automated reclamation status workflow with validation rules, business logic enforcement, audit trails, and TF/CFE-specific processing
So that I can efficiently process tax reclamations through the complete lifecycle while maintaining compliance, transparency, and integration with existing site/client/billing relationships

Context & Integration

Current System Integration Points:

Extends existing ReclamationService (/Users/ayoub/projects/emtb/apps/api/src/reclamation/reclamation.service.ts)
Leverages existing ReclamationStatus enum (NOUVELLE, ACCEPTEE, EN_ATTENTE, ACCEPTEE_PARTIELLEMENT, REFUSEE, FACTURATION, ARCHIVEE, DEMANDE_COMPLEMENTAIRE)
Integrates with existing ReclamationType enum (TF, CFE) with specific validation rules
Maintains compatibility with Site-Client-Cadastre-ApporteurAffaire relationships
Connects with existing Facture and FacturePartenaire billing systems
Preserves JSON field usage for degrevement, incidenceCfe, and interetMoratoire data

Existing Functionality to Preserve:

All CRUD operations (GET /reclamations, POST /reclamations, PATCH /reclamations/:id, DELETE /reclamations/:id)
Site-based reclamation queries (GET /reclamations/site/:siteId)
Reclamation statistics endpoint (GET /reclamations/stats) with status grouping
Complex Prisma includes for relationship loading (site.client, site.cadastre, factures, facturesPartenaires)
Date handling for dateDemande, dateDeDebut, dateFin, dateRetour
JSON field management for degrevement data and billing calculations
Existing status-based business logic throughout the billing system

Acceptance Criteria

AC1: Status Transition Validation & TF/CFE Business Rules

Given I am processing reclamation status changes
When I attempt to update a reclamation status
Then the system should:

Validate transition rules based on ReclamationType: TF vs CFE specific workflows
Enforce NOUVELLE → ACCEPTEE → FACTURATION primary workflow for both types
Allow TF-specific transitions: NOUVELLE → EN_ATTENTE → ACCEPTEE for complex TF cases
Support CFE-specific transitions: NOUVELLE → ACCEPTEE_PARTIELLEMENT → FACTURATION for partial CFE approvals
Validate DEMANDE_COMPLEMENTAIRE can be entered from any status except ARCHIVEE and FACTURATION
Prevent invalid transitions (NOUVELLE → FACTURATION without acceptance)
Ensure REFUSEE is terminal except for reactivation to NOUVELLE with proper justification
Check business prerequisites: montantAttendu validation, site status compatibility, client relationship integrity
Validate degrevement data completeness for CFE transitions to ACCEPTEE
Maintain backward compatibility with existing status update patterns

AC2: Enhanced Status History Tracking & Audit Trail

Given reclamation status changes occur
When any status transition happens
Then the system should:

Create comprehensive status history entries with previous status, new status, timestamp, and responsible user
Track status change reason, business justification, and supporting documentation references
Log TF/CFE-specific validation results and degrevement data changes
Store transition validation results and business rule evaluations
Record automatic status changes triggered by billing processes or system workflows
Maintain permanent audit trail with data integrity controls and cryptographic hashing
Track relationship context (Site ID, Client ID, associated Factures)
Log JSON field modifications (degrevement, incidenceCfe, interetMoratoire changes)
Provide comprehensive audit API endpoint for compliance reporting and regulatory requirements

AC3: Automated Status Progression & Business Logic

Given reclamation processing workflows
When specific conditions are met
Then the system should:

Auto-progress ACCEPTEE reclamations to FACTURATION when billing criteria are satisfied
Implement CFE-specific logic: validate incidenceCfe data before FACTURATION transition
Handle TF-specific logic: verify degrevement calculations and tax year compliance
Auto-transition to EN_ATTENTE when additional documentation is required
Move to DEMANDE_COMPLEMENTAIRE when client follow-up is needed with automatic notifications
Progress to ARCHIVEE when reclamations are fully processed and billing is complete
Validate montantAttendu against degrevement calculations before financial status transitions
Check Site status compatibility and Client relationship integrity during transitions
Integrate with existing billing workflows to trigger Facture creation at FACTURATION status

AC4: Site/Client/Billing Integration & Relationship Validation

Given the existing Site-Client-Facture ecosystem
When reclamation status changes occur
Then the system should:

Validate Site status compatibility with reclamation status transitions
Ensure Client relationship integrity and active status during processing
Integrate with Facture creation when reclamations reach FACTURATION status
Synchronize with FacturePartenaire workflows for commission and partner billing
Maintain ApporteurAffaire relationship context throughout status transitions
Validate cadastre information completeness for TF reclamations before acceptance
Check Site configuration requirements for CFE reclamations (incidenceCfe data)
Preserve existing complex Prisma includes and relationship loading patterns
Trigger billing calculations based on degrevement data and montantAttendu values

AC5: TF vs CFE Workflow Specialization

Given different reclamation types (TF/CFE) have distinct processing requirements
When managing status workflows
Then the system should:

Implement TF-specific validation: cadastre data completeness, tax year validation, property assessment requirements
Enforce CFE-specific validation: business activity verification, incidenceCfe calculation, establishment data requirements
Support TF workflow: NOUVELLE → EN_ATTENTE (document review) → ACCEPTEE → FACTURATION
Support CFE workflow: NOUVELLE → ACCEPTEE/ACCEPTEE_PARTIELLEMENT → FACTURATION with business impact analysis
Validate degrevement data structure according to type: TF property-based vs CFE business-based calculations
Handle interetMoratoire calculations differently for TF (property-based) vs CFE (business revenue-based)
Enforce type-specific document requirements and validation rules
Support different billing patterns: TF annual cycles vs CFE quarterly assessments

AC6: Evolution Tracking & Comprehensive Audit

Given compliance and regulatory requirements for tax reclamation processing
When status workflow operations occur
Then the system should:

Track all status-related actions with full user context, IP address, and system state
Maintain immutable audit logs with cryptographic integrity verification
Record workflow rule evaluations, validation results, and business decision rationales
Log system-driven status changes with complete automation context
Track degrevement data modifications with before/after JSON comparisons
Monitor billing integration points and financial transaction correlations
Record Site/Client relationship validations and integrity checks
Support comprehensive audit report generation with regulatory compliance formatting
Maintain audit trail export capabilities for external tax authority requirements
Log performance metrics for workflow compliance and processing efficiency

AC7: Backward Compatibility & System Integration

Given existing reclamation functionality throughout the system
When enhanced status workflow is implemented
Then it should:

Maintain existing PATCH /reclamations/:id API with identical request/response format
Preserve existing ReclamationStatus enum values and database schema compatibility
Keep existing reclamation statistics calculation and status-based filtering
Maintain performance of existing queries with efficient indexing strategies
Support existing status-dependent business logic in billing and reporting systems
Ensure seamless integration with Site, Facture, and FacturePartenaire workflows
Preserve JSON field handling patterns for degrevement, incidenceCfe, and interetMoratoire
Maintain existing date handling and validation for all DateTime fields
Keep existing Prisma include patterns for complex relationship loading

Technical Requirements

Database Schema Changes (Additive Only)

-- Reclamation status history table
CREATE TABLE reclamation_status_history (
  id SERIAL PRIMARY KEY,
  reclamation_id INTEGER NOT NULL REFERENCES reclamations(id) ON DELETE CASCADE,
  previous_status VARCHAR(30),
  new_status VARCHAR(30) NOT NULL,
  change_reason VARCHAR(200),
  business_justification TEXT,
  changed_by INTEGER REFERENCES users(id),
  changed_at TIMESTAMP DEFAULT NOW(),
  system_triggered BOOLEAN DEFAULT FALSE,
  validation_results JSONB,
  degrevement_changes JSONB, -- Before/after degrevement data
  billing_impact JSONB, -- Financial impact calculation
  site_context JSONB, -- Site and Client context at time of change
  tf_cfe_specific_data JSONB, -- Type-specific validation data
  supporting_document_ids INTEGER[],
  approval_required BOOLEAN DEFAULT FALSE,
  approved_by INTEGER REFERENCES users(id),
  approved_at TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW()
);

-- Status workflow rules for TF/CFE specialization
CREATE TABLE reclamation_status_workflow_rules (
  id SERIAL PRIMARY KEY,
  from_status VARCHAR(30),
  to_status VARCHAR(30) NOT NULL,
  reclamation_type VARCHAR(10) NOT NULL, -- TF or CFE
  site_requirements JSONB, -- Site status and configuration requirements
  client_requirements JSONB, -- Client status and validation requirements
  financial_requirements JSONB, -- montantAttendu and degrevement validation
  document_requirements JSONB, -- Required documents and validation rules
  degrevement_validation JSONB, -- Degrevement data validation rules
  requires_approval BOOLEAN DEFAULT FALSE,
  required_role VARCHAR(50),
  prerequisite_conditions JSONB,
  validation_rules JSONB,
  auto_notification BOOLEAN DEFAULT TRUE,
  billing_trigger BOOLEAN DEFAULT FALSE, -- Triggers billing creation
  is_active BOOLEAN DEFAULT TRUE,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW(),
  CONSTRAINT unique_workflow_rule UNIQUE(from_status, to_status, reclamation_type)
);

-- Status change notifications with TF/CFE context
CREATE TABLE reclamation_status_notifications (
  id SERIAL PRIMARY KEY,
  reclamation_id INTEGER NOT NULL REFERENCES reclamations(id) ON DELETE CASCADE,
  status_history_id INTEGER REFERENCES reclamation_status_history(id) ON DELETE CASCADE,
  notification_type VARCHAR(50) NOT NULL, -- EMAIL, IN_APP, WEBHOOK
  recipient_user_id INTEGER REFERENCES users(id),
  recipient_email VARCHAR(255),
  webhook_url VARCHAR(500),
  subject VARCHAR(255),
  message TEXT,
  tf_cfe_context JSONB, -- Type-specific notification context
  billing_context JSONB, -- Billing and financial context
  site_client_context JSONB, -- Site and Client information
  status VARCHAR(30) DEFAULT 'PENDING', -- PENDING, SENT, FAILED, DELIVERED
  sent_at TIMESTAMP,
  delivered_at TIMESTAMP,
  error_message TEXT,
  retry_count INTEGER DEFAULT 0,
  created_at TIMESTAMP DEFAULT NOW()
);

-- Status workflow audit (immutable)
CREATE TABLE reclamation_status_audit (
  id SERIAL PRIMARY KEY,
  reclamation_id INTEGER NOT NULL,
  status_history_id INTEGER,
  event_type VARCHAR(50) NOT NULL, -- STATUS_CHANGE, VALIDATION, BILLING_TRIGGER, RULE_EVALUATION
  event_data JSONB NOT NULL,
  user_context JSONB,
  system_context JSONB,
  reclamation_context JSONB, -- Reclamation state snapshot
  financial_context JSONB, -- Financial and billing context
  relationship_context JSONB, -- Site/Client/Facture relationships
  ip_address INET,
  user_agent TEXT,
  session_id VARCHAR(100),
  timestamp TIMESTAMP DEFAULT NOW(),
  audit_hash VARCHAR(64), -- For integrity verification
  regulatory_context JSONB -- For compliance and regulatory reporting
);

-- Indexes for performance and reporting
CREATE INDEX idx_reclamation_status_history_reclamation_id ON reclamation_status_history(reclamation_id);
CREATE INDEX idx_reclamation_status_history_changed_at ON reclamation_status_history(changed_at DESC);
CREATE INDEX idx_reclamation_status_history_status ON reclamation_status_history(new_status);
CREATE INDEX idx_reclamation_status_history_type_status ON reclamation_status_history(new_status) 
  WHERE system_triggered = false; -- For manual status changes
CREATE INDEX idx_reclamation_workflow_rules_type_from_to ON reclamation_status_workflow_rules(reclamation_type, from_status, to_status);
CREATE INDEX idx_reclamation_notifications_status ON reclamation_status_notifications(status);
CREATE INDEX idx_reclamation_notifications_recipient ON reclamation_status_notifications(recipient_user_id);
CREATE INDEX idx_reclamation_audit_reclamation_id ON reclamation_status_audit(reclamation_id);
CREATE INDEX idx_reclamation_audit_timestamp ON reclamation_status_audit(timestamp DESC);
CREATE INDEX idx_reclamation_audit_event_type ON reclamation_status_audit(event_type);
CREATE INDEX idx_reclamation_audit_regulatory ON reclamation_status_audit USING GIN(regulatory_context);

Enhanced API Endpoints (Additive + Backward Compatible)

// Enhanced status management (maintains existing PATCH /reclamations/:id)
PATCH /reclamations/:id - Enhanced with workflow validation, history, and notifications (backward compatible)
GET /reclamations/:id/status/history - Get status change history with audit trail
GET /reclamations/:id/status/transitions - Get available status transitions based on TF/CFE type
POST /reclamations/:id/status/validate-transition - Validate status change before applying
POST /reclamations/:id/status/progress - Auto-progress status based on business rules

// TF/CFE specific workflow endpoints
GET /reclamations/tf/workflow-status - Get TF-specific workflow statistics and metrics
GET /reclamations/cfe/workflow-status - Get CFE-specific workflow statistics and metrics
POST /reclamations/:id/tf/validate-degrevement - Validate TF degrevement data for status progression
POST /reclamations/:id/cfe/validate-incidence - Validate CFE incidence calculations for status progression

// Status workflow management
GET /reclamations/status/workflow-rules - Get status transition rules by type (TF/CFE)
POST /reclamations/status/workflow-rules - Create/update workflow rules with TF/CFE specialization
GET /reclamations/status/statistics - Enhanced statistics with TF/CFE breakdown and transition metrics
GET /reclamations/status/audit - Get status workflow audit trail with regulatory compliance format

// Billing integration endpoints
POST /reclamations/:id/status/trigger-billing - Manually trigger billing creation from FACTURATION status
GET /reclamations/billing-ready - Get reclamations ready for billing based on status workflow
POST /reclamations/bulk-progress-to-billing - Bulk progress eligible reclamations to FACTURATION

// Site/Client integration endpoints
GET /reclamations/site/:siteId/status-summary - Enhanced site-based status summary with workflow metrics
GET /reclamations/client/:clientId/status-workflow - Get client's reclamation workflow status
POST /reclamations/validate-site-compatibility - Validate site compatibility for status transitions

// Notification management
GET /reclamations/:id/status/notifications - Get status change notifications
POST /reclamations/:id/status/notifications/resend - Resend failed notifications
PATCH /reclamations/notifications/preferences - Update notification preferences

// Monitoring and reporting
GET /reclamations/status/metrics - Status workflow performance metrics with TF/CFE breakdown
GET /reclamations/status/compliance-report - Generate compliance audit report for tax authorities
GET /reclamations/status/workflow-health - System health for status workflows
GET /reclamations/status/processing-times - Processing time metrics by status and type

Service Extensions

// Enhanced ReclamationService with preserved existing methods
class ReclamationService {
  // ... existing methods preserved exactly as they are ...
  
  // Enhanced status workflow methods
  async updateStatusWithWorkflow(
    id: number, 
    status: ReclamationStatus, 
    options?: StatusWorkflowOptions
  ): Promise<Reclamation> {
    // Enhanced status update with workflow validation
    return this.executeStatusWorkflow(id, status, options);
  }

  async validateStatusTransition(
    reclamationId: number, 
    fromStatus: ReclamationStatus, 
    toStatus: ReclamationStatus,
    reclamationType: ReclamationType
  ): Promise<StatusTransitionValidation>
  
  async getStatusHistory(reclamationId: number): Promise<ReclamationStatusHistory[]>
  async getAvailableTransitions(reclamationId: number): Promise<StatusTransition[]>
  async autoProgressStatus(reclamationId: number): Promise<ReclamationStatusResult>
  
  // TF/CFE specific validation methods
  async validateTfDegrevement(
    reclamationId: number, 
    degrementData: any
  ): Promise<TfValidationResult>
  
  async validateCfeIncidence(
    reclamationId: number, 
    incidenceData: any
  ): Promise<CfeValidationResult>
  
  // Billing integration methods
  async progressToBilling(reclamationId: number): Promise<BillingProgressResult>
  async getBillingReadyReclamations(): Promise<Reclamation[]>
  async triggerBillingCreation(reclamationId: number): Promise<FactureCreationResult>
  
  // Site/Client integration methods
  async validateSiteCompatibility(
    reclamationId: number, 
    targetStatus: ReclamationStatus
  ): Promise<SiteCompatibilityResult>
  
  async getClientReclamationWorkflow(clientId: number): Promise<ClientWorkflowSummary>
  
  // Notification methods
  async sendStatusChangeNotification(statusHistoryId: number): Promise<void>
  async getStatusNotifications(reclamationId: number): Promise<StatusNotification[]>
  async resendFailedNotifications(reclamationId: number): Promise<NotificationResult>
  
  // Audit and compliance methods
  async getStatusAuditTrail(
    reclamationId: number, 
    options?: AuditOptions
  ): Promise<ReclamationStatusAudit[]>
  
  async generateComplianceReport(
    criteria: ComplianceCriteria
  ): Promise<ComplianceReport>
  
  async getWorkflowMetrics(
    type?: ReclamationType
  ): Promise<WorkflowMetrics>
  
  async validateWorkflowIntegrity(): Promise<WorkflowHealthReport>
}

// Status workflow configuration interface
interface StatusWorkflowConfig {
  tfWorkflow: {
    transitionRules: Record<ReclamationStatus, StatusTransitionRule[]>;
    degrementValidation: DegrementValidationConfig;
    cadastreRequirements: CadastreValidationConfig;
    billingTriggers: BillingTriggerConfig;
  };
  
  cfeWorkflow: {
    transitionRules: Record<ReclamationStatus, StatusTransitionRule[]>;
    incidenceValidation: IncidenceValidationConfig;
    businessActivityRequirements: BusinessActivityValidationConfig;
    billingTriggers: BillingTriggerConfig;
  };
  
  commonWorkflow: {
    auditRequirements: AuditConfig;
    notificationSettings: NotificationConfig;
    performanceThresholds: PerformanceConfig;
    complianceSettings: ComplianceConfig;
  };
}

Test Automation Requirements

Unit Tests - Status Workflow Validation

describe('ReclamationStatusWorkflowService', () => {
  // Status transition validation tests
  describe('Status Transition Validation', () => {
    it('should validate TF-specific status transitions (NOUVELLE → EN_ATTENTE → ACCEPTEE)')
    it('should validate CFE-specific status transitions (NOUVELLE → ACCEPTEE_PARTIELLEMENT)')
    it('should reject invalid transitions for both TF and CFE types')
    it('should validate montantAttendu requirements before financial status changes')
    it('should check degrevement data completeness for TF transitions to ACCEPTEE')
    it('should validate incidenceCfe data for CFE transitions to FACTURATION')
    it('should enforce site status compatibility during transitions')
    it('should validate client relationship integrity')
    it('should handle emergency override with proper authorization')
    it('should prevent transitions from terminal statuses (REFUSEE, ARCHIVEE) without justification')
  })

  // TF/CFE specialization tests
  describe('TF/CFE Workflow Specialization', () => {
    it('should apply TF-specific business rules and validations')
    it('should apply CFE-specific business rules and validations')
    it('should validate degrevement structure according to reclamation type')
    it('should handle interetMoratoire calculations differently for TF vs CFE')
    it('should enforce type-specific document requirements')
    it('should validate cadastre requirements for TF reclamations')
    it('should validate business activity data for CFE reclamations')
    it('should support different billing patterns for TF (annual) vs CFE (quarterly)')
  })

  // Status history tracking tests
  describe('Status History & Audit Trail', () => {
    it('should create comprehensive status history entry on every status change')
    it('should record TF/CFE-specific validation results')
    it('should track degrevement data changes with before/after comparisons')
    it('should log billing impact calculations and financial context')
    it('should record site/client relationship context')
    it('should maintain audit integrity with cryptographic hash verification')
    it('should handle concurrent status changes safely with transaction isolation')
    it('should preserve regulatory compliance data for audit reports')
  })

  // Automated status progression tests
  describe('Automated Status Progression', () => {
    it('should auto-progress ACCEPTEE to FACTURATION when billing criteria met')
    it('should handle TF-specific auto-progression with degrevement validation')
    it('should handle CFE-specific auto-progression with incidence validation')
    it('should auto-transition to EN_ATTENTE when documents required')
    it('should progress to ARCHIVEE when billing complete')
    it('should respect business rules during automated progressions')
  })

  // Billing integration tests
  describe('Billing System Integration', () => {
    it('should trigger Facture creation when reaching FACTURATION status')
    it('should validate FacturePartenaire relationships during billing')
    it('should calculate billing amounts based on degrevement data')
    it('should handle TF vs CFE billing pattern differences')
    it('should maintain billing transaction integrity during status changes')
  })

  // Backward compatibility tests
  describe('Backward Compatibility', () => {
    it('should preserve existing update() method signature and behavior')
    it('should maintain existing API response format for status updates')
    it('should keep existing ReclamationStatus enum behavior')
    it('should preserve getReclamationStats() calculation methods')
    it('should maintain findBySiteId() query patterns and performance')
    it('should preserve JSON field handling for degrevement data')
  })
})

Integration Tests - TF/CFE Workflow Systems

describe('Reclamation Status Workflow Integration', () => {
  // Full TF workflow integration
  describe('TF Complete Workflow Integration', () => {
    it('should handle complete TF reclamation lifecycle with proper status transitions')
    it('should integrate cadastre validation with TF status changes')
    it('should validate degrevement calculations throughout TF workflow')
    it('should maintain Site-Client-Cadastre relationship integrity during TF processing')
    it('should trigger appropriate TF billing when reaching FACTURATION status')
    it('should handle TF-specific document validation and progression')
  })

  // Full CFE workflow integration
  describe('CFE Complete Workflow Integration', () => {
    it('should handle complete CFE reclamation lifecycle with business validations')
    it('should integrate business activity verification with CFE status changes')
    it('should validate incidenceCfe calculations throughout CFE workflow')
    it('should support CFE partial acceptance workflow (ACCEPTEE_PARTIELLEMENT)')
    it('should trigger appropriate CFE billing with business impact calculations')
    it('should handle CFE quarterly assessment patterns')
  })

  // Cross-system integration
  describe('Cross-System Integration', () => {
    it('should maintain transaction integrity during complex multi-system workflows')
    it('should handle approval workflows with multiple stakeholders')
    it('should preserve Site-Client-ApporteurAffaire relationship integrity')
    it('should integrate with FacturePartenaire commission calculations')
    it('should synchronize with billing system state changes')
    it('should handle notification delivery across multiple channels')
  })

  // Performance and concurrency
  describe('Workflow Performance & Concurrency', () => {
    it('should handle concurrent status changes without data conflicts')
    it('should maintain performance with large audit trail datasets')
    it('should efficiently process bulk status updates for both TF and CFE')
    it('should handle notification queue processing under high load')
    it('should optimize complex Prisma queries with proper indexing')
    it('should maintain response times during peak processing periods')
  })

  // API integration and compatibility
  describe('API Integration & Compatibility', () => {
    it('should maintain existing API contracts and response formats')
    it('should provide enhanced functionality through new workflow endpoints')
    it('should handle error scenarios gracefully with proper error messages')
    it('should maintain proper HTTP status codes and error formatting')
    it('should preserve existing query patterns and filtering capabilities')
    it('should support backward-compatible status update operations')
  })
})

End-to-End Tests - Business Workflows

describe('Reclamation Status Workflow E2E', () => {
  // Complete business workflow scenarios
  describe('Complete Business Workflows', () => {
    it('should process TF reclamation from NOUVELLE through FACTURATION to ARCHIVEE')
    it('should process CFE reclamation with partial acceptance and billing reconciliation')
    it('should handle complex TF case with EN_ATTENTE for additional documentation')
    it('should process CFE reclamation with DEMANDE_COMPLEMENTAIRE and client follow-up')
    it('should handle reclamation rejection and reactivation workflow')
    it('should process bulk reclamations with mixed TF/CFE types efficiently')
  })

  // Regulatory compliance scenarios
  describe('Regulatory Compliance Scenarios', () => {
    it('should maintain complete audit trail for tax authority inspection')
    it('should generate compliance reports with all required regulatory data')
    it('should handle data retention and archiving according to legal requirements')
    it('should support audit export in standard regulatory formats')
    it('should maintain data integrity and non-repudiation for compliance')
  })

  // Error handling and recovery
  describe('Error Handling & Recovery', () => {
    it('should recover gracefully from billing system failures during FACTURATION')
    it('should handle site/client data inconsistencies without workflow corruption')
    it('should manage notification delivery failures with proper retry mechanisms')
    it('should maintain workflow integrity during database connection issues')
    it('should provide clear error messages for business rule violations')
  })

  // Performance validation
  describe('Performance Validation', () => {
    it('should process 1000+ reclamation status changes within performance thresholds')
    it('should maintain sub-second response times for status transition validations')
    it('should handle large audit trail queries efficiently')
    it('should process notification queues without significant delays')
    it('should maintain acceptable performance during peak processing periods')
  })
})

Monitoring & Compliance Test Requirements

describe('Workflow Monitoring & Compliance', () => {
  // Workflow performance monitoring
  describe('Performance Monitoring', () => {
    it('should track average processing times for TF vs CFE workflows')
    it('should monitor status transition success rates and failure patterns')
    it('should measure billing integration performance and accuracy')
    it('should track notification delivery success rates across channels')
    it('should monitor audit trail generation and storage performance')
  })

  // Compliance validation
  describe('Compliance Validation', () => {
    it('should validate audit trail completeness and integrity')
    it('should ensure regulatory data retention compliance')
    it('should verify non-repudiation capabilities for status changes')
    it('should validate export formats for tax authority reporting')
    it('should check data anonymization capabilities for compliance')
  })

  // System health monitoring
  describe('System Health Monitoring', () => {
    it('should monitor workflow rule evaluation performance')
    it('should track database query performance and optimization')
    it('should monitor notification system health and queue depths')
    it('should validate backup and recovery procedures for workflow data')
    it('should ensure high availability during critical processing periods')
  })
})

Definition of Done

Risk Mitigation

Primary Risk: Breaking existing Site/Client/Facture relationships and billing workflows Mitigation: All enhancements are additive, existing service methods preserved, comprehensive relationship testing, and billing integration validation

Secondary Risk: Performance degradation with complex audit trail queries Mitigation: Proper database indexing strategy, query optimization, and performance monitoring implementation

Tertiary Risk: TF/CFE workflow specialization causing confusion or errors Mitigation: Clear type-specific validation rules, comprehensive test coverage, and detailed business rule documentation

Rollback Plan: Database migrations are reversible, new workflow endpoints can be disabled via feature flags, existing CRUD functionality remains isolated and unaffected

Evolution Tracking

This story enhances the reclamation processing system while maintaining full backward compatibility. Key evolution points:

Status Workflow Enhancement: Transforms basic status tracking into comprehensive workflow automation
TF/CFE Specialization: Adds type-specific processing rules while maintaining unified API
Audit Trail Integration: Introduces comprehensive tracking without impacting existing operations
Billing System Integration: Enhances existing billing relationships with automated workflow triggers
Performance Optimization: Adds monitoring and optimization capabilities for sustained system performance

The implementation preserves all existing functionality while providing a foundation for advanced reclamation processing capabilities, regulatory compliance, and operational efficiency improvements.

Story Overview​

User Story​

Context & Integration​

Acceptance Criteria​

AC1: Status Transition Validation & TF/CFE Business Rules​

AC2: Enhanced Status History Tracking & Audit Trail​

AC3: Automated Status Progression & Business Logic​

AC4: Site/Client/Billing Integration & Relationship Validation​

AC5: TF vs CFE Workflow Specialization​

AC6: Evolution Tracking & Comprehensive Audit​

AC7: Backward Compatibility & System Integration​

Technical Requirements​

Database Schema Changes (Additive Only)​

Enhanced API Endpoints (Additive + Backward Compatible)​

Service Extensions​

Test Automation Requirements​

Unit Tests - Status Workflow Validation​

Integration Tests - TF/CFE Workflow Systems​

End-to-End Tests - Business Workflows​

Monitoring & Compliance Test Requirements​

Definition of Done​

Risk Mitigation​

Evolution Tracking​