Saltearse al contenido
Documentación de la Plataforma Algesta

Frontend Feature Modules

Frontend Feature Modules

Version: 1.0 Date: 2025-11-19 Project: Algesta Dashboard React

Tabla de Contenidos

  1. Patrón de Módulo de Funcionalidad
  2. Documentación de Módulos de Funcionalidad
  3. Patrones de Integración de Funcionalidades
  4. Patrones Comunes Entre Funcionalidades

Patrón de Módulo de Funcionalidad

El Dashboard de Algesta sigue la estructura de funcionalidades Bulletproof React. Cada funcionalidad es autocontenida y organizada consistentemente.

Estructura de Directorio Estándar

features/[feature-name]/
├── api/              # API calls (e.g., get-orders.ts, patch-order.ts)
├── components/       # Feature-specific components
├── hooks/            # Custom React hooks
├── pages/            # Page components (optional)
├── schema/           # Zod validation schemas
├── validations/      # Additional validation logic
├── constants/        # Feature constants (e.g., table columns)
├── utils/            # Feature utilities
├── types/            # TypeScript types
└── index.ts          # Public API exports

Convenciones de Nomenclatura

  • Archivos: kebab-case (ej., get-orders.ts, order-Resumen-card.tsx)
  • Componentes: PascalCase (ej., OrderResumenCard, ModalFormOrder)
  • Hooks: camelCase con prefijo use (ej., useOrders, useCreateOrderForm)
  • Funciones API: camelCase (ej., getOrders, updateOrder)

Documentación de Módulos de Funcionalidad

1. Funcionalidad Auth

Propósito: Autenticación y registro de usuarios

Roles de Usuario: Todos (rutas públicas)

Componentes Clave:

  • login-form.tsx - Formulario de login con email y contraseña
  • signup-client-form.tsx - Formulario de registro de cliente
  • signup-provider-form.tsx - Formulario de registro de proveedor
  • signup-base-form.tsx - Lógica de formulario compartida
  • forgot-password-form.tsx - Solicitud de recuperación de contraseña
  • reset-password-form.tsx - Establecer nueva contraseña
  • auth-layout.tsx - Diseño consistente para páginas de autenticación

Endpoints API:

  • /api/auth/login - Login de usuario
  • /api/auth/register - Registro de usuario
  • /api/auth/forgot-password - Solicitud de restablecimiento de contraseña
  • /api/auth/reset-password - Restablecer contraseña

Esquemas de Validación:

  • login-schema.ts - Validación de email y contraseña
  • signup-schema.ts - Validación de registro
  • forgot-password-schema.ts - Validación de email
  • reset-password-schema.ts - Validación de nueva contraseña

Rutas:

  • /auth/login - Página de login
  • /auth/register-client - Registro de cliente
  • /auth/register-provider - Registro de proveedor
  • /auth/forgot-password - Recuperación de contraseña
  • /auth/reset-password - Restablecer contraseña

Integración: Utiliza react-query-auth para gestión de estado de autenticación. Token JWT almacenado en localStorage e incluido en todas las solicitudes API subsecuentes.

Referencia: src/Funcionalidades/auth/

2. Orders Feature

Propósito: Complete order lifecycle management from creation to completion

User Roles: Admin, Agent

Key Componentes:

  • List & Filters:
    • orders-list-filters.tsx - Filter and search orders
    • order-Resumen-card.tsx - Order Descripción General card
  • Forms:
    • modal-form-order.tsx - Create/edit order modal
    • order-form.tsx - Order form fields
  • Assignment:
    • assignation-card.tsx - Provider assignment card
    • expandable-quotation-order.tsx - Quotation details
    • time-auction.tsx - Auction countdown timer
  • Work Execution:
    • final-report.tsx - Work completion report
    • work-progress-card.tsx - Progress tracking

API Endpoints:

  • get-orders.ts - List orders with pagination and filters
  • get-order.ts - Get single order details
  • patch-order.ts - Update order
  • post-order-asset.ts - Add asset to order
  • post-provider-technical-visit.ts - Schedule technical visit
  • final-report-accept.ts - Approve work
  • final-report-reject.ts - Reject work

Hooks:

  • use-order-filter-query-state.ts - URL state for filters
  • use-create-order-form.ts - Order creation form logic
  • use-edit-order-form.ts - Order editing form logic
  • use-asset-form.ts - Asset addition form
  • use-orders.ts - Fetch orders list
  • use-order.ts - Fetch single order

Validation Schemas:

  • create-order-schema.ts - Order creation validation
  • edit-order-schema.ts - Order update validation
  • asset-schema.ts - Asset validation

Routes:

  • /app/orders - Orders list
  • /app/orders/:id - Order details
  • /app/orders/:id/work-report - Work report view

State Flow:

sequenceDiagram
    participant Admin as Admin/Agent
    participant OrderForm as Order Form
    participant API as API
    participant Auction as Auction System
    participant Provider as Provider
    participant Client as Client

    Admin->>OrderForm: Create new order
    OrderForm->>API: POST /api/orders
    API->>Auction: Create auction
    Auction->>Provider: Notify providers
    Provider->>Auction: Submit bids
    Admin->>Auction: Select winning bid
    Auction->>Provider: Assign work
    Provider->>API: Complete work
    API->>Client: Notify completion
    Client->>API: Approve/Reject work

Reference: src/Funcionalidades/orders/

3. Marketplace/Auctions Feature

Propósito: Auction system for provider bidding and quotation selection

User Roles: Admin, Agent (view/manage), Provider (bid)

Key Componentes:

Admin/Agent Componentes:

  • auction-list-filters.tsx - Filter auctions
  • auction-card.tsx - Auction Descripción General card
  • auction-finished-dialog.tsx - Finished auction details
  • bid-list.tsx - List of bids for auction
  • select-quotation-form.tsx - Select winning quotation

Provider Componentes:

  • provider-auction-card.tsx - Auction card for providers
  • provider-offer-form.tsx - Submit bid/offer
  • provider-auction-details.tsx - Auction details

API Endpoints:

  • auctions.ts - List Activo auctions
  • get-finished-auctions.ts - List Completod auctions
  • auction-bids.ts - Get bids for an auction
  • provider-auction-details.ts - Auction details for provider
  • submit-bid.ts - Provider submits bid

Hooks:

  • use-auction-list-filter-query-state.ts - Admin/Agent auction filters
  • use-provider-auction-list-filter-query-state.ts - Provider auction filters
  • use-auction-bid-filter-query-state.ts - Bid list filters
  • use-auctions.ts - Fetch auctions list
  • use-submit-bid.ts - Submit bid mutation

Routes:

Admin/Agent:

  • /app/marketplace/auctions - Activo auctions list
  • /app/marketplace/auctions/:id/bids - Auction bids
  • /app/marketplace/auctions/finished - Finished auctions

Provider:

  • /app/marketplace/provider/auctions - Available auctions
  • /app/marketplace/provider/auctions/:id - Auction details
  • /app/marketplace/provider/auctions/:id/offer - Submit offer

Workflow:

flowchart TD
    A[Order Created] --> B[Auction Created]
    B --> C[Auction Open for Bids]
    C --> D{Bidding Period}
    D -->|Providers Submit Bids| E[Bids Collected]
    E --> F[Auction Closed]
    F --> G{Admin/Agent Review}
    G -->|Select Winner| H[Winner Selected]
    G -->|No Suitable Bids| I[Reopen Auction]
    H --> J[Provider Assigned]
    I --> C

Reference: src/Funcionalidades/marketplace/

4. Providers Feature

Propósito: Provider-specific functionality for work management, invoices, profile, and Document uploads

User Roles: Provider

Key Componentes:

Work Management:

  • provider-works-list-filters.tsx - Filter works
  • work-detail-info-card.tsx - Work information
  • work-detail-client-card.tsx - Client information

Work Process Flow (7 steps):

  1. accept-reject-work.tsx - Accept or reject assigned work
  2. start-work.tsx - Mark work as started
  3. work-inspection.tsx - Initial inspection
  4. register-process.tsx - Register work progress
  5. final-register.tsx - Final registration
  6. send-report.tsx - Submit final report
  7. Resumen-view.tsx - Work Resumen

Invoices:

  • invoices-filters.tsx - Filter invoices
  • invoice-detail.tsx - Invoice details
  • card-advance-payment.tsx - Advance payment card
  • card-final-payment.tsx - Final payment card

Profile:

  • personal-info-card.tsx - Personal information
  • service-offered-card.tsx - Services offered
  • history-performance-card.tsx - Performance history

Documentos:

  • upload-Documento-item.tsx - Document upload item
  • header-card-upload-Documento.tsx - Upload header

API Endpoints:

  • get-work-details.ts - Get work details
  • get-work-Resumen.ts - Get work Resumen for report
  • update-work-details.ts - Update work progress
  • post-send-report.ts - Submit final report
  • get-invoices.ts - List invoices
  • provider-profile.ts - Get/update profile
  • upload-Documento.ts - Upload required Documentos
  • post-discount-provider.ts - Request discount
  • get-initial-inspection.ts - Get inspection data

Hooks:

  • use-provider-works-filter-query-state.ts - Work list filters
  • use-provider-work-state.ts - Work detail state
  • use-provider-invoice-state.ts - Invoice state
  • use-upload-Documento.ts - Document upload logic

Routes:

  • /app/providers/my-works - Works list
  • /app/providers/my-works/:id - Work details
  • /app/providers/invoices - Invoices list
  • /app/providers/profile - Provider profile
  • /app/providers/upload-Documentos - Document upload

Work Process Flow:

stateDiagram-v2
    [*] --> Assigned: Work Assigned
    Assigned --> Accepted: Accept Work
    Assigned --> Rejected: Reject Work
    Rejected --> [*]
    Accepted --> Started: Start Work
    Started --> Inspection: Initial Inspection
    Inspection --> InProgress: Register Process
    InProgress --> InProgress: Update Progress
    InProgress --> FinalRegister: Final Register
    FinalRegister --> ReportSent: Send Report
    ReportSent --> Completed: Client Approves
    ReportSent --> InProgress: Client Rejects
    Completed --> [*]

Reference: src/Funcionalidades/providers/

5. Assets Feature

Propósito: Asset management, lifecycle tracking, and error management

User Roles: Admin, Agent

Key Componentes:

List Views:

  • list-filter.tsx - Asset list filters
  • list-filter-errors.tsx - Error list filters

Forms:

  • information-asset.tsx - Asset information form
  • assessment.tsx - Asset assessment form
  • purchase-record.tsx - Purchase record form
  • level-of-importance.tsx - Importance level form

HV (Historia de Vida/Lifecycle):

  • information-asset-hv.tsx - Asset lifecycle info
  • assessment-hv.tsx - Assessment history
  • historical-record-hv.tsx - Historical records
  • purchase-record-hv.tsx - Purchase history
  • level-of-importance-hv.tsx - Importance history

Modals:

  • modal-create-Activo.tsx - Create asset modal
  • modal-export.tsx - Export asset data

API Endpoints:

  • get-assets.ts - List assets with filters
  • get-categories.ts - Get asset categories
  • get-lifecycle.ts - Get asset lifecycle/history
  • get-companies.ts - Get companies for assignment
  • delete-asset.ts - Delete asset
  • export-asset.ts - Export asset data

Hooks:

  • use-assets-filter-query-state.ts - Asset list filters
  • use-create-assets-form.ts - Asset creation form
  • use-update-assets-form.ts - Asset update form

Validation Schemas:

  • create-assets-schema.ts - Asset creation validation
  • update-assets-schema.ts - Asset update validation

Routes:

  • /app/assets - Assets list
  • /app/assets/:id - Asset details
  • /app/assets/errors - Asset errors list
  • /app/assets/errors/:id - Error details

Asset Lifecycle States:

StateDescriptionTransitions To
ActivoAsset in useMaintenance, InActivo
MaintenanceUnder maintenanceActivo, InActivo
InActivoNot in useActivo, Disposed
DisposedRemoved from inventory-
ErrorAsset with errorsMaintenance, Activo

Reference: src/Funcionalidades/assets/

6. Clients Feature

Propósito: Client-facing order tracking, quotation approval, and provider rating

User Roles: Client

Key Componentes:

  • client-orders-list-filters.tsx - Filter client orders
  • order-detail-info-card.tsx - Order information
  • order-detail-reports-card.tsx - Work reports
  • service-rating-dialog.tsx - Rate provider service
  • modal-success-work.tsx - Approve work modal
  • modal-reject-work.tsx - Reject work modal

API Endpoints:

  • get-orders.ts - List client orders
  • get-order-details.ts - Get order details
  • quotation-accept.ts - Approve quotation
  • quotation-reject.ts - Reject quotation
  • final-report-accept.ts - Approve final report
  • final-report-reject.ts - Reject final report
  • rate-provider.ts - Submit provider rating

Hooks:

  • use-client-orders-filter-query-state.ts - Order list filters
  • use-orders.ts - Fetch orders
  • use-order-details.ts - Fetch order details

Routes:

  • /app/clients/my-orders - Orders list
  • /app/clients/my-orders/:id - Order details

Client Journey:

sequenceDiagram
    participant Client
    participant Dashboard
    participant Admin
    participant Provider

    Client->>Dashboard: View my orders
    Dashboard->>Client: Show order list
    Admin->>Dashboard: Create order for client
    Dashboard->>Client: Notify new order
    Client->>Dashboard: View order details
    Provider->>Dashboard: Submit quotation
    Dashboard->>Client: Notify quotation ready
    Client->>Dashboard: Approve/Reject quotation
    Provider->>Dashboard: Complete work
    Dashboard->>Client: Notify work complete
    Client->>Dashboard: Review and approve work
    Client->>Dashboard: Rate provider service

Reference: src/Funcionalidades/clients/

7. Users Feature

Propósito: User management for clients, providers, and management users

User Roles: Admin (full access), Agent (limited access)

Key Componentes:

  • modal-create-user.tsx - Create user modal
  • modal-update-user.tsx - Update user modal
  • modal-base-form.tsx - Shared form Componente
  • search.tsx - User search
  • filter-users.tsx - User filters
  • info-preview-Documento-provider.tsx - Provider Documento preview

API Endpoints:

  • get-clients.ts - List clients
  • get-providers.ts - List providers
  • get-management-users.ts - List management users
  • post-user.ts - Create user
  • update-user.ts - Update user
  • delete-user.ts - Delete user

Hooks:

  • use-user-query-state.ts - User list filters
  • use-create-user-form.ts - User creation form
  • use-update-user-form.ts - User update form

Validation Schemas:

  • schema/index.ts - User validation schemas

Routes:

  • /app/users - Clients list
  • /app/users/providers - Providers list
  • /app/users/management - Management users list (Admin only)
  • /app/users/client/:id - Client details
  • /app/users/provider/:id - Provider details

User Types:

User TypeDescriptionManaged By
ClientEnd customers who request servicesAdmin, Agent
ProviderService providers who execute workAdmin, Agent
AgentCustomer service representativesAdmin
AdminPlatform administratorsAdmin

Reference: src/Funcionalidades/users/

8. Dashboard Feature

Propósito: KPIs and Métricas visualization for business insights

User Roles: Admin, Agent

Key Componentes:

  • dashboard-list-filters.tsx - Date range and filters
  • header-buttons.tsx / header-button.tsx - Action buttons
  • Métrica-chart.tsx - Chart Componente
  • custom-bar-shape.tsx - Custom chart shapes
  • modal-report-comment.tsx - Report comments
  • modal-success-report.tsx - Success feedback

Hooks:

  • use-dashboard-filter-query-state.ts - Dashboard filters

Routes:

  • /app/dashboard - Main dashboard

Key Métricas Displayed:

  • Total orders (by Estado)
  • Revenue Métricas
  • Provider performance
  • Order completion rates
  • Average response times
  • Client satisfaction scores

Visualization: Uses Recharts for data visualization including bar charts, line charts, and pie charts.

Reference: src/Funcionalidades/dashboard/

9. Contracts & Policies Feature

Propósito: Contract and policy management, discount requests, Documento Requisitos

User Roles: Admin, Agent, Accountant, Guarantees

Key Componentes:

  • order-contracts-policies-details.tsx - Contract details
  • discount-authorization-request.tsx - Discount request form
  • contract-policies-list-filters.tsx - Filters
  • contracts-tab.tsx / policies-tab.tsx / Documentos-tab.tsx - Tabbed interface
  • contract.tsx / policy.tsx / Documento.tsx - Individual items

API Endpoints:

  • get-contracts-policies.ts - List contracts and policies
  • post-discount-request.ts - Request discount authorization
  • post-not-required-Documento.ts - Mark Documento as not required
  • post-not-required-policy.ts - Mark policy as not required

Hooks:

  • use-contract-policies-filter-query-state.ts - Filters
  • use-policy-form.ts - Policy form
  • use-discount-request-form.ts - Discount request form
  • use-not-required-Documento-form.ts - Documento exemption form

Routes (per paths.ts and router.tsx):

  • /dashboard/accountant/contracts - Accountant contracts & policies view (key: contracts-and-policies)
    • Route file: src/app/routes/dashboard/accountants/contract-policies/contract-policies.tsx
  • /dashboard/contracts - Admin contracts & policies view (key: admin-contracts-and-policies)
    • Route file: src/app/routes/dashboard/contracts-policies/contracts-policies.tsx
  • /dashboard/guarantees/contracts-policies - Guarantees view (key: guarantees-contracts-and-policies)
    • Route file: src/app/routes/dashboard/guarantees/contracts-policies.tsx

Reference: src/Funcionalidades/contracts-policies/

10. Accountants Feature

Propósito: Financial tracking, accounting, and payment management

User Roles: Admin, Agent, Accountant

Key Componentes:

  • financial-Resumen.tsx - Financial Descripción General
  • list-filter.tsx - Accounting filters

API Endpoints:

  • get-accounting.ts - Get accounting data

Hooks:

  • use-accountant-filter-query-state.ts - Filters
  • use-accounting-modal-state.ts - Modal state
  • use-advanced-form.ts - Advanced payment form
  • use-finish-form.ts - Finish payment form

Routes (per paths.ts and router.tsx):

  • /dashboard/accountant/accounting - Accounting Descripción General (key: accounting)
    • Route file: src/app/routes/dashboard/accountants/accounting/acounting.tsx
  • /dashboard/accountant/contracts - Related contracts (key: contracts-and-policies)
    • Route file: src/app/routes/dashboard/accountants/contract-policies/contract-policies.tsx

Reference: src/Funcionalidades/accountants/

Note: The accountants feature directory is located at src/app/routes/dashboard/accountants/ with two main sub-Funcionalidades:

  • accounting/ - Financial tracking
  • contract-policies/ - Contract and policy management for accountants

11. Monitoring Panel Feature

Propósito: Message monitoring and communication tracking

User Roles: Admin, Agent, Client

Key Componentes:

  • monitoring-list-filters.tsx - Message filters

API Endpoints:

  • get-messages.ts - List messages

Hooks:

  • use-monitoring-filter-query-state.ts - Message filters

Routes:

  • /app/monitoring-panel - Monitoring panel

Reference: src/Funcionalidades/monitoring-panel/

Feature Integration Patterns

Feature Interaction Flow:

flowchart TD
    A[Orders] -->|Creates| B[Auctions]
    B -->|Assigns| C[Providers]
    C -->|Executes| D[Work]
    D -->|Notifies| E[Clients]
    E -->|Approves| F[Accounting]
    A -->|Tracks| G[Assets]
    A -->|Requires| H[Contracts]
    I[Users] -->|Manages| A
    I -->|Manages| C
    I -->|Manages| E
    J[Dashboard] -->|Aggregates| A
    J -->|Aggregates| C
    J -->|Aggregates| F
    K[Monitoring] -->|Tracks| A
    K -->|Tracks| C
    K -->|Tracks| E

Feature Dependencies:

FeatureDepends OnUsed By
Auth-All Funcionalidades
OrdersAssets, ContractsAuctions, Clients, Dashboard
AuctionsOrdersProviders, Accounting
ProvidersAuctionsAccounting, Clients
Assets-Orders
ClientsOrders-
UsersAuthAll Funcionalidades
DashboardOrders, Providers, Accounting-
Contracts-Orders, Accounting
AccountingOrders, ProvidersDashboard
Monitoring--

Common Patterns Across Funcionalidades

1. API Call Pattern

features/[feature]/api/get-items.ts
import { API_CLIENT } from '@/lib/api-client';
import type { ApiResponse, Item, Pagination } from '@/types/api';


export const getItems = async (params: ItemFilters): Promise<ApiResponse<Item[], Pagination>> => {
  const response = await API_CLIENT.get('/api/items', { params });
  return response.data;
};


// features/[feature]/hooks/use-items.ts
import { useQuery } from '@tanstack/react-query';
import { getItems } from '../api/get-items';


export const useItems = (filters: ItemFilters) => {
  return useQuery({
    queryKey: ['items', filters],
    queryFn: () => getItems(filters),
  });
};

2. Filter State Management (nuqs)

features/[feature]/hooks/use-item-filter-query-state.ts
import { useQueryStates, parseAsString, parseAsInteger } from 'nuqs';


export const useItemFilterQueryState = () => {
  const [filters, setFilters] = useQueryStates({
    status: parseAsString,
    page: parseAsInteger.withDefault(1),
    limit: parseAsInteger.withDefault(10),
  });


  return { filters, setFilters };
};

3. Form Handling (React Hook Form + Zod)

features/[feature]/hooks/use-create-item-form.ts
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { createItemSchema } from '../schema';


export const useCreateItemForm = () => {
  const form = useForm({
    resolver: zodResolver(createItemSchema),
    defaultValues: {
      name: '',
      description: '',
    },
  });


  const { mutate: createItem } = useCreateItem();


  const onSubmit = form.handleSubmit((data) => {
    createItem(data);
  });


  return { form, onSubmit };
};

4. Data Table with Server-Side Pagination

features/[feature]/components/items-list.tsx
import { DataTableServer } from '@/components/ui';
import { useItems } from '../hooks/use-items';
import { useItemFilterQueryState } from '../hooks/use-item-filter-query-state';
import { itemsColumns } from '../constants/items-columns';


export const ItemsList = () => {
  const { filters, setFilters } = useItemFilterQueryState();
  const { data, isLoading } = useItems(filters);


  return (
    <DataTableServer
      columns={itemsColumns}
      data={data?.items ?? []}
      pagination={data?.pagination}
      isLoading={isLoading}
    />
  );
};

5. Modal Dialogs for Create/Edit

features/[feature]/components/modal-create-item.tsx
import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/components/ui';
import { Form, Button } from '@/components/ui';
import { useCreateItemForm } from '../hooks/use-create-item-form';


export const ModalCreateItem = ({ open, onOpenChange }: Props) => {
  const { form, onSubmit } = useCreateItemForm();


  return (
    <Dialog open={open} onOpenChange={onOpenChange}>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Create Item</DialogTitle>
        </DialogHeader>
        <Form {...form}>
          <form onSubmit={onSubmit}>
            {/* Form fields */}
            <Button type="submit">Create</Button>
          </form>
        </Form>
      </DialogContent>
    </Dialog>
  );
};

References:

  • algesta-dashboard-react/src/Funcionalidades/orders/
  • algesta-dashboard-react/src/Funcionalidades/providers/
  • algesta-dashboard-react/src/Funcionalidades/assets/
  • algesta-dashboard-react/src/Funcionalidades/marketplace/
  • All other feature directories
  • API files, Componente files, hook files from codebase