Report Model¶

interface Report {
  // Identification
  id: string;                    // UUID, primary key
  tenant_id: string;             // UUID, tenant ownership

  // Metadata
  name: string;                  // Report name
  description?: string;          // Report description
  report_type: ReportType;       // Type of report

  // Source
  workbook_id?: string;          // Source workbook
  scenario_ids?: string[];       // Scenarios included
  execution_id?: string;         // Compliance execution

  // Template
  template_id?: string;          // Report template
  template_version?: number;     // Template version used

  // Parameters
  parameters: ReportParameters;  // Report configuration

  // Date Range
  date_range: DateRange;         // Report period
  as_of_date: string;            // Data as-of date

  // Status
  status: ReportStatus;

  // Output
  format: ReportFormat;
  file_url?: string;             // Generated file URL
  file_size_bytes?: number;      // File size
  page_count?: number;           // Number of pages

  // Generation
  generated_at?: string;         // Generation timestamp
  generation_duration_ms?: number;

  // Scheduling
  schedule?: ReportSchedule;
  next_scheduled_run?: string;

  // Sharing
  shared_with?: ReportShare[];
  public_link?: string;          // Public access URL
  public_link_expires_at?: string;

  // Audit
  created_at: string;
  updated_at: string;
  created_by: string;
}

enum ReportType {
  // Compliance Reports
  COMPLIANCE_SUMMARY = "compliance_summary",
  COMPLIANCE_DETAIL = "compliance_detail",
  BREACH_REPORT = "breach_report",
  COVERAGE_ANALYSIS = "coverage_analysis",

  // Scenario Reports
  SCENARIO_COMPARISON = "scenario_comparison",
  TRADE_IMPACT = "trade_impact",
  WHAT_IF_ANALYSIS = "what_if_analysis",

  // Portfolio Reports
  PORTFOLIO_SUMMARY = "portfolio_summary",
  HOLDINGS_DETAIL = "holdings_detail",
  CONCENTRATION_ANALYSIS = "concentration_analysis",

  // Analytics Reports
  TREND_ANALYSIS = "trend_analysis",
  CUSHION_HISTORY = "cushion_history",

  // Custom
  CUSTOM = "custom"
}

enum ReportStatus {
  DRAFT = "draft",               // Being configured
  PENDING = "pending",           // Queued for generation
  GENERATING = "generating",     // Currently generating
  COMPLETED = "completed",       // Successfully generated
  FAILED = "failed",             // Generation failed
  EXPIRED = "expired"            // Report file expired
}

enum ReportFormat {
  PDF = "pdf",                   // PDF document
  EXCEL = "excel",               // Excel workbook
  CSV = "csv",                   // CSV data export
  HTML = "html",                 // HTML report
  JSON = "json"                  // JSON data
}

interface ReportParameters {
  // Content selection
  sections?: ReportSection[];    // Sections to include
  metrics?: string[];            // Metrics to display

  // Data filtering
  filters?: ReportFilter[];      // Data filters

  // Grouping
  group_by?: string[];           // Grouping columns
  sort_by?: SortConfig[];        // Sort configuration

  // Display options
  display_options?: DisplayOptions;

  // Comparison
  compare_to?: CompareConfig;    // Comparison configuration

  // Custom parameters (for templates)
  custom?: Record<string, any>;
}

enum ReportSection {
  // Executive sections
  EXECUTIVE_SUMMARY = "executive_summary",
  KEY_METRICS = "key_metrics",

  // Compliance sections
  COMPLIANCE_OVERVIEW = "compliance_overview",
  TEST_RESULTS = "test_results",
  BREACH_DETAILS = "breach_details",
  CUSHION_ANALYSIS = "cushion_analysis",

  // Portfolio sections
  PORTFOLIO_COMPOSITION = "portfolio_composition",
  TOP_HOLDINGS = "top_holdings",
  CONCENTRATION_BREAKDOWN = "concentration_breakdown",

  // Scenario sections
  SCENARIO_SUMMARY = "scenario_summary",
  CHANGE_DETAILS = "change_details",
  IMPACT_ANALYSIS = "impact_analysis",

  // Analytics sections
  TREND_CHARTS = "trend_charts",
  HISTORICAL_COMPARISON = "historical_comparison",

  // Appendix
  DATA_TABLES = "data_tables",
  METHODOLOGY = "methodology"
}

interface ReportFilter {
  field: string;                 // Field to filter
  operator: FilterOperator;      // Filter operator
  value: any;                    // Filter value
  values?: any[];                // For IN operator
}

enum FilterOperator {
  EQUALS = "eq",
  NOT_EQUALS = "ne",
  GREATER_THAN = "gt",
  GREATER_EQUAL = "gte",
  LESS_THAN = "lt",
  LESS_EQUAL = "lte",
  IN = "in",
  NOT_IN = "not_in",
  CONTAINS = "contains",
  STARTS_WITH = "starts_with",
  BETWEEN = "between",
  IS_NULL = "is_null",
  IS_NOT_NULL = "is_not_null"
}

interface SortConfig {
  field: string;
  direction: "asc" | "desc";
}

interface DisplayOptions {
  // General
  show_header: boolean;
  show_footer: boolean;
  show_page_numbers: boolean;
  show_timestamps: boolean;

  // Tables
  table_style: "compact" | "standard" | "detailed";
  max_rows_per_table?: number;
  show_totals: boolean;
  highlight_breaches: boolean;

  // Charts
  chart_style: "minimal" | "standard" | "detailed";
  color_scheme: "default" | "monochrome" | "custom";

  // Numbers
  decimal_places: number;
  percentage_format: boolean;
  currency_format?: string;

  // Branding
  include_logo: boolean;
  custom_colors?: BrandColors;
}

interface CompareConfig {
  compare_type: "scenario" | "historical" | "baseline";

  // For scenario comparison
  scenario_id?: string;

  // For historical comparison
  historical_date?: string;

  // Display
  show_delta: boolean;
  show_percentage_change: boolean;
  highlight_changes: boolean;
}

interface DateRange {
  type: DateRangeType;

  // For custom range
  start_date?: string;           // ISO 8601 date
  end_date?: string;             // ISO 8601 date

  // For relative range
  relative_period?: number;      // Number of periods
  relative_unit?: TimeUnit;      // Period unit
}

enum DateRangeType {
  CUSTOM = "custom",
  TODAY = "today",
  YESTERDAY = "yesterday",
  THIS_WEEK = "this_week",
  LAST_WEEK = "last_week",
  THIS_MONTH = "this_month",
  LAST_MONTH = "last_month",
  THIS_QUARTER = "this_quarter",
  LAST_QUARTER = "last_quarter",
  THIS_YEAR = "this_year",
  LAST_YEAR = "last_year",
  RELATIVE = "relative"
}

enum TimeUnit {
  DAYS = "days",
  WEEKS = "weeks",
  MONTHS = "months",
  QUARTERS = "quarters",
  YEARS = "years"
}

interface ReportSchedule {
  enabled: boolean;
  frequency: ScheduleFrequency;

  // Timing
  time: string;                  // HH:MM format
  timezone: string;              // IANA timezone

  // For weekly
  day_of_week?: number;          // 0-6 (Sunday-Saturday)

  // For monthly
  day_of_month?: number;         // 1-31

  // Distribution
  auto_distribute: boolean;
  distribution_list: DistributionRecipient[];

  // Retention
  keep_last_n?: number;          // Keep N most recent
  auto_delete_after_days?: number;
}

enum ScheduleFrequency {
  DAILY = "daily",
  WEEKLY = "weekly",
  MONTHLY = "monthly",
  QUARTERLY = "quarterly"
}

interface DistributionRecipient {
  type: "user" | "email" | "group";
  value: string;                 // User ID, email, or group ID
  name?: string;                 // Display name
}

interface ReportShare {
  id: string;
  report_id: string;

  // Recipient
  shared_with_type: "user" | "email" | "public";
  shared_with_value?: string;    // User ID or email

  // Permissions
  can_view: boolean;
  can_download: boolean;
  can_reshare: boolean;

  // Expiry
  expires_at?: string;

  // Tracking
  view_count: number;
  download_count: number;
  last_accessed_at?: string;

  // Audit
  shared_at: string;
  shared_by: string;
}

interface ReportTemplate {
  // Identification
  id: string;
  tenant_id?: string;            // null for system templates

  // Metadata
  name: string;
  description?: string;
  category: ReportType;

  // Template definition
  version: number;
  sections: TemplateSectionConfig[];
  default_parameters: ReportParameters;

  // Styling
  style: TemplateStyle;

  // System vs custom
  is_system: boolean;
  is_default: boolean;

  // Audit
  created_at: string;
  updated_at: string;
}

interface TemplateSectionConfig {
  section: ReportSection;
  enabled: boolean;
  order: number;
  title?: string;                // Custom title
  config?: Record<string, any>;  // Section-specific config
}

interface TemplateStyle {
  // Page setup
  page_size: "A4" | "letter" | "legal";
  orientation: "portrait" | "landscape";
  margins: { top: number; right: number; bottom: number; left: number };

  // Typography
  font_family: string;
  title_font_size: number;
  body_font_size: number;

  // Colors
  primary_color: string;
  secondary_color: string;
  accent_color: string;

  // Header/Footer
  header_height: number;
  footer_height: number;
  header_content?: string;
  footer_content?: string;
}

interface CreateReportRequest {
  name: string;
  description?: string;
  report_type: ReportType;

  // Source
  workbook_id?: string;
  scenario_ids?: string[];
  execution_id?: string;

  // Template
  template_id?: string;

  // Parameters
  parameters?: ReportParameters;

  // Date range
  date_range?: DateRange;
  as_of_date?: string;

  // Output
  format: ReportFormat;

  // Schedule
  schedule?: ReportSchedule;

  // Generate immediately
  generate_now?: boolean;
}

interface GenerateReportRequest {
  // Override parameters
  parameters?: Partial<ReportParameters>;
  date_range?: DateRange;
  as_of_date?: string;
  format?: ReportFormat;

  // Notification
  notify_on_complete?: boolean;
  notification_email?: string;
}

interface ReportResponse {
  id: string;
  name: string;
  description?: string;
  report_type: ReportType;
  status: ReportStatus;
  format: ReportFormat;

  // Source
  workbook_id?: string;
  scenario_ids?: string[];

  // Dates
  as_of_date: string;
  date_range: DateRange;

  // File info
  file_url?: string;
  file_size_bytes?: number;
  page_count?: number;

  // Generation
  generated_at?: string;

  // Schedule
  is_scheduled: boolean;
  next_scheduled_run?: string;

  // Audit
  created_at: string;
  created_by: string;
}

interface ReportDetailResponse extends ReportResponse {
  parameters: ReportParameters;
  template_id?: string;
  template_name?: string;

  schedule?: ReportSchedule;

  shared_with: ReportShare[];
  public_link?: string;
  public_link_expires_at?: string;

  // Generation history
  generation_history: GenerationRecord[];
}

interface GenerationRecord {
  id: string;
  generated_at: string;
  duration_ms: number;
  status: "completed" | "failed";
  error_message?: string;
  file_url?: string;
  file_size_bytes?: number;
  triggered_by: "manual" | "scheduled" | "api";
}

interface ReportListResponse {
  items: ReportResponse[];
  total: number;
  page: number;
  page_size: number;

  // Aggregations
  by_type: Record<ReportType, number>;
  by_status: Record<ReportStatus, number>;
}

interface ShareReportRequest {
  // Recipient
  share_type: "user" | "email";
  share_value: string;           // User ID or email

  // Permissions
  can_download?: boolean;        // Default: true
  can_reshare?: boolean;         // Default: false

  // Expiry
  expires_at?: string;

  // Notification
  send_notification?: boolean;
  custom_message?: string;
}

interface CreatePublicLinkRequest {
  expires_at?: string;           // Optional expiry
  password?: string;             // Optional password protection
  allow_download?: boolean;      // Allow file download
  max_views?: number;            // Maximum view count
}

interface PublicLinkResponse {
  link: string;                  // Full public URL
  expires_at?: string;
  password_protected: boolean;
  allow_download: boolean;
  max_views?: number;
  current_views: number;
}

interface ComplianceReportData {
  // Summary
  summary: ComplianceSummary;

  // Test results
  test_results: TestResultDetail[];

  // Breaches
  active_breaches: BreachDetail[];
  resolved_breaches: BreachDetail[];

  // Cushion analysis
  cushion_analysis: CushionDetail[];

  // Trends
  historical_compliance: ComplianceHistoryPoint[];
}

interface ComplianceSummary {
  overall_status: ComplianceStatus;
  as_of_date: string;

  tests_total: number;
  tests_passed: number;
  tests_failed: number;
  tests_warning: number;

  active_breaches: number;
  critical_breaches: number;

  pass_rate: number;             // Percentage
  average_cushion: number;       // Average cushion %
}

interface CushionDetail {
  test_name: string;
  test_category: string;

  current_value: number;
  threshold: number;
  cushion: number;
  cushion_percentage: number;

  status: CushionStatus;
  trend: "improving" | "stable" | "declining";

  // Historical
  previous_cushion?: number;
  change_from_previous?: number;
}