{
  "feature": "report-generation",
  "version": "1.0.0",
  "description": "Scheduled and on-demand report generation with PDF, Excel, and CSV output, background processing, caching, email delivery, and cron scheduling.\n",
  "category": "workflow",
  "tags": [
    "reports",
    "pdf",
    "excel",
    "csv",
    "scheduled-jobs",
    "data-export",
    "background-processing"
  ],
  "actors": [
    {
      "id": "report_requester",
      "name": "Report Requester",
      "type": "human",
      "description": "Requests on-demand reports or configures scheduled reports"
    },
    {
      "id": "report_engine",
      "name": "Report Engine",
      "type": "system",
      "description": "Processes report templates, queries data, and generates output files"
    },
    {
      "id": "scheduler",
      "name": "Scheduler",
      "type": "system",
      "description": "Triggers scheduled report generation based on cron expressions"
    }
  ],
  "fields": [
    {
      "name": "report_id",
      "type": "text",
      "label": "Report ID",
      "required": true,
      "validation": [
        {
          "type": "pattern",
          "value": "^[a-z0-9-]+$",
          "message": "Report ID must be lowercase alphanumeric with hyphens"
        }
      ]
    },
    {
      "name": "name",
      "type": "text",
      "label": "Report Name",
      "required": true,
      "validation": [
        {
          "type": "minLength",
          "value": 1,
          "message": "Report name is required"
        },
        {
          "type": "maxLength",
          "value": 200,
          "message": "Report name must be 200 characters or fewer"
        }
      ]
    },
    {
      "name": "template",
      "type": "text",
      "label": "Report Template",
      "required": true
    },
    {
      "name": "data_source",
      "type": "text",
      "label": "Data Source",
      "required": true
    },
    {
      "name": "parameters",
      "type": "json",
      "label": "Query Parameters",
      "required": false
    },
    {
      "name": "format",
      "type": "select",
      "label": "Output Format",
      "required": true,
      "options": [
        {
          "value": "pdf",
          "label": "PDF"
        },
        {
          "value": "xlsx",
          "label": "Excel (XLSX)"
        },
        {
          "value": "csv",
          "label": "CSV"
        }
      ]
    },
    {
      "name": "schedule",
      "type": "text",
      "label": "Cron Schedule",
      "required": false,
      "validation": [
        {
          "type": "pattern",
          "value": "^[0-9*,/-]+ [0-9*,/-]+ [0-9*,/-]+ [0-9*,/-]+ [0-9*,/-]+$",
          "message": "Schedule must be a valid five-field cron expression"
        }
      ]
    },
    {
      "name": "recipients",
      "type": "json",
      "label": "Email Recipients",
      "required": false
    },
    {
      "name": "status",
      "type": "select",
      "label": "Status",
      "required": true,
      "options": [
        {
          "value": "pending",
          "label": "Pending"
        },
        {
          "value": "processing",
          "label": "Processing"
        },
        {
          "value": "completed",
          "label": "Completed"
        },
        {
          "value": "failed",
          "label": "Failed"
        },
        {
          "value": "cached",
          "label": "Cached"
        }
      ]
    },
    {
      "name": "file_url",
      "type": "url",
      "label": "Generated File URL",
      "required": false
    },
    {
      "name": "file_size_bytes",
      "type": "number",
      "label": "File Size (bytes)",
      "required": false
    },
    {
      "name": "generated_at",
      "type": "datetime",
      "label": "Generated At",
      "required": false
    },
    {
      "name": "expires_at",
      "type": "datetime",
      "label": "Cache Expires At",
      "required": false
    }
  ],
  "rules": {
    "max_file_size": {
      "description": "Generated report files must not exceed 100 MB. If the output exceeds this limit, the report fails with an error and suggests narrowing parameters or splitting into multiple reports.\n"
    },
    "background_processing": {
      "description": "Reports that are estimated to take longer than 5 seconds must be processed in a background job. The requester receives immediate acknowledgment with a report ID for status polling.\n"
    },
    "cache_recent_reports": {
      "description": "Completed reports are cached for 1 hour. Requests with identical template, data source, and parameters within the cache window return the cached file instead of regenerating.\n"
    },
    "parameterized_queries_only": {
      "description": "All data source queries must use parameterized inputs to prevent injection attacks. Raw user input must never be interpolated into query strings.\n"
    },
    "schedule_validation": {
      "description": "Cron schedule expressions must be valid five-field cron format. Minimum allowed interval is 15 minutes to prevent excessive load.\n"
    },
    "recipient_notification": {
      "description": "When recipients are configured, the generated report is emailed as an attachment (under 25 MB) or as a download link (over 25 MB).\n"
    }
  },
  "outcomes": {
    "on_demand_report_generated": {
      "priority": 1,
      "given": [
        "user requests a report with template, data source, and parameters",
        "no cached report exists for the same parameters"
      ],
      "then": [
        {
          "action": "transition_state",
          "field": "status",
          "from": "pending",
          "to": "processing"
        },
        {
          "action": "call_service",
          "target": "report_engine",
          "description": "Execute parameterized query and render report in requested format"
        },
        {
          "action": "transition_state",
          "field": "status",
          "from": "processing",
          "to": "completed"
        },
        {
          "action": "set_field",
          "target": "file_url",
          "description": "Store URL to generated file"
        },
        {
          "action": "set_field",
          "target": "generated_at",
          "description": "Record generation timestamp"
        },
        {
          "action": "set_field",
          "target": "expires_at",
          "description": "Set cache expiry to 1 hour from generation"
        },
        {
          "action": "emit_event",
          "event": "report.generated",
          "payload": [
            "report_id",
            "name",
            "format",
            "file_url",
            "file_size_bytes"
          ]
        }
      ],
      "result": "Report generated in background and download URL provided to requester"
    },
    "cached_report_returned": {
      "priority": 2,
      "given": [
        "user requests a report with template, data source, and parameters",
        "a cached report exists for identical parameters",
        {
          "field": "expires_at",
          "source": "db",
          "operator": "gt",
          "value": "now",
          "description": "Cache has not expired"
        }
      ],
      "then": [
        {
          "action": "set_field",
          "target": "status",
          "value": "cached"
        },
        {
          "action": "emit_event",
          "event": "report.cache_hit",
          "payload": [
            "report_id",
            "generated_at",
            "expires_at"
          ]
        }
      ],
      "result": "Cached report returned immediately without regeneration"
    },
    "scheduled_report_triggered": {
      "priority": 3,
      "given": [
        "cron schedule fires for a configured report",
        {
          "field": "schedule",
          "source": "db",
          "operator": "exists"
        }
      ],
      "then": [
        {
          "action": "call_service",
          "target": "report_engine",
          "description": "Generate report using stored template and parameters"
        },
        {
          "action": "notify",
          "channel": "email",
          "description": "Send report to all configured recipients"
        },
        {
          "action": "emit_event",
          "event": "report.scheduled.completed",
          "payload": [
            "report_id",
            "name",
            "format",
            "recipient_count"
          ]
        }
      ],
      "result": "Scheduled report generated and delivered to all recipients",
      "error": "REPORT_INVALID_SCHEDULE"
    },
    "report_delivered_to_recipients": {
      "priority": 4,
      "given": [
        "report generation completes successfully",
        {
          "field": "recipients",
          "source": "db",
          "operator": "exists"
        }
      ],
      "then": [
        {
          "action": "notify",
          "channel": "email",
          "description": "Email report as attachment or download link based on file size"
        },
        {
          "action": "emit_event",
          "event": "report.delivered",
          "payload": [
            "report_id",
            "recipients",
            "delivery_method"
          ]
        }
      ],
      "result": "Report delivered to all configured recipients via email"
    },
    "report_exceeds_size_limit": {
      "priority": 5,
      "given": [
        "report generation produces output exceeding 100 MB"
      ],
      "then": [
        {
          "action": "transition_state",
          "field": "status",
          "from": "processing",
          "to": "failed"
        },
        {
          "action": "emit_event",
          "event": "report.failed",
          "payload": [
            "report_id",
            "reason",
            "file_size_bytes"
          ]
        }
      ],
      "result": "Report generation fails with size limit exceeded error",
      "error": "REPORT_SIZE_EXCEEDED"
    },
    "report_generation_fails": {
      "priority": 6,
      "given": [
        "report engine encounters an error during generation"
      ],
      "then": [
        {
          "action": "transition_state",
          "field": "status",
          "from": "processing",
          "to": "failed"
        },
        {
          "action": "emit_event",
          "event": "report.failed",
          "payload": [
            "report_id",
            "reason",
            "error_details"
          ]
        }
      ],
      "result": "Report generation fails and requester is notified with error details",
      "error": "REPORT_GENERATION_FAILED"
    }
  },
  "errors": [
    {
      "code": "REPORT_SIZE_EXCEEDED",
      "message": "Generated report exceeds the 100 MB size limit. Narrow parameters or split into multiple reports.",
      "status": 413
    },
    {
      "code": "REPORT_GENERATION_FAILED",
      "message": "An error occurred while generating the report. Check data source and template configuration.",
      "status": 500
    },
    {
      "code": "REPORT_TEMPLATE_NOT_FOUND",
      "message": "The specified report template does not exist.",
      "status": 404
    },
    {
      "code": "REPORT_DATA_SOURCE_ERROR",
      "message": "Failed to connect to or query the specified data source.",
      "status": 500
    },
    {
      "code": "REPORT_INVALID_SCHEDULE",
      "message": "Cron schedule expression is invalid or interval is below the 15-minute minimum.",
      "status": 400
    },
    {
      "code": "REPORT_INVALID_PARAMETERS",
      "message": "One or more query parameters are invalid or missing required values.",
      "status": 400
    }
  ],
  "events": [
    {
      "name": "report.generated",
      "description": "A report was successfully generated",
      "payload": [
        "report_id",
        "name",
        "format",
        "file_url",
        "file_size_bytes"
      ]
    },
    {
      "name": "report.cache_hit",
      "description": "A cached report was returned instead of regenerating",
      "payload": [
        "report_id",
        "generated_at",
        "expires_at"
      ]
    },
    {
      "name": "report.scheduled.completed",
      "description": "A scheduled report was generated and delivered",
      "payload": [
        "report_id",
        "name",
        "format",
        "recipient_count"
      ]
    },
    {
      "name": "report.delivered",
      "description": "A report was delivered to recipients via email",
      "payload": [
        "report_id",
        "recipients",
        "delivery_method"
      ]
    },
    {
      "name": "report.failed",
      "description": "Report generation failed due to an error",
      "payload": [
        "report_id",
        "reason",
        "error_details"
      ]
    }
  ],
  "related": [
    {
      "feature": "automation-rules",
      "type": "optional",
      "reason": "Automation rules can trigger on-demand reports based on record events"
    },
    {
      "feature": "task-management",
      "type": "optional",
      "reason": "Report generation jobs can be tracked as background tasks"
    },
    {
      "feature": "dashboard-analytics",
      "type": "recommended",
      "reason": "Dashboard widgets may offer report export functionality"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_report_generation",
        "description": "Scheduled and on-demand report generation with PDF, Excel, and CSV output, background processing, caching, email delivery, and cron scheduling.\n",
        "success_metrics": [
          {
            "metric": "processing_time",
            "target": "< 5s",
            "measurement": "Time from request to completion"
          },
          {
            "metric": "success_rate",
            "target": ">= 99%",
            "measurement": "Successful operations divided by total attempts"
          }
        ],
        "constraints": [
          {
            "type": "performance",
            "description": "Must not block dependent workflows",
            "negotiable": true
          }
        ]
      }
    ],
    "autonomy": {
      "level": "semi_autonomous",
      "human_checkpoints": [
        "before making irreversible changes"
      ],
      "escalation_triggers": [
        "error_rate > 5"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "on_demand_report_generated",
          "permission": "autonomous"
        },
        {
          "action": "cached_report_returned",
          "permission": "autonomous"
        },
        {
          "action": "scheduled_report_triggered",
          "permission": "autonomous"
        },
        {
          "action": "report_delivered_to_recipients",
          "permission": "autonomous"
        },
        {
          "action": "report_exceeds_size_limit",
          "permission": "autonomous"
        },
        {
          "action": "report_generation_fails",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "reliability",
        "over": "speed",
        "reason": "workflow steps must complete correctly before proceeding"
      }
    ]
  }
}