Feature/spec implementation alignment

[raguerobermudez]

This pull request aligns the Infobus API with the OpenAPI contract (datahub.yml), focusing on response shape consistency, types, error envelopes, and schema-safe outputs across:

• GTFS Schedule
• GTFS Realtime
• External endpoints (service_alerts, user_reports / user_data, wide_alerts / weather / social)

Summary of Changes

GTFS Schedule

• Adjusted schedule endpoints to match OpenAPI:
  • Pure array responses where required.
  • Consistent limit / offset slicing without DRF pagination envelopes.
  • Filter/query behavior aligned for predictable, schema-safe results.

External Endpoints

• Implemented a minimal viable service_alerts endpoint and updated other external endpoints using a spec-first approach (contract compliance over “invented” data).
• Hardened user_reports:
  • Validation (e.g., evidence maxItems)
  • Minimization/anonymization (best-effort redaction in description)
  • Evidence handling policy (do not publicly persist b64)
  • Configurable retention (filter on GET, best-effort cleanup on POST)
• Standardized social / weather / wide_alerts / user_data behavior:
  • Errors follow {code,message}
  • Outputs are filtered/normalized to satisfy required fields (e.g., valid url + timestamp)
  • Timestamps normalized to timezone-aware values when required

OpenAPI Consistency Guarantees

• Errors are unified to { "code": int, "message": string }.
• Array endpoints return arrays (no DRF pagination envelope); limit/offset preserves payload shape.
• Nullability & enums are enforced:
  • no null where disallowed
  • no enum values outside the allowed set
  • safe defaults (e.g., [] instead of null)

Configuration

• DATAHUB_REALTIME_TTL_SECONDS (default 300)
• DATAHUB_API_KEY (protects write operations)
• DATAHUB_USER_REPORTS_RETENTION_DAYS (default 30)

Note (Untested / Pending Spec Approval)

This change set has not been fully tested or end-to-end verified yet, as final validation is pending spec approval/confirmation and full environment verification.

Tooling Note

Implementation work was guided using GitHub Copilot (GPT-5.2) as an assistive tool during development.