01 — Arquitectura

1. Visión general

Sistema multi-tenant de control de asistencia con geocercas y anti-fraude. Componentes:

1. App móvil Flutter — captura ubicación, valida integridad del dispositivo, autoriza (estándar / huella-FaceID / facial) y envía el check-in/out.
2. Backend FastAPI — autentica (JWT), valida geocerca (ST_DWithin), es la autoridad de tiempo (NTP), escribe eventos inmutables y sincroniza con Odoo.
3. PostgreSQL + PostGIS — fuente de verdad; eventos append-only con cadena de hash.
4. Panel web — dashboard para RR.HH. con mapa y reportes.
5. Odoo — ERP de nómina vía XML-RPC (hr.attendance).

2. Principios de diseño

• Servidor como autoridad de tiempo: el timestamp del servidor (server_time) es el dato legal del registro; la hora del dispositivo es solo una claim que se valida.
• Append-only con tamper-evidence: los eventos no se editan ni borran (trigger SQL + REVOKE). Cada evento encadena hash = HMAC_SHA256(secret, prev_hash || fila); alterar la tabla rompe la cadena y es detectable en auditoría.
• Anti-spoofing en dos capas: local (móvil) y remota (servidor). Ninguna es suficiente sola.
• Offline primero: la app siempre puede registrar; persiste cifrado y sincroniza con idempotency_key para no duplicar.
• Desacople con el ERP: patrón outbox (odoo_sync) para que una caída de Odoo no pierda asistencias.

3. Flujo de un check-in

sequenceDiagram
  participant App as App Flutter
  participant API as FastAPI
  participant DB as PostgreSQL+PostGIS
  participant Odoo as Odoo

  App->>App: biometría + detección mock/root/jailbreak + GPS
  App->>API: POST /attendance/check-in (JWT, coords, flags, idempotency_key)
  API->>API: valida JWT + offset NTP + flags anti-spoofing
  API->>DB: ST_DWithin(site.geom, coords, radius_m)
  DB-->>API: inside/outside
  API->>DB: INSERT evento (cadena de hash, server_time)
  API->>DB: INSERT odoo_sync (pending)
  API-->>App: 200 { geofence_status, server_time, hash }
  Note over Odoo: worker asíncrono
  DB->>Odoo: XML-RPC hr.attendance create/write

4. Estructura de carpetas

asistencia-geo/
├── docs/       ← documentación técnica y legal
├── db/         ← DDL + triggers de inmutabilidad + seed
├── backend/    ← FastAPI (app/ por capas: core, models, schemas, api, services, tasks)
├── mobile/     ← Flutter (lib/ por feature + core)
└── web/        ← panel web React + Vite + MapLibre

Backend (capas)

• app/core — configuración, seguridad (JWT/Argon2), NTP, criptografía de PII.
• app/models — SQLAlchemy 2 (typed ORM) reflejo de db/000_schema.sql.
• app/schemas — Pydantic v2 (validación de entrada/salida).
• app/api — routers (auth, attendance, sites, employees, reports, time, health).
• app/services — lógica de negocio (geofence, attendance, payroll_rules, odoo_client, alerts, notifications).
• app/tasks — APScheduler (recordatorios de salida, worker de Odoo).

Móvil (features)

• core — config, red, almacenamiento seguro, tiempo NTP.
• features/attendance — modelo, repositorio y servicios (GPS, mock, seguridad, biometría, facial, check-in).
• features/sync — cola offline + sincronización con retry.
• features/maps — visualización de geocerca.

5. Seguridad en tránsito y reposo

• Tránsito: TLS 1.3 en toda la API. Pinning opcional en la app.
• Reposo: contraseñas Argon2id; PII (teléfono, foto, embedding facial) cifrada con AES-256-GCM (app/core/crypto.py, clave en PII_ENC_KEY). La cadena de hash usa un secreto independiente (ATTENDANCE_HASH_SECRET).
• Claves: nunca en el código; vía variables de entorno / gestor de secretos.

6. Escalabilidad

• FastAPI async + asyncpg manejan alta concurrencia de check-ins.
• La cadena de hash serializa los inserts por empresa con bloqueo de la fila chain_state; a volúmenes extremos se particiona por company_id o se usa un hash-linking asíncrono.
• Redis opcional para rate-limiting y caché; PostGIS con índice GIST para ST_DWithin.