mirror of
https://github.com/marcogll/telegram_new_socias.git
synced 2026-01-13 13:15:16 +00:00
docs: Actualizar y consolidar la documentación de la base de datos
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.
This commit is contained in:
Marco Gallegos
10
Readme.md
10
Readme.md
@@ -10,7 +10,9 @@ Este repositorio está pensado como **proyecto Python profesional**, modular y l
|
|||||||
|
|
||||||
Vanessa no es un chatbot genérico: es una interfaz conversacional para procesos reales de negocio.
|
Vanessa no es un chatbot genérico: es una interfaz conversacional para procesos reales de negocio.
|
||||||
|
|
||||||
- **Onboarding completo de nuevas socias (`/welcome`)**: Recolecta datos, valida que no existan duplicados en la DB, registra a la usuaria en `USERS_ALMA` y envía los datos a n8n.
|
- **Onboarding completo de nuevas socias (`/welcome`)**: Recolecta datos, valida que no existan duplicados en la DB, y ejecuta un registro en dos fases:
|
||||||
|
1. **Crea un usuario de acceso** en la tabla `USERS_ALMA.users` para la autenticación del bot.
|
||||||
|
2. **Crea un perfil de empleada** completo en la tabla `vanity_hr.data_empleadas`, que es la tabla maestra de RRHH.
|
||||||
- **Solicitud de vacaciones (`/vacaciones`)**: Flujo dinámico para gestionar días de descanso.
|
- **Solicitud de vacaciones (`/vacaciones`)**: Flujo dinámico para gestionar días de descanso.
|
||||||
- **Solicitud de permisos por horas (`/permiso`)**: Incluye clasificación de motivos mediante IA (Gemini).
|
- **Solicitud de permisos por horas (`/permiso`)**: Incluye clasificación de motivos mediante IA (Gemini).
|
||||||
|
|
||||||
@@ -100,8 +102,10 @@ Este comando levantará el bot y un contenedor de MySQL (si se usa el compose po
|
|||||||
|
|
||||||
### modules/database.py
|
### modules/database.py
|
||||||
- Centraliza la conexión a las 3 bases de datos (`USERS_ALMA`, `vanity_hr`, `vanity_attendance`).
|
- Centraliza la conexión a las 3 bases de datos (`USERS_ALMA`, `vanity_hr`, `vanity_attendance`).
|
||||||
- **Verificación de duplicados**: Ya no usa Google Sheets; ahora verifica el `telegram_id` directamente en la tabla `users`.
|
- **Verificación de duplicados**: Verifica el `telegram_id` en `USERS_ALMA.users` para evitar registros duplicados.
|
||||||
- **Registro de usuarias**: Función `register_user` para insertar candidatas tras el onboarding.
|
- **Registro de usuarias**: La función `register_user` implementa un registro en dos pasos:
|
||||||
|
1. Crea o actualiza el registro en `USERS_ALMA.users` para control de acceso.
|
||||||
|
2. Crea o actualiza el perfil completo de la empleada en `vanity_hr.data_empleadas`.
|
||||||
|
|
||||||
### modules/onboarding.py
|
### modules/onboarding.py
|
||||||
Recolección exhaustiva de datos. Al finalizar:
|
Recolección exhaustiva de datos. Al finalizar:
|
||||||
|
|||||||
10
db_logic.md
10
db_logic.md
@@ -206,3 +206,13 @@ 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.
|
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.
|
||||||
219
db_tasks.md
219
db_tasks.md
@@ -1,219 +0,0 @@
|
|||||||
# 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.
|
|
||||||
|
|
||||||
Reference in New Issue
Block a user