telegram_new_socias/db_logic.md

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

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

Los capturados desde /horario generan un registro por día mediante upsert (por telegram_id + dia_semana).

---

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

---

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 vanity_hr.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
• Persistencia: vanity_hr.horario_empleadas (clave telegram_id + dia_semana)
• Formato: conversión de 10:00 AM → 10:00:00

---

5. Consultas Operativas

-- 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_hr.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.

---

DB Implementation Tasks

1. Create initialization script: Write a SQL script to create the databases and tables.
2. Modify docker-compose.yml: Mount the initialization script.
3. Update .env.example: Add new environment variables.
4. Implement SQLAlchemy models: Create Python classes for each table.
5. Refactor database logic: Use the new models in the application.