mirror of
https://github.com/marcogll/telegram_new_socias.git
synced 2026-01-13 13:15:16 +00:00
Create db_logic.md
This commit is contained in:
Marco Gallegos
208
db_logic.md
Normal file
208
db_logic.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user