move_detect/server/src/Repository/EventRepository.php

<?php
declare(strict_types=1);
namespace App\Repository;

interface EventRepository
{
    public function insert(array $event): int;
    /** The event_id of a previously-ingested event with this uuid, or null. Backs ingest
     *  idempotency (a re-sent event dedups instead of duplicating). */
    public function idByUuid(string $uuid): ?int;
    public function recent(int $limit, ?string $severity): array;
    /**
     * Keyset (cursor) page over the (occurred_at DESC, event_id DESC) sort key.
     * Pass null/null for the first page; then the (occurred_at, event_id) of the last
     * returned row to fetch strictly older events. Stable under concurrent inserts —
     * new events land at the head and never shift a page window.
     * $site (when non-null) restricts the page to events whose denormalized site matches —
     * the SQL half of the site-scope access control (see App\Security\SiteScope).
     */
    public function page(int $limit, ?string $severity, ?string $beforeTs, ?int $beforeId, ?string $site = null): array;
    public function find(int $id): ?array;
    public function acknowledge(int $id, string $user): bool;
    /**
     * Spatial points for the heatmap: events of this camera since $sinceOccurredAt that carry
     * a spatial point, newest first, capped at $limit. $site (non-null) applies the same
     * site-scope filter as page(). Rows: {x, y, severity, event_type, occurred_at}.
     */
    public function heatmapPoints(string $cameraId, float $sinceOccurredAt, ?string $site, int $limit): array;
    /**
     * Tag an event as a false positive AND acknowledge it (an FP is a handled event —
     * leaving it unacknowledged would keep it alarming). Idempotent on the FP flag:
     * the FIRST tagger is preserved. Returns false only when the event does not exist.
     */
    public function markFalsePositive(int $id, string $user): bool;
    /**
     * FP-rate aggregation for the stats panel: per (camera_id, event_type) totals and
     * false-positive counts since $sinceOccurredAt, only groups with at least one FP.
     * $site applies the same fail-closed scope filter as page().
     * Rows: {camera_id, event_type, total, fp}.
     */
    public function fpStats(float $sinceOccurredAt, ?string $site): array;
    /**
     * Aggregations for the safety operations report, all over the same window + site scope:
     *  - by_type: [{event_type, severity, count, unacked, fp}]
     *  - by_camera: [{camera_id, count, critical_high}] worst-first, top $topCameras
     *  - tta: {acked, avg_s, max_s} for acknowledged critical+high (FP-tagged rows excluded —
     *    a dismissed false alarm is not an emergency response)
     *  - ergo_metrics: raw metrics arrays of ergo_report rows (caller sums)
     */
    public function reportSummary(float $sinceOccurredAt, ?string $site, int $topCameras,
                                  ?float $untilOccurredAt = null): array;
    /**
     * Bare (occurred_at, event_type) pairs of non-ergo events in the window, newest first,
     * capped at $limit — bucketing (weekday×hour patterns, spike baselines) happens in PHP
     * so the SQL stays portable (the sqlite integration harness has no FROM_UNIXTIME).
     */
    public function occurrenceTimes(float $sinceOccurredAt, ?string $site, int $limit): array;
    /** Full mapped event rows in the window, newest first, capped — the label-dataset export. */
    public function exportRows(float $sinceOccurredAt, ?string $site, int $limit): array;
    /** Detections (non-ergo) for one camera in [from, to) — the action before/after counter. */
    public function countForCamera(string $cameraId, float $from, float $to, ?string $site): int;
    /**
     * True if this camera has ever reported an event — the closest thing to "does this camera
     * exist", playing the role DeviceRepository::exists() plays for devices.
     * NOT move_cameras: that table has no registration flow and no repository (see schema.sql),
     * so it is empty in every deployment — checking it would reject every real camera.
     */
    public function cameraExists(string $cameraId): bool;
    /**
     * Delete event rows older than $cutoff, at most $limit per call. Opt-in only
     * (Config::eventRetentionDays defaults to 0 = never) — see that method for why safety
     * incident rows are not expired by default. Returns the number deleted.
     */
    public function purgeOlderThan(float $cutoff, int $limit = 500): int;
    /**
     * The site this camera's events are recorded under (from its most recent event), or null
     * when the camera is unknown OR its device has no site assigned. Pair with cameraExists()
     * to tell those two apart, exactly as DeviceRepository::exists()/siteFor() are paired.
     */
    public function siteForCamera(string $cameraId): ?string;
}