Files
OnEverControl/AGENTS.md
T

58 lines
4.7 KiB
Markdown

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