move_detect/server/src/Ingest/EventValidator.php

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

final class EventValidator
{
    /**
     * Accepted wire codes. MUST stay in sync with three other places, and the sync is not
     * enforced by anything but review — RouteTableTest cross-checks routes, but nothing
     * cross-checks this list:
     *   - edge/events.py            EventType (what the edge can emit)
     *   - server/schema.sql         chk_events_type (defense-in-depth CHECK)
     *   - the front-end TYPE_LABELS maps (app.js / detail.js / report.js / compliance.js /
     *     package.js) and the 유형 filter in View/events.php
     *
     * A type missing HERE is the worst of the four: the edge emits it, the server answers 400,
     * and edge/queue.py retries the row 20 times before dropping it — so the detector looks
     * implemented, is fully tested on the device, and produces nothing. That is exactly what
     * happened to camera_moved/camera_obstructed/low_light when they were added.
     */
    private const TYPES = ['fall','no_motion','immobility','ghost','zone_warning',
        'zone_restricted','pinch','monitoring_degraded','device_fault',
        'lone_worker','overcapacity','overstay','near_fall','ergo_report',
        // 감시 자체의 건전성 (edge/detectors/integrity.py)
        'camera_moved','camera_obstructed','low_light',
        // 서버가 발행하지만(EscalationWatch, 검증기를 거치지 않음) 유형 집합은 한 곳에 모은다.
        'unacked_escalation',
        // 모델 확보 후 활성화 (edge/detectors/pending.py) — 지금은 엣지가 발화하지 않는다.
        'ppe_missing','proximity','fire_smoke'];
    private const SEVERITIES = ['critical','high','warning','info'];
    private const REQUIRED = ['device_id','camera_id','event_type','severity','occurred_at'];

    public static function validate(array $p): array
    {
        $errors = [];
        foreach (self::REQUIRED as $k) {
            if (!array_key_exists($k, $p) || $p[$k] === '' || $p[$k] === null) $errors[] = "missing:$k";
        }
        if (isset($p['event_type']) && !in_array($p['event_type'], self::TYPES, true)) $errors[] = 'bad:event_type';
        if (isset($p['severity']) && !in_array($p['severity'], self::SEVERITIES, true)) $errors[] = 'bad:severity';
        $snaps = $p['snapshots'] ?? [];
        if (!is_array($snaps)) $errors[] = 'bad:snapshots';
        elseif (count($snaps) > 3) $errors[] = 'too_many:snapshots';
        else foreach ($snaps as $s) if (!is_string($s)) { $errors[] = 'bad:snapshot_item'; break; }

        // Type guards for required fields
        if (isset($p['device_id']) && !is_string($p['device_id'])) $errors[] = 'bad:device_id';
        if (isset($p['camera_id']) && !is_string($p['camera_id'])) $errors[] = 'bad:camera_id';
        if (isset($p['occurred_at']) && !is_numeric($p['occurred_at'])) $errors[] = 'bad:occurred_at';

        // Type guards for optional fields
        if (isset($p['track_id']) && !is_numeric($p['track_id'])) $errors[] = 'bad:track_id';
        if (isset($p['zone_id']) && !is_string($p['zone_id'])) $errors[] = 'bad:zone_id';
        if (isset($p['duration_s']) && !is_numeric($p['duration_s'])) $errors[] = 'bad:duration_s';
        // Optional normalized point (heatmap raw material): [x, y], both finite numbers. Range is
        // NOT enforced — a foot a hair outside 0..1 must not reject a FALL alert; renderers clamp.
        if (isset($p['spatial'])) {
            $sp = $p['spatial'];
            if (!is_array($sp) || count($sp) !== 2
                || !is_numeric($sp[0] ?? null) || !is_numeric($sp[1] ?? null)
                || !is_finite((float)$sp[0]) || !is_finite((float)$sp[1])) {
                $errors[] = 'bad:spatial';
            }
        }
        // Optional idempotency key: the edge generates a stable 32-hex uuid per event and re-sends
        // it on retry so the server can dedup. Enforce the exact shape (matches CHAR(32) + the
        // snapshot-uuid convention); a malformed key is a bug, not a silent pass.
        if (isset($p['event_uuid']) && (!is_string($p['event_uuid']) || !preg_match('/^[0-9a-f]{32}$/', $p['event_uuid']))) {
            $errors[] = 'bad:event_uuid';
        }

        // Length caps matching the DB columns (device_id/camera_id VARCHAR(64), zone_id
        // CHAR(32)). Without these an overlong id is a MySQL 'Data too long' 500 that the edge
        // re-queues and retries forever; a 400 lets it drop the poison event instead.
        foreach (['device_id' => 64, 'camera_id' => 64, 'zone_id' => 32] as $k => $max) {
            if (isset($p[$k]) && is_string($p[$k]) && mb_strlen($p[$k]) > $max) $errors[] = "too_long:$k";
        }

        if ($errors) return ['ok' => false, 'errors' => $errors, 'clean' => []];

        $clean = [
            'event_uuid' => isset($p['event_uuid']) ? (string)$p['event_uuid'] : null,
            'device_id' => (string)$p['device_id'],
            'camera_id' => (string)$p['camera_id'],
            'event_type' => (string)$p['event_type'],
            'severity' => (string)$p['severity'],
            'track_id' => isset($p['track_id']) ? (int)$p['track_id'] : null,
            'zone_id' => isset($p['zone_id']) ? (string)$p['zone_id'] : null,
            'occurred_at' => (float)$p['occurred_at'],
            'duration_s' => (float)($p['duration_s'] ?? 0.0),
            'metrics' => is_array($p['metrics'] ?? null) ? $p['metrics'] : [],
            'spatial_x' => isset($p['spatial']) ? (float)$p['spatial'][0] : null,
            'spatial_y' => isset($p['spatial']) ? (float)$p['spatial'][1] : null,
        ];
        return ['ok' => true, 'errors' => [], 'clean' => $clean];
    }
}