You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
66 lines
3.9 KiB
Markdown
66 lines
3.9 KiB
Markdown
# Arquitectura y responsabilidades
|
|
|
|
Módulos principales
|
|
- src/server.ts
|
|
- Expone endpoints (webhook, /metrics), valida entorno, lanza migraciones y arranque.
|
|
- Extrae texto de mensajes con lógica tolerante a formatos (texto/caption).
|
|
- src/db.ts
|
|
- Abre la base de datos (data/…), aplica PRAGMAs por defecto y expone helpers.
|
|
- initializeDatabase() ejecuta migraciones up-only.
|
|
- src/db/migrations/index.ts
|
|
- Registro de migraciones con versión, nombre, checksum y función up.
|
|
- Helpers para inspección del esquema (tableHasColumn).
|
|
|
|
Servicios (src/services)
|
|
- command.ts: orquesta el manejo de comandos. Entrada: { sender, groupId, message, mentions }.
|
|
- contacts.ts: resolución de nombres de contactos vía Evolution API con caché en memoria y TTL.
|
|
- group-sync.ts: sincronización de grupos y miembros, cachés en memoria, schedulers configurables.
|
|
- identity.ts: gestión de alias ↔ user_id real; caché en memoria y tabla user_aliases.
|
|
- maintenance.ts: limpieza programada de miembros inactivos según retención.
|
|
- metrics.ts: contadores y gauges in-memory con render a Prometheus o JSON.
|
|
- rate-limit.ts: token bucket por usuario, con burst, refill y cooldown de notificación.
|
|
- reminders.ts: recordatorios según preferencias (zona horaria, frecuencia, hora).
|
|
- response-queue.ts: cola de respuestas con intentos, backoff y limpieza.
|
|
- webhook-manager.ts: configuración de webhooks salientes (si aplica).
|
|
|
|
Utilidades (src/utils)
|
|
- whatsapp.ts: normalización de IDs, helpers para distinguir usuario/grupo.
|
|
- formatting.ts: utilidades de representación (IDs, fechas abreviadas, etc.).
|
|
|
|
Tareas (src/tasks)
|
|
- model.ts: interfaces Task, TaskAssignment, etc.
|
|
- service.ts: operaciones de alto nivel sobre tareas (crear, asignar, soltar, etc.).
|
|
|
|
Dependencias internas
|
|
- La mayoría de servicios aceptan/injectan una instancia Database estática configurable para test.
|
|
- utils no dependen de servicios; servicios pueden usar utils y db.
|
|
- server.ts invoca servicios y metrics; no debe contener lógica de dominio pesada.
|
|
|
|
Puntos de extensión
|
|
- Nuevos comandos: ver how-to/adding-command.md.
|
|
- Nuevas tablas/campos: ver how-to/adding-migration.md.
|
|
- Ajustes de sincronización de grupos/miembros: ver how-to/adjusting-group-sync.md.
|
|
- Nuevas variables de entorno: ver how-to/adding-env.md.
|
|
- Nuevas métricas: usar Metrics.inc/set/get y documentar en operations.md.
|
|
|
|
Observabilidad y errores
|
|
- Logging pragmático en operaciones críticas; errores de migración detienen el arranque.
|
|
- Métricas:
|
|
- sync_runs_total, contadores de alias resueltos, etc.
|
|
- Estados de gauges/counters expuestos en /metrics (Prom/JSON).
|
|
|
|
Control de acceso por grupos (allowed_groups)
|
|
- Esquema: tabla allowed_groups (group_id PK, label, status: pending|allowed|blocked, discovered_at/updated_at, discovered_by).
|
|
- Servicio: AllowedGroups con caché en memoria e interfaz isAllowed, setStatus, upsertPending, listByStatus, seedFromEnv.
|
|
- Flujo:
|
|
- Discover (GROUP_GATING_MODE='discover'): ante tráfico de un grupo desconocido, se registra como pending y se retorna temprano; opcionalmente se notifica a ADMIN_USERS (NOTIFY_ADMINS_ON_DISCOVERY='true').
|
|
- Enforce (GROUP_GATING_MODE='enforce'): se ignoran mensajes/comandos en grupos no allowed; /admin tiene bypass para permitir aprobación in situ.
|
|
- Superficies aplicadas:
|
|
- server.ts: retorno temprano en discover y enforce; excepción para /admin.
|
|
- services/command.ts: guard de enforce para evitar procesar comandos de grupos no allowed.
|
|
- services/group-sync.ts: sincronización de miembros salta grupos no allowed (incluye scheduler).
|
|
- tasks/service.ts: en enforce, crear tareas con group_id=null si el grupo no está allowed (compatibilidad).
|
|
- reminders.ts: omite tareas/grupos no allowed al generar recordatorios en enforce.
|
|
- Observabilidad:
|
|
- Gauges allowed_groups_total_* y counters unknown_groups_discovered_total, messages_blocked_group_total, commands_blocked_total, sync_skipped_group_total, admin_actions_total_{allow,block}.
|