# Report Management

This library provides comprehensive report management functionality for the ACoreX Platform, featuring a powerful Report Runner that enables users to discover, configure, and execute reports through an intuitive interface.

## 🎯 **Core Features**

### **Report Runner System**

- **Hierarchical Category Navigation**: Tree-based browsing through organized report categories
- **Dynamic Parameter Configuration**: Auto-generated forms based on report parameter definitions
- **Real-time Search**: Search across reports and categories with instant results
- **Responsive Layout**: Adaptive UI for desktop and mobile devices
- **State Management**: Persistent navigation and form state using NgRx Signals

### **Current Capabilities**

- ✅ Report discovery and browsing
- ✅ Category-based organization
- ✅ Dynamic parameter forms with widget support
- ✅ Parameter validation and form management
- ✅ Responsive navigation with breadcrumbs
- ✅ Search and filtering functionality
- ✅ Integration with platform layout system

## 📚 **Architecture**

### **Core Components**

```typescript
// Main Report Runner Components
AXPReportRunnerRootViewModel; // State management with NgRx Signals
AXMReportRunnerRootPageComponent; // Main navigation and layout
AXPReportRunnerParametersView; // Dynamic parameter form builder

// Data Providers
AXMReportDefinitionProvider; // Report definition data access
AXMReportCategoryProvider; // Category hierarchy management
```

### **Widget Integration**

The system leverages the platform's widget catalog for parameter inputs:

```typescript
// Supported Parameter Widgets
- TextBox, NumberBox, DateTimeBox
- SelectBox (single/multi-select)
- ToggleSwitch, CheckBox
- DocumentAttachment
- LargeTextBox for descriptions
- Lookup widgets for entity references
```

## 🚀 **Planned Enhancements**

### **Phase 1: Core Functionality Completion**

#### **🔥 High Priority (Essential)**

**1. Report Results Management**

```typescript
// Missing critical functionality
- Report viewer/preview component
- Export options (PDF, Excel, CSV, JSON)
- Print functionality with formatting options
- Email/share report results
- Save generated reports for later access
```

**2. Report History & Favorites**

```typescript
// User experience improvements
- Recently run reports with quick access
- Favorite/bookmark frequently used reports
- Quick re-run with previously saved parameters
- Personal report library and organization
- Usage statistics and recommendations
```

**3. Enhanced Export System**

```typescript
// Professional output options
- Multi-format export (PDF, Excel, CSV, Word)
- Custom report templates and styling
- Batch export capabilities
- Automated delivery options
- Watermarking and branding
```

### **Phase 2: Advanced Features**

#### **📊 Scheduled Reports & Automation**

**4. Report Scheduling**

```typescript
// Automated report generation
- Cron-based scheduling (daily, weekly, monthly, custom)
- Email delivery automation with distribution lists
- Parameter preset management for scheduled runs
- Schedule conflict resolution and queue management
- Notification system for failed/successful runs
```

**5. Report Templates & Presets**

```typescript
// Parameter management and reusability
- Save parameter combinations as named templates
- Share parameter presets across teams
- Default parameter values per user/role/department
- Template versioning and change tracking
- Import/export template configurations
```

#### **🎨 Dashboard Integration**

**6. Dashboard & Visualization**

```typescript
// Interactive reporting experience
- Convert reports to dashboard widgets
- Embed reports in custom dashboards
- Real-time data refresh capabilities
- Interactive charts and visualizations
- Drill-down functionality from summaries
```

### **Phase 3: Enterprise Features**

#### **🔐 Security & Governance**

**7. Advanced Access Control**

```typescript
// Enterprise security features
- Role-based report access with fine-grained permissions
- Parameter-level security and data masking
- Row-level security integration
- Audit trail for all report activities
- Compliance reporting and data governance
```

**8. Report Analytics & Insights**

```typescript
// Usage and performance analytics
- Report execution statistics and performance metrics
- User behavior analytics and usage patterns
- Popular reports ranking and recommendations
- Resource usage monitoring and optimization
- Cost analysis for report generation
```

#### **🤝 Collaboration & Workflow**

**9. Team Collaboration**

```typescript
// Collaborative reporting features
- Share reports with specific users/groups/roles
- Comments and annotations on reports
- Report approval workflows and review processes
- Team workspaces with shared report collections
- Notification system for shared reports
```

**10. Report Builder/Designer**

```typescript
// Self-service report creation
- Visual drag-and-drop report designer
- Template gallery with industry-specific templates
- Data source configuration and mapping
- Preview mode with sample data
- Version control for custom reports
```

### **Phase 4: Integration & Advanced Analytics**

#### **🔌 External Integration**

**11. API & Integration Platform**

```typescript
// Programmatic access and integration
- REST API for external applications
- Webhook notifications for report events
- Integration with external data sources
- Third-party tool connectors (Tableau, Power BI)
- Mobile app with offline capabilities
```

**12. Advanced Search & Discovery**

```typescript
// Enhanced content discovery
- AI-powered report recommendations
- Semantic search with natural language queries
- Advanced filtering by metadata, usage, performance
- Tag-based organization and discovery
- Related reports suggestions
```

## 💡 **Implementation Roadmap**

### **Quarter 1: Foundation**

- ✅ Complete Report Results Viewer
- ✅ Implement Export System (PDF, Excel)
- ✅ Add Report History and Favorites

### **Quarter 2: User Experience**

- 🔄 Scheduled Reports and Automation
- 🔄 Parameter Templates and Presets
- 🔄 Advanced Search and Filtering

### **Quarter 3: Enterprise Ready**

- ⏳ Dashboard Integration
- ⏳ Access Control and Security
- ⏳ Report Analytics

### **Quarter 4: Advanced Features**

- ⏳ Collaboration Tools
- ⏳ Report Builder/Designer
- ⏳ External Integrations

## 📦 **Usage**

### **Installation**

```typescript
import { AXMReportManagementModule } from '@acorex/modules/report-management';

@NgModule({
  imports: [AXMReportManagementModule],
})
export class AppModule {}
```

### **Navigation**

```typescript
// Navigate to report runner
this.router.navigate(['reports']);

// Navigate to specific category
this.router.navigate(['reports', 'category-id']);

// Navigate to report with parameters
this.router.navigate(['reports', 'category-id'], {
  queryParams: { report: 'report-id' },
});
```

### **Custom Parameter Groups**

```typescript
// Example: Custom WHS incident parameters
const whsIncidentParameters: AXPReportParameterGroup = {
  name: 'incidentDetails',
  title: 'Incident Details',
  parameters: [
    {
      path: 'incidentType',
      title: 'Incident Type',
      widget: {
        type: AXPWidgetsList.Editors.SelectBox,
        options: {
          dataSource: ['Injury', 'Near Miss', 'Property Damage'],
        },
      },
    },
    // ... more parameters
  ],
};
```

## 🛠️ **API Reference**

### **Public Exports**

```typescript
// Core Module
export { AXMReportManagementModule } from './lib/module';

// ViewModels
export { AXPReportRunnerRootViewModel } from './lib/features/report-runner/report-runner.viewmodel';

// Components
export { AXMReportRunnerRootPageComponent } from './lib/features/report-runner/report-runner-root-page/report-runner-root-page.component';

// Services and Providers
export { AXMReportDefinitionProvider, AXMReportCategoryProvider } from './lib/features/report-runner/reports.provider';

// Types and Interfaces
export * from './lib/types';
```

### **Key Interfaces**

```typescript
// Report Definition Structure
interface AXPReportDefinition {
  id: string;
  title: string;
  description?: string;
  categoryIds: string[];
  parameterGroups: AXPReportParameterGroup[];
}

// Category Structure
interface AXPReportCategory {
  id: string;
  title: string;
  description?: string;
  parentId?: string;
  hasChild: boolean;
  hasReport: boolean;
}

// Parameter Group Configuration
interface AXPReportParameterGroup {
  name: string;
  title: string;
  description?: string;
  parameters: AXPReportParameter[];
}
```

## 🤝 **Contributing**

When contributing to this module:

1. **Follow the established patterns** for parameter groups and widget usage
2. **Add comprehensive tests** for new features
3. **Update documentation** including this README
4. **Consider backward compatibility** when modifying existing APIs
5. **Follow the platform's coding standards** and conventions

## 📋 **Status Legend**

- ✅ **Completed**: Feature is implemented and available
- 🔄 **In Progress**: Currently being developed
- ⏳ **Planned**: Scheduled for future development
- 💡 **Proposed**: Under consideration for future releases

---

> 💡 **Note**: This module is actively developed as part of the ACoreX Platform. For the latest updates and detailed API documentation, please refer to the platform documentation.
