White Paper Técnico — Sistema de Control de Asistencia Georeferenciado

Documento: explicación técnica de la aplicación (arquitectura, algoritmos, modelo de datos, seguridad y mapa de fuentes). Versión del producto: 0.3.1 · Fecha: 2026-09-22 · Autor: Rocky (IA DevOps) + Javier Páez

Este documento es el white sheet técnico de la aplicación. Complementa a: 07 — Manual DevOps, 08 — Versiones y 09 — Stack tecnológico. El mapa de fuentes (§11) apunta al código real en el repositorio (git).

1. Resumen ejecutivo

Sistema empresarial de control de asistencia georeferenciado para cumplimiento laboral mexicano (LFT / NOM-037 / INAI). El empleado registra su entrada/salida desde una app móvil que valida: (1) quién (biometría local + reconocimiento facial on-device), (2) dónde (GPS + geocerca PostGIS), (3) cuándo (hora firmada por el servidor, no por el dispositivo) y (4) que el dispositivo no está manipulado (anti-spoofing de mock-location / root / jailbreak).

Cada registro es un evento inmutable encadenado con HMAC-SHA256 (tamper-evidence), apto como evidencia legal. La administración (RR.HH.) opera un panel web con mapa, geocercas, empleados, turnos y aprobaciones. La salida se sincroniza con Odoo 18 (hr.attendance) mediante un outbox idempotente.

2. Alcance funcional

3. Arquitectura de referencia

Ver diagrama PNG docs/diagrams/01-arquitectura.png.

Capas:

┌─────────────────────────────────────────────────────────────┐
│  Clientes:  App Flutter (Android/iOS)  ·  Panel web React   │
└───────────────┬─────────────────────────┬───────────────────┘
                │ HTTPS + JWT (Bearer)    │ HTTPS + JWT
                ▼                         ▼
        ┌───────────────────────────────────────────┐
        │  Cloudflare CDN → nginx (Linode)          │
        └────────────────────┬──────────────────────┘
                             ▼
        ┌───────────────────────────────────────────┐
        │  Backend FastAPI (uvicorn, async)         │
        │   auth · attendance · sites · admin ...   │
        │   geofence · payroll · odoo_client · hash │
        └──────┬──────────────────────────┬─────────┘
               │ asyncpg (SQLAlchemy 2)   │ XML-RPC (odoorpc)
               ▼                          ▼
   ┌──────────────────────┐      ┌──────────────────────┐
   │ PostgreSQL 15+PostGIS│      │ Odoo 18 (hr.attend.) │
   └──────────────────────┘      └──────────────────────┘

Principios de diseño: 1. Backend async end-to-end (FastAPI + SQLAlchemy 2 asyncio + asyncpg). 2. Eventos append-only: la asistencia no se edita ni borra; se corrige con eventos nuevos + auditoría. 3. Autoridad de tiempo en el servidor (NTP), nunca el reloj del dispositivo. 4. PII cifrada en reposo (AES-256-GCM vía Fernet). 5. Separación por capas (api/ → services/ → models/ → core/).

4. Modelo de datos

Ver db/000_schema.sql y diagrama docs/diagrams/03-er-diagrama.png.

4.1 Entidades núcleo

4.2 Enumeraciones (backend/app/models/models.py)

• UserRole: employee, admin
• ProfileType: site, remote
• EventType: check_in, check_out
• EventSource: gps, manual, admin
• AuthMethod: standard, biometric, face
• GeofenceStatus: inside, outside, not_required
• ApprovalStatus: pending, approved, rejected
• JornadaType: diurna, nocturna, mixta
• OdooSyncStatus: pending, sent, error

4.3 Inmutabilidad (db/001_immutability.sql)

• Trigger trg_events_immutable bloquea UPDATE/DELETE sobre attendance_events.
• REVOKE de privilegios de escritura sobre la tabla.
• Cadena de hash en la capa de aplicación (§6.4).

5. Flujo de check-in / check-out (end-to-end)

Ver diagrama docs/diagrams/02-flujo-checkin.png.

1. App móvil (mobile/lib/features/attendance/) — el usuario elige Entrada o Salida.
2. Biometría (biometric_service.dart) — local_auth (huella/rostro).
3. Anti-spoofing (mock_location_detector.dart, security_service.dart) — mock/root/jailbreak.
4. GPS (geolocation_service.dart) — geolocator con accuracy_m.
5. POST /attendance/check-in (backend/app/api/attendance.py + services/attendance.py):
   • Valida JWT + offset de tiempo (NTP) + flags anti-spoofing.
   • Evalúa geocerca services/geofence.py → (GeofenceStatus, site_id).
   • No bloquea fuera de zona/horario: guarda el evento y, si procede, una aprobación pending.
   • Inserta el evento inmutable con cadena de hash + fila en odoo_sync (pendiente).
6. Respuesta 200 con geofence_status, server_time, approval_status.
7. Worker APScheduler (tasks/scheduler.py) sincroniza odoo_sync → Odoo.

5.1 Reglas de geocerca (services/geofence.py)

• Perfil remote → not_required (guarda coordenadas, sin validación de radio).
• Perfil site sin coordenadas / sin sitio vigente / fuera del radio → outside (pendiente de aprobación).
• Perfil site dentro del radio → inside (válido).

La consulta usa ST_DWithin sobre geography (distancias en metros), tomando el sitio primario vigente (is_primary DESC + valid_until).

6. Seguridad

6.1 Autenticación (core/security.py)

• JWT (PyJWT): access token (sub, type, iat, exp) + refresh token.
• Contraseñas: Argon2id (argon2-cffi). Un hash malformado nunca autentica.

6.2 Cifrado de PII en reposo (core/crypto.py)

• AES-256-GCM vía Fernet (cryptography). Clave en PII_ENC_KEY.
• Valores cifrados como BYTEA. Desencriptado fallido → ValueError (nunca leak).

6.3 Autoridad de tiempo (core/ntp.py)

• El servidor firma server_time_ms con HMAC-SHA256 (SERVER_TIME_SECRET).
• La app valida la firma y calcula su offset; el reloj del dispositivo es solo un claim.
• MAX_TIME_OFFSET_MS descarta dispositivos con reloj muy desviado.

6.4 Cadena de hash / tamper-evidence (core/hash_chain.py)

• Por evento: hash = HMAC_SHA256(ATTENDANCE_HASH_SECRET, prev_hash || canonical_row).
• canonical_row es determinista (campos ordenados: coords, flags, server_time, idempotency_key, etc.).
• Alterar una fila invalida toda la cadena posterior (el prev_hash del evento N+1 ya no coincide).

6.5 Anti-spoofing (móvil)

• flutter_jailbreak_detection (root/jailbreak).
• Detección de mock location (mock_location_detector.dart).
• Reconocimiento facial on-device google_mlkit_face_detection (sin subir biometría al servidor).
• MAX_GPS_ACCURACY_M descarta fijaciones GPS imprecisas (posible spoofing).

7. Motor de nómina (LFT) — services/payroll_rules.py

Funciones puras (testeables, sin BD) que codifican la ley federal:

• Jornadas: diurna 8h (06:00–20:00), nocturna 7h (20:00–06:00), mixta 7.5h.
• Clasificación de jornada (classify_jornada) por proporción de franja nocturna.
• Horas extra: máximo 3 h/día; primeras 9 h/semana al doble (100%), excedente al triple (200%).
• Retardos (compute_retardo_minutes): diferencia entre entrada real y hora programada.
• Resumen diario (compute_workday): ordinarias, extra, retardos, pausas.

La autoridad del tipo de jornada es shifts.jornada_type; classify_jornada es heurística de respaldo. Ver backend/tests/test_payroll_rules.py.

8. Integración Odoo — patrón outbox idempotente

Ver docs/05-odoo-integration.md y PLAN_INTEGRACION_ODOO.md.

• odoo_client.py envuelve odoorpc (XML-RPC) contra hr.attendance.
• Outbox odoo_sync: cada evento genera una fila pending; el worker la marca sent/error de forma idempotente (nunca duplica un check-in en Odoo).
• Empleados: users.odoo_employee_id mapea al hr.employee de Odoo.
• Pendiente (solo plan): schema de producción (odoo_sync), campos custom x_* en Odoo, usuario API + credenciales .env, enable_scheduler=True, y el sync de entrada de empleados.

9. Modo offline (parcial)

• Cola offline cifrada (mobile/lib/core/storage/offline_store.dart): guarda check-ins locales cuando no hay red (connectivity_plus).
• Sync idempotente (mobile/lib/features/sync/sync_service.dart): reenvía con idempotency_key (UUID) para evitar duplicados.

10. Cumplimiento legal

• LFT: registro de jornada, horas extra (doble/triple), retardos (§7).
• NOM-037 (teletrabajo): perfiles site/remote, geocercas, consentimientos.
• INAI / LFPDPPP: consents explícitos, PII cifrada en reposo, datos mínimos.
• Evidencia: eventos inmutables con cadena de hash y hora firmada por servidor.
• Ver docs/04-nom037-y-lft.md.

11. Mapa de fuentes (dónde vive cada cosa)

Backend — backend/

Base de datos — db/

Móvil — mobile/lib/

Panel web — web/

Infraestructura

12. Despliegue

Detalle operativo completo en docs/07-devops-manual.md y diagrama docs/diagrams/04-despliegue.png.

• Producción: Linode 172.238.169.174 → Cloudflare → nginx → systemd ia-asistencia.service (uvicorn :8095) → Docker asistencia-postgis (:5433) → Odoo :8069.
• APK: publicados en /opt/ia-intt/html/downloads/asistencia/ (binarios no van a git; solo el checksum SHA256SUMS.txt).

13. Roadmap

1. Odoo end-to-end: habilitar outbox en producción (schema + credenciales + scheduler).
2. Push de recordatorios de salida (FCM/APNs) — hoy notifications.py es un stub.
3. Cierre de CORS (allow_origins=["*"] → dominios concretos).
4. Hardening Odoo (cerrar 8069 al exterior).
5. Build iOS completo (hoy el directorio ios/ está parcial).