# LK Camera Switch Aplicativo desktop Windows para visualizar, alternar e gravar streams RTSP de câmeras IP Yoosee na rede local. ## Masterplan - Entregar um monitor local simples para portões, ruas, ranchos e outros pontos com câmeras IP, sem depender do aplicativo Yoosee ou de nuvem. - Permitir que operadores visualizem uma câmera por vez, naveguem manualmente ou alternem automaticamente entre câmeras habilitadas. - Priorizar a conexão RTSP via FFmpeg incluído no instalador Electron, com mensagens claras para streams indisponíveis. - Persistir cadastro, preferências e credenciais localmente no perfil do usuário Windows; senhas são protegidas com `safeStorage`. - Manter a primeira versão focada em preview, troca de câmera, teste de conexão e gravação MP4. ## Tech Stack & Architecture - **UI:** React + TypeScript, iniciado em `src/main.tsx`. - **Build web:** Vite (`vite.config.ts`), gerando `dist/`. - **Navegação:** `react-router-dom` com `HashRouter` em `src/App.tsx`. Rotas funcionam no Electron sem servidor HTTP externo. - **Desktop Windows:** Electron: - Processo principal: `electron/main.cjs` - Bridge segura: `electron/preload.cjs` - Renderer: build React carregado de `dist/index.html` - **Vídeo e gravação:** `ffmpeg-static`, executado pelo processo Electron principal. - Preview RTSP é convertido para **MJPEG** a 10 fps e exposto somente em `127.0.0.1` por um servidor HTTP temporário. - Gravação recebe o RTSP diretamente e salva MP4 localmente. - Há apenas um processo de preview e um processo de gravação ativos por vez. - **Ícones:** `lucide-react`. - **Fonte:** Inter carregada pelo Google Fonts em `index.html`. - **Persistência:** - No Electron: arquivo `lk-camera-switch-state.json` em `app.getPath('userData')`. - Senhas são criptografadas antes de gravar usando `safeStorage`. - No preview web, `src/lib/storage.ts` usa o KV exposto em `window.genmb.kv`; senhas não devem ser consideradas armazenamento seguro nesse modo. - **Estado:** `App.tsx` é o controlador central do estado de interface: - `appState`: câmeras e configurações persistidas. - `currentCameraId`, `autoSwitching`, `paused`, `recording`. - `nativeAvailable` e `nativeStreamUrl` para capacidades Electron/FFmpeg. - **Padrão importante:** componentes de páginas recebem estado e callbacks do `App.tsx`; não criar stores globais paralelos. ## File Structure ```text electron/ ├── main.cjs # Processo principal: janela, persistência, FFmpeg, RTSP, gravação e IPC. ├── preload.cjs # API segura window.lkCamera para o renderer. └── README.md # Instruções para criar o instalador NSIS Windows. src/ ├── main.tsx # Bootstrap React, StrictMode, CSS e AppErrorBoundary. ├── App.tsx # Estado central, rotas, persistência, troca automática e conexão de stream. ├── types.ts # Tipos Camera, Settings, AppState, status e seedState inicial. ├── pages/ │ ├── HomePage.tsx # Monitor principal: vídeo, controles, gravação e troca automática. │ ├── CamerasPage.tsx # Cadastro, ativação, edição, teste e exclusão de câmeras. │ ├── SettingsPage.tsx # Preferências de gravação, inicialização, volume, tela cheia e intervalo. │ └── NotFoundPage.tsx # Estado para rota inexistente. ├── components/ │ ├── AppLayout.tsx # Cabeçalho e navegação Monitor/Câmeras/Configurações. │ ├── CameraFormModal.tsx # Formulário com validação para criar/editar câmera. │ ├── ConfirmDeleteModal.tsx # Confirmação de exclusão permanente. │ ├── Modal.tsx # Modal acessível com Escape e retenção de foco. │ ├── Button.tsx # Botão compartilhado e variantes visuais. │ ├── StatusPill.tsx # Indicador ONLINE/CONECTANDO/OFFLINE. │ ├── Toast.tsx # Avisos temporários de sucesso, erro e informação. │ └── AppErrorBoundary.tsx # Evita tela totalmente em branco em erro de renderização. ├── lib/ │ ├── storage.ts # Abstração de persistência Electron/KV e normalização de estado. │ └── utils.ts # cn(), safeState() e makeStreamUrl(). └── styles/ └── main.css # Tokens visuais e classes utilitárias da interface. index.html # HTML raiz, Inter e SDK KV usado no preview web. package.json # Scripts, dependências Electron/Vite e configuração de empacotamento. vite.config.ts # Configuração do Vite. ``` ## Key Features ### Cadastro de câmeras O modelo `Camera` em `src/types.ts` inclui: - `id` - `name` - `ip` - `port` - `username` - `password` - `protocol` (`rtsp` ou `http`) - `streamUrl` - `enabled` - `status` (`online`, `offline` ou `checking`) - `lastError` opcional O estado inicial inclui a câmera **PORTÃO** com IP `192.168.5.5`. Novas câmeras recebem `crypto.randomUUID()` em `src/components/CameraFormModal.tsx`. Regras: - Nome, IP e porta são obrigatórios no formulário. - A porta deve estar entre 1 e 65535. - URL manual, se informada, deve iniciar com `rtsp://`, `http://` ou `https://`. - O nome salvo é normalizado para maiúsculas. - Câmeras desativadas não participam da navegação nem da troca automática. - Exclusão remove a configuração salva; não há lixeira. ### Construção de URL RTSP `makeStreamUrl()` em `src/lib/utils.ts` usa `streamUrl` quando preenchida. Caso contrário, monta: ```text {protocol}://{usuario}:{senha}@{ip}:{porta} ``` Credenciais são codificadas com `encodeURIComponent`. Isso gera uma URL base, sem caminho RTSP específico; muitas Yoosee exigem um caminho fornecido pelo fabricante. Nesses casos, a URL RTSP manual é obrigatória. ### Preview de vídeo No desktop, `App.tsx` chama `window.lkCamera.startStream(camera)`. O handler `lk:stream:start` em `electron/main.cjs`: 1. Exige URL `rtsp://`. 2. Finaliza o preview anterior. 3. Executa FFmpeg com transporte RTSP TCP. 4. Converte o vídeo para MJPEG. 5. Entrega a URL `http://127.0.0.1:{porta}/stream?...` ao renderer. Não expor esse servidor em rede: ele deve continuar vinculado a `127.0.0.1`. Quando não há Electron ou FFmpeg, o preview nativo não funciona. O modo web é destinado a desenvolvimento da interface, não à operação RTSP real. ### Teste de conexão `lk:connection:test` executa FFmpeg por até três segundos com saída nula. Retorna: ```ts { ok: boolean; message: string } ``` A página de câmeras deve exibir a mensagem retornada e atualizar o status de forma coerente. Uma URL HTTP pode passar pela validação do formulário, mas o pipeline Electron atual requer RTSP para preview, teste e gravação. ### Troca automática - Intervalos suportados pela interface: 5, 10, 15, 20, 30 e 60 segundos. - `App.tsx` cria o timer com `settings.switchInterval`. - Com duas ou mais câmeras habilitadas, a troca prioriza câmeras cujo status não seja `offline`. - Se todas estiverem offline, ainda percorre a lista habilitada para permitir nova tentativa de conexão. - `autoSwitchOnOpen` inicia a troca ao abrir somente quando existem ao menos duas câmeras habilitadas. ### Gravação A gravação é iniciada por `lk:recording:start(camera, folder)` e interrompida por `lk:recording:stop`. Requisitos do processo Electron: - Validar URL RTSP e disponibilidade de FFmpeg. - Criar a pasta de gravações, se necessário. - Salvar arquivos com nome seguro, removendo acentos e caracteres inválidos: ```text PORTAO_2026-09-03_14-30-00.mp4 ``` - Usar a pasta escolhida em Configurações; a pasta padrão é destinada a `LK Camera Switch\Gravações`. - A gravação deve continuar sendo tratada como uma única sessão ativa. Não iniciar uma segunda gravação sem encerrar a atual. ### API Electron exposta ao renderer `electron/preload.cjs` expõe somente `window.lkCamera`: ```ts loadState(): Promise saveState(state: AppState): Promise isFfmpegAvailable(): Promise startStream(camera: Camera): Promise<{ url: string }> stopStream(): Promise testConnection(camera: Camera): Promise<{ ok: boolean; message: string }> startRecording(camera: Camera, folder: string): Promise<{ filePath: string }> stopRecording(): Promise chooseRecordingFolder(): Promise setLaunchAtStartup(enabled: boolean): Promise ``` Não importar módulos Electron diretamente em arquivos dentro de `src/`. Toda nova capacidade nativa deve passar por IPC no `main.cjs`, depois por `preload.cjs`, e receber tipagem em `src/vite-env.d.ts`. ## Design Guidelines - Interface escura, operacional e de alto contraste. - Fundo base definido como `#0a0f17` na janela Electron; tokens e demais cores estão em `src/styles/main.css`. - Cards, bordas discretas e superfícies escuras organizam vídeo, controles e formulários. - Cor primária identifica ações principais; vermelho é reservado para gravação, erros e ações destrutivas. - `StatusPill.tsx` usa: - verde para ONLINE; - amarelo para CONECTANDO; - vermelho para OFFLINE. - Tipografia Inter, com títulos em caixa alta e espaçamento de letras maior para identificação do produto/status. - Os botões de operação usam área mínima de toque de 44px (`min-h-11`). - Layout máximo de `1600px`, com vídeo priorizado na tela Monitor. - Em telas menores, textos secundários da navegação são ocultados, mas os ícones permanecem visíveis. - Modais devem reutilizar `Modal.tsx`, que suporta clique externo, Escape e foco preso no diálogo. ## App Flow 1. **Inicialização** - `App.tsx` carrega o estado salvo. - Seleciona a primeira câmera habilitada; se não houver, usa a primeira cadastrada. - Detecta se Electron/FFmpeg está disponível. - Se `autoSwitchOnOpen` estiver ativo e houver duas câmeras habilitadas, inicia a alternância. 2. **Monitor** - Usuário abre `/` para visualizar a câmera atual. - Anterior/Próxima percorrem somente câmeras habilitadas. - Pausar interrompe o stream nativo atual. - Ao mudar de câmera, o stream anterior é encerrado antes da próxima tentativa. - Falhas de conexão atualizam a câmera para `offline`, preservam `lastError` e devem ser comunicadas por toast/estado de vídeo. 3. **Câmeras** - Em `/cameras`, usuário adiciona, edita, testa, habilita/desabilita ou exclui câmeras. - Desabilitar ou excluir a câmera atual exige que o monitor consiga escolher outra habilitada ou fique sem câmera selecionada. - Ao editar credenciais ou URL da câmera atual, a conexão deve ser reiniciada para usar os novos dados. 4. **Configurações** - Em `/settings`, usuário ajusta intervalo, pasta, inicialização automática, início automático da troca, volume e tela cheia. - Seleção de pasta usa o diálogo nativo Electron quando disponível. - Inicialização automática do Windows depende de `app.setLoginItemSettings()` e só tem efeito no aplicativo instalado. ## Conventions - Usar TypeScript e tipos de `src/types.ts`; não substituir `Camera` ou `AppState` por objetos ad hoc. - Componentes React usam PascalCase e arquivo com o mesmo nome. - Funções e variáveis usam camelCase; status e valores persistidos permanecem em minúsculas (`online`, `offline`, `checking`). - Reutilizar `Button.tsx`, `Modal.tsx`, `StatusPill.tsx` e `Toast.tsx` em vez de criar controles divergentes. - Manter a composição de classes com `cn()` de `src/lib/utils.ts`. - Seguir as classes e tokens já definidos em `src/styles/main.css`; não introduzir uma segunda biblioteca de estilos. - Persistir alterações através de `persist()`/`saveState()`. Não chamar apenas `setAppState()` para dados que precisam sobreviver ao fechamento. - Tratar erros de IPC com `try/catch` e mensagens em português orientadas ao operador. - Ao adicionar uma página: 1. Criar `src/pages/NovaPagina.tsx`. 2. Registrar a rota em `src/App.tsx`. 3. Adicionar item de navegação em `src/components/AppLayout.tsx` somente se for uma tela principal. - Ao adicionar uma função nativa: 1. Implementar handler `ipcMain.handle()` em `electron/main.cjs`. 2. Expor método mínimo em `electron/preload.cjs`. 3. Declarar a assinatura em `src/vite-env.d.ts`. 4. Verificar `window.lkCamera` no renderer para preservar o preview web. ## Platform (GenMB) This app is built and hosted on GenMB. **Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists. **Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime. **Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config. **Built-in services (relative API paths only, never hardcode domains):** - `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth - `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth` **File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file). **Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.