mirror of
https://github.com/marcogll/hr_soul23.git
synced 2026-01-13 13:25:16 +00:00
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).
284 lines
6.5 KiB
Markdown
284 lines
6.5 KiB
Markdown
# 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
|
||
|
||
1. **Consultar `TASKS.md`**: Identifica tu rol de agente y las tareas asignadas.
|
||
2. **Revisar `docs/CONVENTIONS.md`**: Asegúrate de que tu trabajo se alinee con las convenciones del proyecto.
|
||
3. **Ejecutar Tareas**: Implementa la funcionalidad o realiza la tarea asignada.
|
||
4. **Actualizar Bitácora**: Documenta lo que hiciste, por qué y cuál fue el resultado en tu archivo de bitácora en `docs/agents/`.
|
||
5. **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.
|