From f6452aae722e3def2f03c0d365c00633b3abd86c Mon Sep 17 00:00:00 2001 From: Consultoria AS Date: Sat, 17 Jan 2026 18:58:36 -0800 Subject: [PATCH] Agregar documentacion de arquitectura y diagramas de base de datos - Diagrama de arquitectura general del sistema - Diagrama de flujo de datos - Diagrama ERD de modulos: Empleados, Gastos, Inventario, Hotel - Documentacion de funciones almacenadas principales - Estados del sistema y tipos de movimientos --- .claude/settings.local.json | 7 +- README.md | 4 + docs/ARQUITECTURA.md | 646 ++++++++++++++++++++++++++++++++++++ 3 files changed, 656 insertions(+), 1 deletion(-) create mode 100644 docs/ARQUITECTURA.md diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 0fa9f52..a4638e3 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -2,7 +2,12 @@ "permissions": { "allow": [ "Bash(curl:*)", - "Bash(git add:*)" + "Bash(git add:*)", + "Bash(git config:*)", + "Bash(git commit:*)", + "Bash(git remote add:*)", + "Bash(git push:*)", + "Bash(cat:*)" ] } } diff --git a/README.md b/README.md index 281c63e..1a503ac 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,10 @@ Sistema integral de gestion para el hotel Hacienda San Angel. Incluye modulos de administracion de empleados, nomina, inventario, gastos, ingresos, y reporteria. +## Documentacion + +- [Arquitectura y Diagramas de Base de Datos](docs/ARQUITECTURA.md) - Diagramas ERD, arquitectura del sistema y flujo de datos + ## Tecnologias ### Backend diff --git a/docs/ARQUITECTURA.md b/docs/ARQUITECTURA.md new file mode 100644 index 0000000..d14d31d --- /dev/null +++ b/docs/ARQUITECTURA.md @@ -0,0 +1,646 @@ +# Arquitectura del Sistema - Hacienda San Angel + +Este documento describe la arquitectura del sistema y la estructura de la base de datos. + +--- + +## Diagrama de Arquitectura General + +```mermaid +flowchart TB + subgraph Cliente["Cliente (Browser)"] + FE[Frontend React] + end + + subgraph Docker["Docker Compose"] + subgraph Frontend["Frontend Container :5172"] + VITE[Vite + React 19] + end + + subgraph Backend["Backend Container :4000"] + EXPRESS[Express.js API] + CONTROLLERS[Controllers] + ROUTES[Routes] + SERVICES[Services] + end + + subgraph Database["PostgreSQL Container :5432"] + PG[(PostgreSQL 15)] + FUNCTIONS[Stored Functions] + end + end + + subgraph External["Servicios Externos"] + STRIPE[Stripe API] + BANXICO[Banxico API] + BREVO[Brevo SMTP] + end + + FE <-->|HTTP/HTTPS| VITE + VITE <-->|API Calls| EXPRESS + EXPRESS --> CONTROLLERS + CONTROLLERS --> ROUTES + CONTROLLERS --> SERVICES + EXPRESS <-->|pg driver| PG + PG --> FUNCTIONS + + SERVICES -->|Payments| STRIPE + SERVICES -->|Exchange Rate| BANXICO + SERVICES -->|Email| BREVO + + style FE fill:#61dafb + style VITE fill:#646cff + style EXPRESS fill:#68a063 + style PG fill:#336791 + style STRIPE fill:#635bff + style BANXICO fill:#006847 + style BREVO fill:#0092ff +``` + +--- + +## Flujo de Datos + +```mermaid +sequenceDiagram + participant U as Usuario + participant F as Frontend (React) + participant B as Backend (Express) + participant DB as PostgreSQL + participant E as Servicios Externos + + U->>F: Interaccion UI + F->>B: HTTP Request (Axios) + B->>DB: Query/Function Call + DB-->>B: Result Set + + alt Requiere servicio externo + B->>E: API Call (Stripe/Banxico/Email) + E-->>B: Response + end + + B-->>F: JSON Response + F-->>U: Actualiza UI +``` + +--- + +## Estructura de Modulos + +```mermaid +flowchart LR + subgraph FrontendModules["Frontend Modules"] + direction TB + AUTH[Auth Context] + DASH[Dashboard] + EMP[Employees] + PAY[Payroll] + EXP[Expenses] + INV[Inventory] + INC[Income] + SET[Settings] + end + + subgraph BackendAPI["Backend API Endpoints"] + direction TB + A1[/api/auth] + A2[/api/employees] + A3[/api/contracts] + A4[/api/expenses] + A5[/api/products] + A6[/api/incomes] + A7[/api/payment] + A8[/api/settings] + end + + AUTH --> A1 + DASH --> A6 + EMP --> A2 + PAY --> A3 + EXP --> A4 + INV --> A5 + INC --> A6 + SET --> A8 +``` + +--- + +## Diagrama de Base de Datos (ERD) + +### Modulo de Empleados y Nomina + +```mermaid +erDiagram + EMPLOYEES { + int id_employees PK + varchar name_employee + varchar rfc_employee UK + bigint nss_employee + int id_position FK + int id_area FK + varchar addres_employee + varchar phone_employee + varchar email_employee + date birthday + varchar curp + } + + CONTRACTS { + int id_contract PK + int id_company FK + int id_properties FK + varchar rfc_employee FK + date contratc_start + date contratc_end + int id_contract_status FK + numeric daily_pay + } + + POSITIONS { + int id_position PK + varchar name_position + varchar spanish_name + } + + AREAS { + int id_area PK + varchar name_area + } + + STATUS_CONTRACT { + int id_stat_contract PK + varchar name_stat_contract + } + + UNIFORMS { + int id_uniform PK + varchar name_uniform + } + + DETAIL_UNIFOR_EMPLOYEE { + int id_detail PK + varchar rfc_employee FK + int id_uniform FK + } + + ATTENDANCE { + int id_attendance PK + varchar first_name + varchar last_name + varchar department + date date + date weekday + time work_start_time + time work_end_time + } + + EMPLOYEES ||--o{ CONTRACTS : has + EMPLOYEES ||--o{ DETAIL_UNIFOR_EMPLOYEE : wears + EMPLOYEES }o--|| POSITIONS : has + EMPLOYEES }o--|| AREAS : belongs_to + CONTRACTS }o--|| STATUS_CONTRACT : has + UNIFORMS ||--o{ DETAIL_UNIFOR_EMPLOYEE : assigned_to +``` + +### Modulo de Gastos y Pagos + +```mermaid +erDiagram + EXPENSES { + int id_expense PK + int id_properties FK + int id_expense_type FK + int id_recurrence FK + varchar description + int id_suppliers FK + date request_date + date payment_deadline + date approval_date + int id_request_by FK + int id_approval_by FK + int id_area FK + int id_expense_cat FK + int id_approval_stat FK + int id_currency FK + numeric subtotal + numeric iva + numeric ieps + numeric total + boolean is_monthly_expense + } + + PURCHASE_DETAIL { + int id_purchase_dt PK + int id_expense FK + int id_product FK + int quantity + int id_tax FK + numeric unit_cost + numeric total + int id_stock_mov FK + } + + PAYMENTS { + int id_payment PK + int id_expense FK + int id_payment_status FK + date payment_date + } + + SUPPLIERS { + int id_suppliers PK + varchar name_suppliers + varchar rfc_suppliers UK + varchar mail + varchar phone + } + + EXPENSE_CATEGORY { + int id_expense_cat PK + varchar name_category + varchar spanish_name + } + + APPROVAL_STATUS { + int id_approval_stat PK + varchar name_approval_stat + } + + PAYMENT_STATUS { + int id_payment_status PK + varchar name_pay_status + } + + CURRENCY { + int id_currency PK + varchar name_currency + } + + TAXES { + int id_tax PK + varchar percentage + numeric number + } + + EXPENSES ||--o{ PURCHASE_DETAIL : contains + EXPENSES ||--|| PAYMENTS : has + EXPENSES }o--|| SUPPLIERS : from + EXPENSES }o--|| EXPENSE_CATEGORY : categorized_as + EXPENSES }o--|| APPROVAL_STATUS : has + EXPENSES }o--|| CURRENCY : in + EXPENSES }o--|| AREAS : belongs_to + PAYMENTS }o--|| PAYMENT_STATUS : has + PURCHASE_DETAIL }o--|| TAXES : taxed_by + PURCHASE_DETAIL }o--o| PRODUCTS : includes +``` + +### Modulo de Inventario + +```mermaid +erDiagram + PRODUCTS { + int id_product PK + bytea image_product + varchar name_product + bigint sku_product + varchar rfc_suppliers FK + numeric price_product + int id_tax FK + int id_prod_category FK + int id_currency FK + int id_unit FK + } + + STOCK { + int id_stock PK + int id_product FK + bigint stock + } + + STOCK_MOVEMENTS { + int id_sto_mov PK + int id_product FK + int id_mov_type FK + date date_st_mov + bigint stock_before + bigint stock_current + } + + STOCK_ADJUSMENTS { + int id_stock_adjusment PK + int id_stock FK + varchar adjustment + date date_adjusment + int id_stock_mov FK + int id_expense FK + int id_product FK + } + + STOCK_DISCARD { + int id_stock_discard PK + int id_product FK + int quantity + varchar reason + date date_discard + int id_stock_mov FK + } + + STOCK_CONSUMPTION { + int id_consumption PK + varchar rfc_employee FK + date consumption_date + int consumption_quantity + int id_product FK + int id_stock_mov FK + } + + PRODUCT_CATEGORY { + int id_prod_category PK + varchar name_prod_category + varchar spanish_name + } + + PRODUCT_TYPE { + int id_product_type PK + varchar name_product_type + varchar spanish_name + } + + DETAIL_PRODUCT_TYPE { + int id_detail PK + int id_product FK + int id_product_type FK + } + + MOVEMENT_TYPE { + int id_mov_type PK + varchar name_mov_type + } + + UNIT { + int id_unit PK + varchar name_unit + } + + PRODUCTS ||--|| STOCK : has + PRODUCTS ||--o{ STOCK_MOVEMENTS : generates + PRODUCTS ||--o{ DETAIL_PRODUCT_TYPE : has + PRODUCTS }o--|| PRODUCT_CATEGORY : categorized_as + PRODUCTS }o--|| UNIT : measured_in + PRODUCTS }o--|| SUPPLIERS : from + STOCK_MOVEMENTS }o--|| MOVEMENT_TYPE : of_type + STOCK_MOVEMENTS ||--o| STOCK_ADJUSMENTS : creates + STOCK_MOVEMENTS ||--o| STOCK_DISCARD : creates + STOCK_MOVEMENTS ||--o| STOCK_CONSUMPTION : creates + PRODUCT_TYPE ||--o{ DETAIL_PRODUCT_TYPE : categorizes + STOCK_CONSUMPTION }o--|| EMPLOYEES : by +``` + +### Modulo de Ingresos y Hotel + +```mermaid +erDiagram + INCOMES { + int id_income PK + varchar room_type + varchar channel_name + date check_in + date check_out + numeric payment_total + varchar guest_name + varchar reservation_id + } + + PROPERTIES { + int id_properties PK + varchar name_propertie + int id_company FK + varchar addres_property + int main_area FK + varchar rfc_property + varchar phone_property + } + + ROOMS { + int id_room PK + varchar name_room + int id_properties FK + int units + numeric average_cost_per_night + int guests + int id_bed FK + } + + AMENITIES { + int id_amenity PK + varchar name_amenity + } + + DETAIL_AMENITIES { + int id_detail PK + int id_amenity FK + int id_room FK + } + + ROOM_PRODUCT { + int id_room_product PK + int id_room FK + int id_product FK + int quantity_product + } + + SERVICES { + int id_service PK + varchar name_service + } + + SERVICES_DETAIL { + int id_service_detail PK + int id_service FK + int id_property FK + varchar percentage + } + + EXCHANGE_RATE { + int id_exchange PK + date date_exchange + numeric rate + } + + PROPERTIES ||--o{ ROOMS : contains + ROOMS ||--o{ DETAIL_AMENITIES : has + ROOMS ||--o{ ROOM_PRODUCT : contains + AMENITIES ||--o{ DETAIL_AMENITIES : in + PRODUCTS ||--o{ ROOM_PRODUCT : used_in + PROPERTIES ||--o{ SERVICES_DETAIL : offers + SERVICES ||--o{ SERVICES_DETAIL : provided_at +``` + +### Modulo de Usuarios y Seguridad + +```mermaid +erDiagram + USERS { + int id_users PK + varchar name_user + int id_properties FK + int id_roles FK + varchar mail + varchar password_user + } + + ROLES { + int id_roles PK + varchar name_roles + } + + COMPANY { + int id_company PK + varchar name_company + varchar rfc_company + } + + USERS }o--|| ROLES : has + USERS }o--|| PROPERTIES : belongs_to + PROPERTIES }o--|| COMPANY : owned_by +``` + +--- + +## Diagrama Completo de Relaciones + +```mermaid +flowchart TB + subgraph Core["Nucleo del Sistema"] + COMPANY[Company] + PROPERTIES[Properties] + USERS[Users] + end + + subgraph HR["Recursos Humanos"] + EMPLOYEES[Employees] + CONTRACTS[Contracts] + ATTENDANCE[Attendance] + end + + subgraph Finance["Finanzas"] + EXPENSES[Expenses] + PAYMENTS[Payments] + INCOMES[Incomes] + end + + subgraph Inventory["Inventario"] + PRODUCTS[Products] + STOCK[Stock] + MOVEMENTS[Stock Movements] + end + + subgraph Hotel["Hotel"] + ROOMS[Rooms] + AMENITIES[Amenities] + SERVICES[Services] + end + + subgraph Catalogs["Catalogos"] + SUPPLIERS[Suppliers] + CATEGORIES[Categories] + POSITIONS[Positions] + AREAS[Areas] + end + + COMPANY --> PROPERTIES + PROPERTIES --> USERS + PROPERTIES --> ROOMS + PROPERTIES --> EMPLOYEES + + EMPLOYEES --> CONTRACTS + EMPLOYEES --> ATTENDANCE + + EXPENSES --> PAYMENTS + EXPENSES --> PRODUCTS + SUPPLIERS --> EXPENSES + SUPPLIERS --> PRODUCTS + + PRODUCTS --> STOCK + STOCK --> MOVEMENTS + + ROOMS --> AMENITIES + ROOMS --> SERVICES + ROOMS --> PRODUCTS + + CATEGORIES --> PRODUCTS + CATEGORIES --> EXPENSES + POSITIONS --> EMPLOYEES + AREAS --> EMPLOYEES + AREAS --> EXPENSES +``` + +--- + +## Funciones Almacenadas Principales + +| Funcion | Descripcion | Modulo | +|---------|-------------|--------| +| `validarusuario()` | Autenticacion de usuarios | Auth | +| `getemployees()` | Listar empleados con contratos | HR | +| `newcontract()` | Crear/renovar contrato de empleado | HR | +| `getcontracts()` | Listar contratos | HR | +| `expiredcontracts()` | Actualizar contratos vencidos | HR | +| `newexpensev2()` | Registrar nuevo gasto | Finance | +| `updateexpensev4()` | Actualizar gasto existente | Finance | +| `getmonthlypayments()` | Obtener pagos mensuales | Finance | +| `getpendingappexpenses()` | Gastos pendientes de aprobacion | Finance | +| `getproductsdisplay()` | Listar productos con stock | Inventory | +| `discardproductsstock()` | Descartar productos | Inventory | +| `consumptionstock()` | Registrar consumo de stock | Inventory | +| `setstockadjusmentsv2()` | Ajustar inventario | Inventory | +| `report_inventoryv2()` | Reporte de movimientos de inventario | Inventory | +| `getincomes()` | Obtener ingresos por periodo | Income | +| `channelscards()` | Analisis de canales de reserva | Income | +| `onegetchange()` | Obtener tipo de cambio | Exchange | +| `new_room()` | Crear habitacion con amenidades | Hotel | +| `new_property()` | Crear propiedad | Hotel | + +--- + +## Tipos de Movimientos de Inventario + +| ID | Tipo | Descripcion | +|----|------|-------------| +| 1 | Purchase | Entrada por compra | +| 2 | Adjustment | Ajuste de inventario | +| 3 | Discard | Descarte/Baja | +| 4 | Sale | Venta | +| 5 | Consumption | Consumo interno | + +--- + +## Estados del Sistema + +### Estados de Contrato +| ID | Estado | +|----|--------| +| 1 | Active | +| 2 | Expired | + +### Estados de Aprobacion +| ID | Estado | +|----|--------| +| 1 | Approved | +| 2 | Rejected | +| 3 | Pending | + +### Estados de Pago +| ID | Estado | +|----|--------| +| 1 | Paid | +| 2 | Pending | + +--- + +## Notas Tecnicas + +1. **Tipo de Cambio**: El sistema consulta automaticamente el tipo de cambio de Banxico para gastos en dolares +2. **Validacion de Stock**: Las funciones de descarte y consumo validan stock disponible antes de procesar +3. **Historial de Movimientos**: Cada movimiento de inventario registra stock anterior y actual +4. **Contratos Automaticos**: Existe una funcion para actualizar automaticamente contratos vencidos