Files

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 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.