uniplatetracker

UniPlateTracker는 UniFi Protect 카메라에서 캡처한 라이선스 플레이트를 추적하기 위한 셀프 호스팅, 프라이빗 대시보드입니다. UniFi NVR에서 웹훅을 통해 감지 이벤트를 수신하고, PostgreSQL 데이터베이스에 기록하며, 웹 인터페이스를 통해 차량 활동을 조회, 검색, 분석할 수 있습니다. 썸네일과 비디오 파일은 사용자의 서버에 저장되며, UK DVLA 조회는 유일한 외부 데이터 소스로 설명되어 있습니다. 주요 기능 - 실시간 이벤트 처리: UniFi Protect 웹훅에서 라이선스 플레이트 감지가 도착하면 즉시 처리됩니다. - 온디맨드 비디오 캡처: 별도의 Node.js 워커가 각 감지에 대해 카메라의 RTSP 스트림에서 짧은 클립을 녹화하며, 사전/사후 이벤트 버퍼링은 별도의 버퍼 관리자 프로세스에서 처리합니다. - 선택적 DVLA 통합 (UK): 차량의 제조사, 색상, 세금, MOT 상태 등의 세부 정보를 가져옵니다. 국제 모드에서는 UK 특정 기능을 비활성화하여 다른 지역에서도 실행할 수 있지만, 비-UK 플레이트는 ENABLE_INTERNATIONAL_API가 구성되지 않으면 "Unknown"으로 표시됩니다. - 관리자 대시보드: 차트와 사용 통계가 포함된 보호된 관리자 영역이며, 초기 관리자가 다른 관리자에게 접근 권한을 부여하거나 취소할 수 있는 계층적 관리자 계정을 지원합니다. 이러한 작업은 검토를 위해 감사 추적에 기록됩니다. - 감지 테이블: 밀도가 높고 정렬 가능한 테이블로, 빠른 읽기를 위해 설계되었습니다. 정렬과 필터링은 데이터베이스에서 실행되므로, 현재 페이지뿐만 아니라 전체 결과 세트에 적용되며, 좁은 화면에서는 카드 목록으로 리플로우됩니다. - 상태 강조 표시: 유효한 MOT를 가진 세금 납부 차량은 시각적으로 조용히 유지되고, 만료, 미납, SORN 차량은 강조 표시됩니다. "DVLA 기록 없음"은 구별되는 빈, 점선 칩으로 표시되어 누락된 정보가 깨끗한 결과로 읽히지 않도록 합니다. - 접근성: 레이블이 지정된 컨트롤, 키보드 조작 가능한 정렬 및 페이징, 테이블의 aria-sort, prefers-reduced-motion 지원. 프로젝트는 제로 위반으로 감사되었다고 명시되어 있습니다. 밝은/어두운 모드는 시스템 기본 설정을 따릅니다. 기술 스택 Next.js 16 (App Router) with TypeScript, React 19, Tailwind CSS v4 및 shadcn/ui; Next.js API 라우트와 별도의 Node.js 워커/버퍼 관리자; 저장소로 PostgreSQL; 비디오 처리로 FFmpeg; UniFi Protect 웹훅 및 DVLA API와의 통합. Tailwind v4는 CSS에서 테마를 가져오므로 tailwind.config.ts는 없으며, 디자인 토큰, 플레이트 및 상태 스타일은 src/app/globals.css의 @theme 블록에 있습니다. 배포 문서화된 기준은 UVC-AI-Pro 카메라 (디바이스 버전 5.1.57) 및 UniFi Protect 9.4.19가 설치된 Debian 12입니다. 다른 구성도 작동할 것으로 예상됩니다. 두 가지 방법이 설명되어 있습니다. - 수동 설치: Node.js 20+, PostgreSQL, FFmpeg 설치; 예제 환경 파일을 .env.local로 복사하고 POSTGRES_URL, SESSION_SECRET 등의 값을 채움; 비디오 캡처를 활성화한 경우 버퍼 및 최종 캡처 디렉토리 생성; 앱과 워커 모두에 대해 종속성 설치; npm run db:init을 실행하여 테이블 생성 및 첫 번째 관리자 이메일 등록; 앱 빌드 및 시작, 선택적으로 PM2로 지속성 유지. - Docker: compose 파일과 환경 템플릿 다운로드, .env.local로 이름 변경, POSTGRES_URL, SESSION_SECRET, NEXTAUTH_URL (localhost 대신 서버의 네트워크 IP 사용) 제공; 일회성 컨테이너를 실행하여 데이터베이스 초기화 및 첫 번째 관리자 생성; Docker Compose로 풀링 및 시작. 웹 인터페이스는 포트 3000, 웹훅 엔드포인트는 포트 4000에서 문서화되어 있습니다. UniFi Protect에서 알람은 Settings > System > Other Settings > Alarm Manager에서 생성되며, ID > LPR에서 알려지지 않은 및 알려진 차량에 대해 트리거되고, LPR 카메라에 스코프되며, 썸네일을 활성화한 상태로 앱의 /webhook URL을 가리킵니다. 문제 해결 노트 감지는 "No clip"으로 표시될 수 있는데, 이는 감지와 캡처가 별도의 경로이기 때문입니다. 웹훅은 행을 쓰지만 워커는 RTSP에서 녹화하므로, 감지는 계속 도착하더라도 캡처가 실패할 수 있습니다. 확인해야 할 사항은 VIDEO_FINAL_CAPTURE_PATH의 최신 파일 날짜, FFmpeg가 여전히 설치되어 있고 예상 경로에 있는지, 카메라 자격 증명이나 RTSP URL이 유효한지, 두 백그라운드 프로세스가 살아 있는지, 앱을 실행하는 사용자가 캡처 디렉토리를 읽을 수 있는지입니다. 점선 "No clip" 타일은 클립이 예상되었지만 누락된 경우이고, 단순한 카메라 아이콘은 감지가 이를 참조하지 않은 경우입니다. 비디오 및 썸네일 요청은 파일 이름이 문자, 숫자, 점, 하이픈, 밑줄만 포함하고 .mp4 또는 .jpg 확장자를 가진 경우에만 404를 반환하지 않으며, 정규화할 때 경로가 변경되면 거부되므로 디렉토리 트래버설은 캡처 디렉토리를 벗어나지 못합니다. 차량 세부 정보가 "Unknown"으로 표시되면 DVLA에 해당 등록 번호에 대한 기록이 없거나 조회가 실패한 것입니다.