9c0cfd2fea
두 유형은 타입 정의(edge/events.py)·서버 검증(EventValidator)·콘솔 필터· 통보 라벨까지 전 구간에 있었으나 생성하는 코드가 어디에도 없었다. 실제로 값을 넣는 것은 seed_demo.php 뿐이었고, 소개서가 내세운 "17종"은 15종이었다. 앞서 고친 EventValidator 누락과 정확히 반대 방향의 같은 병이다. 그때는 감지기가 있는데 서버가 막았고, 이번엔 서버·UI가 열려 있는데 감지기가 없다. 어느 쪽이든 화면은 멀쩡해 보인다. 엣지가 낼 수 없는 유형이라 서버에 둔다 — 전원·회선이 끊긴 노드는 자기가 죽었다고 신고할 수 없다. 하트비트의 부재로만 관측된다. App\Alert\DeviceHealthWatch: - dispatch_alerts.php 1분 크론의 1단계. 에스컬레이션·통보보다 앞에 두어 같은 실행 안에서 발행된 장치 이벤트가 곧바로 통보 대상이 되게 했다. - 멱등은 EscalationWatch와 같은 방식(event_uuid UNIQUE 충돌)이되, 장치 건전성은 연속 상태라 uuid 앵커를 '장애 구간의 시작'으로 잡았다. device_fault는 last_heartbeat_at(장애 내내 불변) → 장애당 정확히 1건. monitoring_degraded는 창 안의 마지막 정상 하트비트 ts. 창 전체가 저하면 시작을 볼 수 없으므로 창 버킷으로 폴백해 시간당 1회 재고지한다 — 의도된 리마인더이고, 매 틱 재발행하는 앵커 드리프트가 아니다. - 성능 저하는 지속을 요구(기본 5분). 한 번 튄 값에 울리면 운영자가 이 유형을 무시하게 되고, 그러면 감시가 멈춘 날에도 아무도 보지 않는다. 엣지 감지기들이 쓰는 규율과 같다. - 하트비트를 한 번도 보낸 적 없는 장치는 장애가 아니다(미설치 노드). 새 현장 첫날이 빨간 벽이 되면 그 사이트는 이 유형을 영영 신뢰하지 않는다. - 죽은 노드에 degraded를 겹쳐 내지 않는다 — 한 고장에 두 알람은 소음이다. - fps NULL을 0으로 강압하지 않는다(측정 실패 ≠ 정지). PdoDeviceMetric Repository가 NULL을 지키는 이유와 같다. - 억제(정비 모드)는 여기서 보지 않는다. 기록은 남기고 통보 여부는 AlertDispatcher가 정한다 — 정비 창은 전화를 끄는 것이지 노드가 죽었던 기록을 지우는 것이 아니다. camera_id는 NOT NULL인데 장치 단위 이벤트에는 카메라가 없다. '__device__' 센티넬을 쓰고, 콘솔은 "장치 전체"로 표시, 구역 편집기 카메라 목록에서는 제외한다(카메라 목록은 보고된 이벤트에서 파생되므로, 두면 존재하지 않는 카메라에 구역을 그리려는 일이 생긴다). 설정 4종 추가(device_stale_seconds 180 · degraded_sustain_seconds 300 · degraded_fps_ratio 0.6 · target_fps 12) — 두 config 템플릿에 한국어 설명과 함께. 낮은 프레임으로 운용하는 현장이 target_fps를 안 맞추면 전 노드가 영구 저하로 보고되므로 그 경고를 템플릿에 적었다. 검증: pytest 308 passed(3 skip: 모델 미동봉·shellcheck 미설치·AF_UNIX, 기존과 동일) · phpunit 240 passed(신규 16). dist 재생성으로 패리티 회복.
91 lines
7.3 KiB
Markdown
91 lines
7.3 KiB
Markdown
# PROJECT_MAP — move_detect
|
|
|
|
> 작업 전 이 문서로 위치를 찾고 필요한 파일만 연다 (전체 재스캔 금지).
|
|
> 새 파일·라우트·스키마 변경 시 해당 섹션을 갱신할 것.
|
|
|
|
## 개요
|
|
|
|
작업장 안전 AI CCTV. Raspberry Pi 5 + Hailo-8 엣지 추론(Python) → HMAC POST → Cafe24
|
|
웹호스팅 PHP+MySQL 대시보드. 감지: 넘어짐 · 넘어짐 후 미동 · 장시간 부동 · 위험구역
|
|
침입(경고/절대금지/협착) · 유령사고(위험 상태로 소실). 스냅샷만 전송, 라이브뷰·영상 없음.
|
|
|
|
## edge/ (Python — Pi에서 구동)
|
|
|
|
| 파일 | 역할 |
|
|
|------|------|
|
|
| `app.py` | `run_once` 파이프라인 (프레임→추론→추적→감지→스냅샷→전송). ambiguous 리셋·stale 필터 |
|
|
| `engine.py` | `EventEngine` — 감지기 오케스트레이션, 쿨다운 dedup, 트랙 forget |
|
|
| `tracking.py` | `IouTracker` — 전역 그리디 IoU 매칭, `ambiguous()` (교차 경합 트랙) |
|
|
| `detectors/` | `fall.py`(FALLING→FALLEN→NO_MOTION, sustained prone) · `immobility.py` · `ghost.py` · `zone.py` · `occupancy.py`(존 규칙: 2인1조/정원/체류상한 — Zone.rules 소비) |
|
|
| `smoothing.py` | 트랙별 키포인트 스무딩 풀 |
|
|
| `snapshot.py` | RingBuffer · FaceBlurrer(PIPA) · Snapshotter |
|
|
| `alert.py` / `serverclient.py` | HMAC+nonce POST, 커스텀 UA, no-redirect |
|
|
| `queue.py` | 오프라인 전송 큐 |
|
|
| `config.py` | env → Config (빈 CAFE24_URL/SECRET는 기동 실패) |
|
|
| `daemon.py` / `runtime.py` / `health.py` | 상주 루프 · 하트비트 텔레메트리 |
|
|
| `adapters/` | hailo_pose · movenet_pose(CPU 폴백) · picamera_source(CSI) · uvc_source(USB) |
|
|
| `probe.py` / `tools/` | 카메라 사전 점검 · HEF/모델 fetch (빌드머신 전용) |
|
|
| `beacon.py` | 현장 경광등·부저 (GPIO). **네트워크 없이 동작하는 유일한 통보 경로** — /api/config 의 `beacons` 로 설정 수신, 하드웨어 없으면 NullBeacon 으로 폴백 |
|
|
| `tuning.py` | 서버 임계값 → 살아 있는 감지기에 적용. 이전에는 `thresholds_from_config()` 가 파싱만 하고 버려서 관리자 변경이 장비에 닿지 않았다 |
|
|
| `detectors/integrity.py` | 카메라 화각 이동·가림·조도 저하 (`camera_moved`/`camera_obstructed`/`low_light`). 존 판정이 조용히 무의미해지는 실패 모드를 드러낸다 |
|
|
| `detectors/pending.py` | 보호구·중장비 근접·화재 — 배선/계약 완료, **모델 미확보로 기본 비활성** (AGPL 아닌 가중치 + HEF 컴파일 필요) |
|
|
|
|
## server/ (PHP 8 + PDO — Cafe24)
|
|
|
|
- 진입: `public/index.php` (라우트 전부 여기),
|
|
뷰: `src/View/{layout,events,login,zones,report,event_detail,admin,compliance,setup,incident_package}.php`
|
|
- `src/Alert/`: `AlertDispatcher`(어떤 통보를 낼지 결정 — 순수 로직, I/O 없음) ·
|
|
`Channels`(email/webhook 발송; `local` 은 엣지가 자체 GPIO 로) · `EscalationWatch`(미확인 위급 →
|
|
`unacked_escalation` 이벤트 발행, event_uuid 로 멱등) ·
|
|
`DeviceHealthWatch`(하트비트 부재 → `device_fault`, 지속 성능저하 → `monitoring_degraded`;
|
|
엣지가 낼 수 없는 두 유형을 서버가 발행. uuid 앵커 = 장애 구간 시작이라 장애당 1건)
|
|
- `src/Api/ThresholdCatalog.php`: 편집 가능한 튜너블의 화이트리스트 + 범위 + 한국어 설명.
|
|
목록에 없는 키는 API 로 저장 불가 (장비가 조용히 무시하는 값을 "설정됨"으로 보이지 않게)
|
|
- `tools/`: `dispatch_alerts.php`(크론 1분) · `maintain.php`(크론 일 1회, 보존기간) ·
|
|
`backup.php`(DB 덤프+스냅샷) · `verify_audit_chain.php`(감사 무결성) · `seed_demo.php`(시연·QA).
|
|
전부 CLI 전용(`bootstrap.php` 가 SAPI 검사), 납품 시 `move_detect_app/tools/` 로 www 밖에 배치
|
|
- 라우트: `POST /api/events`(ingest, HMAC) · `POST /api/heartbeat` · `GET /api/config` ·
|
|
`GET /api/events` · `GET /api/devices` · `GET /api/heatmap/{camera}`(spatial 집계) ·
|
|
`GET /api/fp-stats`(오탐율) · `GET/POST /api/zones*` · `POST /login|/logout` ·
|
|
`GET /snap/{uuid}` · `POST /events/{id}/ack` · `POST /events/{id}/false-positive`(오탐 태그,
|
|
ack 겸함) · `GET /api/report`(운영 지표+시간패턴+전조경보+추이) ·
|
|
`GET /api/export/labels`(라벨 JSONL, 관리자) · `GET/POST /api/actions`(개선 조치·전후 효과) ·
|
|
`GET /api/devices/{id}/metrics`(성능 시계열) · `GET/POST /api/admin/thresholds*`(임계값 편집,
|
|
admin) · `GET/POST /api/admin/channels*`(통보 채널, admin) · `GET/POST /api/suppressions*`(정비
|
|
억제) · `GET/POST /api/risks*`(위험성평가) · `GET/POST /api/handovers`(교대 인수인계) ·
|
|
`GET /api/events/{id}/package`(사고조사 패키지) ·
|
|
페이지 `/`, `/login`, `/zones`, `/report`(안전 리포트), `/compliance`(안전 관리),
|
|
`/admin`(시스템 설정), `/setup`(설치 점검), `/events/{id}/view`, `/events/{id}/package/view`
|
|
- `src/Ingest/` HMAC+nonce+rate-limit+replay 방지 · `src/Auth/` argon2id/세션/RBAC/CSRF ·
|
|
`src/Dashboard/` 이벤트목록·디바이스상태·존편집·스냅샷프록시·시스템설정·억제·규정 ·
|
|
`src/Alert/` 통보 결정·발송·에스컬레이션 · `src/Repository/` 14종 (인터페이스+PDO)
|
|
- 감사로그는 **해시체인**(prev_hash/entry_hash). 수정·삭제·우회삽입이 전부 탐지된다 —
|
|
`tools/verify_audit_chain.php`, 손상 시 종료 코드 1
|
|
- 프런트: `public/assets/app.js`(이벤트 콘솔 — 엄격 시간순 정렬 · 뷰모드(전체/미확인만) ·
|
|
날짜 조회(커서 시딩) · 확인 제자리 전환+토스트 · 오탐 2단계 · 경보음 음소거 · 날짜 구분선) ·
|
|
`device-tree.js`(장치→카메라 트리 레일) · `zone-draw.js`(장치·카메라 선택기 · 존 채움/라벨칩 ·
|
|
삭제 2단계) · `detail.js`(상세 + 확인/오탐 판정) · `report.js`(표본·유의성 게이트) · `app.css`
|
|
- UI 불변식: 스트림 정렬은 **항상 occurred_at 내림차순** — 확인 상태가 순서를 바꾸면 안 됨
|
|
(연대기 = 사고 재구성 근거). 처리 큐는 정렬이 아니라 필터(`filters.unackedOnly`)로만 만든다.
|
|
- 페이지 명칭은 nav 라벨 · `<h1>` · `<title>` 세 곳이 동일 문자열 (`이벤트`/`구역 설정`/`안전 리포트`).
|
|
날짜 표기는 `YYYY-MM-DD` 로 3개 화면 통일 (각 파일의 로컬 `formatTime`/`fmtDate`).
|
|
- DB: `schema.sql` (테이블 prefix `move_`), 마이그레이션 `migrations/`.
|
|
존 행의 `rules_json`(선택) = 점유 규칙 {min_workers,max_workers,max_dwell_s} — 편집기 저장 시
|
|
ZoneConfigController가 검증, /api/config로 엣지 전달
|
|
- 배포: `server/deploy/build_cafe24_package.sh` → zip, `server/docs/server-deploy.md`
|
|
|
|
## deploy/ · dist/ (납품)
|
|
|
|
- `deploy/`: Pi 설치 — `setup_online.sh`, `bundle/build_offline_bundle.sh`(폐쇄망),
|
|
`systemd/move-detect-edge.service`, `device.env`(사전 프로비저닝)
|
|
- `dist/`: `1_cafe24_upload/` · `2_pi_install/` · `PROVISION_SECRETS.md`
|
|
|
|
## tests/
|
|
|
|
- Python: `tests/` 31파일 (pytest) — 하드웨어 필요 테스트는 `tests/hardware/` + skip 마커
|
|
- PHP: `server/tests/` 19파일 (phpunit, in-memory repo; PDO 통합은 skip 게이트)
|
|
|
|
## docs/
|
|
|
|
`delivery-audit.md`(감사 43건, 전부 완료 — OFF-HW 실장비 검증만 잔여) · `pilot-runbook.md` ·
|
|
`hardware-bringup.md` · `INDEX.md`(작업 기록)
|