From 7696a0f4928568892a2c2961e3727010839df531 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 16 Dec 2025 16:47:37 +0000 Subject: [PATCH 1/3] feat: Add database schema documentation Creates a new `db_tasks.md` file that defines the database schema for the bot. This documentation includes table definitions for: - `users`: To store user information. - `permissions`: To manage user permissions for specific actions. - `welcome_flow_data`: To store data collected during the `/welcome` onboarding flow. The file also explains how the bot will interact with these tables to manage users, permissions, and the onboarding process. --- db_tasks.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 db_tasks.md diff --git a/db_tasks.md b/db_tasks.md new file mode 100644 index 0000000..6b2c6b6 --- /dev/null +++ b/db_tasks.md @@ -0,0 +1,72 @@ +# Definición de Tablas y Campos para la Base de Datos + +Este documento describe la estructura de la base de datos necesaria para el bot Vanessa, incluyendo tablas para usuarios, permisos y el flujo de bienvenida. + +## 1. Tabla de Usuarios (`users`) + +Esta tabla almacena la información básica de cada usuario que interactúa con el bot. + +| Campo | Tipo | Descripción | +|--------------|---------------|--------------------------------------------------| +| `id` | `INT` (PK) | Identificador único del usuario. | +| `telegram_id`| `BIGINT` | ID de Telegram del usuario. | +| `username` | `VARCHAR(255)`| Nombre de usuario de Telegram. | +| `first_name` | `VARCHAR(255)`| Nombre del usuario. | +| `last_name` | `VARCHAR(255)`| Apellido del usuario. | +| `is_active` | `BOOLEAN` | Indica si el usuario está activo (default `true`).| +| `created_at` | `DATETIME` | Fecha y hora de creación del registro. | +| `updated_at` | `DATETIME` | Fecha y hora de la última actualización. | + +## 2. Tabla de Permisos (`permissions`) + +Esta tabla gestiona los permisos de los usuarios para realizar acciones específicas. + +| Campo | Tipo | Descripción | +|-----------------------|------------|--------------------------------------------------------------------------| +| `id` | `INT` (PK) | Identificador único del permiso. | +| `user_id` | `INT` (FK) | Referencia al `id` del usuario en la tabla `users`. | +| `can_update_records` | `BOOLEAN` | Permite al usuario actualizar registros (default `false`). | +| `can_access_reports` | `BOOLEAN` | Permite al usuario acceder a reportes (default `false`). | +| `created_at` | `DATETIME` | Fecha y hora de creación del registro. | +| `updated_at` | `DATETIME` | Fecha y hora de la última actualización. | + +## 3. Tabla de Datos del Flujo de Bienvenida (`welcome_flow_data`) + +Esta tabla almacena los datos recopilados durante el flujo de `/welcome`. + +| Campo | Tipo | Descripción | +|-----------------|---------------|---------------------------------------------------------| +| `id` | `INT` (PK) | Identificador único del registro. | +| `user_id` | `INT` (FK) | Referencia al `id` del usuario en la tabla `users`. | +| `full_name` | `VARCHAR(255)`| Nombre completo del usuario. | +| `curp` | `VARCHAR(18)` | CURP del usuario. | +| `rfc` | `VARCHAR(13)` | RFC del usuario. | +| `nss` | `VARCHAR(11)` | Número de Seguridad Social (NSS) del usuario. | +| `address` | `TEXT` | Dirección del usuario. | +| `bank_account` | `VARCHAR(20)` | Número de cuenta bancaria del usuario. | +| `phone_number` | `VARCHAR(15)` | Número de teléfono del usuario. | +| `status` | `VARCHAR(50)` | Estado del flujo (e.g., 'in_progress', 'completed'). | +| `created_at` | `DATETIME` | Fecha y hora de creación del registro. | +| `updated_at` | `DATETIME` | Fecha y hora de la última actualización. | + +## 4. Interacción con la Base de Datos + +A continuación, se describe cómo el bot interactúa con estas tablas. + +### a. Gestión de Usuarios + +- **Creación de Usuario**: Cuando un nuevo usuario interactúa con el bot por primera vez (e.g., al usar `/start`), se crea un nuevo registro en la tabla `users` con su `telegram_id`, `username`, `first_name` y `last_name`. +- **Actualización de Usuario**: La información del usuario se puede actualizar si cambia su nombre de usuario, nombre o apellido en Telegram. +- **Estado del Usuario**: El campo `is_active` se utiliza para desactivar a un usuario si deja la empresa, sin eliminar sus registros. + +### b. Flujo de `/welcome` + +- **Inicio del Flujo**: Cuando un usuario inicia el flujo de `/welcome`, se crea un registro en la tabla `welcome_flow_data` con el `user_id` correspondiente y un estado de `in_progress`. +- **Recopilación de Datos**: A medida que el usuario proporciona su información (nombre, CURP, RFC, etc.), los campos correspondientes en la tabla `welcome_flow_data` se actualizan. +- **Finalización del Flujo**: Una vez que el usuario ha proporcionado toda la información, el estado en `welcome_flow_data` se actualiza a `completed`. + +### c. Gestión de Permisos + +- **Asignación de Permisos**: Los permisos se asignan a los usuarios a través de la tabla `permissions`. Por defecto, los usuarios no tienen permisos para actualizar registros o acceder a reportes. +- **Verificación de Permisos**: Antes de ejecutar comandos que requieran permisos especiales (e.g., un comando para actualizar la información de otro usuario), el bot consulta la tabla `permissions` para verificar si el usuario tiene los permisos necesarios. +- **Actualización de Registros**: Si un usuario tiene el permiso `can_update_records` establecido en `true`, podrá modificar la información en la tabla `welcome_flow_data` de otros usuarios. From c35a6cb6069d9f8c8659aa568dbf7ca125d903fe Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 16 Dec 2025 17:08:15 +0000 Subject: [PATCH 2/3] feat: Update database schema documentation Updates the `db_tasks.md` file to reflect the new database schema and role-based permission system. This change introduces: - A new `vacations` table to track vacation requests. - A new `permission_requests` table for hourly leave requests. - A redesigned `users` table with more detailed employee information and a `role` column. - A renamed and expanded `onboarding_data` table. - An updated database interaction section explaining the `user`, `manager`, and `admin` roles. --- db_tasks.md | 144 +++++++++++++++++++++++++++++++++------------------- 1 file changed, 91 insertions(+), 53 deletions(-) diff --git a/db_tasks.md b/db_tasks.md index 6b2c6b6..5a32eb1 100644 --- a/db_tasks.md +++ b/db_tasks.md @@ -1,72 +1,110 @@ # Definición de Tablas y Campos para la Base de Datos -Este documento describe la estructura de la base de datos necesaria para el bot Vanessa, incluyendo tablas para usuarios, permisos y el flujo de bienvenida. +Este documento describe la estructura de la base de datos para el bot Vanessa, diseñada para gestionar la información de empleadas, solicitudes y permisos. -## 1. Tabla de Usuarios (`users`) +## 1. Tabla de Usuarias (`users`) -Esta tabla almacena la información básica de cada usuario que interactúa con el bot. +Almacena la información central y el estado de cada empleada. -| Campo | Tipo | Descripción | -|--------------|---------------|--------------------------------------------------| -| `id` | `INT` (PK) | Identificador único del usuario. | -| `telegram_id`| `BIGINT` | ID de Telegram del usuario. | -| `username` | `VARCHAR(255)`| Nombre de usuario de Telegram. | -| `first_name` | `VARCHAR(255)`| Nombre del usuario. | -| `last_name` | `VARCHAR(255)`| Apellido del usuario. | -| `is_active` | `BOOLEAN` | Indica si el usuario está activo (default `true`).| -| `created_at` | `DATETIME` | Fecha y hora de creación del registro. | -| `updated_at` | `DATETIME` | Fecha y hora de la última actualización. | +| Campo | Tipo | Descripción | +|-------------------|-------------------------------|--------------------------------------------------------------------| +| `id` | `INT` (PK) | Identificador único de la usuaria. | +| `employee_number` | `VARCHAR(50)` (Unique) | Número de empleada único (e.g., "GAMM20260201"). | +| `telegram_id` | `BIGINT` (Unique) | ID de Telegram de la usuaria. | +| `telegram_username`| `VARCHAR(255)` | Nombre de usuario de Telegram. | +| `full_name` | `VARCHAR(255)` | Nombre completo. | +| `preferred_name` | `VARCHAR(100)` | Nombre con el que prefiere que la llamen. | +| `email` | `VARCHAR(255)` (Unique) | Correo electrónico. | +| `phone_number` | `VARCHAR(20)` | Teléfono celular. | +| `position` | `VARCHAR(100)` | Puesto que desempeña (e.g., "manager"). | +| `branch` | `VARCHAR(100)` | Sucursal a la que pertenece (e.g., "plaza_cima"). | +| `hire_date` | `DATE` | Fecha de ingreso a la empresa. | +| `status` | `ENUM('activo', 'inactivo')` | Estatus actual de la empleada. | +| `role` | `ENUM('user', 'manager', 'admin')` | Nivel de permisos en el sistema (por defecto: 'user'). | +| `created_at` | `DATETIME` | Fecha de creación del registro. | +| `updated_at` | `DATETIME` | Fecha de última actualización. | -## 2. Tabla de Permisos (`permissions`) +## 2. Tabla de Datos de Onboarding (`onboarding_data`) -Esta tabla gestiona los permisos de los usuarios para realizar acciones específicas. +Almacena la información detallada recopilada durante el flujo `/welcome`. Se vincula 1-a-1 con la tabla `users`. -| Campo | Tipo | Descripción | -|-----------------------|------------|--------------------------------------------------------------------------| -| `id` | `INT` (PK) | Identificador único del permiso. | -| `user_id` | `INT` (FK) | Referencia al `id` del usuario en la tabla `users`. | -| `can_update_records` | `BOOLEAN` | Permite al usuario actualizar registros (default `false`). | -| `can_access_reports` | `BOOLEAN` | Permite al usuario acceder a reportes (default `false`). | -| `created_at` | `DATETIME` | Fecha y hora de creación del registro. | -| `updated_at` | `DATETIME` | Fecha y hora de la última actualización. | +| Campo | Tipo | Descripción | +|-------------------------------|----------------|--------------------------------------------------------------------------| +| `id` | `INT` (PK) | Identificador único. | +| `user_id` | `INT` (FK) | Referencia a `users.id`. | +| `date_of_birth` | `DATE` | Fecha de nacimiento. | +| `place_of_birth` | `VARCHAR(255)` | Lugar de nacimiento. | +| `rfc` | `VARCHAR(13)` | RFC. | +| `curp` | `VARCHAR(18)` | CURP. | +| `nss` | `VARCHAR(11)` | Número de Seguridad Social. | +| `address_street` | `VARCHAR(255)` | Calle del domicilio. | +| `address_ext_number` | `VARCHAR(20)` | Número exterior. | +| `address_int_number` | `VARCHAR(20)` | Número interior (si aplica). | +| `address_neighborhood` | `VARCHAR(255)` | Colonia. | +| `address_zip_code` | `VARCHAR(10)` | Código Postal. | +| `address_city` | `VARCHAR(255)` | Ciudad. | +| `address_state` | `VARCHAR(255)` | Estado. | +| `emergency_contact_name` | `VARCHAR(255)` | Nombre del contacto de emergencia. | +| `emergency_contact_phone` | `VARCHAR(20)` | Teléfono del contacto de emergencia. | +| `emergency_contact_relationship` | `VARCHAR(50)`| Parentesco del contacto de emergencia. | +| `registration_source` | `VARCHAR(50)` | Origen del registro (e.g., "telegram_bot"). | +| `bot_version` | `VARCHAR(50)` | Versión del bot que procesó el alta. | +| `registration_time_minutes` | `INT` | Tiempo que tardó el registro en minutos. | +| `bot_interactions` | `INT` | Número de interacciones con el bot durante el alta. | +| `created_at` | `DATETIME` | Fecha de creación. | -## 3. Tabla de Datos del Flujo de Bienvenida (`welcome_flow_data`) +## 3. Tabla de Vacaciones (`vacations`) -Esta tabla almacena los datos recopilados durante el flujo de `/welcome`. +Mantiene un registro de las solicitudes de vacaciones de las empleadas. -| Campo | Tipo | Descripción | -|-----------------|---------------|---------------------------------------------------------| -| `id` | `INT` (PK) | Identificador único del registro. | -| `user_id` | `INT` (FK) | Referencia al `id` del usuario en la tabla `users`. | -| `full_name` | `VARCHAR(255)`| Nombre completo del usuario. | -| `curp` | `VARCHAR(18)` | CURP del usuario. | -| `rfc` | `VARCHAR(13)` | RFC del usuario. | -| `nss` | `VARCHAR(11)` | Número de Seguridad Social (NSS) del usuario. | -| `address` | `TEXT` | Dirección del usuario. | -| `bank_account` | `VARCHAR(20)` | Número de cuenta bancaria del usuario. | -| `phone_number` | `VARCHAR(15)` | Número de teléfono del usuario. | -| `status` | `VARCHAR(50)` | Estado del flujo (e.g., 'in_progress', 'completed'). | -| `created_at` | `DATETIME` | Fecha y hora de creación del registro. | -| `updated_at` | `DATETIME` | Fecha y hora de la última actualización. | +| Campo | Tipo | Descripción | +|---------------|-------------------------------------|--------------------------------------------------------------------| +| `id` | `INT` (PK) | Identificador único de la solicitud. | +| `user_id` | `INT` (FK) | Empleada que solicita (`users.id`). | +| `start_date` | `DATE` | Fecha de inicio de las vacaciones. | +| `end_date` | `DATE` | Fecha de fin de las vacaciones. | +| `status` | `ENUM('pending', 'approved', 'rejected')` | Estado de la solicitud. | +| `approver_id` | `INT` (FK, nullable) | Manager o admin que aprobó/rechazó la solicitud (`users.id`). | +| `comments` | `TEXT` | Comentarios del solicitante o del aprobador. | +| `created_at` | `DATETIME` | Fecha de creación de la solicitud. | +| `updated_at` | `DATETIME` | Fecha de última actualización (aprobación/rechazo). | -## 4. Interacción con la Base de Datos +## 4. Tabla de Permisos por Horas (`permission_requests`) -A continuación, se describe cómo el bot interactúa con estas tablas. +Registro de solicitudes de permisos por horas (llegar tarde, salir temprano, etc.). -### a. Gestión de Usuarios +| Campo | Tipo | Descripción | +|---------------|-------------------------------------|--------------------------------------------------------------------| +| `id` | `INT` (PK) | Identificador único del permiso. | +| `user_id` | `INT` (FK) | Empleada que solicita (`users.id`). | +| `request_date`| `DATE` | Fecha para la cual se solicita el permiso. | +| `start_time` | `TIME` | Hora de inicio del permiso. | +| `end_time` | `TIME` | Hora de fin del permiso. | +| `reason` | `TEXT` | Motivo de la solicitud. | +| `status` | `ENUM('pending', 'approved', 'rejected')` | Estado del permiso. | +| `approver_id` | `INT` (FK, nullable) | Manager o admin que gestionó el permiso (`users.id`). | +| `created_at` | `DATETIME` | Fecha de creación de la solicitud. | +| `updated_at` | `DATETIME` | Fecha de la gestión. | -- **Creación de Usuario**: Cuando un nuevo usuario interactúa con el bot por primera vez (e.g., al usar `/start`), se crea un nuevo registro en la tabla `users` con su `telegram_id`, `username`, `first_name` y `last_name`. -- **Actualización de Usuario**: La información del usuario se puede actualizar si cambia su nombre de usuario, nombre o apellido en Telegram. -- **Estado del Usuario**: El campo `is_active` se utiliza para desactivar a un usuario si deja la empresa, sin eliminar sus registros. +## 5. Interacción con la Base de Datos y Sistema de Roles -### b. Flujo de `/welcome` +El bot utiliza un sistema de roles para gestionar el acceso a los datos y funcionalidades. -- **Inicio del Flujo**: Cuando un usuario inicia el flujo de `/welcome`, se crea un registro en la tabla `welcome_flow_data` con el `user_id` correspondiente y un estado de `in_progress`. -- **Recopilación de Datos**: A medida que el usuario proporciona su información (nombre, CURP, RFC, etc.), los campos correspondientes en la tabla `welcome_flow_data` se actualizan. -- **Finalización del Flujo**: Una vez que el usuario ha proporcionado toda la información, el estado en `welcome_flow_data` se actualiza a `completed`. +### a. Roles de Usuario -### c. Gestión de Permisos +- **`user`**: Es el rol por defecto. Puede registrarse (`/welcome`), solicitar vacaciones (`/vacaciones`), pedir permisos (`/permiso`) y recibir notificaciones sobre el estado de sus solicitudes. +- **`manager`**: Tiene los mismos permisos que un `user`, pero además puede consultar la información de otras usuarias a través del flujo `/data_socias`. También puede aprobar o rechazar solicitudes de vacaciones y permisos de las usuarias a su cargo. +- **`admin`**: Tiene acceso completo a toda la información y funcionalidades. Puede gestionar usuarios, aprobar cualquier solicitud y acceder a todos los datos. -- **Asignación de Permisos**: Los permisos se asignan a los usuarios a través de la tabla `permissions`. Por defecto, los usuarios no tienen permisos para actualizar registros o acceder a reportes. -- **Verificación de Permisos**: Antes de ejecutar comandos que requieran permisos especiales (e.g., un comando para actualizar la información de otro usuario), el bot consulta la tabla `permissions` para verificar si el usuario tiene los permisos necesarios. -- **Actualización de Registros**: Si un usuario tiene el permiso `can_update_records` establecido en `true`, podrá modificar la información en la tabla `welcome_flow_data` de otros usuarios. +### b. Flujo de Solicitudes (Vacaciones y Permisos) + +1. **Creación**: Una usuaria (`user`) inicia el flujo (`/vacaciones` o `/permiso`). El bot crea un nuevo registro en la tabla correspondiente (`vacations` o `permission_requests`) con el estado `'pending'`. +2. **Notificación**: Se notifica a los `managers` y `admins` sobre la nueva solicitud. +3. **Gestión**: Un `manager` o `admin` revisa la solicitud. +4. **Actualización**: El `manager`/`admin` aprueba o rechaza la solicitud. El bot actualiza el registro correspondiente, cambiando el `status` a `'approved'` o `'rejected'`, y guardando el `approver_id`. +5. **Notificación Final**: Se notifica a la usuaria solicitante sobre la resolución de su petición. + +### c. Acceso a Datos (`/data_socias`) + +- Cuando un `manager` o `admin` utiliza el comando `/data_socias`, el bot consulta la tabla `users` y `onboarding_data` para devolver la información de las empleadas. +- Un `manager` solo podrá ver la información de las usuarias que reportan a él/ella (lógica de negocio a implementar), mientras que un `admin` podrá ver la de todas. From be4057b3ed030cd87f5de80aac3755ced509f1c1 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 16 Dec 2025 17:27:13 +0000 Subject: [PATCH 3/3] feat: Enhance database schema for vacation and permission tracking This commit significantly enhances the database schema defined in `db_tasks.md` to create a robust system for tracking employee vacations and permission requests. Key changes include: - **`users` table:** Added `vacation_days_assigned` and `vacation_days_taken` fields to maintain a running balance of employee vacation days. - **`vacations` table:** Overhauled the table with detailed fields such as `business_days`, `with_pay`, `approver_comments`, `approval_date`, and `affects_payroll` to create a comprehensive vacation tracking system. - **`permission_requests` table:** Similarly enhanced with fields like `category`, `with_pay`, and `affects_payroll` for detailed tracking of hourly leaves. - **Interaction Logic:** Updated the documentation to explain how vacation balances are automatically calculated and updated upon the approval of a request. --- db_tasks.md | 171 +++++++++++++++++++++++++--------------------------- 1 file changed, 81 insertions(+), 90 deletions(-) diff --git a/db_tasks.md b/db_tasks.md index 5a32eb1..0f9d930 100644 --- a/db_tasks.md +++ b/db_tasks.md @@ -1,110 +1,101 @@ # Definición de Tablas y Campos para la Base de Datos -Este documento describe la estructura de la base de datos para el bot Vanessa, diseñada para gestionar la información de empleadas, solicitudes y permisos. +Este documento describe la estructura de la base de datos para el bot Vanessa, diseñada para gestionar la información de empleadas, solicitudes y permisos de forma detallada. ## 1. Tabla de Usuarias (`users`) -Almacena la información central y el estado de cada empleada. +Almacena la información central, el estado y el balance de vacaciones de cada empleada. -| Campo | Tipo | Descripción | -|-------------------|-------------------------------|--------------------------------------------------------------------| -| `id` | `INT` (PK) | Identificador único de la usuaria. | -| `employee_number` | `VARCHAR(50)` (Unique) | Número de empleada único (e.g., "GAMM20260201"). | -| `telegram_id` | `BIGINT` (Unique) | ID de Telegram de la usuaria. | -| `telegram_username`| `VARCHAR(255)` | Nombre de usuario de Telegram. | -| `full_name` | `VARCHAR(255)` | Nombre completo. | -| `preferred_name` | `VARCHAR(100)` | Nombre con el que prefiere que la llamen. | -| `email` | `VARCHAR(255)` (Unique) | Correo electrónico. | -| `phone_number` | `VARCHAR(20)` | Teléfono celular. | -| `position` | `VARCHAR(100)` | Puesto que desempeña (e.g., "manager"). | -| `branch` | `VARCHAR(100)` | Sucursal a la que pertenece (e.g., "plaza_cima"). | -| `hire_date` | `DATE` | Fecha de ingreso a la empresa. | -| `status` | `ENUM('activo', 'inactivo')` | Estatus actual de la empleada. | -| `role` | `ENUM('user', 'manager', 'admin')` | Nivel de permisos en el sistema (por defecto: 'user'). | -| `created_at` | `DATETIME` | Fecha de creación del registro. | -| `updated_at` | `DATETIME` | Fecha de última actualización. | +| Campo | Tipo | Descripción | +|--------------------------|-------------------------------|--------------------------------------------------------------------------| +| `id` | `INT` (PK) | Identificador único de la usuaria. | +| `employee_number` | `VARCHAR(50)` (Unique) | Número de empleada único. | +| `telegram_id` | `BIGINT` (Unique) | ID de Telegram de la usuaria. | +| `telegram_username` | `VARCHAR(255)` | Nombre de usuario de Telegram. | +| `full_name` | `VARCHAR(255)` | Nombre completo. | +| `preferred_name` | `VARCHAR(100)` | Nombre preferido de la empleada. | +| `email` | `VARCHAR(255)` (Unique) | Correo electrónico. | +| `phone_number` | `VARCHAR(20)` | Teléfono celular. | +| `position` | `VARCHAR(100)` | Puesto que desempeña. | +| `branch` | `VARCHAR(100)` | Sucursal a la que pertenece. | +| `hire_date` | `DATE` | Fecha de ingreso a la empresa. | +| `status` | `ENUM('activo', 'inactivo')` | Estatus actual de la empleada. | +| `role` | `ENUM('user', 'manager', 'admin')` | Nivel de permisos en el sistema (por defecto: 'user'). | +| `vacation_days_assigned` | `INT` | Días de vacaciones asignados para el periodo actual. | +| `vacation_days_taken` | `INT` (Default: 0) | Suma de días de vacaciones aprobados y tomados. | +| `created_at` | `DATETIME` | Fecha de creación del registro. | +| `updated_at` | `DATETIME` | Fecha de última actualización. | -## 2. Tabla de Datos de Onboarding (`onboarding_data`) +## 2. Tabla de Solicitudes de Vacaciones (`vacations`) -Almacena la información detallada recopilada durante el flujo `/welcome`. Se vincula 1-a-1 con la tabla `users`. +Registro detallado de las solicitudes de vacaciones. -| Campo | Tipo | Descripción | -|-------------------------------|----------------|--------------------------------------------------------------------------| -| `id` | `INT` (PK) | Identificador único. | -| `user_id` | `INT` (FK) | Referencia a `users.id`. | -| `date_of_birth` | `DATE` | Fecha de nacimiento. | -| `place_of_birth` | `VARCHAR(255)` | Lugar de nacimiento. | -| `rfc` | `VARCHAR(13)` | RFC. | -| `curp` | `VARCHAR(18)` | CURP. | -| `nss` | `VARCHAR(11)` | Número de Seguridad Social. | -| `address_street` | `VARCHAR(255)` | Calle del domicilio. | -| `address_ext_number` | `VARCHAR(20)` | Número exterior. | -| `address_int_number` | `VARCHAR(20)` | Número interior (si aplica). | -| `address_neighborhood` | `VARCHAR(255)` | Colonia. | -| `address_zip_code` | `VARCHAR(10)` | Código Postal. | -| `address_city` | `VARCHAR(255)` | Ciudad. | -| `address_state` | `VARCHAR(255)` | Estado. | -| `emergency_contact_name` | `VARCHAR(255)` | Nombre del contacto de emergencia. | -| `emergency_contact_phone` | `VARCHAR(20)` | Teléfono del contacto de emergencia. | -| `emergency_contact_relationship` | `VARCHAR(50)`| Parentesco del contacto de emergencia. | -| `registration_source` | `VARCHAR(50)` | Origen del registro (e.g., "telegram_bot"). | -| `bot_version` | `VARCHAR(50)` | Versión del bot que procesó el alta. | -| `registration_time_minutes` | `INT` | Tiempo que tardó el registro en minutos. | -| `bot_interactions` | `INT` | Número de interacciones con el bot durante el alta. | -| `created_at` | `DATETIME` | Fecha de creación. | +| Campo | Tipo | Descripción | +|---------------------|------------------------------------|--------------------------------------------------------------------------| +| `id` | `INT` (PK) | Identificador numérico de la solicitud. | +| `request_id` | `VARCHAR(50)` (Unique) | Identificador alfanumérico único de la solicitud (e.g., "7c32a085..."). | +| `user_id` | `INT` (FK) | Empleada que solicita (`users.id`). | +| `status` | `ENUM('pendiente', 'aprobado', 'rechazado')` | Estado actual de la solicitud. | +| `start_date` | `DATE` | Fecha de inicio de las vacaciones. | +| `end_date` | `DATE` | Fecha de fin de las vacaciones. | +| `requested_days` | `INT` | Número de días naturales solicitados. | +| `business_days` | `INT` | Número de días hábiles que abarca la solicitud. | +| `reason` | `TEXT` | Motivo de la solicitud. | +| `with_pay` | `BOOLEAN` | `TRUE` si es con goce de sueldo. | +| `leave_type` | `ENUM('con_goce', 'sin_goce')` | Clasificación del tipo de permiso. | +| `request_date` | `DATETIME` | Fecha y hora en que se creó la solicitud. | +| `processed_date` | `DATETIME` | Fecha y hora en que se procesó en el sistema (e.g., envío a webhook). | +| `source` | `VARCHAR(50)` | Origen de la solicitud (e.g., "telegram_bot"). | +| `approver_id` | `INT` (FK, nullable) | Usuario (`users.id`) que aprobó o rechazó. | +| `approval_date` | `DATETIME` (nullable) | Fecha y hora de la aprobación o rechazo. | +| `approver_comments` | `TEXT` (nullable) | Comentarios del aprobador. | +| `affects_payroll` | `BOOLEAN` | `TRUE` si la solicitud tiene implicaciones en la nómina. | -## 3. Tabla de Vacaciones (`vacations`) +## 3. Tabla de Solicitudes de Permisos por Horas (`permission_requests`) -Mantiene un registro de las solicitudes de vacaciones de las empleadas. +Registro detallado de permisos especiales por horas. -| Campo | Tipo | Descripción | -|---------------|-------------------------------------|--------------------------------------------------------------------| -| `id` | `INT` (PK) | Identificador único de la solicitud. | -| `user_id` | `INT` (FK) | Empleada que solicita (`users.id`). | -| `start_date` | `DATE` | Fecha de inicio de las vacaciones. | -| `end_date` | `DATE` | Fecha de fin de las vacaciones. | -| `status` | `ENUM('pending', 'approved', 'rejected')` | Estado de la solicitud. | -| `approver_id` | `INT` (FK, nullable) | Manager o admin que aprobó/rechazó la solicitud (`users.id`). | -| `comments` | `TEXT` | Comentarios del solicitante o del aprobador. | -| `created_at` | `DATETIME` | Fecha de creación de la solicitud. | -| `updated_at` | `DATETIME` | Fecha de última actualización (aprobación/rechazo). | +| Campo | Tipo | Descripción | +|---------------------|------------------------------------|--------------------------------------------------------------------------| +| `id` | `INT` (PK) | Identificador numérico del permiso. | +| `request_id` | `VARCHAR(50)` (Unique) | Identificador alfanumérico único (e.g., "1LSRADeDNfY"). | +| `user_id` | `INT` (FK) | Empleada que solicita (`users.id`). | +| `category` | `VARCHAR(100)` | Categoría del permiso (e.g., "PERSONAL", "MÉDICO"). | +| `status` | `ENUM('pendiente', 'aprobado', 'rechazado')` | Estado actual del permiso. | +| `permission_date` | `DATE` | Fecha para la cual se solicita el permiso. | +| `start_time` | `TIME` | Hora de inicio del permiso. | +| `end_time` | `TIME` | Hora de fin del permiso. | +| `reason` | `TEXT` | Motivo detallado del permiso. | +| `with_pay` | `BOOLEAN` | `TRUE` si es con goce de sueldo. | +| `leave_type` | `ENUM('con_goce', 'sin_goce')` | Clasificación del tipo de permiso. | +| `request_date` | `DATETIME` | Fecha y hora en que se creó la solicitud. | +| `processed_date` | `DATETIME` | Fecha y hora en que se procesó. | +| `source` | `VARCHAR(50)` | Origen de la solicitud. | +| `approver_id` | `INT` (FK, nullable) | Usuario (`users.id`) que gestionó el permiso. | +| `approval_date` | `DATETIME` (nullable) | Fecha y hora de la gestión. | +| `approver_comments` | `TEXT` (nullable) | Comentarios del aprobador. | +| `affects_payroll` | `BOOLEAN` | `TRUE` si el permiso tiene implicaciones en la nómina. | -## 4. Tabla de Permisos por Horas (`permission_requests`) +## 4. Interacción con la Base de Datos y Lógica de Negocio -Registro de solicitudes de permisos por horas (llegar tarde, salir temprano, etc.). +### a. Sistema de Roles -| Campo | Tipo | Descripción | -|---------------|-------------------------------------|--------------------------------------------------------------------| -| `id` | `INT` (PK) | Identificador único del permiso. | -| `user_id` | `INT` (FK) | Empleada que solicita (`users.id`). | -| `request_date`| `DATE` | Fecha para la cual se solicita el permiso. | -| `start_time` | `TIME` | Hora de inicio del permiso. | -| `end_time` | `TIME` | Hora de fin del permiso. | -| `reason` | `TEXT` | Motivo de la solicitud. | -| `status` | `ENUM('pending', 'approved', 'rejected')` | Estado del permiso. | -| `approver_id` | `INT` (FK, nullable) | Manager o admin que gestionó el permiso (`users.id`). | -| `created_at` | `DATETIME` | Fecha de creación de la solicitud. | -| `updated_at` | `DATETIME` | Fecha de la gestión. | - -## 5. Interacción con la Base de Datos y Sistema de Roles - -El bot utiliza un sistema de roles para gestionar el acceso a los datos y funcionalidades. - -### a. Roles de Usuario - -- **`user`**: Es el rol por defecto. Puede registrarse (`/welcome`), solicitar vacaciones (`/vacaciones`), pedir permisos (`/permiso`) y recibir notificaciones sobre el estado de sus solicitudes. -- **`manager`**: Tiene los mismos permisos que un `user`, pero además puede consultar la información de otras usuarias a través del flujo `/data_socias`. También puede aprobar o rechazar solicitudes de vacaciones y permisos de las usuarias a su cargo. -- **`admin`**: Tiene acceso completo a toda la información y funcionalidades. Puede gestionar usuarios, aprobar cualquier solicitud y acceder a todos los datos. +- **`user`**: Rol estándar para todas las empleadas. Pueden solicitar vacaciones y permisos, y consultar su propio estado. +- **`manager`**: Puede realizar las mismas acciones que un `user`, y adicionalmente, aprobar/rechazar solicitudes y consultar datos de las usuarias a su cargo. +- **`admin`**: Acceso total. Puede gestionar todos los datos de todas las usuarias y solicitudes. ### b. Flujo de Solicitudes (Vacaciones y Permisos) -1. **Creación**: Una usuaria (`user`) inicia el flujo (`/vacaciones` o `/permiso`). El bot crea un nuevo registro en la tabla correspondiente (`vacations` o `permission_requests`) con el estado `'pending'`. -2. **Notificación**: Se notifica a los `managers` y `admins` sobre la nueva solicitud. -3. **Gestión**: Un `manager` o `admin` revisa la solicitud. -4. **Actualización**: El `manager`/`admin` aprueba o rechaza la solicitud. El bot actualiza el registro correspondiente, cambiando el `status` a `'approved'` o `'rejected'`, y guardando el `approver_id`. -5. **Notificación Final**: Se notifica a la usuaria solicitante sobre la resolución de su petición. +1. **Creación**: Una usuaria crea una solicitud. El sistema la inserta en la tabla `vacations` o `permission_requests` con estado `'pendiente'`. +2. **Aprobación**: Un `manager` o `admin` revisa la solicitud. Al aprobarla: + * El `status` de la solicitud cambia a `'aprobado'`. + * Se registran el `approver_id`, `approval_date` y `approver_comments`. +3. **Actualización de Balance de Vacaciones**: + * **Si la solicitud es de vacaciones y fue aprobada**: El sistema debe sumar los `business_days` de la solicitud al campo `vacation_days_taken` de la usuaria en la tabla `users`. + * Esta lógica asegura que el balance de días tomados siempre esté sincronizado con los registros aprobados. -### c. Acceso a Datos (`/data_socias`) +### c. Lógica de Negocio Clave -- Cuando un `manager` o `admin` utiliza el comando `/data_socias`, el bot consulta la tabla `users` y `onboarding_data` para devolver la información de las empleadas. -- Un `manager` solo podrá ver la información de las usuarias que reportan a él/ella (lógica de negocio a implementar), mientras que un `admin` podrá ver la de todas. +- **Balance de Vacaciones**: El balance de días disponibles de una empleada se calcula en tiempo real como `vacation_days_assigned` - `vacation_days_taken`. +- **Nómina**: El campo `affects_payroll` sirve como una bandera para que los sistemas externos de RRHH sepan que una solicitud específica (e.g., un permiso sin goce de sueldo) requiere un ajuste en la nómina. +- **Auditoría**: Todas las fechas (`request_date`, `approval_date`) y IDs (`user_id`, `approver_id`) permiten una auditoría completa de cada solicitud.