feat: add live Gen5W telemetry dashboard

README.md

@@ -23,6 +23,8 @@ Car는 차량 모뎀/게이트웨이에서 받은 상태를 수집해 DB에 저
 - 수집 공백을 반영한 차량 상태 경과 시간 표시
 - 도어/경계/시동/공조 상태 해석
 - 실시간 차량 도어/트렁크 열림 표시
+- Gen5W 헤드유닛의 약 2,000개 MQTT 지표를 5초 snapshot으로 결합한 실시간 텔레메트리 패널
+- 주행·전원, HEV·12V, 도어·안전, 공조, 내비 안내, 헤드유닛·미디어 상태의 반응형 요약
 - PWA icon 제공
 
 ## 주요 API
@@ -31,6 +33,7 @@ Car는 차량 모뎀/게이트웨이에서 받은 상태를 수집해 DB에 저
 - `api.php?action=command`: 차량 명령 전송
 - `monitor.php?mode=ajax`: monitor 상태 AJAX
 - `monitor.php?mode=usage`: 데이터 사용량 AJAX
+- `monitor.php?mode=telemetry`: 인증된 브라우저용 Gen5W MQTT 텔레메트리 요약
 - `monitor.php?mode=usage-calibration`: 관리자 전용 데이터 사용량 보정 기준점 조회/저장
 - `monitor.php?mode=auth-login`: 브라우저 직접 접근 비밀번호 화면용 공통 암호 검증
 
@@ -73,6 +76,51 @@ Car는 차량 모뎀/게이트웨이에서 받은 상태를 수집해 DB에 저
 - Car DB tables: 차량 상태, 로그, 차트용 기록, TCP 요청 큐
 - 사용량 수집값, 통신사 과금 단위 추정값, 월별 보정 기준
 - `/volume1/web/config/car.php`: TCP, DB, token, 허용 IP 설정
+- `/volume1/web/config/car-mqtt.php`: 읽기 전용 MQTT 계정과 Tailscale 연결 설정
+- `/volume1/web/config/car-cache/telemetry.json`: 웹 계정만 읽는 retained snapshot 단기 캐시
+
+## Gen5W MQTT 텔레메트리
+
+`NiroTelemetrySnapshot.php`는 차량이 5초마다 발행하는 retained `niro/gen5w/state`와 availability `niro/gen5w/status`를 읽습니다. 브라우저에는 약 2,000개 원시 snapshot 전체를 보내지 않고 운전에 의미 있는 선별 지표와 수집 상태만 반환합니다. 현재 화면은 다음 정보를 결합합니다.
+
+- 주행 상태, 속도, 기어, 주차 브레이크, 카메라 상태와 주행 가능 거리
+- 12V SOC, LDC 충전, HEV 모드·충전 상태, 모터 사용과 누적 주행거리
+- 네 도어의 열림·잠금, 트렁크, 등화, 안전벨트와 DTC 경고
+- 공조 전원, A/C, AUTO·DUAL, 풍량, 좌우 설정 온도와 외기 온도
+- 경로 안내, 다음 회전 거리, 제한 속도, 경로 이탈과 단속 지점 정보
+- MICOM 연결, 부팅, 헤드유닛·AV 전원, 미디어 소스와 음량
+
+차량 세대상 제공하지 않는 값은 `-1`, `255`, `65535`, `4294967295`, `0xff`, `0xffffffff` sentinel로 구분해 `미지원`으로 표시합니다. 값의 존재만으로 기능이 활성화됐다고 판단하지 않으며, 원시 ECU 쓰기나 제어 명령은 MQTT 경로에서 수행하지 않습니다.
+
+Synology Tailscale 패키지는 userspace networking으로 실행되어 일반 `tcp://100.x.x.x` 소켓에 Tailnet route가 생기지 않습니다. 따라서 `transport=tailscale_nc`일 때 PHP는 shell을 거치지 않는 `proc_open()` 배열 명령으로 Tailscale CLI의 `nc` 스트림을 열고 그 위에서 MQTT 3.1.1을 처리합니다. 호스트명은 영문·숫자·점·밑줄·하이픈만 허용하고 포트는 정수 범위로 제한합니다.
+
+비밀 설정 예시는 다음과 같습니다. 실제 비밀번호는 Git에 넣지 않습니다.
+
+```php
+<?php
+return [
+    'transport' => 'tailscale_nc',
+    'tailscale_binary' => '/var/packages/Tailscale/target/bin/tailscale',
+    'host' => 'raspberry',
+    'port' => 1883,
+    'username' => 'car_dashboard',
+    'password' => '비공개 읽기 전용 비밀번호',
+    'state_topic' => 'niro/gen5w/state',
+    'availability_topic' => 'niro/gen5w/status',
+    'cache_path' => '/volume1/web/config/car-cache/telemetry.json',
+    'cache_ttl' => 4,
+    'stale_after' => 20,
+    'timeout' => 3.0,
+];
+```
+
+`car_dashboard` MQTT 계정은 `niro/gen5w/state`와 `niro/gen5w/status` 두 topic의 read 권한만 가집니다. `NiroTelemetrySnapshot.php`는 같은 웹 요청이 1초마다 반복돼도 broker snapshot은 최대 4초 동안 웹 전용 캐시에서 재사용합니다. 새 수집이 실패하면 직전 cache를 표시하되 `stale`과 cache fallback 상태를 함께 반환합니다.
+
+요약 계약 회귀시험은 CLI에서만 실행됩니다.
+
+```bash
+php tests/NiroTelemetrySnapshotTest.php
+```
 
 ## 처리 흐름
 
@@ -124,6 +172,8 @@ Worker 교체나 예외 종료로 `processing`, `ui_timeout_pending` 상태가
 
 - 차량 API는 API token 또는 허용 IP 정책을 사용합니다.
 - 차량 모니터 화면과 `monitor.php?mode=ajax`, `monitor.php?mode=usage`는 런처 공통 인증 쿠키 또는 사이트 관리자 세션이 유효할 때만 응답합니다.
+- `monitor.php?mode=telemetry`도 동일한 브라우저 인증을 통과해야 하며 원시 MQTT snapshot과 broker 비밀번호는 응답하지 않습니다.
+- MQTT 계정은 표시 topic 두 개만 읽을 수 있고 publish 권한이 없습니다. 비밀 파일과 snapshot cache는 저장소 밖에 두고 웹 실행 계정만 읽도록 유지합니다.
 - `monitor.php?mode=usage-calibration`은 사이트 관리자 세션이 확인될 때만 응답합니다. 일반 PIN 쿠키로 들어온 사용자는 화면에서 설정 아이콘이 보이지 않고, 직접 API를 호출해도 차단됩니다.
 - 공통 암호로 로그인한 일반 인증은 30분 유지하고, 사이트 관리자 세션이 확인되면 관리자 장기 쿠키를 발급해 PWA에서 반복 인증이 뜨는 일을 줄입니다.
 - PWA로 설치한 차량 모니터는 manifest 시작 URL `/car/monitor.php?pwa=1`로 진입합니다. 이 요청은 기존 공통 인증 쿠키가 있으면 유지하고, 사이트 관리자 세션이면 관리자 쿠키를 발급한 뒤 `/car/monitor.php`로 되돌아가므로 설치형 앱 진입 때 반복 PIN 화면이 뜨는 일을 줄입니다.