Site Status Automation & Business Rules - Brownfield User Story

Story Overview

Epic: Site & Cadastre Management Enhancement
Story: Story 3 - Site Status Automation & Business Rules
Story Type: Enhancement (Brownfield)
Priority: High
Estimated Effort: 12 story points

User Story

As a site administrator
I want to automate site status transitions based on document completion and business rule validation
So that I can ensure proper site lifecycle progression, maintain compliance with business rules, and have comprehensive audit trails for all status operations while seamlessly integrating with document workflows and cadastre processes

Context & Integration

Current System Integration Points:

• Extends existing SiteService (/Users/ayoub/projects/emtb/apps/api/src/site/site.service.ts) with status automation logic
• Leverages existing SiteStatus enum (NOUVEAU, DEMANDE_DOCUMENTS_CADASTRAUX, DOCUMENTS_CADASTREAUX_RECUS, DOCUMENTS_MANQUANTS, BILAN_AUDIT, SITE_ARCHIVE, RECLAMATION_EN_COURS, RAS)
• Integrates with Site Document Workflow from Story 1 for automated status progression triggers
• Coordinates with Enhanced Cadastre Integration from Story 2 for cadastral status validation
• Maintains compatibility with existing Site-Client-Cadastre-Reclamation-ApporteurAffaire relationships
• Utilizes existing site status field and JSON fields (bilanAudit, typePropriete, documentsReference)

Existing Functionality to Preserve:

• All Site CRUD operations (GET /sites, POST /sites, PATCH /sites/:id, DELETE /sites/:id) with consistent status handling
• Manual site status updates through existing update endpoints
• Site creation with default status NOUVEAU and existing relationship loading patterns
• Site status progression patterns already established in the system
• Integration with reclamation workflow (RECLAMATION_EN_COURS status)
• Performance of existing site queries with proper relationship includes

Acceptance Criteria

AC1: Automated Status Transitions Based on Document Completion

Given a site with document workflow integration from Story 1
When documents are completed or validated
Then the system should:

• Automatically transition from NOUVEAU to DEMANDE_DOCUMENTS_CADASTRAUX when initial client documents are validated
• Progress to DOCUMENTS_CADASTREAUX_RECUS when cadastral documents from Story 2 are received and validated
• Trigger DOCUMENTS_MANQUANTS status when required documents become incomplete or invalid
• Advance to BILAN_AUDIT status when all technical documents are validated and audit can commence
• Support transition to SITE_ARCHIVE when site lifecycle is complete with proper archival workflow
• Handle RECLAMATION_EN_COURS status integration with existing reclamation processes
• Complete to RAS (Rien à Signaler) when all processes are concluded with no outstanding issues

AC2: Business Rule Validation for Status Changes with SiteStatus Enum

Given the existing SiteStatus enum progression rules
When status transitions are requested (automated or manual)
Then the system should:

• Validate allowed status transitions: NOUVEAU → DEMANDE_DOCUMENTS_CADASTRAUX → DOCUMENTS_CADASTREAUX_RECUS → BILAN_AUDIT → RAS/SITE_ARCHIVE
• Block invalid status jumps (e.g., NOUVEAU directly to BILAN_AUDIT without intermediate steps)
• Allow emergency status changes to DOCUMENTS_MANQUANTS from any status when document issues are detected
• Enable RECLAMATION_EN_COURS status from any operational status when reclamation processes begin
• Support bidirectional transitions for correction workflows (e.g., BILAN_AUDIT back to DOCUMENTS_MANQUANTS)
• Validate business prerequisites: document completion, cadastre assignment, client validation, technical review completion
• Implement role-based authorization for manual status overrides
• Log all business rule validations with detailed reasoning for audit purposes

AC3: Site Lifecycle Reporting & Audit Trail Functionality

Given site status automation and business rule operations
When generating lifecycle reports and audit trails
Then the system should:

• Generate comprehensive site lifecycle reports showing status progression timelines with duration at each stage
• Provide status distribution analytics across all sites (count per status, average time per stage)
• Create audit trails for every status transition including automated triggers, business rule validations, and manual overrides
• Track performance metrics: average time from NOUVEAU to DOCUMENTS_CADASTREAUX_RECUS, document completion rates, audit processing times
• Generate compliance reports showing adherence to business rules and status progression standards
• Support filtering and searching of audit trails by date range, user, status transition, business rule type
• Export audit data in multiple formats (CSV, PDF, JSON) for external review and compliance reporting
• Provide site lifecycle dashboards with real-time status distribution and trend analysis

AC4: Integration with Site Document Workflow (Story 1)

Given the Site Document Workflow system from Story 1
When document workflow events occur
Then the status automation should:

• Listen to document completion events to trigger automatic status progressions
• Validate document requirements are met before allowing status transitions
• Update status based on document workflow stages (document upload → validation → completion → status progression)
• Coordinate with document missing alerts to trigger DOCUMENTS_MANQUANTS status
• Support document-driven business rule validation (e.g., specific document types required for BILAN_AUDIT)
• Integrate with document audit trails to provide complete site operation history
• Handle bulk document operations that may affect multiple site statuses simultaneously
• Maintain synchronization between document workflow state and site status progression

AC5: Integration with Enhanced Cadastre Integration (Story 2)

Given the Enhanced Cadastre Integration system from Story 2
When cadastral processes occur
Then the status automation should:

• Trigger status progression to DEMANDE_DOCUMENTS_CADASTRAUX when cadastre is assigned and ready for document requests
• Progress to DOCUMENTS_CADASTREAUX_RECUS when cadastre confirms document receipt and validation
• Integrate with cadastre communication tracking for status validation business rules
• Coordinate with cadastre performance monitoring to identify processing bottlenecks affecting status progression
• Support cadastre-initiated status updates through business rule validation
• Handle cadastre reassignment scenarios with appropriate status transition logic
• Validate cadastre-specific business rules before allowing status changes (e.g., cadastre capacity, regional requirements)
• Maintain audit trails that include cadastre-related status transition reasons

AC6: Business Rule Engine & Configuration Management

Given complex business rules for status transitions
When managing status automation rules
Then the system should:

• Implement configurable business rule engine for status transition validation
• Support rule templates for different site types, client categories, and regional requirements
• Enable business rule versioning with change tracking and rollback capabilities
• Provide rule testing and validation tools before deployment
• Support conditional business rules based on site properties (typePropriete JSON field), client type, cadastre region
• Implement rule priority and conflict resolution mechanisms
• Enable business rule audit trails showing which rules triggered status changes
• Support business rule performance monitoring and optimization
• Provide rule management interface for authorized administrators
• Enable business rule templates for common scenarios (standard property, complex property, reclamation cases)

AC7: Status Automation Performance Monitoring & Business Rule Compliance

Given automated status transitions and business rule enforcement
When monitoring system performance
Then it should track:

• Status automation performance metrics: transition processing time, rule evaluation efficiency, bulk operation performance
• Business rule compliance rates: successful validations vs. blocked transitions, rule violation patterns
• Status progression bottlenecks: stages with longest durations, common blocking issues, document/cadastre dependencies
• Automation effectiveness: percentage of automatic vs. manual status changes, error rates, rollback frequency
• System performance impact: response time impact on existing site operations, database performance under automation load
• User experience metrics: time saved through automation, reduction in manual status management tasks
• Integration performance: document workflow coordination efficiency, cadastre integration response times
• Audit trail system performance: storage efficiency, query performance for compliance reporting

AC8: Evolution Tracking & Comprehensive Audit Trail for Status Operations

Given all site status automation operations
When performing any status-related activity
Then the system should:

• Maintain detailed audit logs for all status transitions (automated and manual) with full context
• Track business rule evaluations including rule versions, input parameters, validation results
• Record integration events from document workflow and cadastre systems affecting status
• Audit configuration changes to business rules, automation settings, and status transition rules
• Track user interactions with status automation including overrides, manual interventions, and administrative actions
• Maintain performance audit data for system optimization and business rule effectiveness analysis
• Store audit data in optimized separate tables for efficient querying and reporting
• Provide comprehensive audit search and filtering with advanced query capabilities
• Support audit data retention policies for compliance requirements
• Generate audit summary reports for management review and regulatory compliance

AC9: Backward Compatibility & System Integration Preservation

Given existing site functionality and status management
When implementing status automation
Then it should:

• Preserve all existing site API endpoints with unchanged response formats for status field
• Maintain manual status update capabilities through existing PATCH /sites/:id endpoint
• Keep existing site creation workflow with NOUVEAU default status intact
• Preserve site status validation in existing update operations
• Maintain performance of existing site queries (findAll, findOne, findByClientId) with status filtering
• Support existing site-reclamation integration with RECLAMATION_EN_COURS status handling
• Keep site JSON fields (bilanAudit, typePropriete) integration with status business rules
• Preserve existing client-site, cadastre-site relationship handling during status transitions

Technical Requirements

Database Schema Changes (Additive Only)

-- Site status automation configuration
CREATE TABLE site_status_automation_rules (
  id SERIAL PRIMARY KEY,
  rule_name VARCHAR(200) NOT NULL,
  rule_version VARCHAR(20) NOT NULL DEFAULT '1.0',
  from_status VARCHAR(50) NOT NULL, -- Maps to SiteStatus enum
  to_status VARCHAR(50) NOT NULL,
  trigger_type VARCHAR(50) NOT NULL, -- DOCUMENT_COMPLETION, CADASTRE_EVENT, MANUAL, SCHEDULED, RECLAMATION_EVENT
  trigger_conditions JSONB NOT NULL, -- Conditions that must be met for rule to apply
  business_rules JSONB NOT NULL, -- Business logic for validation
  is_automatic BOOLEAN DEFAULT TRUE, -- Whether this rule can trigger automatic transitions
  requires_manual_approval BOOLEAN DEFAULT FALSE,
  priority INTEGER DEFAULT 100, -- Rule priority for conflict resolution
  is_active BOOLEAN DEFAULT TRUE,
  created_by INTEGER REFERENCES users(id),
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW(),
  valid_from TIMESTAMP DEFAULT NOW(),
  valid_until TIMESTAMP,
  rule_metadata JSONB -- Additional rule configuration
);

-- Site status transition history
CREATE TABLE site_status_transitions (
  id SERIAL PRIMARY KEY,
  site_id INTEGER NOT NULL REFERENCES sites(id) ON DELETE CASCADE,
  from_status VARCHAR(50) NOT NULL, -- Previous SiteStatus
  to_status VARCHAR(50) NOT NULL, -- New SiteStatus
  transition_type VARCHAR(30) NOT NULL, -- AUTOMATIC, MANUAL, RULE_BASED, DOCUMENT_TRIGGERED, CADASTRE_TRIGGERED
  rule_id INTEGER REFERENCES site_status_automation_rules(id),
  triggered_by VARCHAR(50), -- DOCUMENT_COMPLETION, CADASTRE_EVENT, USER_ACTION, BUSINESS_RULE
  trigger_data JSONB, -- Specific trigger information (document IDs, cadastre events, etc.)
  business_rule_validations JSONB, -- Results of business rule checks
  performed_by INTEGER REFERENCES users(id), -- User who triggered transition (NULL for automatic)
  performed_at TIMESTAMP DEFAULT NOW(),
  validation_results JSONB, -- Detailed validation results
  rollback_data JSONB, -- Data needed for potential rollback
  notes TEXT, -- Manual notes for transition
  processing_duration_ms INTEGER, -- Time taken to process transition
  integration_events JSONB, -- Related document/cadastre events
  audit_metadata JSONB -- Additional audit information
);

-- Site status business rule violations
CREATE TABLE site_status_rule_violations (
  id SERIAL PRIMARY KEY,
  site_id INTEGER NOT NULL REFERENCES sites(id) ON DELETE CASCADE,
  rule_id INTEGER REFERENCES site_status_automation_rules(id),
  attempted_from_status VARCHAR(50) NOT NULL,
  attempted_to_status VARCHAR(50) NOT NULL,
  violation_type VARCHAR(50) NOT NULL, -- INVALID_TRANSITION, MISSING_PREREQUISITES, BUSINESS_RULE_FAILED
  violation_details JSONB NOT NULL, -- Detailed violation information
  attempted_by INTEGER REFERENCES users(id),
  attempted_at TIMESTAMP DEFAULT NOW(),
  resolution_status VARCHAR(30) DEFAULT 'OPEN', -- OPEN, RESOLVED, ACKNOWLEDGED
  resolution_notes TEXT,
  resolved_by INTEGER REFERENCES users(id),
  resolved_at TIMESTAMP
);

-- Site status automation metrics
CREATE TABLE site_status_automation_metrics (
  id SERIAL PRIMARY KEY,
  site_id INTEGER NOT NULL REFERENCES sites(id) ON DELETE CASCADE,
  current_status VARCHAR(50) NOT NULL,
  total_transitions INTEGER DEFAULT 0,
  automatic_transitions INTEGER DEFAULT 0,
  manual_transitions INTEGER DEFAULT 0,
  rule_violations INTEGER DEFAULT 0,
  average_stage_duration_hours DECIMAL(10,2), -- Average time in current status
  total_lifecycle_duration_hours DECIMAL(10,2), -- Total time from NOUVEAU to current
  document_completion_rate DECIMAL(5,2), -- Percentage of required documents completed
  cadastre_processing_efficiency DECIMAL(5,2), -- Cadastre-related efficiency score
  business_rule_compliance_rate DECIMAL(5,2), -- Compliance with business rules
  last_transition_date TIMESTAMP,
  next_expected_transition_date TIMESTAMP,
  bottleneck_indicators JSONB, -- Identified process bottlenecks
  performance_score DECIMAL(5,2), -- Overall site processing performance
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW(),
  UNIQUE(site_id)
);

-- Site status workflow configurations
CREATE TABLE site_status_workflow_config (
  id SERIAL PRIMARY KEY,
  workflow_name VARCHAR(200) NOT NULL,
  workflow_version VARCHAR(20) NOT NULL DEFAULT '1.0',
  site_type VARCHAR(100), -- Optional filter by site type from typePropriete
  client_type VARCHAR(100), -- Optional filter by client category
  region VARCHAR(100), -- Optional regional configuration
  status_progression JSONB NOT NULL, -- Defined status flow for this workflow
  automation_settings JSONB NOT NULL, -- Automation preferences and thresholds
  business_rule_overrides JSONB, -- Workflow-specific business rule modifications
  notification_settings JSONB, -- Workflow-specific notification configuration
  performance_targets JSONB, -- Expected processing times per status
  is_default BOOLEAN DEFAULT FALSE,
  is_active BOOLEAN DEFAULT TRUE,
  created_by INTEGER REFERENCES users(id),
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- Performance optimization indexes
CREATE INDEX idx_site_status_transitions_site_id ON site_status_transitions(site_id);
CREATE INDEX idx_site_status_transitions_performed_at ON site_status_transitions(performed_at);
CREATE INDEX idx_site_status_transitions_from_status ON site_status_transitions(from_status);
CREATE INDEX idx_site_status_transitions_to_status ON site_status_transitions(to_status);
CREATE INDEX idx_site_status_transitions_trigger_type ON site_status_transitions(transition_type);
CREATE INDEX idx_site_status_automation_rules_from_to ON site_status_automation_rules(from_status, to_status);
CREATE INDEX idx_site_status_automation_rules_active ON site_status_automation_rules(is_active) WHERE is_active = true;
CREATE INDEX idx_site_status_rule_violations_site_id ON site_status_rule_violations(site_id);
CREATE INDEX idx_site_status_rule_violations_resolution ON site_status_rule_violations(resolution_status);
CREATE INDEX idx_site_status_automation_metrics_site_id ON site_status_automation_metrics(site_id);
CREATE INDEX idx_site_status_automation_metrics_current_status ON site_status_automation_metrics(current_status);
CREATE INDEX idx_site_status_workflow_config_active ON site_status_workflow_config(is_active) WHERE is_active = true;

Enhanced Service Layer Architecture

// Enhanced SiteService with status automation
class SiteService {
  // ... existing methods preserved ...
  
  // Status automation core methods
  async evaluateStatusTransition(
    siteId: number, 
    targetStatus: SiteStatus, 
    triggeredBy: string,
    triggerData?: any,
    userId?: number
  ): Promise<{ canTransition: boolean, violations: string[], applicableRules: any[] }>
  
  async executeAutomaticStatusTransition(
    siteId: number, 
    triggerType: string,
    triggerData: any,
    userId?: number
  ): Promise<Site>
  
  async validateBusinessRules(
    siteId: number,
    fromStatus: SiteStatus,
    toStatus: SiteStatus,
    context: any
  ): Promise<{ valid: boolean, violations: string[], passedRules: any[] }>
  
  // Integration with Story 1 (Document Workflow)
  async onDocumentCompleted(siteId: number, documentData: any, userId: number): Promise<void>
  async onDocumentValidated(siteId: number, documentData: any, userId: number): Promise<void>
  async onDocumentMissing(siteId: number, missingDocuments: string[], userId: number): Promise<void>
  
  // Integration with Story 2 (Cadastre Integration)
  async onCadastreAssigned(siteId: number, cadastreData: any, userId: number): Promise<void>
  async onCadastreDocumentsReceived(siteId: number, cadastreData: any, userId: number): Promise<void>
  async onCadastralProcessingComplete(siteId: number, cadastreData: any, userId: number): Promise<void>
  
  // Status workflow management
  async getSiteStatusWorkflow(siteId: number): Promise<StatusWorkflow>
  async getAvailableStatusTransitions(siteId: number): Promise<{ automatic: SiteStatus[], manual: SiteStatus[] }>
  async forceStatusTransition(siteId: number, targetStatus: SiteStatus, reason: string, userId: number): Promise<Site>
  async rollbackStatusTransition(transitionId: number, userId: number): Promise<Site>
  
  // Business rule management
  async createStatusAutomationRule(ruleData: CreateStatusRuleDto, userId: number): Promise<StatusAutomationRule>
  async updateStatusAutomationRule(ruleId: number, updates: UpdateStatusRuleDto, userId: number): Promise<StatusAutomationRule>
  async getActiveStatusRules(fromStatus?: SiteStatus, toStatus?: SiteStatus): Promise<StatusAutomationRule[]>
  async testStatusRule(ruleId: number, testData: any): Promise<RuleTestResult>
  
  // Lifecycle reporting and analytics
  async getSiteLifecycleReport(siteId: number): Promise<LifecycleReport>
  async getStatusDistributionAnalytics(filters?: AnalyticsFilters): Promise<StatusAnalytics>
  async getStatusTransitionMetrics(dateRange: DateRange): Promise<TransitionMetrics>
  async getBusinessRuleComplianceReport(dateRange: DateRange): Promise<ComplianceReport>
  
  // Performance monitoring
  async getStatusAutomationPerformance(): Promise<AutomationPerformance>
  async getStatusProcessingBottlenecks(): Promise<ProcessingBottleneck[]>
  async optimizeStatusWorkflowPerformance(siteId?: number): Promise<void>
  
  // Enhanced existing methods with status automation integration
  async updateWithStatusValidation(id: number, updateSiteDto: UpdateSiteDto, userId: number): Promise<Site>
  async createWithWorkflowSetup(createSiteDto: CreateSiteDto, userId: number): Promise<Site>
  
  // Bulk operations with status automation
  async bulkStatusTransition(siteIds: number[], targetStatus: SiteStatus, userId: number): Promise<BulkOperationResult>
  async bulkStatusValidation(siteIds: number[]): Promise<BulkValidationResult>
  async bulkWorkflowOptimization(siteIds: number[]): Promise<void>
}

// Status automation rule engine
class SiteStatusRuleEngine {
  async evaluateRule(rule: StatusAutomationRule, site: Site, context: any): Promise<RuleEvaluationResult>
  async findApplicableRules(fromStatus: SiteStatus, toStatus: SiteStatus, site: Site): Promise<StatusAutomationRule[]>
  async validateRuleConflicts(rules: StatusAutomationRule[]): Promise<RuleConflict[]>
  async executeRuleChain(site: Site, triggerData: any): Promise<RuleExecutionResult>
}

New API Endpoints (Additive)

// Status automation management endpoints
POST /sites/:id/status/evaluate-transition - Evaluate if status transition is allowed
PUT /sites/:id/status/auto-transition - Execute automatic status transition
POST /sites/:id/status/force-transition - Force manual status transition with override
PUT /sites/:id/status/rollback/:transitionId - Rollback a status transition

// Business rule management
GET /sites/status-rules - Get all status automation rules
POST /sites/status-rules - Create new status automation rule
GET /sites/status-rules/:id - Get specific rule details
PUT /sites/status-rules/:id - Update status automation rule
DELETE /sites/status-rules/:id - Deactivate status automation rule
POST /sites/status-rules/:id/test - Test status rule with sample data

// Status workflow endpoints
GET /sites/:id/workflow - Get site's current workflow status and progress
GET /sites/:id/available-transitions - Get available status transitions for site
GET /sites/:id/transition-history - Get complete status transition history
POST /sites/:id/workflow/optimize - Optimize workflow for better performance

// Lifecycle reporting and analytics
GET /sites/:id/lifecycle-report - Generate comprehensive lifecycle report
GET /sites/analytics/status-distribution - Get system-wide status distribution
GET /sites/analytics/transition-metrics - Get status transition performance metrics
GET /sites/analytics/business-rule-compliance - Get business rule compliance analytics
GET /sites/analytics/workflow-performance - Get workflow performance analytics
GET /sites/analytics/processing-bottlenecks - Get identified processing bottlenecks

// Integration event endpoints (for Stories 1 & 2)
POST /sites/:id/events/document-completed - Trigger from document workflow
POST /sites/:id/events/document-validated - Document validation event
POST /sites/:id/events/document-missing - Document missing event
POST /sites/:id/events/cadastre-assigned - Cadastre assignment event
POST /sites/:id/events/cadastre-documents-received - Cadastre documents received
POST /sites/:id/events/cadastral-processing-complete - Cadastre processing complete

// Bulk status operations
POST /sites/bulk/status-transition - Bulk status transitions with validation
POST /sites/bulk/status-validation - Validate status transitions for multiple sites
POST /sites/bulk/workflow-optimization - Bulk workflow optimization
GET /sites/bulk/operation-status/:operationId - Get bulk operation status

// Audit and compliance
GET /sites/:id/audit/status-transitions - Get detailed status transition audit
GET /sites/:id/audit/business-rules - Get business rule validation audit
GET /sites/audit/violations - Get system-wide rule violations
POST /sites/audit/compliance-report - Generate comprehensive compliance report
GET /sites/audit/performance-metrics - Get audit system performance metrics

// Workflow configuration
GET /sites/workflow-configs - Get available workflow configurations
POST /sites/workflow-configs - Create new workflow configuration
GET /sites/workflow-configs/:id - Get workflow configuration details
PUT /sites/workflow-configs/:id - Update workflow configuration
GET /sites/:id/workflow-config - Get site's assigned workflow configuration
PUT /sites/:id/assign-workflow/:configId - Assign workflow configuration to site

Test Automation Requirements

Unit Tests for Status Automation

describe('SiteStatusAutomationService', () => {
  // Core status automation functionality
  describe('Status Transition Logic', () => {
    it('should validate allowed SiteStatus enum transitions (NOUVEAU → DEMANDE_DOCUMENTS_CADASTRAUX)')
    it('should block invalid status transitions (NOUVEAU → BILAN_AUDIT directly)')
    it('should allow emergency transitions to DOCUMENTS_MANQUANTS from any status')
    it('should handle RECLAMATION_EN_COURS status from operational statuses')
    it('should support bidirectional transitions for corrections (BILAN_AUDIT → DOCUMENTS_MANQUANTS)')
    it('should validate business rule prerequisites before transitions')
    it('should execute automatic transitions based on trigger events')
    it('should create audit trail entries for all status changes')
  })
  
  // Business rule validation
  describe('Business Rule Engine', () => {
    it('should evaluate business rules correctly for status transitions')
    it('should handle rule priorities and conflict resolution')
    it('should support conditional rules based on site properties (typePropriete)')
    it('should validate role-based authorization for manual overrides')
    it('should track business rule compliance rates')
    it('should handle rule versioning and rollback scenarios')
    it('should optimize rule evaluation performance')
  })
  
  // Integration with Stories 1 & 2
  describe('Document Workflow Integration (Story 1)', () => {
    it('should trigger status transitions on document completion events')
    it('should validate document requirements before status progression')
    it('should handle document validation triggering DOCUMENTS_MANQUANTS')
    it('should coordinate with document workflow audit trails')
    it('should process bulk document events affecting multiple site statuses')
  })
  
  describe('Cadastre Integration (Story 2)', () => {
    it('should progress to DEMANDE_DOCUMENTS_CADASTRAUX on cadastre assignment')
    it('should transition to DOCUMENTS_CADASTREAUX_RECUS on cadastral confirmation')
    it('should integrate with cadastre communication tracking')
    it('should handle cadastre reassignment scenarios')
    it('should validate cadastre-specific business rules')
    it('should coordinate with cadastre performance monitoring')
  })
  
  // Performance and monitoring
  describe('Performance Monitoring', () => {
    it('should track status automation performance metrics')
    it('should identify processing bottlenecks in status transitions')
    it('should monitor business rule compliance rates')
    it('should measure automation effectiveness vs manual operations')
    it('should track integration performance with document and cadastre workflows')
    it('should optimize status transition processing times')
  })
})

Integration Tests for Status Automation

describe('Site Status Automation Integration', () => {
  // Complete workflow integration
  describe('End-to-End Status Workflows', () => {
    it('should complete full lifecycle: NOUVEAU → DEMANDE_DOCUMENTS_CADASTRAUX → DOCUMENTS_CADASTREAUX_RECUS → BILAN_AUDIT → RAS')
    it('should handle complex workflow with DOCUMENTS_MANQUANTS interruptions')
    it('should manage RECLAMATION_EN_COURS integration with existing reclamation processes')
    it('should support SITE_ARCHIVE workflow with proper archival procedures')
    it('should coordinate document workflow and cadastre integration simultaneously')
    it('should handle concurrent status transitions safely')
    it('should maintain data integrity during bulk status operations')
  })
  
  // Business rule validation integration
  describe('Business Rule Integration', () => {
    it('should enforce business rules across integrated workflows')
    it('should handle rule conflicts between document and cadastre requirements')
    it('should validate cross-system business rules (document + cadastre + status)')
    it('should maintain rule consistency during system integrations')
    it('should track rule violations across integrated systems')
  })
  
  // System integration preservation
  describe('Backward Compatibility Integration', () => {
    it('should preserve existing site CRUD operations with status automation')
    it('should maintain site-client relationships during automated status changes')
    it('should keep cadastre-site relationships intact during status progression')
    it('should preserve reclamation-site associations with RECLAMATION_EN_COURS status')
    it('should maintain apporteur-site relationships during automated workflows')
    it('should preserve performance of existing site queries with status automation')
  })
  
  // Audit trail integration
  describe('Comprehensive Audit Trail Integration', () => {
    it('should create complete audit trails across document, cadastre, and status operations')
    it('should maintain audit data integrity during integrated workflows')
    it('should support complex audit queries across multiple integrated systems')
    it('should generate comprehensive compliance reports')
    it('should track performance metrics across integrated systems')
  })
})

End-to-End Test Scenarios for Status Automation

describe('Site Status Automation E2E Tests', () => {
  // Complete lifecycle scenarios
  describe('Complete Site Lifecycle Automation', () => {
    it('should automate site from creation to completion: NOUVEAU → RAS with document and cadastre integration')
    it('should handle complex site with multiple document types and cadastre interactions')
    it('should manage interrupted workflow with DOCUMENTS_MANQUANTS and recovery')
    it('should process site with reclamation: normal flow → RECLAMATION_EN_COURS → resolution → continue')
    it('should archive completed site: workflow completion → SITE_ARCHIVE with audit preservation')
  })
  
  // Business rule enforcement scenarios
  describe('Business Rule Enforcement E2E', () => {
    it('should enforce document completion rules before DEMANDE_DOCUMENTS_CADASTRAUX transition')
    it('should validate cadastre assignment requirements for cadastral document progression')
    it('should block invalid manual status changes that violate business rules')
    it('should allow authorized overrides with proper audit trail')
    it('should handle rule conflicts and resolution through priority system')
  })
  
  // Integration coordination scenarios
  describe('Multi-System Integration E2E', () => {
    it('should coordinate document upload → validation → cadastre notification → status progression')
    it('should handle cadastre assignment → document requirements sync → status automation')
    it('should manage concurrent document and cadastre events affecting same site')
    it('should support bulk operations across document, cadastre, and status systems')
    it('should maintain system consistency during partial failures and recovery')
  })
  
  // Performance and monitoring scenarios
  describe('Performance Monitoring E2E', () => {
    it('should track performance metrics throughout complete site lifecycle')
    it('should identify and report processing bottlenecks in real-time')
    it('should optimize workflow performance based on historical data')
    it('should maintain system performance under high automation load')
    it('should generate accurate performance reports across integrated systems')
  })
})

Automated Test Scenarios for Business Rule Compliance

describe('Automated Business Rule Compliance Testing', () => {
  // Status progression compliance
  describe('Status Progression Compliance', () => {
    it('should validate compliance with SiteStatus enum progression rules')
    it('should test all valid transition paths automatically')
    it('should verify blocked transitions generate proper violation records')
    it('should validate emergency transition allowances (DOCUMENTS_MANQUANTS)')
    it('should test bidirectional transition compliance')
    it('should verify role-based authorization compliance')
  })
  
  // Document integration compliance
  describe('Document Integration Compliance', () => {
    it('should verify document completion requirements for each status transition')
    it('should validate document-driven status automation compliance')
    it('should test document missing detection and DOCUMENTS_MANQUANTS triggering')
    it('should verify document audit integration compliance')
  })
  
  // Cadastre integration compliance
  describe('Cadastre Integration Compliance', () => {
    it('should validate cadastre assignment requirements for status progression')
    it('should test cadastral document processing compliance')
    it('should verify cadastre communication integration compliance')
    it('should validate cadastre performance impact on status transitions')
  })
  
  // Audit trail compliance
  describe('Audit Trail Compliance', () => {
    it('should verify complete audit trail generation for all status operations')
    it('should validate audit data integrity and completeness')
    it('should test audit trail search and reporting functionality')
    it('should verify compliance report accuracy and completeness')
    it('should validate audit data retention and archival compliance')
  })
})

Performance Tests for Status Automation

describe('Status Automation Performance Tests', () => {
  // Core performance tests
  describe('Status Transition Performance', () => {
    it('should maintain <200ms response time for single status transitions')
    it('should handle bulk status transitions within performance thresholds')
    it('should optimize business rule evaluation performance')
    it('should maintain database performance during high automation load')
    it('should preserve existing site query performance with automation extensions')
  })
  
  // Integration performance
  describe('Integration Performance', () => {
    it('should maintain performance during document workflow integration events')
    it('should optimize cadastre integration event processing')
    it('should handle concurrent integration events efficiently')
    it('should maintain audit trail write performance during high activity')
  })
  
  // System scalability
  describe('System Scalability', () => {
    it('should scale status automation with increasing site volumes')
    it('should maintain performance with growing audit trail data')
    it('should handle increasing business rule complexity efficiently')
    it('should optimize memory usage during bulk automation operations')
  })
})

Regression Tests for Backward Compatibility

describe('Status Automation Backward Compatibility', () => {
  // Existing API compatibility
  describe('API Compatibility', () => {
    it('should preserve existing site CRUD API response formats')
    it('should maintain existing site creation workflow (NOUVEAU default status)')
    it('should preserve manual status update functionality through PATCH /sites/:id')
    it('should maintain existing site query performance and response format')
    it('should preserve site status filtering and sorting functionality')
  })
  
  // Relationship preservation
  describe('Relationship Preservation', () => {
    it('should maintain site-client relationships during status automation')
    it('should preserve site-cadastre relationships with automated status changes')
    it('should keep site-reclamation relationships intact with RECLAMATION_EN_COURS handling')
    it('should maintain site-apporteur relationships during workflow automation')
    it('should preserve site JSON fields integration (bilanAudit, typePropriete)')
  })
  
  // Existing functionality preservation
  describe('Existing Functionality Preservation', () => {
    it('should preserve existing site reference generation and unique constraints')
    it('should maintain existing site client-based queries (findByClientId)')
    it('should keep existing site include patterns for relationships')
    it('should preserve existing site deletion and archival functionality')
    it('should maintain existing site statistics and reporting compatibility')
  })
})

Change Tracking & Evolution

Version History & Configuration Management

// Status automation configuration management
interface SiteStatusAutomationConfig {
  version: string; // Configuration version
  automationEnabled: boolean;
  defaultWorkflowId: string;
  businessRuleEngine: {
    enabled: boolean;
    strictMode: boolean; // Block all invalid transitions
    allowEmergencyOverrides: boolean;
    ruleEvaluationTimeout: number; // milliseconds
  };
  integrationSettings: {
    documentWorkflowIntegration: boolean; // Story 1 integration
    cadastreIntegrationEnabled: boolean; // Story 2 integration
    auditTrailIntegration: boolean;
    performanceMonitoringEnabled: boolean;
  };
  performanceThresholds: {
    maxTransitionTimeMs: number;
    maxRuleEvaluationTimeMs: number;
    maxAuditWriteTimeMs: number;
    bulkOperationBatchSize: number;
  };
  monitoringSettings: {
    enablePerformanceTracking: boolean;
    enableBottleneckDetection: boolean;
    enableComplianceMonitoring: boolean;
    metricsRetentionDays: number;
  };
  auditSettings: {
    auditAllTransitions: boolean;
    auditBusinessRules: boolean;
    auditPerformanceMetrics: boolean;
    retentionPolicyDays: number;
  };
}

// Evolution tracking metrics
interface StatusAutomationEvolutionMetrics {
  automationAdoptionRate: number; // Percentage of automatic vs manual transitions
  businessRuleEffectiveness: number; // Success rate of business rule enforcement
  integrationHealth: {
    documentWorkflowSync: number; // Health score of Story 1 integration
    cadastreIntegrationSync: number; // Health score of Story 2 integration
    auditTrailIntegrity: number; // Audit system health
  };
  performanceEvolution: {
    averageTransitionTime: number; // Trend over time
    ruleEvaluationEfficiency: number;
    systemThroughput: number; // Transitions per minute
  };
  systemMaturity: {
    workflowOptimization: number; // How well-optimized workflows are
    ruleComplexityGrowth: number; // Growth in business rule sophistication
    integrationStability: number; // Stability of integrated systems
  };
}

Monitoring & Operational Metrics

// Comprehensive monitoring dashboard metrics
interface SiteStatusAutomationMonitoring {
  // Real-time status metrics
  realTimeMetrics: {
    activeTransitions: number;
    pendingRuleEvaluations: number;
    currentSystemLoad: number;
    averageResponseTime: number;
  };
  
  // Automation effectiveness
  automationEffectiveness: {
    automatedTransitionsPerHour: number;
    manualInterventionRate: number;
    errorRate: number;
    rollbackRate: number;
  };
  
  // Business rule performance
  businessRuleMetrics: {
    rulesEvaluated: number;
    ruleSuccessRate: number;
    averageRuleEvaluationTime: number;
    mostTriggeredRules: Array<{ ruleId: string; count: number }>;
  };
  
  // Integration health
  integrationHealth: {
    documentWorkflowEvents: number; // Events from Story 1
    cadastreIntegrationEvents: number; // Events from Story 2
    integrationSuccessRate: number;
    integrationLatency: number;
  };
  
  // System performance impact
  performanceImpact: {
    existingApiResponseTime: number; // Impact on existing endpoints
    databasePerformanceImpact: number;
    memoryUsageIncrease: number;
    auditTrailWritePerformance: number;
  };
  
  // Lifecycle analytics
  lifecycleAnalytics: {
    averageTimeToCompletion: number; // NOUVEAU to final status
    bottleneckStages: Array<{ status: SiteStatus; averageDuration: number }>;
    completionRateByStage: Record<SiteStatus, number>;
    workflowEfficiencyScore: number;
  };
}

// Alert and notification configuration
interface StatusAutomationAlerts {
  performanceAlerts: {
    slowTransitionThreshold: number; // milliseconds
    highErrorRateThreshold: number; // percentage
    systemOverloadThreshold: number; // concurrent operations
  };
  businessRuleAlerts: {
    highViolationRateThreshold: number;
    ruleConflictDetection: boolean;
    complianceDropThreshold: number;
  };
  integrationAlerts: {
    documentWorkflowDisconnection: boolean;
    cadastreIntegrationFailure: boolean;
    auditTrailCorruption: boolean;
  };
  operationalAlerts: {
    bulkOperationFailures: boolean;
    unusualStatusDistribution: boolean;
    workflowBottleneckDetection: boolean;
  };
}

Definition of Done

Functional Requirements Completion

• Status Automation Core: Automated transitions operational for all SiteStatus enum values with proper business rule validation
• Business Rule Engine: Configurable rule engine deployed with version management and conflict resolution
• Document Workflow Integration: Seamless coordination with Story 1 document completion events triggering status transitions
• Cadastre Integration: Complete coordination with Story 2 cadastral processes affecting status progression
• Lifecycle Reporting: Comprehensive site lifecycle reports with status progression analytics implemented
• Audit Trail System: Complete audit trails for all status operations with search and reporting capabilities

Technical Requirements Completion

• Database Schema: All status automation tables deployed with proper indexing and performance optimization
• API Endpoints: New status automation endpoints documented in Swagger with proper authentication and authorization
• Service Layer: Enhanced SiteService with status automation methods maintaining backward compatibility
• Business Rule Engine: Rule evaluation system deployed with performance optimization and monitoring
• Integration Architecture: Event-driven integration with document workflow and cadastre systems operational
• Performance Optimization: Response time targets met for status transitions and business rule evaluation

Quality Assurance Completion

• Unit Test Coverage: ≥ 95% test coverage for status automation functionality including business rule engine
• Integration Tests: Complete integration test suite validating coordination with Stories 1 & 2
• End-to-End Tests: Full lifecycle automation testing from NOUVEAU to final status with all integrations
• Performance Tests: Status automation performance validated with no regression in existing site operations
• Security Testing: Business rule security, audit trail protection, and role-based authorization validated
• Regression Testing: Complete backward compatibility verification with existing site functionality

Business Rule & Compliance Completion

• Rule Configuration: Default business rules configured for all valid SiteStatus transitions
• Compliance Monitoring: Business rule compliance tracking and violation reporting operational
• Audit Compliance: Complete audit trail system meeting regulatory compliance requirements
• Workflow Optimization: Status workflow performance optimization based on business rule analysis
• Role-Based Authorization: Proper user role validation for manual overrides and rule management

Integration & Compatibility Completion

• Story 1 Integration: Document workflow events properly triggering status automation with audit trails
• Story 2 Integration: Cadastre events coordinating with status transitions and business rule validation
• Backward Compatibility: All existing site API endpoints maintaining response format and performance
• Relationship Preservation: Site-Client-Cadastre-Reclamation-ApporteurAffaire relationships intact during automation
• JSON Fields Integration: Existing site JSON fields (bilanAudit, typePropriete, documentsReference) working with business rules

Monitoring & Analytics Completion

• Performance Monitoring: Real-time monitoring dashboard for status automation performance operational
• Business Rule Analytics: Business rule effectiveness and compliance analytics implemented
• Lifecycle Analytics: Site lifecycle progression analytics with bottleneck identification
• Integration Health Monitoring: Health monitoring for document workflow and cadastre integration connections
• Alert System: Automated alerting for performance issues, rule violations, and integration failures

Documentation & Training Completion

• API Documentation: Complete Swagger documentation for all new status automation endpoints
• Technical Documentation: System architecture documentation including business rule engine and integration patterns
• Business Rule Documentation: Documentation for configuring and managing status automation rules
• Operations Manual: Operational procedures for monitoring, troubleshooting, and maintaining status automation
• Integration Guide: Complete guide for coordinating with document workflow (Story 1) and cadastre integration (Story 2)
• User Training: Training materials for administrators managing status automation and business rules

Risk Mitigation & Rollback Strategy

Primary Risks & Mitigations

1. Status Automation Complexity Risk

   • Risk: Complex business rule interactions causing unexpected status transitions
   • Mitigation: Comprehensive rule testing framework, rule conflict detection, staged deployment with gradual automation enablement
   • Monitoring: Real-time rule evaluation monitoring, violation tracking, rollback capabilities

2. Integration Coordination Risk

   • Risk: Status automation conflicts with document workflow (Story 1) and cadastre integration (Story 2)
   • Mitigation: Event-driven integration architecture, integration health monitoring, circuit breakers for failing integrations
   • Monitoring: Integration success rate tracking, latency monitoring, automated failover mechanisms

3. Performance Impact Risk

   • Risk: Status automation causing performance degradation in existing site operations
   • Mitigation: Performance benchmarking, query optimization, separate processing for automation operations
   • Monitoring: Response time monitoring, database performance tracking, load testing validation

4. Business Rule Governance Risk

   • Risk: Business rules becoming too complex or conflicting, affecting operational efficiency
   • Mitigation: Rule versioning system, approval workflow for rule changes, rule impact analysis
   • Monitoring: Rule effectiveness metrics, compliance rate tracking, rule usage analytics

5. Data Integrity Risk During Automation

   • Risk: Automated status transitions causing data inconsistency across integrated systems
   • Mitigation: Transaction management, data validation at each transition, audit trail verification
   • Monitoring: Data consistency checks, audit trail validation, integrity monitoring

Comprehensive Rollback Strategy

// Rollback capabilities at multiple levels
interface RollbackStrategy {
  // Immediate rollback options
  immediate: {
    disableAutomation: () => void; // Switch to manual-only status management
    rollbackTransition: (transitionId: number) => Promise<void>; // Rollback specific transition
    disableRule: (ruleId: number) => Promise<void>; // Disable problematic business rule
    fallbackToManual: (siteId: number) => Promise<void>; // Remove site from automation
  };
  
  // System-level rollback
  systemLevel: {
    disableIntegrations: () => Promise<void>; // Disconnect from Stories 1 & 2
    revertToBasicStatus: () => Promise<void>; // Use only basic status functionality
    rollbackDatabaseChanges: (migrationVersion: string) => Promise<void>; // Database rollback
    restoreBackup: (backupTimestamp: Date) => Promise<void>; // Full system restore
  };
  
  // Gradual rollback
  gradual: {
    reduceAutomationScope: (percentage: number) => Promise<void>; // Reduce automation gradually
    disableComplexRules: () => Promise<void>; // Keep simple rules, disable complex ones
    isolateProblematicSites: (siteIds: number[]) => Promise<void>; // Remove specific sites from automation
  };
  
  // Recovery procedures
  recovery: {
    dataIntegrityRestore: () => Promise<void>; // Restore data consistency
    auditTrailReconciliation: () => Promise<void>; // Reconcile audit data
    performanceBaslineRestore: () => Promise<void>; // Restore original performance
    integrationReconnection: () => Promise<void>; // Reconnect with Stories 1 & 2
  };
}

Emergency Procedures

1. Critical Issue Response

   • Immediate automation disabling via feature flags
   • Automatic fallback to manual status management
   • Real-time alerting to technical team
   • Rollback decision tree based on issue severity

2. Data Recovery Procedures

   • Automated backup verification before major operations
   • Point-in-time recovery capabilities for status data
   • Audit trail reconstruction from backup systems
   • Cross-system data consistency validation and repair

3. Integration Failure Handling

   • Automatic circuit breakers for failed integrations with Stories 1 & 2
   • Queue-based event processing with retry mechanisms
   • Graceful degradation to independent status management
   • Integration health restoration procedures

Dependencies

Internal Dependencies

• Site Module Foundation: Existing SiteService architecture and database schema maintained and extended
• Document Workflow Integration (Story 1): Event-driven integration for document completion triggering status transitions
• Cadastre Integration (Story 2): Coordination with cadastral processes affecting status progression
• User Authentication System: Role-based authorization for status automation rules and manual overrides
• Audit System Infrastructure: Comprehensive audit logging for compliance and monitoring requirements

External Dependencies

• Event Processing Infrastructure: Message queue or event bus for coordinating integrated systems
• Rule Engine Framework: Business rule evaluation engine with performance optimization capabilities
• Monitoring Infrastructure: Real-time monitoring system for automation performance and health tracking
• Reporting System: Analytics and reporting platform for lifecycle reporting and compliance dashboards
• Backup and Recovery System: Automated backup system for rollback capabilities and disaster recovery

Integration Coordination Requirements

• Story 1 Coordination: Document workflow completion events must trigger status automation evaluation
• Story 2 Coordination: Cadastre assignment and document processing events must integrate with status transitions
• Cross-Story Audit Integration: Unified audit trail across document workflow, cadastre integration, and status automation
• Performance Coordination: Ensure combined system performance meets requirements across all three stories
• Configuration Management: Coordinated configuration management across integrated systems

---

Story Status: Ready for Implementation
Last Updated: 2025-09-09
Reviewed By: Technical Lead & Integration Architect
Approved By: Product Owner & Compliance Officer
Integration Dependencies: Stories 1 & 2 must be completed or in parallel development with coordination protocols
Priority Notes: Critical for complete site lifecycle automation and business rule compliance