mirror of
https://github.com/marcogll/telegram_new_socias.git
synced 2026-01-13 13:15:16 +00:00
9cb9513c41
Se ha actualizado el archivo para describir con mayor precisión el proceso de registro de usuarios en dos fases, que implica la creación de un registro tanto en la base de datos como en . Además, se ha consolidado la documentación de la base de datos eliminando el archivo redundante y fusionando su contenido en . Esto asegura que sirva como la única fuente de verdad para la especificación técnica de la base de datos.
218 lines
11 KiB
Markdown
218 lines
11 KiB
Markdown
# 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.
|
|
|
|
---
|
|
|
|
# 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. |