Report
Data Entity
Description
Stores generated reports for organizations, covering team activity summaries, Bufdir compliance exports, and custom ad-hoc reports built by Org Admins and Coordinators via the Admin Web Portal.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key. Stable identifier for the report record. | PKrequiredunique |
organization_id |
uuid |
FK to organizations. Report is strictly scoped to one tenant; cross-org access is forbidden. | required |
report_type |
enum |
Discriminates between report workflows. team_report = coordinator activity summary; bufdir_report = government grant compliance export; custom_report = ad-hoc user-defined report. | required |
name |
string |
Human-readable report title. Auto-generated for standard reports (e.g. 'Team Report Q1 2025'); user-supplied for custom reports. | required |
description |
text |
Optional free-text description of the report's scope, filters applied, or purpose. | - |
status |
enum |
Lifecycle state of the report. draft = parameters saved but not yet run; generating = async job in progress; completed = results available; failed = generation error. | required |
period_start |
datetime |
Inclusive start of the reporting period. All activity data aggregated from this timestamp. | required |
period_end |
datetime |
Inclusive end of the reporting period. Must be >= period_start. | required |
filters |
json |
Serialized filter parameters applied during generation (e.g. area_ids, role_filter, include_unapproved). Stored for reproducibility and audit. | - |
schema_id |
string |
References a report schema definition in the report-schema-registry. Required for custom_report type; null for standard report types. | - |
row_count |
integer |
Number of data rows included in the completed report. Null until status = completed. Used for empty-report warnings. | - |
error_message |
text |
Error detail when status = failed. Exposed to Org Admin for diagnosis; never shown to end users. | - |
generated_by |
uuid |
FK to users. The Org Admin or Coordinator who triggered report generation. Used for audit trail. | required |
generated_at |
datetime |
Timestamp when generation completed (status transitioned to completed or failed). Null while in draft or generating. | - |
file_path |
string |
Storage path or signed URL to the exported CSV/XLSX file. Populated by report-csv-export-service after generation. Null for reports not yet exported. | - |
created_at |
datetime |
Record creation timestamp. | required |
updated_at |
datetime |
Last modification timestamp. Updated on status transitions and file_path writes. | required |
Database Indexes
idx_reports_organization_id
Columns: organization_id
idx_reports_organization_type
Columns: organization_id, report_type
idx_reports_organization_period
Columns: organization_id, period_start, period_end
idx_reports_status
Columns: status
idx_reports_generated_by
Columns: generated_by
idx_reports_created_at
Columns: created_at
Validation Rules
period_end_after_start
error
Validation failed
valid_organization_reference
error
Validation failed
valid_generated_by_user
error
Validation failed
report_type_enum_constraint
error
Validation failed
name_not_empty
error
Validation failed
schema_id_registered
error
Validation failed
Business Rules
org_scoped_access
A report record is always owned by exactly one organization. No user — including Global Admins without explicit time-bounded support access — may read or write reports belonging to a different organization.
completed_report_immutability
Once status transitions to 'completed', the report's filters, period, schema_id, and row_count fields become immutable. Only file_path may be updated post-completion (to attach an export artifact).
bufdir_report_role_guard
Bufdir report generation and export are restricted to Organization Administrators. Coordinators may access team_report and custom_report types but not bufdir_report.
custom_report_schema_required
A report with report_type = 'custom_report' must reference a valid schema_id from the report-schema-registry. Attempting to generate without a valid schema is rejected.
single_active_generation_per_org_type
An organization may not have more than one report of the same report_type in 'generating' status simultaneously. A second generation request is rejected with a conflict error until the first completes or fails.
empty_report_warning
When generation completes and row_count = 0, the service emits a warning to the requesting user indicating no activity data matched the selected period and filters. The record is still persisted as completed.