move_detect/server/tools/dispatch_alerts.php

<?php
/**
 * 통보 디스패처 — 크론 진입점.
 *
 * 크론 등록 (1분 주기). 아래 한 줄을 그대로 쓰되, 앞의 분 필드는 별표+슬래시+1 입니다 —
 * 이 주석 안에 그대로 적으면 PHP 블록 주석이 거기서 끝나 파일이 파싱되지 않습니다:
 *
 *   <매분>  /usr/bin/php /path/to/move_detect_app/tools/dispatch_alerts.php >> /path/alerts.log 2>&1
 *
 * 정확한 크론 표기는 server/docs/server-deploy.md §11 을 보십시오.
 *
 * 하는 일 4가지:
 *   1. 하트비트가 끊긴 노드에 `device_fault`, 성능이 지속 저하된 노드에 `monitoring_degraded`
 *      이벤트를 발행한다. 엣지는 이걸 스스로 못 한다 — 죽은 노드는 자기가 죽었다고 신고할 수 없다.
 *   2. 미확인 채로 임계 시간을 넘긴 위급/높음 이벤트에 `unacked_escalation` 이벤트를 발행한다.
 *   3. 최근 창의 이벤트를 채널 규칙에 따라 통보한다 (즉시 채널 + 지연 에스컬레이션 채널).
 *   4. 실패한 전달을 재시도한다.
 *
 * 1번이 2·3번보다 먼저 오는 것은 의도적이다: 같은 실행 안에서 발행된 장치 이벤트가 곧바로
 * 통보 대상이 되어야 한다. 뒤에 두면 노드가 죽은 사실이 다음 크론까지 1분 늦게 전달된다.
 *
 * 이 파일이 없으면 이 제품은 "사고를 기록하는 시스템"이지 "사고에 대응하는 시스템"이 아니다.
 * 새벽에 넘어진 작업자를 아무도 모른 채 아침을 맞는 상황이 정확히 이 구멍이었다.
 *
 * --dry-run 은 어떤 통보가 나갔을지만 출력하고 아무것도 보내지 않으며 원장에도 쓰지 않는다.
 * 채널을 처음 설정할 때 반드시 먼저 돌려볼 것 — 잘못된 수신자 목록으로 첫 발송을 하면
 * 그 사이트에서는 두 번 다시 이 기능을 켜지 않는다.
 */
declare(strict_types=1);

require __DIR__ . '/bootstrap.php';

use App\Alert\{AlertDispatcher, Channels, DeviceHealthWatch, EscalationWatch, MultiDownWatch};
use App\Repository\Pdo\{PdoEventRepository, PdoAlertRepository, PdoSuppressionRepository,
    PdoDeviceRepository, PdoDeviceMetricRepository, PdoAppStateRepository};

[$cfg, $pdo] = tool_boot();
$args = tool_args($argv);

$now = time();
$dryRun = isset($args['dry-run']);
// 창은 재시도 여유를 포함해야 한다: 크론이 몇 번 건너뛰어도 그 사이 이벤트가 통보 없이
// 흘러가면 안 된다. 기본 1시간.
$window = max(60, min(86400, (int)($args['window'] ?? 3600)));
$escalateAfter = max(30, min(86400, (int)($args['escalate-after'] ?? $cfg->escalateAfterSeconds())));
$limit = max(1, min(2000, (int)($args['limit'] ?? 500)));
$maxAttempts = max(1, min(20, (int)($args['max-attempts'] ?? 5)));

$events = new PdoEventRepository($pdo);
$alerts = new PdoAlertRepository($pdo);
$suppressions = new PdoSuppressionRepository($pdo);

$baseUrl = $cfg->publicBaseUrl();
if ($baseUrl === '') {
    fwrite(STDERR, "config.php 에 public_base_url 이 없습니다. 통보 메시지의 사건 링크가 만들어지지 않습니다.\n");
    exit(2);
}
$channels = new Channels($baseUrl, 8, $cfg->timezone());

// --- 1. 장치 건전성 발행 --------------------------------------------------------------
// 이 두 유형은 서버만 발행할 수 있다. 노드가 응답하지 않는다는 사실은 응답하지 않는 노드가
// 아니라 그것을 기다리는 쪽에서만 관측된다.
//
// 이 단계는 반드시 격리한다. 장치 건전성은 move_devices·move_device_metrics 를 읽는데, 통보
// 경로는 그 두 표를 건드리지 않는다 — 즉 여기서 나는 예외(마이그레이션 미적용, 공유호스팅
// 커넥션 한도, lock timeout)는 원래대로면 정상 발송됐을 실행을 통째로 죽인다. 그러면 새벽 3시
// 넘어짐이 통보되지 않고, 원인이 지속형이라 매분 반복되면서 콘솔은 멀쩡해 보인다.
// 장치 건전성은 부가 기능이고 통보는 이 제품의 존재 이유다 — 실패하면 로그만 남기고 계속 간다.
$healthFiled = [];
if (!$dryRun) {
    try {
        $health = new DeviceHealthWatch(
            $events, new PdoDeviceRepository($pdo), new PdoDeviceMetricRepository($pdo));
        $healthFiled = $health->run($now, [
            'stale_after_s' => $cfg->deviceStaleSeconds(),
            'sustain_s' => $cfg->degradedSustainSeconds(),
            'fps_ratio' => $cfg->degradedFpsRatio(),
            'target_fps' => $cfg->targetFps(),
        ]);
    } catch (Throwable $e) {
        fwrite(STDERR, date('c') . ' device-health error (통보는 계속 진행): '
            . $e->getMessage() . PHP_EOL);
    }
}
foreach ($healthFiled as $f) {
    fwrite(STDOUT, sprintf('%s %s: %s (event=%d)' . PHP_EOL,
        date('c'), $f['event_type'], $f['device_id'], $f['event_id']));
}

// --- 2. 에스컬레이션 발행 -------------------------------------------------------------
$watch = new EscalationWatch($events);
$escalated = [];
if (!$dryRun) {
    try {
        $escalated = $watch->run($now, $escalateAfter, $window, $limit);
    } catch (Throwable $e) {
        fwrite(STDERR, date('c') . ' escalation error (통보는 계속 진행): '
            . $e->getMessage() . PHP_EOL);
    }
}
if ($escalated !== []) {
    fwrite(STDOUT, date('c') . " escalated: " . implode(',', $escalated) . "\n");
}

// --- 2b. 동시 다발 쓰러짐 -------------------------------------------------------------
// 같은 자리에서 짧은 시간에 둘이 쓰러진 것은 넘어짐 두 건이 아니라 질식·가스·폭발이다.
// 에스컬레이션 뒤, 통보 앞에 둔다 — 같은 실행에서 바로 통보되어야 한다.
// 1단계와 같은 이유로 격리한다: 부가 판단이 통보를 죽이면 안 된다.
$multiFiled = [];
if (!$dryRun) {
    try {
        $multiFiled = (new MultiDownWatch($events))->run($now, ['limit' => $limit]);
    } catch (Throwable $e) {
        fwrite(STDERR, date('c') . ' multi-down error (통보는 계속 진행): '
            . $e->getMessage() . PHP_EOL);
    }
}
foreach ($multiFiled as $f) {
    fwrite(STDOUT, sprintf('%s multi_down: %d명 %s (event=%d)' . PHP_EOL,
        date('c'), $f['people'], $f['scope'], $f['event_id']));
}

// --- 3. 통보 --------------------------------------------------------------------------
$dispatcher = new AlertDispatcher($events, $alerts, $suppressions);

// local 채널은 디스패처가 계획 단계에서 제외한다 (엣지가 자체 GPIO 로 즉시 울린다 —
// App\Alert\AlertDispatcher::planFor 주석 참조). 여기 도달하는 것은 email/webhook 뿐이다.
$send = function (array $event, array $channel) use ($channels, $dryRun): void {
    if ($dryRun) {
        fwrite(STDOUT, sprintf("  [dry-run] event=%d -> %s(%s) : %s\n",
            $event['event_id'], $channel['kind'], $channel['name'], $channels->subject($event)));
        return;
    }
    $channels->send($event, $channel);
};

$stats = ['considered' => 0, 'sent' => 0, 'suppressed' => 0, 'failed' => 0, 'skipped' => 0];
try {
    if ($dryRun) {
        // run() claims a ledger row per delivery, which is exactly what must NOT happen during a
        // rehearsal: a claimed row is never retried, so a dry run would silently consume the
        // first real notification for every event in the window. Plan only.
        foreach ($events->forNotification((float)($now - $window), $limit) as $ev) {
            $stats['considered']++;
            foreach ($dispatcher->planFor($ev, $alerts->channels($ev['site'] ?? null), $now) as $d) {
                if ($d['suppressed']) { $stats['suppressed']++; continue; }
                $send($ev, $d['channel']);
                $stats['sent']++;
            }
        }
    } else {
        $stats = $dispatcher->run($now, $window, $limit, $send);
    }
} catch (Throwable $e) {
    fwrite(STDERR, date('c') . ' dispatcher error (재시도는 계속 진행): ' . $e->getMessage() . PHP_EOL);
    // exit 하지 않는다: 여기 도달하는 예외는 저장소·DB 장애이고, 4단계 재시도 패스가 바로 그 전이 장애에서 회복하려고 존재한다.
}

// --- 4. 실패 재시도 -------------------------------------------------------------------
$retried = 0;
if (!$dryRun) {
    foreach ($alerts->retryable($maxAttempts, 100) as $row) {
        $event = $events->find((int)$row['event_id']);
        if ($event === null) continue;
        // 재시도 시점에 이미 확인된 사건이면 더 보내지 않는다 — 사람이 이미 붙었다.
        if (!empty($event['acknowledged_by']) || !empty($event['false_positive_by'])) continue;
        $channel = null;
        foreach ($alerts->allChannels(null) as $c) {
            if ((int)$c['channel_id'] === (int)$row['channel_id']) { $channel = $c; break; }
        }
        if ($channel === null) continue;
        try {
            $channels->send($event, $channel);
            $alerts->markSent((int)$row['event_id'], (int)$row['channel_id'], $now);
            $retried++;
        } catch (Throwable $e) {
            $alerts->markFailed((int)$row['event_id'], (int)$row['channel_id'], $e->getMessage(), $now);
        }
    }
}

// --- 5. 생존 기록 ---------------------------------------------------------------------
// 여기까지 왔다는 것은 이 프로세스가 돌았다는 뜻이다. 통보·확대·장치 이상 발행이 전부 이 한
// 프로세스에 걸려 있어서, 크론이 멈추면 화면은 그냥 조용해지고 그 침묵은 "사고 없음"과
// 구별되지 않는다. 죽은 노드를 하트비트의 부재로 판정하는 바로 그 논리를 우리 자신에게도
// 적용한다 — 감시자의 생존은 감시자가 아닌 쪽(대시보드)이 읽는다.
//
// 단계별 예외 처리 밖에, 마지막에 무조건 남긴다: 어느 단계가 실패했더라도 프로세스는 살아
// 있었고, 여기서 구별하려는 것은 "통보가 틀렸다"가 아니라 "아무도 안 돌고 있다"이다.
// dry-run 은 남기지 않는다 — 사람이 손으로 확인해 본 것을 크론이 도는 증거로 삼으면,
// 크론이 죽은 뒤에도 화면이 초록으로 남는다.
if (!$dryRun) {
    try {
        (new PdoAppStateRepository($pdo))->set('dispatch_alerts.last_run', (string)$now, $now);
    } catch (Throwable $e) {
        fwrite(STDERR, date('c') . ' 생존 기록 실패(통보에는 영향 없음): ' . $e->getMessage() . PHP_EOL);
    }
}

fwrite(STDOUT, sprintf(
    "%s considered=%d sent=%d suppressed=%d failed=%d skipped=%d retried=%d escalated=%d health=%d multi=%d%s\n",
    date('c'), $stats['considered'], $stats['sent'], $stats['suppressed'],
    $stats['failed'], $stats['skipped'], $retried, count($escalated), count($healthFiled), count($multiFiled), $dryRun ? ' (dry-run)' : ''
));
exit(0);