From fbb8649748378c4bdf1643941c6b3705f7ad44f3 Mon Sep 17 00:00:00 2001 From: Marco Gallegos Date: Thu, 18 Dec 2025 13:09:21 -0600 Subject: [PATCH] Create db_logic.md --- db_logic.md | 208 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 208 insertions(+) create mode 100644 db_logic.md diff --git a/db_logic.md b/db_logic.md new file mode 100644 index 0000000..8bd90ca --- /dev/null +++ b/db_logic.md @@ -0,0 +1,208 @@ +# Sistema Integrado de Gestión (Vanity) + +Este repositorio documenta la **especificación técnica completa** del ecosistema Vanity: infraestructura de datos, diccionarios de campos sin truncar, relaciones entre entidades y reglas de negocio que gobiernan los Bots, Recursos Humanos y el sistema de Asistencia. + +El objetivo es servir como **fuente de verdad técnica** para desarrollo, mantenimiento, auditoría y escalamiento. + +--- + +## 1. Arquitectura de Datos + +El sistema se distribuye en **tres bases de datos** dentro del mismo servidor, permitiendo integridad referencial y consultas cruzadas controladas: + +* **USERS_ALMA** → Seguridad, autenticación y control de acceso. +* **vanity_hr** → Gestión de personal, vacaciones, permisos y reglas laborales. +* **vanity_attendance** → Control de asistencia y programación de horarios. + +--- + +## 2. Diccionario de Datos + +### 2.1 Base de Datos: `vanity_hr` + +#### Tabla: `data_empleadas` (Maestra — 44 campos) + +Tabla central de Recursos Humanos. Contiene información contractual, personal, de contacto y metadatos de registro. + +| Campo | Tipo | Key | Descripción | +| ------------------------- | ------------ | --- | ---------------------------------- | +| numero_empleado | varchar(15) | PRI | ID único de nómina | +| puesto | varchar(50) | | Cargo / Puesto | +| sucursal | varchar(50) | | Sucursal asignada | +| fecha_ingreso | date | | Fecha de alta (base de antigüedad) | +| estatus | varchar(15) | | Activo / Baja | +| nombre_completo | varchar(150) | | Nombre completo concatenado | +| nombre | varchar(50) | | Nombre(s) | +| nombre_preferido | varchar(50) | | Apodo o nombre de preferencia | +| apellido_paterno | varchar(50) | | Primer apellido | +| apellido_materno | varchar(50) | | Segundo apellido | +| fecha_nacimiento | date | | Fecha de nacimiento | +| lugar_nacimiento | varchar(50) | | Ciudad / Estado | +| rfc | varchar(13) | UNI | RFC | +| curp | varchar(18) | UNI | CURP | +| email | varchar(100) | | Correo electrónico | +| telefono_celular | varchar(15) | | Teléfono móvil | +| domicilio_calle | varchar(255) | | Calle | +| domicilio_numero_exterior | varchar(10) | | Número exterior | +| domicilio_numero_interior | varchar(10) | | Número interior | +| domicilio_numero_texto | varchar(50) | | Referencias | +| domicilio_colonia | varchar(255) | | Colonia | +| domicilio_codigo_postal | varchar(10) | | CP | +| domicilio_ciudad | varchar(100) | | Ciudad | +| domicilio_estado | varchar(50) | | Estado | +| domicilio_completo | varchar(255) | | Dirección formateada | +| emergencia_nombre | varchar(100) | | Contacto de emergencia | +| emergencia_telefono | varchar(15) | | Teléfono de emergencia | +| emergencia_parentesco | varchar(50) | | Parentesco | +| referencia_1_nombre | varchar(100) | | Referencia 1 | +| referencia_1_telefono | varchar(15) | | Teléfono ref 1 | +| referencia_1_tipo | varchar(20) | | Tipo ref 1 | +| referencia_2_nombre | varchar(100) | | Referencia 2 | +| referencia_2_telefono | varchar(15) | | Teléfono ref 2 | +| referencia_2_tipo | varchar(20) | | Tipo ref 2 | +| referencia_3_nombre | varchar(100) | | Referencia 3 | +| referencia_3_telefono | varchar(15) | | Teléfono ref 3 | +| referencia_3_tipo | varchar(20) | | Tipo ref 3 | +| origen_registro | varchar(50) | | Web / Bot | +| telegram_usuario | varchar(50) | | Username Telegram | +| telegram_chat_id | bigint | | ID de chat Telegram | +| bot_version | varchar(20) | | Versión del bot | +| fecha_registro | datetime | | Timestamp creación | +| tiempo_registro_minutos | int | | Duración del registro | +| fecha_procesamiento | datetime(3) | | Timestamp procesado | + +--- + +#### Tabla: `vacaciones` (14 campos) + +| Campo | Tipo | Key | Descripción | +| ------------------- | ----------- | --- | -------------------------------------------- | +| vacaciones_id | varchar(50) | PRI | ID de solicitud | +| numero_empleado | varchar(15) | MUL | Relación con empleada | +| tipo_solicitud | varchar(20) | | VACACIONES | +| estatus | enum | | pendiente / aprobado / rechazado / cancelado | +| fecha_inicio | date | | Inicio | +| fecha_fin | date | | Fin | +| dias_solicitados | int | | Total días | +| dias_habiles | int | | Días descontados | +| motivo | text | | Observaciones | +| con_goce_sueldo | tinyint(1) | | 1 = Sí | +| fecha_solicitud | datetime | | Creación | +| fecha_procesamiento | datetime(3) | | Cambio de estatus | +| origen | varchar(20) | | telegram_bot / web | +| afecta_nomina | tinyint(1) | | Impacto en pago | + +--- + +#### Tabla: `permisos` (9 campos) + +| Campo | Tipo | Key | Descripción | +| ------------------ | ----------- | --- | -------------------------------------------- | +| permiso_id | varchar(50) | PRI | ID de permiso | +| numero_empleado | varchar(15) | MUL | Relación RH | +| categoria | enum | | PERSONAL / MEDICO / OFICIAL / OTRO | +| estatus | enum | | pendiente / aprobado / rechazado / cancelado | +| fecha_inicio | date | | Fecha | +| horario_especifico | varchar(50) | | Rango horario | +| motivo | text | | Razón | +| con_goce_sueldo | tinyint(1) | | 0 / 1 | +| afecta_nomina | tinyint(1) | | Impacto | + +--- + +### 2.2 Base de Datos: `vanity_attendance` + +#### Tabla: `asistencia_registros` (9 campos) + +| Campo | Tipo | Key | Descripción | +| ----------------- | ----------- | --- | -------------- | +| id_asistencia | int | PRI | Auto-increment | +| numero_empleado | varchar(15) | MUL | Relación RH | +| fecha | date | | Día | +| hora_entrada_real | time | | Entrada | +| hora_salida_real | time | | Salida | +| minutos_retraso | int | | Calculado | +| minutos_extra | int | | Excedente | +| sucursal_registro | varchar(50) | | Sucursal | +| telegram_id_usado | bigint | | ID Telegram | + +--- + +#### Tabla: `horario_empleadas` (Diccionario de turnos) + +| Campo | Tipo | Key | Descripción | +| -------------------- | ----------- | --- | ---------------- | +| id_horario | int | PRI | ID | +| numero_empleado | varchar(15) | MUL | Relación RH | +| telegram_id | bigint | | Llave webhook | +| dia_semana | varchar(20) | | monday, tuesday… | +| hora_entrada_teorica | time | | Entrada | +| hora_salida_teorica | time | | Salida | + +--- + +### 2.3 Base de Datos: `USERS_ALMA` + +#### Tabla: `users` (10 campos) + +| Campo | Tipo | Key | Descripción | +| ----------- | ------------ | --- | ---------------------- | +| id | int | PRI | ID interno | +| username | varchar(50) | UNI | Usuario | +| role | enum | | admin / manager / user | +| first_name | varchar(100) | | Nombre | +| last_name | varchar(100) | | Apellidos | +| email | varchar(100) | UNI | Correo | +| cell_phone | varchar(20) | | Teléfono | +| telegram_id | varchar(50) | UNI | Auth bot | +| created_at | timestamp | | Creación | +| updated_at | timestamp | | Actualización | + +--- + +## 3. Reglas de Negocio + +### 3.1 Vacaciones + +* **Antigüedad**: `FLOOR(DATEDIFF(fecha_inicio, fecha_ingreso) / 365.25)` +* **Ventana**: mínimo 12 días, máximo 45 días de anticipación +* **Validación**: no se permite solicitar periodos no cumplidos + +### 3.2 Asistencia + +* Identificación por `telegram_id` +* Cruce con `horario_empleadas` según día +* Cálculo de retraso contra horario teórico + +--- + +## 4. Integración Webhook (Horarios) + +* **Identificación**: `body.telegram.user_id` +* **Operación**: Upsert por día +* **Formato**: conversión de `10:00 AM` → `10:00:00` + +--- + +## 5. Consultas Operativas + +```sql +-- Saldo actual de vacaciones +SELECT * FROM vanity_hr.vista_saldos_vacaciones +WHERE numero_empleado = ?; + +-- Última solicitud +SELECT * FROM vanity_hr.vacaciones +WHERE numero_empleado = ? +ORDER BY fecha_solicitud DESC +LIMIT 1; + +-- Horario del día +SELECT hora_entrada_teorica +FROM vanity_attendance.horario_empleadas +WHERE telegram_id = ? AND dia_semana = 'monday'; +``` + +--- + +Este documento define el **contrato técnico** del sistema Vanity. Cualquier cambio estructural debe reflejarse aquí antes de pasar a producción.