# P1-B 클라우드 수신·대시보드 (Cloud Ingest + Dashboard) Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Cafe24 웹호스팅(PHP+MySQL)에서 도는 관제 백엔드/대시보드 — 엣지(P1-A)가 보내는 서명된 이벤트+스냅샷을 안전하게 수신·저장하고, 인증된 안전관리자가 실시간 사고 목록·상세를 보고, 위험구역 폴리곤을 그려 Pi로 동기한다.

**Architecture:** 바닐라 PHP(프레임워크 없음) + PDO + PHPUnit. 프론트컨트롤러 라우터 → 컨트롤러 → **Repository 인터페이스**(PDO/MySQL 구현) 뒤에 DB. 보안 핵심 로직(HMAC+nonce 검증·입력검증·이미지 재인코딩·RBAC·세션)은 순수·mock repo로 PHPUnit 로컬 완결. DB 통합은 게이트(로컬 pdo_sqlite or Cafe24 MySQL). 스냅샷은 **웹루트 밖** 저장, 인증 PHP 프록시로만 서빙.

**Tech Stack:** PHP 8.5, Composer(dev: phpunit만), PDO(MySQL 타깃), gd(이미지 재인코딩), openssl/hash(HMAC), session/argon2id(인증). 런타임 외부 의존성 0(vendor는 phpunit 개발 전용).

## Global Constraints

- **PHP 8.5**, `declare(strict_types=1);` 모든 파일. PSR-4 오토로드(`App\` → `cloud/src/`).
- **폐쇄망/공유호스팅:** 런타임 composer 의존성 금지(대시보드는 vendor 없이 동작). phpunit은 개발 전용. Cafe24 `public_html`에 `cloud/public/`만 웹 노출.
- **HMAC 계약(P1-A와 정확히 일치):** 서명 = `hmac-sha256(nonce + timestamp + body, per_device_secret)` hex. P1-A `edge/alert.py::sign`과 바이트 동일하게 검증. 헤더 `X-Signature`, `X-Nonce`, `X-Timestamp`.
- **replay 방지:** nonce 1회성(저장·재사용 거부) + timestamp 윈도우(기본 300초).
- **스냅샷:** base64 JPEG를 **gd로 재인코딩**(페이로드 제거·강제 .jpg·랜덤 UUID 파일명), **웹루트 밖**(`cloud/storage/snapshots/`) 저장, 인증 프록시로만 서빙. 원본 바이트 절대 그대로 저장 금지.
- **SQL:** 전부 prepared statement(placeholder). event_type/severity/level 등은 **화이트리스트 enum** 검증.
- **인증:** 로그인 필수(argon2id), 세션 쿠키 HttpOnly+Secure+SameSite=Lax, CSRF 토큰, brute-force 잠금. RBAC: admin/operator/viewer.
- **심각도 색상 단독 금지(NF9):** 텍스트(위급/높음/경고)+아이콘+색, 색맹안전 팔레트.
- **시크릿:** per-device secret·DB 자격증명은 env/시크릿 파일(`cloud/config.php`는 `.gitignore`), 하드코딩 금지.
- **테스트:** 로직은 mock repository로 DB 없이 단위테스트. DB 통합은 마지막 게이트 태스크(로컬 pdo_sqlite or Cafe24).
- 파일 작고 단일책임. 컨트롤러는 얇게(검증·오케스트레이션), 로직은 서비스/헬퍼로.

## File Structure

```
cloud/
  composer.json                 # PSR-4 autoload + phpunit(dev)
  phpunit.xml
  config.example.php            # DB dsn, snapshot dir, nonce ttl 등 (실배포 config.php는 gitignore)
  schema.sql                    # MySQL DDL (+ sqlite 호환 노트)
  public/                       # === Cafe24 웹루트 (이것만 노출) ===
    index.php                   # 프론트컨트롤러
    .htaccess                   # 라우팅 rewrite + storage/src 접근 차단
    assets/{app.css, app.js, zone-draw.js}
  src/
    Config.php
    Http/{Request.php, Response.php, Router.php}
    Db/Database.php
    Security/{Hmac.php, Csrf.php, Password.php}
    Ingest/{EventValidator.php, ImageProcessor.php, IngestController.php}
    Api/{HeartbeatController.php, ConfigController.php}
    Auth/{Session.php, Rbac.php, AuthController.php}
    Dashboard/{EventListController.php, EventDetailController.php, SnapshotProxy.php, ZoneConfigController.php}
    Geometry/Polygon.php
    Repository/                 # 인터페이스
      EventRepository.php, UserRepository.php, DeviceRepository.php,
      ZoneRepository.php, ThresholdRepository.php, NonceRepository.php,
      RateLimiterRepository.php, AuditRepository.php, SnapshotRepository.php
    Repository/Pdo/             # PDO 구현 (DB 게이트 태스크)
      Pdo*.php
    View/                       # 서버렌더 템플릿(php)
      layout.php, login.php, events.php, event_detail.php, zones.php
  storage/                      # === 웹루트 밖 ===
    snapshots/                  # 재인코딩된 JPEG (UUID)
  tests/                        # PHPUnit + InMemory 테스트더블
    Support/InMemoryRepositories.php
    *Test.php
```

---

## Task 1: 스캐폴드 (composer, autoload, Config, PHPUnit)

**Files:**
- Create: `cloud/composer.json`, `cloud/phpunit.xml`, `cloud/src/Config.php`, `cloud/config.example.php`, `cloud/tests/ConfigTest.php`, `cloud/.gitignore`

**Interfaces:**
- Consumes: (없음)
- Produces: `App\Config` with `Config::fromArray(array $a): Config` and typed getters `dbDsn(), dbUser(), dbPass(), snapshotDir(), nonceTtl(): int, timestampWindow(): int, rateLimitPerMin(): int`.

- [ ] **Step 1: composer.json + autoload**

```json
{
  "name": "move-detect/cloud",
  "type": "project",
  "require": { "php": ">=8.2" },
  "require-dev": { "phpunit/phpunit": "^11" },
  "autoload": { "psr-4": { "App\\": "src/" } },
  "autoload-dev": { "psr-4": { "App\\Tests\\": "tests/" } }
}
```

- [ ] **Step 2: phpunit.xml**

```xml
<?xml version="1.0"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         bootstrap="vendor/autoload.php" colors="true">
  <testsuites>
    <testsuite name="unit"><directory>tests</directory></testsuite>
  </testsuites>
</phpunit>
```

- [ ] **Step 3: `.gitignore`** (cloud/)

```
/vendor/
/config.php
/storage/snapshots/*
!/storage/snapshots/.gitkeep
```

- [ ] **Step 4: 실패 테스트** — `cloud/tests/ConfigTest.php`

```php
<?php
declare(strict_types=1);
namespace App\Tests;
use App\Config;
use PHPUnit\Framework\TestCase;

final class ConfigTest extends TestCase
{
    public function testTypedGettersWithDefaults(): void
    {
        $c = Config::fromArray(['db_dsn' => 'sqlite::memory:']);
        $this->assertSame('sqlite::memory:', $c->dbDsn());
        $this->assertSame(300, $c->timestampWindow());
        $this->assertSame(60, $c->rateLimitPerMin());
        $this->assertSame(86400, $c->nonceTtl());
    }

    public function testOverrides(): void
    {
        $c = Config::fromArray(['db_dsn' => 'x', 'timestamp_window' => 120, 'rate_limit_per_min' => 30]);
        $this->assertSame(120, $c->timestampWindow());
        $this->assertSame(30, $c->rateLimitPerMin());
    }
}
```

- [ ] **Step 5: 실패 확인**

Run: `cd cloud && composer install -q && ./vendor/bin/phpunit tests/ConfigTest.php`
Expected: FAIL — `Class "App\Config" not found`

- [ ] **Step 6: 구현** — `cloud/src/Config.php`

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

final class Config
{
    private function __construct(private array $a) {}

    public static function fromArray(array $a): self { return new self($a); }

    public function dbDsn(): string { return (string)($this->a['db_dsn'] ?? ''); }
    public function dbUser(): string { return (string)($this->a['db_user'] ?? ''); }
    public function dbPass(): string { return (string)($this->a['db_pass'] ?? ''); }
    public function snapshotDir(): string { return (string)($this->a['snapshot_dir'] ?? __DIR__ . '/../storage/snapshots'); }
    public function nonceTtl(): int { return (int)($this->a['nonce_ttl'] ?? 86400); }
    public function timestampWindow(): int { return (int)($this->a['timestamp_window'] ?? 300); }
    public function rateLimitPerMin(): int { return (int)($this->a['rate_limit_per_min'] ?? 60); }
}
```

- [ ] **Step 7: config.example.php** (배포 참조)

```php
<?php
return [
    'db_dsn'  => 'mysql:host=localhost;dbname=move_detect;charset=utf8mb4',
    'db_user' => 'CHANGEME',
    'db_pass' => 'CHANGEME',
    'snapshot_dir' => __DIR__ . '/storage/snapshots',
    'timestamp_window' => 300,
    'rate_limit_per_min' => 60,
];
```

- [ ] **Step 8: 통과 + 커밋**

Run: `./vendor/bin/phpunit tests/ConfigTest.php` → PASS

```bash
git add cloud/composer.json cloud/phpunit.xml cloud/.gitignore cloud/config.example.php cloud/src/Config.php cloud/tests/ConfigTest.php
git commit -m "feat(cloud): P1-B scaffold — composer autoload + Config"
```

---

## Task 2: HMAC 검증 (Hmac::sign/verify) — P1-A 계약 일치

**Files:**
- Create: `cloud/src/Security/Hmac.php`, `cloud/tests/HmacTest.php`

**Interfaces:**
- Consumes: (없음)
- Produces: `App\Security\Hmac::sign(string $secret, string $nonce, string $ts, string $body): string` (hex), `Hmac::verify(string $secret, string $nonce, string $ts, string $body, string $sig): bool` (hash_equals, 상수시간).

- [ ] **Step 1: 실패 테스트** — `cloud/tests/HmacTest.php`

```php
<?php
declare(strict_types=1);
namespace App\Tests;
use App\Security\Hmac;
use PHPUnit\Framework\TestCase;

final class HmacTest extends TestCase
{
    public function testSignMatchesPythonEdgeContract(): void
    {
        // P1-A edge/alert.py::sign = HMAC-SHA256(nonce+ts+body, secret) hex
        $sig = Hmac::sign('secret', 'n1', '1000.0', '{"a":1}');
        $expected = hash_hmac('sha256', 'n1' . '1000.0' . '{"a":1}', 'secret');
        $this->assertSame($expected, $sig);
        $this->assertSame(64, strlen($sig));
    }

    public function testVerifyTrueOnMatchFalseOnTamper(): void
    {
        $sig = Hmac::sign('secret', 'n1', '1000.0', 'body');
        $this->assertTrue(Hmac::verify('secret', 'n1', '1000.0', 'body', $sig));
        $this->assertFalse(Hmac::verify('secret', 'n1', '1000.0', 'body-TAMPERED', $sig));
        $this->assertFalse(Hmac::verify('wrong', 'n1', '1000.0', 'body', $sig));
    }
}
```

- [ ] **Step 2: 실패 확인**

Run: `./vendor/bin/phpunit tests/HmacTest.php` → FAIL (class not found)

- [ ] **Step 3: 구현** — `cloud/src/Security/Hmac.php`

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

final class Hmac
{
    public static function sign(string $secret, string $nonce, string $ts, string $body): string
    {
        return hash_hmac('sha256', $nonce . $ts . $body, $secret);
    }

    public static function verify(string $secret, string $nonce, string $ts, string $body, string $sig): bool
    {
        $expected = self::sign($secret, $nonce, $ts, $body);
        return hash_equals($expected, $sig);
    }
}
```

- [ ] **Step 4: 통과 + 커밋**

Run: `./vendor/bin/phpunit tests/HmacTest.php` → PASS

```bash
git add cloud/src/Security/Hmac.php cloud/tests/HmacTest.php
git commit -m "feat(cloud): HMAC sign/verify matching P1-A edge contract"
```

---

## Task 3: Repository 인터페이스 + InMemory 테스트더블

**Files:**
- Create: `cloud/src/Repository/{EventRepository,UserRepository,DeviceRepository,ZoneRepository,ThresholdRepository,NonceRepository,RateLimiterRepository,AuditRepository,SnapshotRepository}.php`, `cloud/tests/Support/InMemoryRepositories.php`, `cloud/tests/RepositoryContractTest.php`

**Interfaces:**
- Consumes: (없음)
- Produces (인터페이스 시그니처 — 이후 태스크가 의존):
  - `DeviceRepository`: `secretFor(string $deviceId): ?string`, `touchHeartbeat(string $deviceId, array $meta): void`, `configVersion(string $deviceId): int`
  - `NonceRepository`: `seen(string $nonce): bool`, `remember(string $nonce, int $expiresAt): void`
  - `RateLimiterRepository`: `hit(string $key, int $windowStart): int` (해당 분 카운트 반환·증가)
  - `EventRepository`: `insert(array $event): int` (event_id), `recent(int $limit, ?string $severity): array`, `find(int $id): ?array`, `acknowledge(int $id, string $user): bool`
  - `SnapshotRepository`: `add(int $eventId, string $fileUuid, string $contentHash): void`, `forEvent(int $eventId): array`, `pathByUuid(string $uuid): ?string`
  - `UserRepository`: `byUsername(string $u): ?array` (id, password_hash, role, site_scope, failed_attempts, locked_until), `recordFailure(int $userId, int $lockUntil): void`, `clearFailures(int $userId): void`
  - `ZoneRepository`: `forDevice(string $deviceId): array`, `forCamera(string $cameraId): array`, `save(array $zone): string`, `delete(string $zoneId): bool`
  - `ThresholdRepository`: `forDevice(string $deviceId): array`
  - `AuditRepository`: `append(string $actor, string $action, string $target, array $before, array $after): void`

- [ ] **Step 1: 인터페이스들 작성** — 각 파일에 `interface` 정의.

`cloud/src/Repository/DeviceRepository.php`:

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

interface DeviceRepository
{
    public function secretFor(string $deviceId): ?string;
    public function touchHeartbeat(string $deviceId, array $meta): void;
    public function configVersion(string $deviceId): int;
}
```

`NonceRepository.php`:

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

interface NonceRepository
{
    public function seen(string $nonce): bool;
    public function remember(string $nonce, int $expiresAt): void;
}
```

`RateLimiterRepository.php`:

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

interface RateLimiterRepository
{
    /** 해당 window(분)의 key 카운트를 1 증가시키고, 증가 후 카운트를 반환한다. */
    public function hit(string $key, int $windowStart): int;
}
```

`EventRepository.php`:

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

interface EventRepository
{
    public function insert(array $event): int;
    public function recent(int $limit, ?string $severity): array;
    public function find(int $id): ?array;
    public function acknowledge(int $id, string $user): bool;
}
```

`SnapshotRepository.php`:

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

interface SnapshotRepository
{
    public function add(int $eventId, string $fileUuid, string $contentHash): void;
    public function forEvent(int $eventId): array;
    public function pathByUuid(string $uuid): ?string;
}
```

`UserRepository.php`:

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

interface UserRepository
{
    public function byUsername(string $username): ?array;
    public function recordFailure(int $userId, int $lockUntil): void;
    public function clearFailures(int $userId): void;
}
```

`ZoneRepository.php`:

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

interface ZoneRepository
{
    public function forDevice(string $deviceId): array;
    public function forCamera(string $cameraId): array;
    public function save(array $zone): string;
    public function delete(string $zoneId): bool;
}
```

`ThresholdRepository.php`:

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

interface ThresholdRepository
{
    public function forDevice(string $deviceId): array;
}
```

`AuditRepository.php`:

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

interface AuditRepository
{
    public function append(string $actor, string $action, string $target, array $before, array $after): void;
}
```

- [ ] **Step 2: InMemory 더블 + 실패 테스트** — `cloud/tests/Support/InMemoryRepositories.php` (테스트 전용 구현)

```php
<?php
declare(strict_types=1);
namespace App\Tests\Support;
use App\Repository\{DeviceRepository, NonceRepository, RateLimiterRepository,
    EventRepository, SnapshotRepository, UserRepository, ZoneRepository,
    ThresholdRepository, AuditRepository};

final class InMemoryDeviceRepository implements DeviceRepository {
    public array $heartbeats = [];
    public function __construct(private array $secrets = [], private array $versions = []) {}
    public function secretFor(string $d): ?string { return $this->secrets[$d] ?? null; }
    public function touchHeartbeat(string $d, array $m): void { $this->heartbeats[$d] = $m; }
    public function configVersion(string $d): int { return $this->versions[$d] ?? 1; }
}
final class InMemoryNonceRepository implements NonceRepository {
    public array $store = [];
    public function seen(string $n): bool { return isset($this->store[$n]); }
    public function remember(string $n, int $exp): void { $this->store[$n] = $exp; }
}
final class InMemoryRateLimiter implements RateLimiterRepository {
    public array $counts = [];
    public function hit(string $k, int $w): int { $key = "$k:$w"; return $this->counts[$key] = ($this->counts[$key] ?? 0) + 1; }
}
final class InMemoryEventRepository implements EventRepository {
    public array $rows = []; private int $seq = 0;
    public function insert(array $e): int { $id = ++$this->seq; $this->rows[$id] = $e + ['event_id' => $id, 'acknowledged_by' => null]; return $id; }
    public function recent(int $limit, ?string $sev): array {
        $r = array_reverse($this->rows, true);
        if ($sev !== null) $r = array_filter($r, fn($x) => $x['severity'] === $sev);
        return array_slice(array_values($r), 0, $limit);
    }
    public function find(int $id): ?array { return $this->rows[$id] ?? null; }
    public function acknowledge(int $id, string $u): bool { if (!isset($this->rows[$id])) return false; $this->rows[$id]['acknowledged_by'] = $u; return true; }
}
final class InMemorySnapshotRepository implements SnapshotRepository {
    public array $rows = []; public array $paths = [];
    public function add(int $e, string $uuid, string $hash): void { $this->rows[$e][] = ['file_uuid' => $uuid, 'content_hash' => $hash]; $this->paths[$uuid] = "/tmp/$uuid.jpg"; }
    public function forEvent(int $e): array { return $this->rows[$e] ?? []; }
    public function pathByUuid(string $u): ?string { return $this->paths[$u] ?? null; }
}
final class InMemoryUserRepository implements UserRepository {
    public function __construct(public array $users = []) {}
    public function byUsername(string $u): ?array { return $this->users[$u] ?? null; }
    public function recordFailure(int $id, int $lock): void { foreach ($this->users as &$row) if ($row['id'] === $id) { $row['failed_attempts'] = ($row['failed_attempts'] ?? 0) + 1; $row['locked_until'] = $lock; } }
    public function clearFailures(int $id): void { foreach ($this->users as &$row) if ($row['id'] === $id) { $row['failed_attempts'] = 0; $row['locked_until'] = 0; } }
}
final class InMemoryZoneRepository implements ZoneRepository {
    public array $zones = []; private int $seq = 0;
    public function forDevice(string $d): array { return array_values(array_filter($this->zones, fn($z) => ($z['device_id'] ?? '') === $d)); }
    public function forCamera(string $c): array { return array_values(array_filter($this->zones, fn($z) => $z['camera_id'] === $c)); }
    public function save(array $z): string { $id = $z['zone_id'] ?? ('z' . (++$this->seq)); $this->zones[$id] = $z + ['zone_id' => $id]; return $id; }
    public function delete(string $id): bool { if (!isset($this->zones[$id])) return false; unset($this->zones[$id]); return true; }
}
final class InMemoryThresholdRepository implements ThresholdRepository {
    public function __construct(private array $data = []) {}
    public function forDevice(string $d): array { return $this->data[$d] ?? []; }
}
final class InMemoryAuditRepository implements AuditRepository {
    public array $log = [];
    public function append(string $a, string $act, string $t, array $b, array $af): void { $this->log[] = compact('a', 'act', 't', 'b', 'af'); }
}
```

그리고 `cloud/tests/RepositoryContractTest.php`:

```php
<?php
declare(strict_types=1);
namespace App\Tests;
use App\Tests\Support\{InMemoryNonceRepository, InMemoryEventRepository, InMemoryRateLimiter};
use PHPUnit\Framework\TestCase;

final class RepositoryContractTest extends TestCase
{
    public function testNonceRememberThenSeen(): void
    {
        $r = new InMemoryNonceRepository();
        $this->assertFalse($r->seen('n1'));
        $r->remember('n1', 999);
        $this->assertTrue($r->seen('n1'));
    }
    public function testEventInsertAndRecent(): void
    {
        $r = new InMemoryEventRepository();
        $id = $r->insert(['severity' => 'high', 'event_type' => 'fall']);
        $this->assertSame(1, $id);
        $this->assertCount(1, $r->recent(10, null));
        $this->assertCount(0, $r->recent(10, 'critical'));
    }
    public function testRateLimiterIncrements(): void
    {
        $r = new InMemoryRateLimiter();
        $this->assertSame(1, $r->hit('dev', 100));
        $this->assertSame(2, $r->hit('dev', 100));
        $this->assertSame(1, $r->hit('dev', 160));
    }
}
```

- [ ] **Step 3: 실패 → 통과**

Run: `./vendor/bin/phpunit tests/RepositoryContractTest.php`
Expected: FAIL (interfaces/doubles absent) → 작성 후 PASS.

- [ ] **Step 4: 커밋**

```bash
git add cloud/src/Repository/*.php cloud/tests/Support/InMemoryRepositories.php cloud/tests/RepositoryContractTest.php
git commit -m "feat(cloud): repository interfaces + in-memory test doubles"
```

---

## Task 4: EventValidator (enum 화이트리스트 + 스키마 검증)

**Files:**
- Create: `cloud/src/Ingest/EventValidator.php`, `cloud/tests/EventValidatorTest.php`

**Interfaces:**
- Consumes: (없음)
- Produces: `App\Ingest\EventValidator::validate(array $payload): array` — `['ok' => bool, 'errors' => string[], 'clean' => array]`. 화이트리스트: event_type ∈ {fall,no_motion,immobility,ghost,zone_warning,zone_restricted,pinch,monitoring_degraded,device_fault}; severity ∈ {critical,high,warning,info}. 필수: device_id, camera_id, event_type, severity, occurred_at. snapshots는 배열(≤3), 문자열 항목.

- [ ] **Step 1: 실패 테스트** — `cloud/tests/EventValidatorTest.php`

```php
<?php
declare(strict_types=1);
namespace App\Tests;
use App\Ingest\EventValidator;
use PHPUnit\Framework\TestCase;

final class EventValidatorTest extends TestCase
{
    private function valid(): array {
        return ['device_id' => 'pi-1', 'camera_id' => 'cam-1', 'event_type' => 'fall',
                'severity' => 'high', 'occurred_at' => 1000.0, 'snapshots' => ['aGk=']];
    }
    public function testAcceptsValid(): void {
        $r = EventValidator::validate($this->valid());
        $this->assertTrue($r['ok'], implode(',', $r['errors']));
        $this->assertSame('fall', $r['clean']['event_type']);
    }
    public function testRejectsUnknownEventType(): void {
        $p = $this->valid(); $p['event_type'] = 'explode';
        $this->assertFalse(EventValidator::validate($p)['ok']);
    }
    public function testRejectsUnknownSeverity(): void {
        $p = $this->valid(); $p['severity'] = 'ULTRA';
        $this->assertFalse(EventValidator::validate($p)['ok']);
    }
    public function testRejectsMissingRequired(): void {
        $p = $this->valid(); unset($p['device_id']);
        $this->assertFalse(EventValidator::validate($p)['ok']);
    }
    public function testRejectsTooManySnapshots(): void {
        $p = $this->valid(); $p['snapshots'] = ['a', 'b', 'c', 'd'];
        $this->assertFalse(EventValidator::validate($p)['ok']);
    }
}
```

- [ ] **Step 2: 실패 확인** → FAIL

- [ ] **Step 3: 구현** — `cloud/src/Ingest/EventValidator.php`

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

final class EventValidator
{
    private const TYPES = ['fall','no_motion','immobility','ghost','zone_warning',
        'zone_restricted','pinch','monitoring_degraded','device_fault'];
    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; }

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

        $clean = [
            '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'] : [],
        ];
        return ['ok' => true, 'errors' => [], 'clean' => $clean];
    }
}
```

- [ ] **Step 4: 통과 + 커밋**

```bash
git add cloud/src/Ingest/EventValidator.php cloud/tests/EventValidatorTest.php
git commit -m "feat(cloud): event payload validator with enum whitelist"
```

---

## Task 5: ImageProcessor (gd 재인코딩 + UUID)

**Files:**
- Create: `cloud/src/Ingest/ImageProcessor.php`, `cloud/tests/ImageProcessorTest.php`

**Interfaces:**
- Consumes: (없음)
- Produces: `App\Ingest\ImageProcessor::reencode(string $base64, int $quality = 80): array` — `['ok'=>bool, 'bytes'=>string, 'uuid'=>string, 'hash'=>string]`. base64 디코드 → gd로 로드 → 순수 JPEG로 재출력(원본 메타/페이로드 제거). 실패 시 `['ok'=>false]`. uuid=랜덤 32hex, hash=sha256(재인코딩 바이트).

- [ ] **Step 1: 실패 테스트** — `cloud/tests/ImageProcessorTest.php`

```php
<?php
declare(strict_types=1);
namespace App\Tests;
use App\Ingest\ImageProcessor;
use PHPUnit\Framework\TestCase;

final class ImageProcessorTest extends TestCase
{
    private function tinyJpegBase64(): string {
        $im = imagecreatetruecolor(8, 8);
        ob_start(); imagejpeg($im); $bytes = ob_get_clean(); imagedestroy($im);
        return base64_encode($bytes);
    }
    public function testReencodeProducesJpeg(): void {
        $r = ImageProcessor::reencode($this->tinyJpegBase64());
        $this->assertTrue($r['ok']);
        $this->assertSame("\xFF\xD8", substr($r['bytes'], 0, 2)); // JPEG magic
        $this->assertSame(32, strlen($r['uuid']));
        $this->assertSame(64, strlen($r['hash']));
    }
    public function testRejectsNonImage(): void {
        $r = ImageProcessor::reencode(base64_encode("not an image <?php echo 1; ?>"));
        $this->assertFalse($r['ok']);
    }
    public function testRejectsBadBase64(): void {
        $this->assertFalse(ImageProcessor::reencode('%%%not-base64%%%')['ok']);
    }
}
```

- [ ] **Step 2: 실패 확인** → FAIL

- [ ] **Step 3: 구현** — `cloud/src/Ingest/ImageProcessor.php`

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

final class ImageProcessor
{
    public static function reencode(string $base64, int $quality = 80): array
    {
        $raw = base64_decode($base64, true);
        if ($raw === false || $raw === '') return ['ok' => false];
        $im = @imagecreatefromstring($raw);
        if ($im === false) return ['ok' => false];
        ob_start();
        $ok = imagejpeg($im, null, $quality);
        $bytes = (string)ob_get_clean();
        imagedestroy($im);
        if (!$ok || $bytes === '') return ['ok' => false];
        return [
            'ok' => true,
            'bytes' => $bytes,
            'uuid' => bin2hex(random_bytes(16)),
            'hash' => hash('sha256', $bytes),
        ];
    }
}
```

- [ ] **Step 4: 통과 + 커밋**

```bash
git add cloud/src/Ingest/ImageProcessor.php cloud/tests/ImageProcessorTest.php
git commit -m "feat(cloud): gd image re-encode (strip payload, uuid, hash)"
```

---

## Task 6: Http Request/Response

**Files:**
- Create: `cloud/src/Http/Request.php`, `cloud/src/Http/Response.php`, `cloud/tests/HttpTest.php`

**Interfaces:**
- Consumes: (없음)
- Produces:
  - `App\Http\Request(string $method, string $path, array $headers, string $body, array $query, array $post)` with getters `method(), path(), header(string $name): ?string, body(), json(): array, query(string $k): ?string, post(string $k): ?string`, and static `fromGlobals(): self`.
  - `App\Http\Response`: static `json(array $data, int $status=200): self`, `text(string $s, int $status=200): self`, `bytes(string $b, string $contentType, int $status=200): self`, `redirect(string $to): self`; getters `status(), headers(), body()`; `send(): void`.

- [ ] **Step 1: 실패 테스트** — `cloud/tests/HttpTest.php`

```php
<?php
declare(strict_types=1);
namespace App\Tests;
use App\Http\{Request, Response};
use PHPUnit\Framework\TestCase;

final class HttpTest extends TestCase
{
    public function testRequestJsonAndHeaderCaseInsensitive(): void {
        $r = new Request('POST', '/api/events', ['X-Nonce' => 'n1'], '{"a":1}', [], []);
        $this->assertSame('POST', $r->method());
        $this->assertSame('n1', $r->header('x-nonce'));
        $this->assertSame(['a' => 1], $r->json());
    }
    public function testResponseJson(): void {
        $res = Response::json(['ok' => true], 201);
        $this->assertSame(201, $res->status());
        $this->assertStringContainsString('application/json', $res->headers()['Content-Type']);
        $this->assertSame('{"ok":true}', $res->body());
    }
}
```

- [ ] **Step 2: 실패 확인** → FAIL

- [ ] **Step 3: 구현** — `cloud/src/Http/Request.php`

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

final class Request
{
    private array $headers;
    public function __construct(
        private string $method, private string $path, array $headers,
        private string $body, private array $query = [], private array $post = []
    ) {
        $this->headers = [];
        foreach ($headers as $k => $v) $this->headers[strtolower($k)] = $v;
    }
    public function method(): string { return $this->method; }
    public function path(): string { return $this->path; }
    public function header(string $name): ?string { return $this->headers[strtolower($name)] ?? null; }
    public function body(): string { return $this->body; }
    public function json(): array { $d = json_decode($this->body, true); return is_array($d) ? $d : []; }
    public function query(string $k): ?string { return isset($this->query[$k]) ? (string)$this->query[$k] : null; }
    public function post(string $k): ?string { return isset($this->post[$k]) ? (string)$this->post[$k] : null; }

    public static function fromGlobals(): self
    {
        $headers = function_exists('getallheaders') ? (getallheaders() ?: []) : [];
        return new self(
            $_SERVER['REQUEST_METHOD'] ?? 'GET',
            parse_url($_SERVER['REQUEST_URI'] ?? '/', PHP_URL_PATH) ?: '/',
            $headers, file_get_contents('php://input') ?: '', $_GET, $_POST
        );
    }
}
```

`cloud/src/Http/Response.php`:

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

final class Response
{
    private function __construct(private int $status, private array $headers, private string $body) {}

    public static function json(array $data, int $status = 200): self {
        return new self($status, ['Content-Type' => 'application/json'], json_encode($data, JSON_UNESCAPED_UNICODE));
    }
    public static function text(string $s, int $status = 200): self {
        return new self($status, ['Content-Type' => 'text/html; charset=utf-8'], $s);
    }
    public static function bytes(string $b, string $contentType, int $status = 200): self {
        return new self($status, ['Content-Type' => $contentType], $b);
    }
    public static function redirect(string $to): self {
        return new self(302, ['Location' => $to], '');
    }
    public function status(): int { return $this->status; }
    public function headers(): array { return $this->headers; }
    public function body(): string { return $this->body; }
    public function send(): void {
        http_response_code($this->status);
        foreach ($this->headers as $k => $v) header("$k: $v");
        echo $this->body;
    }
}
```

- [ ] **Step 4: 통과 + 커밋**

```bash
git add cloud/src/Http/Request.php cloud/src/Http/Response.php cloud/tests/HttpTest.php
git commit -m "feat(cloud): Http Request/Response primitives"
```

---

## Task 7: IngestController (POST /api/events) — 보안 파이프라인 통합

**Files:**
- Create: `cloud/src/Ingest/IngestController.php`, `cloud/tests/IngestControllerTest.php`

**Interfaces:**
- Consumes: `Hmac` (T2), `EventValidator`/`ImageProcessor` (T4/T5), `Request`/`Response` (T6), `DeviceRepository`/`NonceRepository`/`RateLimiterRepository`/`EventRepository`/`SnapshotRepository` (T3), `Config` (T1)
- Produces: `App\Ingest\IngestController(Config, DeviceRepository, NonceRepository, RateLimiterRepository, EventRepository, SnapshotRepository)` with `handle(Request $req, int $now): Response`. 순서: rate limit → device secret 조회 → HMAC 검증 → timestamp 윈도우 → nonce replay → 검증 → 이미지 재인코딩·저장 → 이벤트+스냅샷 insert. 실패는 401/400/429, 성공 201 `{event_id}`.

- [ ] **Step 1: 실패 테스트** — `cloud/tests/IngestControllerTest.php`

```php
<?php
declare(strict_types=1);
namespace App\Tests;
use App\Config;
use App\Http\Request;
use App\Security\Hmac;
use App\Ingest\IngestController;
use App\Tests\Support\{InMemoryDeviceRepository, InMemoryNonceRepository,
    InMemoryRateLimiter, InMemoryEventRepository, InMemorySnapshotRepository};
use PHPUnit\Framework\TestCase;

final class IngestControllerTest extends TestCase
{
    private string $dir;
    protected function setUp(): void { $this->dir = sys_get_temp_dir() . '/snaps' . bin2hex(random_bytes(4)); mkdir($this->dir); }

    private function make(array $secrets = ['pi-1' => 'sekret']): array {
        $cfg = Config::fromArray(['snapshot_dir' => $this->dir, 'timestamp_window' => 300, 'rate_limit_per_min' => 60]);
        $dev = new InMemoryDeviceRepository($secrets);
        $nonce = new InMemoryNonceRepository();
        $rl = new InMemoryRateLimiter();
        $events = new InMemoryEventRepository();
        $snaps = new InMemorySnapshotRepository();
        $c = new IngestController($cfg, $dev, $nonce, $rl, $events, $snaps);
        return [$c, $events, $snaps, $nonce];
    }
    private function jpegB64(): string { $im = imagecreatetruecolor(8, 8); ob_start(); imagejpeg($im); $b = ob_get_clean(); imagedestroy($im); return base64_encode($b); }

    private function signedReq(string $secret, array $payload, string $nonce = 'n1', string $ts = '1000'): Request {
        $body = json_encode($payload, JSON_UNESCAPED_UNICODE);
        $sig = Hmac::sign($secret, $nonce, $ts, $body);
        return new Request('POST', '/api/events',
            ['X-Nonce' => $nonce, 'X-Timestamp' => $ts, 'X-Signature' => $sig], $body, [], []);
    }
    private function payload(): array {
        return ['device_id' => 'pi-1', 'camera_id' => 'cam-1', 'event_type' => 'fall',
                'severity' => 'high', 'occurred_at' => 1000.0, 'snapshots' => [$this->jpegB64()]];
    }

    public function testAcceptsValidSignedEvent(): void {
        [$c, $events, $snaps] = $this->make();
        $res = $c->handle($this->signedReq('sekret', $this->payload()), now: 1000);
        $this->assertSame(201, $res->status());
        $this->assertCount(1, $events->rows);
        $id = json_decode($res->body(), true)['event_id'];
        $this->assertCount(1, $snaps->forEvent($id)); // snapshot re-encoded + stored
    }
    public function testRejectsBadSignature(): void {
        [$c] = $this->make();
        $req = $this->signedReq('WRONG', $this->payload());
        $this->assertSame(401, $c->handle($req, now: 1000)->status());
    }
    public function testRejectsReplayedNonce(): void {
        [$c] = $this->make();
        $req = $this->signedReq('sekret', $this->payload());
        $this->assertSame(201, $c->handle($req, now: 1000)->status());
        $this->assertSame(401, $c->handle($req, now: 1000)->status()); // same nonce again
    }
    public function testRejectsStaleTimestamp(): void {
        [$c] = $this->make();
        $req = $this->signedReq('sekret', $this->payload(), ts: '1000');
        $this->assertSame(401, $c->handle($req, now: 5000)->status()); // 4000s > 300 window
    }
    public function testRejectsUnknownDevice(): void {
        [$c] = $this->make([]); // no secrets
        $this->assertSame(401, $c->handle($this->signedReq('x', $this->payload()), now: 1000)->status());
    }
}
```

- [ ] **Step 2: 실패 확인** → FAIL

- [ ] **Step 3: 구현** — `cloud/src/Ingest/IngestController.php`

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

use App\Config;
use App\Http\{Request, Response};
use App\Security\Hmac;
use App\Repository\{DeviceRepository, NonceRepository, RateLimiterRepository,
    EventRepository, SnapshotRepository};

final class IngestController
{
    public function __construct(
        private Config $cfg,
        private DeviceRepository $devices,
        private NonceRepository $nonces,
        private RateLimiterRepository $rateLimiter,
        private EventRepository $events,
        private SnapshotRepository $snapshots,
    ) {}

    public function handle(Request $req, int $now): Response
    {
        $payload = $req->json();
        $deviceId = (string)($payload['device_id'] ?? '');
        $window = intdiv($now, 60);
        if ($deviceId !== '' && $this->rateLimiter->hit($deviceId, $window) > $this->cfg->rateLimitPerMin()) {
            return Response::json(['error' => 'rate_limited'], 429);
        }

        $nonce = $req->header('X-Nonce') ?? '';
        $ts = $req->header('X-Timestamp') ?? '';
        $sig = $req->header('X-Signature') ?? '';
        $secret = $deviceId !== '' ? $this->devices->secretFor($deviceId) : null;
        if ($secret === null || $nonce === '' || $ts === '' || $sig === '') {
            return Response::json(['error' => 'unauthorized'], 401);
        }
        if (!Hmac::verify($secret, $nonce, $ts, $req->body(), $sig)) {
            return Response::json(['error' => 'bad_signature'], 401);
        }
        if (abs($now - (int)(float)$ts) > $this->cfg->timestampWindow()) {
            return Response::json(['error' => 'stale_timestamp'], 401);
        }
        if ($this->nonces->seen($nonce)) {
            return Response::json(['error' => 'replay'], 401);
        }
        $this->nonces->remember($nonce, $now + $this->cfg->nonceTtl());

        $v = EventValidator::validate($payload);
        if (!$v['ok']) return Response::json(['error' => 'invalid', 'details' => $v['errors']], 400);

        $eventId = $this->events->insert($v['clean']);
        foreach (($payload['snapshots'] ?? []) as $b64) {
            $img = ImageProcessor::reencode((string)$b64);
            if (!$img['ok']) continue;
            $path = rtrim($this->cfg->snapshotDir(), '/\\') . '/' . $img['uuid'] . '.jpg';
            file_put_contents($path, $img['bytes']);
            $this->snapshots->add($eventId, $img['uuid'], $img['hash']);
        }
        return Response::json(['event_id' => $eventId], 201);
    }
}
```

> **NOTE (implementer):** `InMemorySnapshotRepository::add` stores a `/tmp/...` path in the double; the controller also writes the real file to `snapshot_dir` (setUp creates the dir). Tests assert on `forEvent()` count only. Rate-limit is checked first so a flood is rejected before crypto work.

- [ ] **Step 4: 통과 + 커밋**

```bash
git add cloud/src/Ingest/IngestController.php cloud/tests/IngestControllerTest.php
git commit -m "feat(cloud): ingest controller (HMAC+nonce+ratelimit+reencode+persist)"
```

---

## Task 8: Password (argon2id) + Csrf

**Files:**
- Create: `cloud/src/Security/Password.php`, `cloud/src/Security/Csrf.php`, `cloud/tests/PasswordCsrfTest.php`

**Interfaces:**
- Consumes: (없음)
- Produces:
  - `App\Security\Password::hash(string $p): string` (PASSWORD_ARGON2ID), `Password::verify(string $p, string $hash): bool`.
  - `App\Security\Csrf::issue(callable $randHex): string`, `Csrf::check(string $expected, string $given): bool` (hash_equals).

- [ ] **Step 1: 실패 테스트** — `cloud/tests/PasswordCsrfTest.php`

```php
<?php
declare(strict_types=1);
namespace App\Tests;
use App\Security\{Password, Csrf};
use PHPUnit\Framework\TestCase;

final class PasswordCsrfTest extends TestCase
{
    public function testHashVerify(): void {
        $h = Password::hash('s3cret!');
        $this->assertNotSame('s3cret!', $h);
        $this->assertTrue(Password::verify('s3cret!', $h));
        $this->assertFalse(Password::verify('wrong', $h));
    }
    public function testCsrf(): void {
        $t = Csrf::issue(fn() => 'abc123');
        $this->assertSame('abc123', $t);
        $this->assertTrue(Csrf::check($t, 'abc123'));
        $this->assertFalse(Csrf::check($t, 'nope'));
    }
}
```

- [ ] **Step 2: 실패 확인** → FAIL

- [ ] **Step 3: 구현** — `cloud/src/Security/Password.php`

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

final class Password
{
    public static function hash(string $plain): string {
        return password_hash($plain, PASSWORD_ARGON2ID);
    }
    public static function verify(string $plain, string $hash): bool {
        return password_verify($plain, $hash);
    }
}
```

`cloud/src/Security/Csrf.php`:

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

final class Csrf
{
    public static function issue(callable $randHex): string { return (string)$randHex(); }
    public static function check(string $expected, string $given): bool {
        return $expected !== '' && hash_equals($expected, $given);
    }
}
```

- [ ] **Step 4: 통과 + 커밋**

```bash
git add cloud/src/Security/Password.php cloud/src/Security/Csrf.php cloud/tests/PasswordCsrfTest.php
git commit -m "feat(cloud): argon2id password + CSRF token helpers"
```

---

## Task 9: Rbac (역할→권한)

**Files:**
- Create: `cloud/src/Auth/Rbac.php`, `cloud/tests/RbacTest.php`

**Interfaces:**
- Consumes: (없음)
- Produces: `App\Auth\Rbac::can(string $role, string $permission): bool`. 권한: `view_events`(all), `acknowledge`(admin,operator), `edit_zones`(admin,operator), `manage_thresholds`(admin), `manage_compliance`(admin).

- [ ] **Step 1: 실패 테스트** — `cloud/tests/RbacTest.php`

```php
<?php
declare(strict_types=1);
namespace App\Tests;
use App\Auth\Rbac;
use PHPUnit\Framework\TestCase;

final class RbacTest extends TestCase
{
    public function testViewerCanOnlyView(): void {
        $this->assertTrue(Rbac::can('viewer', 'view_events'));
        $this->assertFalse(Rbac::can('viewer', 'acknowledge'));
        $this->assertFalse(Rbac::can('viewer', 'edit_zones'));
    }
    public function testOperator(): void {
        $this->assertTrue(Rbac::can('operator', 'acknowledge'));
        $this->assertTrue(Rbac::can('operator', 'edit_zones'));
        $this->assertFalse(Rbac::can('operator', 'manage_thresholds'));
    }
    public function testAdminAll(): void {
        foreach (['view_events','acknowledge','edit_zones','manage_thresholds','manage_compliance'] as $p) {
            $this->assertTrue(Rbac::can('admin', $p));
        }
    }
    public function testUnknownDenied(): void {
        $this->assertFalse(Rbac::can('ghost', 'view_events'));
        $this->assertFalse(Rbac::can('admin', 'unknown_perm'));
    }
}
```

- [ ] **Step 2: 실패 확인** → FAIL

- [ ] **Step 3: 구현** — `cloud/src/Auth/Rbac.php`

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

final class Rbac
{
    private const MATRIX = [
        'admin'    => ['view_events','acknowledge','edit_zones','manage_thresholds','manage_compliance'],
        'operator' => ['view_events','acknowledge','edit_zones'],
        'viewer'   => ['view_events'],
    ];
    public static function can(string $role, string $permission): bool {
        return in_array($permission, self::MATRIX[$role] ?? [], true);
    }
}
```

- [ ] **Step 4: 통과 + 커밋**

```bash
git add cloud/src/Auth/Rbac.php cloud/tests/RbacTest.php
git commit -m "feat(cloud): RBAC permission matrix"
```

---

## Task 10: Session + AuthController (로그인/brute-force 잠금)

**Files:**
- Create: `cloud/src/Auth/Session.php`, `cloud/src/Auth/AuthController.php`, `cloud/tests/AuthControllerTest.php`

**Interfaces:**
- Consumes: `Password` (T8), `Request`/`Response` (T6), `UserRepository`/`AuditRepository` (T3)
- Produces:
  - `interface App\Auth\SessionStore { get(string $k): mixed; set(string $k, mixed $v): void; clear(): void; }`, `ArraySessionStore` (test), `PhpSessionStore` (prod, secure cookie).
  - `App\Auth\AuthController(UserRepository $users, AuditRepository $audit, int $maxAttempts=5, int $lockSeconds=900)` with `login(Request $req, SessionStore $sess, int $now): Response` and `logout(SessionStore $sess): Response`. Locks after maxAttempts; 200 on success (sets user in session), 401 on bad creds, 423 when locked.

- [ ] **Step 1: 실패 테스트** — `cloud/tests/AuthControllerTest.php`

```php
<?php
declare(strict_types=1);
namespace App\Tests;
use App\Http\Request;
use App\Security\Password;
use App\Auth\{AuthController, ArraySessionStore};
use App\Tests\Support\{InMemoryUserRepository, InMemoryAuditRepository};
use PHPUnit\Framework\TestCase;

final class AuthControllerTest extends TestCase
{
    private function users(): InMemoryUserRepository {
        return new InMemoryUserRepository(['alice' => [
            'id' => 1, 'username' => 'alice', 'password_hash' => Password::hash('pw'),
            'role' => 'operator', 'site_scope' => null, 'failed_attempts' => 0, 'locked_until' => 0,
        ]]);
    }
    private function req(string $u, string $p): Request {
        return new Request('POST', '/login', [], '', [], ['username' => $u, 'password' => $p]);
    }
    public function testLoginSuccessSetsSession(): void {
        $c = new AuthController($this->users(), new InMemoryAuditRepository());
        $sess = new ArraySessionStore();
        $res = $c->login($this->req('alice', 'pw'), $sess, now: 1000);
        $this->assertSame(200, $res->status());
        $this->assertSame(1, $sess->get('user_id'));
        $this->assertSame('operator', $sess->get('role'));
    }
    public function testBadPasswordIs401(): void {
        $c = new AuthController($this->users(), new InMemoryAuditRepository());
        $this->assertSame(401, $c->login($this->req('alice', 'nope'), new ArraySessionStore(), now: 1000)->status());
    }
    public function testLockoutAfterMaxAttempts(): void {
        $repo = $this->users();
        $c = new AuthController($repo, new InMemoryAuditRepository(), maxAttempts: 3, lockSeconds: 900);
        for ($i = 0; $i < 3; $i++) $c->login($this->req('alice', 'bad'), new ArraySessionStore(), now: 1000);
        // now locked, even correct password is 423
        $this->assertSame(423, $c->login($this->req('alice', 'pw'), new ArraySessionStore(), now: 1000)->status());
    }
}
```

- [ ] **Step 2: 실패 확인** → FAIL

- [ ] **Step 3: 구현** — `cloud/src/Auth/Session.php`

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

interface SessionStore {
    public function get(string $key): mixed;
    public function set(string $key, mixed $value): void;
    public function clear(): void;
}

final class ArraySessionStore implements SessionStore {
    private array $d = [];
    public function get(string $k): mixed { return $this->d[$k] ?? null; }
    public function set(string $k, mixed $v): void { $this->d[$k] = $v; }
    public function clear(): void { $this->d = []; }
}

final class PhpSessionStore implements SessionStore {
    public function __construct() { if (session_status() !== PHP_SESSION_ACTIVE) session_start([
        'cookie_httponly' => true, 'cookie_secure' => true, 'cookie_samesite' => 'Lax',
    ]); }
    public function get(string $k): mixed { return $_SESSION[$k] ?? null; }
    public function set(string $k, mixed $v): void { $_SESSION[$k] = $v; }
    public function clear(): void { $_SESSION = []; session_destroy(); }
}
```

`cloud/src/Auth/AuthController.php`:

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

use App\Http\{Request, Response};
use App\Security\Password;
use App\Repository\{UserRepository, AuditRepository};

final class AuthController
{
    public function __construct(
        private UserRepository $users,
        private AuditRepository $audit,
        private int $maxAttempts = 5,
        private int $lockSeconds = 900,
    ) {}

    public function login(Request $req, SessionStore $sess, int $now): Response
    {
        $username = (string)$req->post('username');
        $password = (string)$req->post('password');
        $u = $this->users->byUsername($username);
        if ($u === null) return Response::json(['error' => 'invalid_credentials'], 401);

        if ((int)($u['locked_until'] ?? 0) > $now) {
            $this->audit->append($username, 'login_locked', 'auth', [], []);
            return Response::json(['error' => 'locked'], 423);
        }
        if (!Password::verify($password, (string)$u['password_hash'])) {
            $attempts = (int)($u['failed_attempts'] ?? 0) + 1;
            $lock = $attempts >= $this->maxAttempts ? $now + $this->lockSeconds : 0;
            $this->users->recordFailure((int)$u['id'], $lock);
            $this->audit->append($username, 'login_failed', 'auth', [], ['attempts' => $attempts]);
            return Response::json(['error' => 'invalid_credentials'], 401);
        }
        $this->users->clearFailures((int)$u['id']);
        $sess->set('user_id', (int)$u['id']);
        $sess->set('username', $u['username']);
        $sess->set('role', $u['role']);
        $sess->set('site_scope', $u['site_scope'] ?? null);
        $this->audit->append($username, 'login_ok', 'auth', [], []);
        return Response::json(['ok' => true], 200);
    }

    public function logout(SessionStore $sess): Response
    {
        $sess->clear();
        return Response::json(['ok' => true], 200);
    }
}
```

> **NOTE (implementer):** the lockout test relies on `InMemoryUserRepository::recordFailure` mutating `failed_attempts`/`locked_until` on the stored row so the next `byUsername` reflects it (the double loops by reference — verify this persists across calls). `login` reads `locked_until` fresh on each call.

- [ ] **Step 4: 통과 + 커밋**

```bash
git add cloud/src/Auth/Session.php cloud/src/Auth/AuthController.php cloud/tests/AuthControllerTest.php
git commit -m "feat(cloud): session store + auth controller with lockout"
```

---

## Task 11: Router + 프론트컨트롤러 준비

**Files:**
- Create: `cloud/src/Http/Router.php`, `cloud/tests/RouterTest.php`

**Interfaces:**
- Consumes: `Request`/`Response` (T6)
- Produces: `App\Http\Router` with `add(string $method, string $path, callable $handler): void` and `dispatch(Request $req): Response` (404 if no match; path params `{id}` → passed to handler as second arg assoc array).

- [ ] **Step 1: 실패 테스트** — `cloud/tests/RouterTest.php`

```php
<?php
declare(strict_types=1);
namespace App\Tests;
use App\Http\{Router, Request, Response};
use PHPUnit\Framework\TestCase;

final class RouterTest extends TestCase
{
    public function testMatchAndParams(): void {
        $r = new Router();
        $r->add('GET', '/events/{id}', fn(Request $req, array $p) => Response::json(['id' => $p['id']]));
        $res = $r->dispatch(new Request('GET', '/events/42', [], '', [], []));
        $this->assertSame(200, $res->status());
        $this->assertSame(['id' => '42'], json_decode($res->body(), true));
    }
    public function testUnmatchedIs404(): void {
        $r = new Router();
        $this->assertSame(404, $r->dispatch(new Request('GET', '/nope', [], '', [], []))->status());
    }
    public function testMethodMismatchIs404(): void {
        $r = new Router();
        $r->add('POST', '/x', fn() => Response::text('ok'));
        $this->assertSame(404, $r->dispatch(new Request('GET', '/x', [], '', [], []))->status());
    }
}
```

- [ ] **Step 2: 실패 확인** → FAIL

- [ ] **Step 3: 구현** — `cloud/src/Http/Router.php`

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

final class Router
{
    private array $routes = [];

    public function add(string $method, string $path, callable $handler): void {
        $regex = '#^' . preg_replace('#\{(\w+)\}#', '(?P<$1>[^/]+)', $path) . '$#';
        $this->routes[] = [strtoupper($method), $regex, $handler];
    }

    public function dispatch(Request $req): Response {
        foreach ($this->routes as [$method, $regex, $handler]) {
            if ($req->method() !== $method) continue;
            if (preg_match($regex, $req->path(), $m)) {
                $params = array_filter($m, 'is_string', ARRAY_FILTER_USE_KEY);
                return $handler($req, $params);
            }
        }
        return Response::json(['error' => 'not_found'], 404);
    }
}
```

- [ ] **Step 4: 통과 + 커밋**

```bash
git add cloud/src/Http/Router.php cloud/tests/RouterTest.php
git commit -m "feat(cloud): path-param router + dispatch"
```

---

## Task 12: 대시보드 컨트롤러 (목록·상세·확인) + 스냅샷 프록시

**Files:**
- Create: `cloud/src/Dashboard/EventListController.php`, `cloud/src/Dashboard/EventDetailController.php`, `cloud/src/Dashboard/SnapshotProxy.php`, `cloud/tests/DashboardTest.php`

**Interfaces:**
- Consumes: `Request`/`Response` (T6), `SessionStore`/`Rbac` (T9/T10), `EventRepository`/`SnapshotRepository`/`AuditRepository` (T3)
- Produces:
  - `EventListController(EventRepository, SessionStore)::json(Request): Response` — 인증 필요, `?severity=` 필터, 최근 100개.
  - `EventDetailController(EventRepository, SnapshotRepository, AuditRepository, SessionStore)::show(Request, array $params): Response`; `acknowledge(Request, array $params): Response` (RBAC `acknowledge`).
  - `SnapshotProxy(SnapshotRepository, SessionStore)::serve(Request, array $params): Response` — 인증 필요, uuid→웹루트밖 파일 바이트 서빙(image/jpeg), 미인증 401, 없음 404.

- [ ] **Step 1: 실패 테스트** — `cloud/tests/DashboardTest.php`

```php
<?php
declare(strict_types=1);
namespace App\Tests;
use App\Http\Request;
use App\Auth\ArraySessionStore;
use App\Dashboard\{EventListController, EventDetailController, SnapshotProxy};
use App\Tests\Support\{InMemoryEventRepository, InMemorySnapshotRepository, InMemoryAuditRepository};
use PHPUnit\Framework\TestCase;

final class DashboardTest extends TestCase
{
    private function authed(string $role = 'operator'): ArraySessionStore {
        $s = new ArraySessionStore(); $s->set('user_id', 1); $s->set('username', 'u'); $s->set('role', $role); return $s;
    }
    public function testListRequiresAuth(): void {
        $repo = new InMemoryEventRepository();
        $c = new EventListController($repo, new ArraySessionStore());
        $this->assertSame(401, $c->json(new Request('GET', '/api/events', [], '', [], []))->status());
    }
    public function testListReturnsRecent(): void {
        $repo = new InMemoryEventRepository();
        $repo->insert(['severity' => 'high', 'event_type' => 'fall']);
        $c = new EventListController($repo, $this->authed());
        $res = $c->json(new Request('GET', '/api/events', [], '', [], []));
        $this->assertSame(200, $res->status());
        $this->assertCount(1, json_decode($res->body(), true)['events']);
    }
    public function testAcknowledgeRequiresPermissionAndSetsUser(): void {
        $repo = new InMemoryEventRepository();
        $id = $repo->insert(['severity' => 'critical', 'event_type' => 'no_motion']);
        $req = new Request('POST', "/events/$id/ack", [], '', [], []);
        // viewer denied
        $cv = new EventDetailController($repo, new InMemorySnapshotRepository(), new InMemoryAuditRepository(), $this->authed('viewer'));
        $this->assertSame(403, $cv->acknowledge($req, ['id' => (string)$id])->status());
        // operator allowed
        $co = new EventDetailController($repo, new InMemorySnapshotRepository(), new InMemoryAuditRepository(), $this->authed('operator'));
        $this->assertSame(200, $co->acknowledge($req, ['id' => (string)$id])->status());
        $this->assertSame('u', $repo->find($id)['acknowledged_by']);
    }
    public function testSnapshotProxyAuthAnd404(): void {
        $snaps = new InMemorySnapshotRepository();
        $proxy = new SnapshotProxy($snaps, new ArraySessionStore()); // unauth
        $this->assertSame(401, $proxy->serve(new Request('GET', '/snap/x', [], '', [], []), ['uuid' => 'x'])->status());
        $proxy2 = new SnapshotProxy($snaps, $this->authed());
        $this->assertSame(404, $proxy2->serve(new Request('GET', '/snap/missing', [], '', [], []), ['uuid' => 'missing'])->status());
    }
}
```

- [ ] **Step 2: 실패 확인** → FAIL

- [ ] **Step 3: 구현** — `cloud/src/Dashboard/EventListController.php`

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

use App\Http\{Request, Response};
use App\Auth\SessionStore;
use App\Repository\EventRepository;

final class EventListController
{
    public function __construct(private EventRepository $events, private SessionStore $sess) {}

    public function json(Request $req): Response
    {
        if ($this->sess->get('user_id') === null) return Response::json(['error' => 'unauthorized'], 401);
        $severity = $req->query('severity');
        $rows = $this->events->recent(100, $severity);
        return Response::json(['events' => $rows], 200);
    }
}
```

`cloud/src/Dashboard/EventDetailController.php`:

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

use App\Http\{Request, Response};
use App\Auth\{SessionStore, Rbac};
use App\Repository\{EventRepository, SnapshotRepository, AuditRepository};

final class EventDetailController
{
    public function __construct(
        private EventRepository $events, private SnapshotRepository $snaps,
        private AuditRepository $audit, private SessionStore $sess
    ) {}

    public function show(Request $req, array $params): Response
    {
        if ($this->sess->get('user_id') === null) return Response::json(['error' => 'unauthorized'], 401);
        $id = (int)($params['id'] ?? 0);
        $event = $this->events->find($id);
        if ($event === null) return Response::json(['error' => 'not_found'], 404);
        return Response::json(['event' => $event, 'snapshots' => $this->snaps->forEvent($id)], 200);
    }

    public function acknowledge(Request $req, array $params): Response
    {
        if ($this->sess->get('user_id') === null) return Response::json(['error' => 'unauthorized'], 401);
        if (!Rbac::can((string)$this->sess->get('role'), 'acknowledge')) return Response::json(['error' => 'forbidden'], 403);
        $id = (int)($params['id'] ?? 0);
        $user = (string)$this->sess->get('username');
        if (!$this->events->acknowledge($id, $user)) return Response::json(['error' => 'not_found'], 404);
        $this->audit->append($user, 'acknowledge', "event:$id", [], []);
        return Response::json(['ok' => true], 200);
    }
}
```

`cloud/src/Dashboard/SnapshotProxy.php`:

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

use App\Http\{Request, Response};
use App\Auth\SessionStore;
use App\Repository\SnapshotRepository;

final class SnapshotProxy
{
    public function __construct(private SnapshotRepository $snaps, private SessionStore $sess) {}

    public function serve(Request $req, array $params): Response
    {
        if ($this->sess->get('user_id') === null) return Response::json(['error' => 'unauthorized'], 401);
        $uuid = (string)($params['uuid'] ?? '');
        $path = $this->snaps->pathByUuid($uuid);
        if ($path === null || !is_file($path)) return Response::json(['error' => 'not_found'], 404);
        return Response::bytes((string)file_get_contents($path), 'image/jpeg', 200);
    }
}
```

- [ ] **Step 4: 통과 + 커밋**

```bash
git add cloud/src/Dashboard/EventListController.php cloud/src/Dashboard/EventDetailController.php cloud/src/Dashboard/SnapshotProxy.php cloud/tests/DashboardTest.php
git commit -m "feat(cloud): dashboard list/detail/ack + auth-gated snapshot proxy"
```

---

## Task 13: Polygon 검증 + ZoneConfigController

**Files:**
- Create: `cloud/src/Geometry/Polygon.php`, `cloud/src/Dashboard/ZoneConfigController.php`, `cloud/tests/ZoneConfigTest.php`

**Interfaces:**
- Consumes: `Request`/`Response` (T6), `SessionStore`/`Rbac`, `ZoneRepository`/`AuditRepository` (T3)
- Produces:
  - `App\Geometry\Polygon::validate(array $points): bool` — ≥3점, 각 점 `[x,y]` 숫자.
  - `ZoneConfigController(ZoneRepository, AuditRepository, SessionStore)`: `list(Request, array): Response` (camera별), `save(Request): Response` (RBAC edit_zones; level ∈ {warning,restricted,pinch}; polygon 검증; zone_id 반환), `delete(Request, array): Response`.

- [ ] **Step 1: 실패 테스트** — `cloud/tests/ZoneConfigTest.php`

```php
<?php
declare(strict_types=1);
namespace App\Tests;
use App\Http\Request;
use App\Auth\ArraySessionStore;
use App\Geometry\Polygon;
use App\Dashboard\ZoneConfigController;
use App\Tests\Support\{InMemoryZoneRepository, InMemoryAuditRepository};
use PHPUnit\Framework\TestCase;

final class ZoneConfigTest extends TestCase
{
    private function authed(string $role = 'operator'): ArraySessionStore {
        $s = new ArraySessionStore(); $s->set('user_id', 1); $s->set('username', 'u'); $s->set('role', $role); return $s;
    }
    public function testPolygonValidation(): void {
        $this->assertTrue(Polygon::validate([[0,0],[10,0],[10,10]]));
        $this->assertFalse(Polygon::validate([[0,0],[10,0]])); // <3
        $this->assertFalse(Polygon::validate([[0,0],[10,0],['x',10]])); // non-numeric
    }
    private function saveReq(array $body): Request {
        return new Request('POST', '/api/zones', [], json_encode($body), [], []);
    }
    public function testSaveRequiresPermission(): void {
        $c = new ZoneConfigController(new InMemoryZoneRepository(), new InMemoryAuditRepository(), $this->authed('viewer'));
        $res = $c->save($this->saveReq(['camera_id' => 'cam-1', 'level' => 'restricted', 'polygon' => [[0,0],[9,0],[9,9]]]));
        $this->assertSame(403, $res->status());
    }
    public function testSaveValidZone(): void {
        $repo = new InMemoryZoneRepository();
        $c = new ZoneConfigController($repo, new InMemoryAuditRepository(), $this->authed('operator'));
        $res = $c->save($this->saveReq(['device_id' => 'pi-1', 'camera_id' => 'cam-1', 'level' => 'restricted', 'polygon' => [[0,0],[9,0],[9,9]]]));
        $this->assertSame(201, $res->status());
        $this->assertCount(1, $repo->forCamera('cam-1'));
    }
    public function testSaveRejectsBadLevelOrPolygon(): void {
        $c = new ZoneConfigController(new InMemoryZoneRepository(), new InMemoryAuditRepository(), $this->authed('operator'));
        $this->assertSame(400, $c->save($this->saveReq(['camera_id' => 'cam-1', 'level' => 'BOOM', 'polygon' => [[0,0],[9,0],[9,9]]]))->status());
        $this->assertSame(400, $c->save($this->saveReq(['camera_id' => 'cam-1', 'level' => 'warning', 'polygon' => [[0,0]]]))->status());
    }
}
```

- [ ] **Step 2: 실패 확인** → FAIL

- [ ] **Step 3: 구현** — `cloud/src/Geometry/Polygon.php`

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

final class Polygon
{
    public static function validate(array $points): bool
    {
        if (count($points) < 3) return false;
        foreach ($points as $pt) {
            if (!is_array($pt) || count($pt) !== 2) return false;
            if (!is_numeric($pt[0]) || !is_numeric($pt[1])) return false;
        }
        return true;
    }
}
```

`cloud/src/Dashboard/ZoneConfigController.php`:

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

use App\Http\{Request, Response};
use App\Auth\{SessionStore, Rbac};
use App\Geometry\Polygon;
use App\Repository\{ZoneRepository, AuditRepository};

final class ZoneConfigController
{
    private const LEVELS = ['warning','restricted','pinch'];

    public function __construct(
        private ZoneRepository $zones, private AuditRepository $audit, private SessionStore $sess
    ) {}

    private function guard(string $perm): ?Response
    {
        if ($this->sess->get('user_id') === null) return Response::json(['error' => 'unauthorized'], 401);
        if (!Rbac::can((string)$this->sess->get('role'), $perm)) return Response::json(['error' => 'forbidden'], 403);
        return null;
    }

    public function list(Request $req, array $params): Response
    {
        if ($this->sess->get('user_id') === null) return Response::json(['error' => 'unauthorized'], 401);
        return Response::json(['zones' => $this->zones->forCamera((string)($params['camera'] ?? ''))], 200);
    }

    public function save(Request $req): Response
    {
        if ($g = $this->guard('edit_zones')) return $g;
        $b = $req->json();
        $level = (string)($b['level'] ?? '');
        $polygon = $b['polygon'] ?? [];
        if (!in_array($level, self::LEVELS, true) || !is_array($polygon) || !Polygon::validate($polygon)) {
            return Response::json(['error' => 'invalid_zone'], 400);
        }
        $zoneId = $this->zones->save([
            'zone_id' => $b['zone_id'] ?? null,
            'device_id' => (string)($b['device_id'] ?? ''),
            'camera_id' => (string)($b['camera_id'] ?? ''),
            'level' => $level,
            'polygon_json' => json_encode($polygon),
        ]);
        $this->audit->append((string)$this->sess->get('username'), 'zone_save', "zone:$zoneId", [], ['level' => $level]);
        return Response::json(['zone_id' => $zoneId], 201);
    }

    public function delete(Request $req, array $params): Response
    {
        if ($g = $this->guard('edit_zones')) return $g;
        $id = (string)($params['id'] ?? '');
        if (!$this->zones->delete($id)) return Response::json(['error' => 'not_found'], 404);
        $this->audit->append((string)$this->sess->get('username'), 'zone_delete', "zone:$id", [], []);
        return Response::json(['ok' => true], 200);
    }
}
```

- [ ] **Step 4: 통과 + 커밋**

```bash
git add cloud/src/Geometry/Polygon.php cloud/src/Dashboard/ZoneConfigController.php cloud/tests/ZoneConfigTest.php
git commit -m "feat(cloud): polygon validation + zone config controller (RBAC)"
```

---

## Task 14: ConfigController + HeartbeatController (Pi 동기 API)

**Files:**
- Create: `cloud/src/Api/ConfigController.php`, `cloud/src/Api/HeartbeatController.php`, `cloud/tests/ApiSyncTest.php`

**Interfaces:**
- Consumes: `Request`/`Response` (T6), `Hmac` (T2), `DeviceRepository`/`ZoneRepository`/`ThresholdRepository` (T3), `Config` (T1)
- Produces:
  - `App\Api\ConfigController(DeviceRepository, ZoneRepository, ThresholdRepository)::get(Request): Response` — `?device_id=`; device secret HMAC 검증(엣지 폴링). 반환 `{version, zones, thresholds}`.
  - `App\Api\HeartbeatController(Config, DeviceRepository)::post(Request, int $now): Response` — HMAC 검증 후 `touchHeartbeat(device_id, {fps,temp,throttle,config_version,at})`. 200.

- [ ] **Step 1: 실패 테스트** — `cloud/tests/ApiSyncTest.php`

```php
<?php
declare(strict_types=1);
namespace App\Tests;
use App\Config;
use App\Http\Request;
use App\Security\Hmac;
use App\Api\{ConfigController, HeartbeatController};
use App\Tests\Support\{InMemoryDeviceRepository, InMemoryZoneRepository, InMemoryThresholdRepository};
use PHPUnit\Framework\TestCase;

final class ApiSyncTest extends TestCase
{
    private function signed(string $method, string $path, string $secret, array $q = [], array $body = []): Request {
        $raw = $body ? json_encode($body) : '';
        $nonce = 'n1'; $ts = '1000';
        $sig = Hmac::sign($secret, $nonce, $ts, $raw);
        return new Request($method, $path, ['X-Nonce' => $nonce, 'X-Timestamp' => $ts, 'X-Signature' => $sig], $raw, $q, []);
    }
    public function testConfigReturnsZonesAndThresholds(): void {
        $dev = new InMemoryDeviceRepository(['pi-1' => 'sek'], ['pi-1' => 7]);
        $zones = new InMemoryZoneRepository(); $zones->save(['device_id' => 'pi-1', 'camera_id' => 'cam-1', 'level' => 'restricted', 'polygon_json' => '[[0,0],[9,0],[9,9]]']);
        $thr = new InMemoryThresholdRepository(['pi-1' => ['fall_prone_s' => 3.0]]);
        $c = new ConfigController($dev, $zones, $thr);
        $res = $c->get($this->signed('GET', '/api/config', 'sek', ['device_id' => 'pi-1']));
        $this->assertSame(200, $res->status());
        $data = json_decode($res->body(), true);
        $this->assertSame(7, $data['version']);
        $this->assertCount(1, $data['zones']);
        $this->assertSame(3.0, $data['thresholds']['fall_prone_s']);
    }
    public function testConfigRejectsBadSignature(): void {
        $dev = new InMemoryDeviceRepository(['pi-1' => 'sek']);
        $c = new ConfigController($dev, new InMemoryZoneRepository(), new InMemoryThresholdRepository());
        $res = $c->get($this->signed('GET', '/api/config', 'WRONG', ['device_id' => 'pi-1']));
        $this->assertSame(401, $res->status());
    }
    public function testHeartbeatStored(): void {
        $cfg = Config::fromArray([]);
        $dev = new InMemoryDeviceRepository(['pi-1' => 'sek']);
        $c = new HeartbeatController($cfg, $dev);
        $body = ['device_id' => 'pi-1', 'fps' => 12.0, 'temp' => 55.0, 'throttle' => false, 'config_version' => 7];
        $res = $c->post($this->signed('POST', '/api/heartbeat', 'sek', [], $body), now: 1000);
        $this->assertSame(200, $res->status());
        $this->assertSame(12.0, $dev->heartbeats['pi-1']['fps']);
    }
}
```

- [ ] **Step 2: 실패 확인** → FAIL

- [ ] **Step 3: 구현** — `cloud/src/Api/ConfigController.php`

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

use App\Http\{Request, Response};
use App\Security\Hmac;
use App\Repository\{DeviceRepository, ZoneRepository, ThresholdRepository};

final class ConfigController
{
    public function __construct(
        private DeviceRepository $devices, private ZoneRepository $zones, private ThresholdRepository $thresholds
    ) {}

    public function get(Request $req): Response
    {
        $deviceId = (string)$req->query('device_id');
        $secret = $deviceId !== '' ? $this->devices->secretFor($deviceId) : null;
        $nonce = $req->header('X-Nonce') ?? ''; $ts = $req->header('X-Timestamp') ?? ''; $sig = $req->header('X-Signature') ?? '';
        if ($secret === null || !Hmac::verify($secret, $nonce, $ts, $req->body(), $sig)) {
            return Response::json(['error' => 'unauthorized'], 401);
        }
        return Response::json([
            'version' => $this->devices->configVersion($deviceId),
            'zones' => $this->zones->forDevice($deviceId),
            'thresholds' => $this->thresholds->forDevice($deviceId),
        ], 200);
    }
}
```

`cloud/src/Api/HeartbeatController.php`:

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

use App\Config;
use App\Http\{Request, Response};
use App\Security\Hmac;
use App\Repository\DeviceRepository;

final class HeartbeatController
{
    public function __construct(private Config $cfg, private DeviceRepository $devices) {}

    public function post(Request $req, int $now): Response
    {
        $b = $req->json();
        $deviceId = (string)($b['device_id'] ?? '');
        $secret = $deviceId !== '' ? $this->devices->secretFor($deviceId) : null;
        $nonce = $req->header('X-Nonce') ?? ''; $ts = $req->header('X-Timestamp') ?? ''; $sig = $req->header('X-Signature') ?? '';
        if ($secret === null || !Hmac::verify($secret, $nonce, $ts, $req->body(), $sig)) {
            return Response::json(['error' => 'unauthorized'], 401);
        }
        $this->devices->touchHeartbeat($deviceId, [
            'fps' => (float)($b['fps'] ?? 0), 'temp' => (float)($b['temp'] ?? 0),
            'throttle' => (bool)($b['throttle'] ?? false), 'config_version' => (int)($b['config_version'] ?? 0),
            'at' => $now,
        ]);
        return Response::json(['ok' => true], 200);
    }
}
```

- [ ] **Step 4: 통과 + 커밋**

```bash
git add cloud/src/Api/ConfigController.php cloud/src/Api/HeartbeatController.php cloud/tests/ApiSyncTest.php
git commit -m "feat(cloud): device config + heartbeat sync API (HMAC)"
```

---

## Task 15: 프론트컨트롤러 배선 + 뷰 + .htaccess (통합)

**Files:**
- Create: `cloud/public/index.php`, `cloud/public/.htaccess`, `cloud/public/assets/{app.css,app.js,zone-draw.js}`, `cloud/src/View/{layout.php,login.php,events.php,event_detail.php,zones.php}`, `cloud/tests/WiringSmokeTest.php`

**Interfaces:**
- Consumes: 전 태스크. `Router`, 모든 컨트롤러, `PhpSessionStore`, PDO repos (T16에서 실제 구현; 여기선 배선만).
- Produces: `cloud/public/index.php` — Config 로드 → PDO repos 생성 → Router에 모든 경로 등록 → dispatch → send. 뷰는 서버렌더 PHP. **테스트는 라우팅 표만 스모크 검증**(핸들러 스텁).

라우트 표:
| method | path | handler |
|---|---|---|
| POST | /api/events | IngestController::handle |
| POST | /api/heartbeat | HeartbeatController::post |
| GET | /api/config | ConfigController::get |
| POST | /login | AuthController::login |
| POST | /logout | AuthController::logout |
| GET | /api/events | EventListController::json |
| GET | /events/{id} | EventDetailController::show |
| POST | /events/{id}/ack | EventDetailController::acknowledge |
| GET | /api/zones/{camera} | ZoneConfigController::list |
| POST | /api/zones | ZoneConfigController::save |
| POST | /api/zones/{id}/delete | ZoneConfigController::delete |
| GET | /snap/{uuid} | SnapshotProxy::serve |
| GET | /, /zones, /login | View render |

- [ ] **Step 1: 라우터 스모크 테스트** — `cloud/tests/WiringSmokeTest.php`

```php
<?php
declare(strict_types=1);
namespace App\Tests;
use App\Http\{Router, Request, Response};
use PHPUnit\Framework\TestCase;

final class WiringSmokeTest extends TestCase
{
    public function testAllRoutesRegisteredAndDispatch(): void {
        $r = new Router();
        $paths = [
            ['POST', '/api/events'], ['POST', '/api/heartbeat'], ['GET', '/api/config'],
            ['POST', '/login'], ['POST', '/logout'], ['GET', '/api/events'],
            ['GET', '/events/{id}'], ['POST', '/events/{id}/ack'],
            ['GET', '/api/zones/{camera}'], ['POST', '/api/zones'],
            ['POST', '/api/zones/{id}/delete'], ['GET', '/snap/{uuid}'],
        ];
        foreach ($paths as [$m, $p]) $r->add($m, $p, fn() => Response::json(['route' => $p]));
        $this->assertSame(200, $r->dispatch(new Request('GET', '/events/9', [], '', [], []))->status());
        $this->assertSame(200, $r->dispatch(new Request('GET', '/snap/abc', [], '', [], []))->status());
        $this->assertSame(404, $r->dispatch(new Request('DELETE', '/api/events', [], '', [], []))->status());
    }
}
```

- [ ] **Step 2: 실패/통과 확인** → 라우터만 검증(회귀 방지). `./vendor/bin/phpunit tests/WiringSmokeTest.php` → PASS.

- [ ] **Step 3: 프론트컨트롤러** — `cloud/public/index.php`

```php
<?php
declare(strict_types=1);
require __DIR__ . '/../vendor/autoload.php';

use App\Config;
use App\Http\{Request, Router, Response};
use App\Db\Database;
use App\Auth\PhpSessionStore;
use App\Repository\Pdo\{PdoDeviceRepository, PdoNonceRepository, PdoRateLimiterRepository,
    PdoEventRepository, PdoSnapshotRepository, PdoUserRepository, PdoZoneRepository,
    PdoThresholdRepository, PdoAuditRepository};
use App\Ingest\IngestController;
use App\Api\{ConfigController, HeartbeatController};
use App\Auth\AuthController;
use App\Dashboard\{EventListController, EventDetailController, SnapshotProxy, ZoneConfigController};

$cfg = Config::fromArray(require __DIR__ . '/../config.php');
$pdo = Database::connect($cfg);
$sess = new PhpSessionStore();
$now = time();

$devices = new PdoDeviceRepository($pdo);
$nonces = new PdoNonceRepository($pdo);
$rate = new PdoRateLimiterRepository($pdo);
$events = new PdoEventRepository($pdo);
$snaps = new PdoSnapshotRepository($pdo, $cfg->snapshotDir());
$users = new PdoUserRepository($pdo);
$zones = new PdoZoneRepository($pdo);
$thr = new PdoThresholdRepository($pdo);
$audit = new PdoAuditRepository($pdo);

$ingest = new IngestController($cfg, $devices, $nonces, $rate, $events, $snaps);
$config = new ConfigController($devices, $zones, $thr);
$heartbeat = new HeartbeatController($cfg, $devices);
$auth = new AuthController($users, $audit);
$list = new EventListController($events, $sess);
$detail = new EventDetailController($events, $snaps, $audit, $sess);
$proxy = new SnapshotProxy($snaps, $sess);
$zoneCtl = new ZoneConfigController($zones, $audit, $sess);

$render = function (string $view): Response {
    ob_start(); require __DIR__ . '/../src/View/' . $view . '.php';
    return Response::text((string)ob_get_clean());
};

$r = new Router();
$r->add('POST', '/api/events', fn(Request $q) => $ingest->handle($q, $now));
$r->add('POST', '/api/heartbeat', fn(Request $q) => $heartbeat->post($q, $now));
$r->add('GET', '/api/config', fn(Request $q) => $config->get($q));
$r->add('POST', '/login', fn(Request $q) => $auth->login($q, $sess, $now));
$r->add('POST', '/logout', fn(Request $q) => $auth->logout($sess));
$r->add('GET', '/api/events', fn(Request $q) => $list->json($q));
$r->add('GET', '/events/{id}', fn(Request $q, array $p) => $detail->show($q, $p));
$r->add('POST', '/events/{id}/ack', fn(Request $q, array $p) => $detail->acknowledge($q, $p));
$r->add('GET', '/api/zones/{camera}', fn(Request $q, array $p) => $zoneCtl->list($q, $p));
$r->add('POST', '/api/zones', fn(Request $q) => $zoneCtl->save($q));
$r->add('POST', '/api/zones/{id}/delete', fn(Request $q, array $p) => $zoneCtl->delete($q, $p));
$r->add('GET', '/snap/{uuid}', fn(Request $q, array $p) => $proxy->serve($q, $p));
$r->add('GET', '/', fn() => $render('events'));
$r->add('GET', '/login', fn() => $render('login'));
$r->add('GET', '/zones', fn() => $render('zones'));

$r->dispatch(Request::fromGlobals())->send();
```

- [ ] **Step 4: .htaccess** — `cloud/public/.htaccess`

```apache
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.php [QSA,L]
```

- [ ] **Step 5: 뷰 + 자산** — 서버렌더 PHP 뷰(로직 없음, 데이터는 JS가 API에서 로드):
  - `src/View/layout.php`: 공통 헤더/네비.
  - `src/View/login.php`: username/password 폼(POST /login), CSRF hidden.
  - `src/View/events.php`: 실시간 목록 컨테이너 + `<script src="/assets/app.js">`.
  - `src/View/event_detail.php`: 상세 컨테이너.
  - `src/View/zones.php`: `<canvas>` + `<script src="/assets/zone-draw.js">`.
  - `public/assets/app.css`: **색맹안전 심각도**(NF9) 클래스 — `.sev-critical`(빨강+아이콘 `⛔`+텍스트 "위급"), `.sev-high`(주황+`⚠`+"높음"), `.sev-warning`(노랑+`△`+"경고"), WCAG-AA 대비. 색 외 텍스트/아이콘 필수.
  - `public/assets/app.js`: 5초 폴링 `GET /api/events`, 심각도별 텍스트+아이콘+색, 미확인 상단고정, 확인 버튼 → `POST /events/{id}/ack`.
  - `public/assets/zone-draw.js`: canvas에 카메라 스냅샷 배경 + 클릭으로 폴리곤 점 추가, level(warning/restricted/pinch) 선택, 저장 → `POST /api/zones`; 기존 구역 `GET /api/zones/{camera}` 로드.

- [ ] **Step 6: 전체 스위트 + 커밋**

Run: `./vendor/bin/phpunit` (전체) — green.

```bash
git add cloud/public cloud/src/View cloud/tests/WiringSmokeTest.php
git commit -m "feat(cloud): front controller wiring + views + zone-draw UI"
```

---

## Task 16: PDO Repository 구현 + schema.sql + 배포 문서 (DB 게이트)

> ⚠️ **DB 통합 태스크.** 로컬에 PDO 드라이버 미로드 시 이 태스크의 DB 실행 테스트는 **게이트**(로컬에서 `pdo_sqlite` 활성 or Cafe24 MySQL). 단위 로직은 이미 T1~T15에서 mock repo로 검증됨. 이 태스크는 PDO 구현 + DDL + 배포 절차.

**Files:**
- Create: `cloud/src/Db/Database.php`, `cloud/src/Repository/Pdo/Pdo{Device,Nonce,RateLimiter,Event,Snapshot,User,Zone,Threshold,Audit}Repository.php` (9개), `cloud/schema.sql`, `cloud/docs/cloud-deploy.md`, `cloud/tests/PdoIntegrationTest.php`

**Interfaces:**
- Consumes: repository 인터페이스(T3), `Config`(T1)
- Produces: `App\Db\Database::connect(Config): PDO` (ERRMODE_EXCEPTION, prepared). 각 `Pdo*Repository`가 인터페이스 구현(전부 prepared statement).

- [ ] **Step 1: Database factory** — `cloud/src/Db/Database.php`

```php
<?php
declare(strict_types=1);
namespace App\Db;
use App\Config;
use PDO;

final class Database
{
    public static function connect(Config $cfg): PDO
    {
        return new PDO($cfg->dbDsn(), $cfg->dbUser(), $cfg->dbPass(), [
            PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
            PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
            PDO::ATTR_EMULATE_PREPARES => false,
        ]);
    }
}
```

- [ ] **Step 2: schema.sql** — MySQL DDL (P1-B 서브셋: users, devices, cameras, zones, events, event_snapshots, thresholds, nonces, rate_limits, audit_log). §7.4 스펙 기준. `event_type`/`severity`/`level`은 애플리케이션 화이트리스트(+ 선택 CHECK). `nonces(nonce PK, expires_at INDEX)`, `rate_limits(rate_key, window)` 유니크. sqlite 호환 노트(AUTOINCREMENT 등) 주석. metrics/polygon_json은 TEXT/JSON.

- [ ] **Step 3: PDO repositories (9개)** — 각 인터페이스를 prepared statement로 구현. 예 `cloud/src/Repository/Pdo/PdoNonceRepository.php`:

```php
<?php
declare(strict_types=1);
namespace App\Repository\Pdo;
use App\Repository\NonceRepository;
use PDO;

final class PdoNonceRepository implements NonceRepository
{
    public function __construct(private PDO $pdo) {}
    public function seen(string $nonce): bool {
        $st = $this->pdo->prepare('SELECT 1 FROM nonces WHERE nonce = ? LIMIT 1');
        $st->execute([$nonce]);
        return (bool)$st->fetchColumn();
    }
    public function remember(string $nonce, int $expiresAt): void {
        $st = $this->pdo->prepare('INSERT INTO nonces (nonce, expires_at) VALUES (?, ?)');
        $st->execute([$nonce, $expiresAt]);
    }
}
```

나머지 8개 동일 패턴(전부 prepared, 문자열 보간 금지):
- `PdoDeviceRepository`: secretFor(SELECT secret), touchHeartbeat(UPDATE/UPSERT), configVersion(SELECT).
- `PdoRateLimiterRepository`: `INSERT ... ON DUPLICATE KEY UPDATE count=count+1` (MySQL) 후 SELECT count. (sqlite는 UPSERT 구문 분기 or SELECT-then-INSERT/UPDATE.)
- `PdoEventRepository`: insert(INSERT, metrics=json_encode), recent(SELECT ORDER BY occurred_at DESC LIMIT, 선택 severity), find(SELECT), acknowledge(UPDATE acknowledged_by/at).
- `PdoSnapshotRepository`: add(INSERT), forEvent(SELECT), pathByUuid(=`snapshotDir/uuid.jpg`, 존재 시).
- `PdoUserRepository`: byUsername(SELECT), recordFailure(UPDATE), clearFailures(UPDATE).
- `PdoZoneRepository`: forDevice/forCamera(SELECT), save(UPSERT by zone_id or INSERT), delete(DELETE).
- `PdoThresholdRepository`: forDevice(SELECT key/value → assoc).
- `PdoAuditRepository`: append(INSERT, before/after=json_encode).

- [ ] **Step 4: (게이트) sqlite 통합 테스트** — `cloud/tests/PdoIntegrationTest.php`:

```php
protected function setUp(): void {
    if (!in_array('sqlite', \PDO::getAvailableDrivers(), true)) {
        $this->markTestSkipped('pdo_sqlite not available on this host');
    }
    // create sqlite :memory:, load sqlite-compatible DDL, then round-trip Pdo*Repository
}
```

로컬 PDO 미로드 환경에서도 `markTestSkipped`로 스위트 green 유지.

- [ ] **Step 5: 배포 문서** — `cloud/docs/cloud-deploy.md`: Cafe24 업로드 절차(`public/`만 웹루트; `storage/`·`src/`·`config.php`는 웹루트 밖 또는 상위 디렉토리), `config.php` 작성(config.example.php 복사), `schema.sql` phpMyAdmin import, per-device secret 발급(admin), 최초 admin 계정 생성 CLI 스니펫(`password_hash` argon2id), HTTPS/HSTS 강제, PHP 버전·gd·openssl 확인, `vendor/`는 배포 제외(런타임 의존성 0), storage/snapshots 쓰기권한.

- [ ] **Step 6: 전체 스위트 + 커밋**

Run: `./vendor/bin/phpunit` — green(통합은 sqlite 없으면 skip).

```bash
git add cloud/src/Db cloud/src/Repository/Pdo cloud/schema.sql cloud/docs/cloud-deploy.md cloud/tests/PdoIntegrationTest.php
git commit -m "feat(cloud): PDO repositories + schema + Cafe24 deploy doc"
```

---

## Self-Review

**1. Spec coverage (P1-B 범위):**
- Ingest HMAC+nonce+timestamp+ratelimit+재인코딩+웹루트밖 → T2·T5·T7 ✓ (NF5, §7.3)
- 인증/RBAC/세션/brute-force → T8·T9·T10 ✓ (NF7, §7.1)
- 최소 대시보드(목록·상세·확인)+스냅샷 프록시 → T12 ✓ (§7.2)
- 구역설정 UI(폴리곤 드로잉·저장) → T13·T15 ✓ (사용자 결정; **P1-A zone-loading 갭 해소** — Pi가 GET /api/config로 zones 폴링→ZoneIntrusionDetector 주입)
- config/heartbeat 동기 API → T14 ✓ (§7.3)
- DB schema+PDO+prepared → T3·T16 ✓ (§7.4, §9.2)
- audit 로그(확인·구역·로그인) → T10·T12·T13 ✓ (append; 해시체인 무결성은 P3)
- 색맹안전 심각도 → T15 뷰 ✓ (NF9)
- **P1-B 범위 밖(다른 단계):** 에스컬레이션·온콜·119(P3), 컴플라이언스 UI(사용자가 구역설정 선택 → 컴플라이언스는 P1-B-2/P2), 감도 다이얼·플릿·통계(P2/P3), legal-hold·해시체인 audit(P3), CSRF 토큰 실제 폼 강제(T8에 헬퍼 있음; 뷰/컨트롤러 강제는 T15 폼 + 후속).

**2. Placeholder scan:** 코드 스텝 모두 실제 PHP. T15 뷰/JS와 T16 PDO 8개·schema.sql은 인터페이스 시그니처(T3)·라우트표가 명확해 기계적 구현(각 지시에 SELECT/INSERT 매핑 명시). T16 DB 실행은 의도적 게이트.

**3. Type consistency:** 컨트롤러 소비 repo 시그니처가 T3 정의와 일치; `Request/Response`·`SessionStore`·`Hmac::verify`·`Rbac::can` 시그니처 태스크 간 일치. Ingest/Config/Heartbeat HMAC 검증이 P1-A `sign(nonce+ts+body)`와 동일(T2 테스트가 계약 고정).

**주의(구현자):** (a) InMemory `recordFailure`/`clearFailures`가 저장 배열 참조 갱신 → 다음 `byUsername` 반영(T10 잠금 테스트 전제). (b) Ingest 테스트 스냅샷 디렉토리 setUp 생성. (c) T15 스모크는 라우터 회귀만 검증(실제 컨트롤러 배선은 T16 PDO 완성 후 통합 구동).

---

## Execution Handoff

**Plan complete. 저장: `docs/superpowers/plans/2026-07-11-p1b-cloud-ingest-dashboard.md`.**

실행 옵션:
1. **Subagent-Driven (추천)** — 태스크마다 새 subagent + 리뷰. `superpowers:subagent-driven-development`.
2. **Inline Execution** — 이 세션 순차 실행. `superpowers:executing-plans`.

어느 방식으로?