4.7 KiB
4.7 KiB
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 colapdtmdlen red local. - Repositorio Git Remoto: Gitea en
https://gitea.oemspot.com.ar/carlostellocba/OnEverControl. - Especificaciones:
specs/NNN-nombre/conspec.md,plan.mdytasks.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.Pathy variables.env; nada de rutas conC:\...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 enCHANGELOG.mdantes 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_nameregistrado 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.mdy la spec activa enspecs/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:
- Actualizar número de versión en
backend/yfrontend/. - Registrar cambios en
CHANGELOG.md. - Ejecutar suite de validación (pytest + build).
- Realizar commit semántico y push a
https://gitea.oemspot.com.ar/carlostellocba/OnEverControl.
- Actualizar número de versión en
- No saltarse la aprobación del usuario antes de pasar a la siguiente fase o tarea.
Límites
- ✅ Siempre: Mantener
MEMORY.mdyCHANGELOG.mdactualizados. Incrementar versiones de backend y frontend antes de subir a Gitea. Respetar principios dedocs/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:
pytestsin advertencias. - Frontend:
npm run buildsin errores de TypeScript y comprobación de interacción táctil. - Versiones: Versiones sincronizadas en
backend/yfrontend/registradas enCHANGELOG.md. - Consultar
MEMORY.mdpara conocer el estado y decisiones entre sesiones.