d066fe217c
Define la estructura de directorios y la documentación inicial para orquestar el trabajo de los agentes de IA. - Crea los directorios `src` y `docs/agents`. - Genera archivos de bitácora individuales para cada uno de los 13 agentes definidos. - Introduce `docs/CONVENTIONS.md` para establecer las reglas de nomenclatura, estilo de código y contratos de API. - Actualiza el `README.md` principal con una sección que detalla el nuevo flujo de trabajo basado en agentes, explicando cómo deben operar y documentar su progreso. Este cambio sienta las bases para un desarrollo estructurado, trazable y coherente, de acuerdo con el rol del Agente 0 (Arquitectura y Orquestación).
Sistema de Gestión de Socias – HR Platform
FQDN: hr.soul23.cloud
Puerto: 3011
Stack principal: Node.js
Despliegue: Docker Compose
1. Descripción general
Este proyecto es una plataforma profesional de gestión de recursos humanos (HR) enfocada en la administración de socias y personal operativo. El sistema está diseñado para operar como un servicio web desacoplado, desplegado mediante contenedores Docker y accesible a través del subdominio hr.soul23.cloud.
La plataforma centraliza información crítica del personal, automatiza procesos administrativos (vacaciones, permisos) y emite eventos hacia sistemas externos mediante webhooks. Desde su diseño base, el sistema está preparado para escalar funcionalmente e integrarse con agentes de inteligencia artificial.
Este README define el alcance funcional, técnico y operativo del proyecto.
2. Alcance (Scope)
El sistema cubre:
- Gestión centralizada de socias.
- Importación automatizada de datos desde Google Sheets.
- Base de datos como fuente única de verdad.
- Búsqueda incremental de personal.
- Gestión de vacaciones conforme a la Ley Federal del Trabajo (México).
- Gestión de permisos.
- Emisión de eventos vía webhooks.
- Arquitectura lista para integración de control de asistencias.
Quedan fuera de este alcance inicial:
- Nómina.
- Evaluaciones de desempeño.
- Autenticación avanzada (SSO).
3. Principios técnicos
- Node.js como runtime principal.
- API REST como interfaz de comunicación.
- Configuración sobre código (no hardcodeo).
- Persistencia transaccional en base de datos.
- Historial inmutable de eventos.
- Contenerización completa para entornos reproducibles.
4. Arquitectura de alto nivel
4.1 Frontend
- Aplicación web.
- Consumo de API vía HTTP.
- Búsqueda incremental (autocomplete).
- Formularios dinámicos.
4.2 Backend (Node.js)
- Servidor HTTP escuchando en puerto 3011.
- Framework recomendado: Express / Fastify.
- Capa de servicios para reglas de negocio.
- Capa de controladores (API).
- Capa de integración (Google Sheets, webhooks).
4.3 Base de datos
Entidades principales:
- Socias
- Sucursales
- Antigüedad / contratos
- Vacaciones
- Permisos
- Eventos emitidos
- Asistencias (fase futura)
5. Despliegue
5.1 Docker Compose
El sistema se desplegará exclusivamente mediante Docker Compose.
Características:
- Un contenedor para el backend Node.js.
- Un contenedor para la base de datos.
- Red interna privada.
- Variables de entorno definidas en
.env.
El servicio Node.js expone:
- Puerto interno: 3011
- Puerto externo: 3011
5.2 Acceso
El servicio será accesible en:
https://hr.soul23.cloud
El balanceo, SSL y DNS se manejan fuera del scope de esta aplicación.
6. Importación desde Google Sheets
Objetivo
Usar Google Sheets como entrada temporal de datos, no como sistema.
Comportamiento
- Lectura vía Google Sheets API.
- Mapeo dinámico de columnas.
- Normalización de valores vacíos (ej. "en trámite").
- Identificación de registros por claves lógicas.
- Logs de sincronización.
7. Gestión de socias
Cada socia incluye:
- ID interno.
- Fecha de ingreso (campo crítico).
- Datos personales y laborales.
- Asociación a sucursal.
La fecha de ingreso gobierna la lógica de vacaciones.
8. Vacaciones
8.1 Marco legal
Las vacaciones se calculan conforme a la Ley Federal del Trabajo (México).
La tabla de días por antigüedad:
- Existe como configuración editable.
- No se hardcodea.
- Puede actualizarse sin cambios de código.
8.2 Ciclo
- Cada socia inicia con 12 días en su primer ciclo.
- El ciclo se calcula desde la fecha de ingreso.
- Los días pueden tomarse en uno o varios periodos.
8.3 Caducidad
- Los días generados en un ciclo caducan al iniciar el siguiente ciclo.
- No existe acumulación indefinida.
El sistema debe calcular:
- Saldo disponible.
- Días consumidos.
- Días vencidos.
8.4 Registro
Cada solicitud guarda:
- Socia.
- Fechas.
- Días utilizados.
- Ciclo.
- Estado.
- Timestamp.
El historial es inmutable.
9. Permisos
- Permisos por horas o días.
- Motivo configurable.
- Historial permanente.
- Relación directa con asistencias futuras.
10. Webhooks
10.1 Principio
Vacaciones y permisos generan eventos de salida.
10.2 Endpoints
Existen únicamente dos endpoints:
/webhook/vacaciones/{token}/webhook/permisos/{token}
10.3 Token
- Token aleatorio de 11 caracteres.
- Forma parte de la URL.
- Identifica el destino.
- No es autenticación.
11. Agentes de Inteligencia Artificial
Los agentes operan sobre:
- Datos estructurados.
- Reglas configuradas.
- Historial real.
No definen reglas nuevas.
12. Seguridad
- Variables sensibles vía entorno.
- Control de acceso (fase futura).
- Bitácora de eventos.
13. Estado del proyecto
- Diseño funcional: ✅
- Diseño técnico: ✅
- Implementación: ⏳
14. Flujo de Trabajo Basado en Agentes
Este proyecto se desarrolla siguiendo una metodología de agentes especializados, donde cada agente (ya sea humano o IA) tiene un conjunto de responsabilidades bien definidas.
14.1 Documentos Clave
TASKS.md: Define el rol y las tareas de cada agente. Este es el punto de partida para cualquier contribución.docs/CONVENTIONS.md: Establece las reglas técnicas y de estilo que todos los agentes deben seguir. La consistencia es fundamental.docs/agents/: Contiene las bitácoras individuales de cada agente. Es obligatorio que cada agente documente sus decisiones, progreso y bloqueos en su archivo correspondiente.
14.2 Proceso de Trabajo
- Consultar
TASKS.md: Identifica tu rol de agente y las tareas asignadas. - Revisar
docs/CONVENTIONS.md: Asegúrate de que tu trabajo se alinee con las convenciones del proyecto. - Ejecutar Tareas: Implementa la funcionalidad o realiza la tarea asignada.
- Actualizar Bitácora: Documenta lo que hiciste, por qué y cuál fue el resultado en tu archivo de bitácora en
docs/agents/. - Enviar Cambios: Sigue las convenciones de nomenclatura de ramas y mensajes de commit.
Este proceso estructurado garantiza la trazabilidad, facilita la colaboración y permite la orquestación eficiente del trabajo.
15. Nota final
Este README es el contrato técnico y funcional del sistema.
Si una implementación contradice este documento, la implementación está mal.