taskbot/docs/how-to/adding-command.md

Cómo añadir un nuevo comando

Objetivo

• Incorporar un comando de texto que procese mensajes entrantes y responda por la cola.

Pasos

1. Parseo en CommandService

   • Ubicación: src/services/command.ts
   • Añade lógica para detectar el patrón (p.ej., "/t listar", "/t info 0012").
   • Normaliza IDs con utils/whatsapp.normalizeWhatsAppId cuando corresponda.
   • Registra métricas si procede (Metrics.inc).

2. Lógica de dominio

   • Si afecta a tareas, delega en src/tasks/service.ts.
   • Asegúrate de crear usuarios con ensureUserExists si se persisten referencias.

3. Respuesta al usuario

   • Encola la respuesta en src/services/response-queue.ts con el destinatario adecuado (usuario o grupo).
   • Incluye metadata JSON si mencionas usuarios (@) para formateo posterior.

4. Rate limiting y UX

   • Verifica RateLimiter.checkAndConsume(sender) si el comando puede ser abusado.
   • Usa RateLimiter.shouldNotify para evitar spam de notificaciones de rate limit.

5. Tests

   • Crea una prueba en tests/unit/services/command..test.ts
   • Usa Database(':memory:') + initializeDatabase(memdb) e inyecta CommandService/TaskService.dbInstance.

6. Documentación

   • Añade una breve descripción del comando a docs/overview.md (flujos) si es relevante.
   • Si el comando expone nuevas métricas o env vars, actualiza docs/operations.md.

Consejos

• Mantén CommandService como orquestador; la lógica compleja debe vivir en servicios dedicados.
• Usa nombres y mensajes consistentes con el resto de comandos.