# AGENTS.md — OnEverControl Cliente web reducido para Puesto de Control y Login en la red local de OnEverAccess, optimizado para tablets táctiles (Android, Windows, iPad) y terminales de garita. ## Stack y estructura - **Backend:** FastAPI (Python 3.11+), Pydantic v2, pymssql, Uvicorn en `backend/`. - **Frontend:** React + TypeScript + Vite (Node.js v20+), Vanilla CSS tokens en `frontend/`. - **Hardware Objetivo:** Tablets Samsung Galaxy Tab A9 y A11 (4 GB RAM, Android). - **Entornos de Ejecución Servidor:** Windows 10/11 (bare-metal / servicio), LXC (Linux Containers en Proxmox/Debian) y Docker / Docker Compose. - **Base de Datos & Hardware:** SQL Server `videoman` (compat 100+) y cola `pdtmdl` en red local. - **Repositorio Git Remoto:** Gitea en `https://gitea.oemspot.com.ar/carlostellocba/OnEverControl`. - **Especificaciones:** `specs/NNN-nombre/` con `spec.md`, `plan.md` y `tasks.md`. ## Comandos - Backend dev: `cd backend && uvicorn app.main:app --reload --port 8000` - Backend tests: `cd backend && pytest` - Frontend dev: `cd frontend && npm run dev` - Frontend tests/build: `cd frontend && npm run test && npm run build` - Git push a Gitea: `git push origin main` ## Convenciones - Código en inglés; interfaz de usuario y documentación en español. - Diseño **Touch-First para 4GB RAM:** Touch targets >= 48px, layout `100dvh`, `inputmode="numeric"`. - Rendimiento y memoria: React memoization (`useCallback`, `React.memo`), liberación estricta de streams de cámara (`MediaStream.getTracks().forEach(t => t.stop())`), cero dependencias infladas. - Portabilidad estricta: Usar siempre `pathlib.Path` y variables `.env`; nada de rutas con `C:\...` ni llamadas exclusivas a Win32 en el backend. - Modelos Pydantic v2 estrictos en el backend. - **Versionado Semántico (SemVer):** El backend (`backend/app/__version__.py` / `pyproject.toml`) y frontend (`frontend/package.json`) deben mantener sus versiones actualizadas y sincronizadas en cada hito o release, registrándolas en `CHANGELOG.md` antes de subir al repositorio Gitea. ## Reglas de dominio / trampas conocidas - **Modo Cliente Reducido:** No implementar módulos de administración general ni ERP de OnEverAccess. - **Hardware Desacoplado:** El frontend NUNCA toca puertos COM; encola órdenes en la tabla `pdtmdl`. Al no requerir COM directo en el backend, permite despliegue nativo en LXC y Docker sin passthrough de hardware. - **Tablet = Workstation:** Toda tablet opera bajo un `workstation_name` registrado en SQL Server. - **Lectura de Documento por Cámara de la Tablet:** La lectura de DNI (PDF417 y QR) se realiza directamente con la cámara de la tablet (Barcode Detection API / ZXing), reemplazando por completo lectores físicos por puerto COM o emuladores de teclado. - **Sin Streaming de Cámaras Hikvision:** No se implementa streaming de cámaras fijas por ISAPI en la versión web (ahorro de batería y ancho de banda en tablets); la tablet solo utiliza su propia cámara integrada para escanear DNI y capturar fotos de evidencia. - **DNI Argentino:** Usar lógica validada de `herramientas/parser_dni.py` (formatos 2009, 2012, 2026 y App). - **FreeTDS & Collation en Linux/LXC:** Asegurar configuración de charset UTF-8 hacia SQL Server con collation `Modern_Spanish_CI_AS`. ## Forma de trabajar (Spec-Driven Development) - Respetar `docs/constitution.md` y la spec activa en `specs/` antes de tocar código. - Implementar **UNA sola tarea a la vez** de `tasks.md`: tests en rojo primero, luego código, tests en verde, marcar y parar. - **Flujo de Versionado y Push a Gitea:** Al completar una fase o release: 1. Actualizar número de versión en `backend/` y `frontend/`. 2. Registrar cambios en `CHANGELOG.md`. 3. Ejecutar suite de validación (pytest + build). 4. Realizar commit semántico y push a `https://gitea.oemspot.com.ar/carlostellocba/OnEverControl`. - No saltarse la aprobación del usuario antes de pasar a la siguiente fase o tarea. ## Límites - ✅ **Siempre:** Mantener `MEMORY.md` y `CHANGELOG.md` actualizados. Incrementar versiones de backend y frontend antes de subir a Gitea. Respetar principios de `docs/constitution.md`. - ⚠️ **Pregunta antes:** Cambios en el modelo de base de datos, nuevas dependencias npm/pip, o divergencias con la spec. - 🚫 **Nunca:** Subir a Gitea con tests fallando o sin actualizar la versión en backend/frontend. Modificar tablas maestras de OnEverAccess fuera de alcance. ## Verificación - Backend: `pytest` sin advertencias. - Frontend: `npm run build` sin errores de TypeScript y comprobación de interacción táctil. - Versiones: Versiones sincronizadas en `backend/` y `frontend/` registradas en `CHANGELOG.md`. - Consultar `MEMORY.md` para conocer el estado y decisiones entre sesiones.