CoroCoro Bot

Bot de Telegram para registrar horas de trabajo de forma sencilla. Permite iniciar y detener sesiones, consultar tus horas, obtener consolidado por usuario y administrar el estado de otros miembros.

Tabla de contenidos

• Estado del proyecto
• Características
• Requisitos
• Instalación rápida
• Configuración
• Uso básico
• Estructura del proyecto
• Guía para desarrolladores
• Documentación técnica
• Documentación automática (PHPDoc)
• Roadmap
• FAQ
• Recursos adicionales
• Créditos

Estado del proyecto

Prototipo funcional / WIP. Falta fortalecer configuración por entorno, pruebas automatizadas y despliegue reproducible.

Características

• Comandos para empezar a trabajar (/trabajar) y pausar (/descansar).
• Consulta de horas personales (/horas) y consolidado global (/consolidado).
• Panel de administración por comandos para verificar estados (/estados) y forzar descanso/trabajo a otros usuarios.
• Persistencia ligera con SleekDB (almacenado en disco).
• Implementado con Nutgram para la capa de Telegram.

Requisitos

• PHP 8.1+ (se usan enums).
• Composer.
• Token de bot de Telegram y una URL pública HTTPS para el webhook.
• Permisos de escritura en src/Database/ para el usuario del servidor web.

Nota de nombres

El paquete en composer.json se llama aefmind/corocoro mientras que el repositorio es corocoritobot. Se alinearán en la siguiente iteración para evitar confusión en instalaciones y futuras publicaciones en Packagist.

Instalación rápida

1. Clona el repositorio y descarga dependencias (nota: el paquete en composer.json se llama aefmind/corocoro, pero el repositorio es corocoritobot; se alineará en una próxima iteración):

git clone https://github.com/aefmind/corocoritobot.git
cd corocoritobot
composer install

2. Configura los valores mínimos:

• Define tu token en src/App/main.php::botToken().
• Agrega los usuarios autorizados en src/App/main.php::users(), asignando rol Admin o User.
• Crea (si no existe) la carpeta src/Database/ con permisos de escritura.

3. Configura el endpoint del webhook apuntando a src/public/niufn38fy3e98fhsff.php. El nombre aleatorio NO es seguridad; usa el token del bot, safeMode, filtrado de IPs (rango de Telegram), validación del header X-Telegram-Bot-Api-Secret-Token o un proxy inverso con autenticación. Nutgram valida el header cuando se define secretToken (actualmente se pasa el token del bot; puedes usar uno dedicado). Para entornos locales puedes usar php -S localhost:8000 -t src/public junto con un túnel tipo ngrok.

4. (Opcional) Crea el archivo src/App/.needsetup y realiza una petición al webhook para que Nutgram intente fijar el webhook automáticamente (asegúrate de ajustar botUrl() con tu URL pública antes de hacerlo).

Configuración

• Token del bot: sustituye el valor retornado por botToken() con tu token real.
• Usuarios autorizados: edita la función users() para declarar administradores y usuarios.
• Directorio de datos: por defecto dbDirectory() apunta a src/Database/. Si cambias la ruta, asegúrate de que exista y tenga permisos de escritura.
• Variables de entorno: se incluye .env.example como referencia; al migrar a carga por entorno, replica sus claves y usa una librería como vlucas/phpdotenv para cargarlas.

Seguridad del webhook

• Mantén safeMode activado (ya configurado en bot.php).
• Define un secretToken dedicado y verifica que el servidor valide el header X-Telegram-Bot-Api-Secret-Token (Nutgram lo hace al recibirlo).
• Restringe el acceso al endpoint a las IPs de Telegram (consulta la lista oficial).
• Considera poner el endpoint detrás de un proxy que aplique TLS y autenticación adicional si se requiere.

Uso básico

Comandos disponibles dentro del chat del bot:

• /start: da la bienvenida y registra al usuario si no existe.
• /trabajar o botón Trabajar: abre una sesión de trabajo.
• /descansar o botón Descansar: cierra la sesión activa y guarda la duración.
• /horas: muestra las horas acumuladas del usuario.
• /consolidado: (solo admin) total global y detalle por usuario.
• /estados: (solo admin) estado actual de todos los usuarios.
• /descansando {usuario} / /trabajando {usuario}: (solo admin) fuerza descanso o trabajo.

Estructura del proyecto

src/
├─ App/
│  ├─ Classes/          # Enums y clases de apoyo
│  ├─ bot.php           # Registro de comandos y webhook
│  ├─ controllers.php   # Lógica principal de cada comando
│  ├─ functions.php     # Helpers y acceso a la base de datos
│  └─ main.php          # Configuración mínima (token, usuarios, rutas)
└─ public/
   ├─ index.php         # Respuesta 404 por defecto
   └─ niufn38fy3e98fhsff.php # Punto de entrada del webhook

Guía para desarrolladores

• Estilo de código: sigue PSR-12 y documenta funciones públicas con PHPDoc.
• Dependencias: gestiona con Composer; no se versiona vendor/ en un flujo típico, aunque está presente en este snapshot.
• Tests: aún no hay suite. Antes de abrir PRs, prueba manualmente los comandos clave.
• Flujo sugerido para nuevas features:
  1. Duplica este repo o crea una rama.
  2. Añade o ajusta comandos en bot.php y su lógica en controllers.php.
  3. Si introduces nuevos roles o configuraciones, refleja los cambios en users() y en la documentación.
  4. Considera agregar pruebas (por ejemplo con Pest o PHPUnit) y CI cuando sea posible.

Contribuir

Consulta CONTRIBUTING.md para abrir issues o PRs y conocer el proceso esperado.

Documentación técnica

• Webhook y modo seguro: se usa Nutgram\RunningMode\Webhook con safeMode activado.
• Persistencia: SleekDB guarda colecciones users y timeRecords en disco (src/Database/).
• Autorización: users() devuelve un mapa username => UserRole. Si el usuario no está, se responde con 403.
• Flujo de comandos: cada comando registrado en bot.php delega en una función de controllers.php, que valida rol, interactúa con la base y responde con teclados inline cuando aplica.

Documentación automática (PHPDoc)

• Añade anotaciones PHPDoc a funciones y controladores para describir parámetros, roles y efectos colaterales.
• Para generar HTML de referencia se puede usar phpDocumentor:

  composer require --dev phpdocumentor/phpdocumentor
  vendor/bin/phpdoc -d src -t docs/api

  Publica el contenido de docs/api en tu hosting estático o revísalo localmente.

Roadmap

• Configuración basada en variables de entorno (.env) y carga segura de secretos.
• Automatizar despliegue del webhook y saneamiento de botUrl().
• Añadir suite de pruebas (unitarias y de integración) y CI.
• Dockerización y receta de desarrollo local (ngrok incluido).
• Internacionalización/multi-idioma y mensajes configurables.
• Reportes más ricos (exportar CSV, rangos de fechas, horas extras).
• Panel web ligero para admins (opcional).
• Alinear el nombre del paquete de Composer (aefmind/corocoro) con el nombre del repositorio (corocoritobot) o publicar un alias en Packagist (prioridad alta para evitar confusiones).

FAQ

• ¿Dónde se guardan los datos? En src/Database/ usando SleekDB.
• ¿Puedo cambiar la ruta del webhook? Sí, renombra src/public/niufn38fy3e98fhsff.php y ajusta la URL que registras con Telegram.
• ¿Qué pasa si dejo una sesión abierta? Solo se contabiliza cuando la cierres con /descansar.

Recursos adicionales

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• CHANGELOG.md
• .env.example

Créditos

Creado por aefmind. Si usas el bot, comparte feedback o PRs para mejorarlo.