Skip to content

devbijao/BIJAO

BranchesTags

Repository files navigation

Bijao - Plataforma de Gestión Inteligente (SaaS)

Bijao es un sistema integral de Punto de Venta (POS), Inventario, Facturación, CRM, suscripciones y Marketing, impulsado fuertemente por Inteligencia Artificial. Está diseñado como un SaaS Multi-tenant donde negocios informales y PYMES pueden gestionar, operar y escalar toda su operación a través de una interfaz moderna y automatizada.

Características Principales

  • POS, Inventario y Facturación interconectados: Toda venta descuenta inventario, genera factura, actualiza el perfil del cliente y calcula la utilidad real al instante.
  • Cotizaciones con conversión automática: Las cotizaciones PENDIENTE se convierten en venta/factura al confirmarlas.
  • CRM y Créditos: Gestión de créditos a clientes con abonos parciales, tasa de interés configurable y seguimiento de mora.
  • Asistente de IA "Keren": Agente conversacional vía WebSocket (Gemini 2.5 Flash) con 21 herramientas que puede leer y modificar datos del negocio en tiempo real.
  • Marketing con Insights: Campañas de alcance con seguimiento de progreso e insights automatizados (mejor producto, cliente top, riesgo de stock, rentabilidad).
  • Calendario y Reservas: Gestión de citas para negocios de servicios con disponibilidad configurable y portal público de agendamiento.
  • Portal / Tienda Pública: Cada negocio tiene su propia tienda online sincronizada con catálogo e inventario.
  • Plantillas de Factura: Editor de plantillas HTML con logo, colores y textos personalizables; generación de PDF al imprimir.
  • Usuarios Múltiples y RBAC: 4 roles (Administrador, Vendedor, Contador, Personalizado) con permisos granulares por usuario.
  • Multi-tenant con aislamiento fuerte: Enmascaramiento de IDs con Fernet encryption, RLS en Supabase y verificación de tenencia en cada endpoint.
  • Auditoría e inmutabilidad: Registro exhaustivo de cada acción (quién, qué, cuándo, desde dónde).
  • Panel Administrativo (Console Bijao): Command Center para la administración global de la plataforma (MRR, salud de negocios, auditoría global).

Stack Tecnológico

Capa Tecnología
Frontend Next.js 16 + React 19 + TypeScript + Tailwind CSS
Backend Python + FastAPI (asíncrono)
Base de Datos & Auth Supabase (PostgreSQL + RLS + GoTrue)
Inteligencia Artificial Gemini 2.5 Flash API (streaming + Function Calling)
Encriptación de IDs Fernet (cryptography)
CAPTCHA Cloudflare Turnstile
Pasarela de Pago ePayco (webhook callback)
Despliegue Frontend Vercel
Despliegue Backend Render / Railway

Arquitectura Multi-tenant y Seguridad

  • El negocio_id actúa como clave de tenant en todas las tablas.
  • El Frontend (Next.js) nunca hace peticiones CRUD directas a Supabase. Todo el tráfico transaccional va al API de FastAPI.
  • ID Masking: Todos los UUIDs se encriptan con Fernet antes de salir al cliente. El backend los desencripta; si el token es inválido devuelve 400.
  • RLS (Row Level Security): Políticas en Supabase bloquean el acceso cruzado entre negocios a nivel de base de datos.
  • Rate Limiting: 5 intentos fallidos de login / 15 min por IP; 3 registros / hora por IP (almacenado en memoria, recomendable Redis en producción).
  • BIJAO_ADMIN: Rol global que bypass RLS con service_role key para administración de plataforma.

Tres clientes Supabase en Backend

  • supabase — cliente principal (service_role, bypasa RLS).
  • supabase_admin — operaciones administrativas internas.
  • supabase_auth — operaciones de autenticación exclusivas (evita contaminación de tokens).

Estructura del Repositorio

/Bijao
├── /backend
│   ├── main.py                  # Entry point FastAPI
│   ├── auth.py                  # JWT, rate limiting, RBAC helpers
│   ├── database.py              # Supabase clients + helpers
│   ├── id_masking.py            # Fernet encrypt/decrypt de UUIDs
│   ├── /routers                 # 17 módulos de endpoints
│   │   ├── auth.py
│   │   ├── negocios.py
│   │   ├── inventario.py
│   │   ├── ventas.py
│   │   ├── cotizaciones.py
│   │   ├── clientes.py
│   │   ├── metricas.py
│   │   ├── marketing.py
│   │   ├── calendario.py
│   │   ├── disponibilidad.py
│   │   ├── equipo.py
│   │   ├── admin.py
│   │   ├── crm.py
│   │   ├── pagos.py
│   │   ├── plantillas.py
│   │   ├── publico.py
│   │   └── chat.py              # WebSocket AI
│   ├── /ai
│   │   ├── agent.py             # BijaoChatAgent (Keren)
│   │   └── tools.py             # 21 herramientas del agente
│   └── /migrations              # Scripts SQL Supabase
│       ├── create_trigger_handle_new_user.sql
│       ├── migration_rbac_admin.sql
│       ├── migration_disponibilidad_reservas.sql
│       ├── migration_crm_creditos.sql
│       ├── migration_plantillas.sql
│       ├── migration_portal_features.sql
│       ├── migration_auth_security.sql
│       └── create_extension_busqueda.sql
├── /frontend
│   ├── /app
│   │   ├── /login
│   │   ├── /registro
│   │   ├── /auth/callback
│   │   ├── /onboarding
│   │   ├── /dashboard
│   │   │   ├── /pos
│   │   │   ├── /ventas
│   │   │   ├── /cotizaciones
│   │   │   ├── /inventario
│   │   │   ├── /clientes
│   │   │   ├── /crm
│   │   │   ├── /marketing
│   │   │   ├── /calendario
│   │   │   ├── /asistente
│   │   │   ├── /calculadora
│   │   │   └── /ajustes
│   │   ├── /admin
│   │   │   ├── /negocios
│   │   │   └── /auditoria
│   │   └── /tienda/[negocio_id]
│   └── /lib
│       ├── api.ts               # 70+ funciones de llamada al backend
│       ├── types.ts             # 30+ interfaces TypeScript
│       ├── formatters.ts
│       ├── printInvoice.ts      # Generación PDF con plantillas
│       └── supabase/
├── /prompts                     # Biblioteca de system prompts IA
└── README.md

Módulos del Backend (17 Routers)

1. Autenticación (/api/auth)

  • Registro con validación, CAPTCHA Turnstile y rate limiting.
  • Login con rate limiting por IP (5 intentos / 15 min).
  • Gestión de sesión JWT con refresh automático.
  • Flujo de confirmación de email post-registro.

2. Negocios (/api/negocios)

  • Crear negocio con onboarding inicial y auto-asignación de rol ADMIN.
  • Obtener y actualizar perfil: nombre, rubro, tipo (PRODUCTO/SERVICIO/MIXTO), tema, logo, color de acento, WhatsApp, duración de servicios, about.

3. Inventario (/api/inventario)

  • CRUD completo de productos y servicios.
  • Paginación server-side con enmascaramiento de IDs.
  • Importación masiva por CSV/Excel.
  • Soporte de tipo PRODUCTO y SERVICIO.

4. Ventas / Facturación (/api/ventas)

  • Creación de facturas con líneas de detalle; el backend calcula totales desde base de datos (ignora precios del frontend).
  • Historial paginado con filtros por cliente, número, fecha y estado.
  • Detalle de factura con productos asociados.
  • Estados: VIGENTE / ANULADA.
  • Eliminación con auditoría.

5. Cotizaciones (/api/cotizaciones)

  • CRUD completo con detalle de líneas.
  • Conversión automática a venta al confirmar (PENDIENTE → CONFIRMADA).
  • Filtrado por estado y paginación.

6. Clientes (/api/clientes)

  • CRUD con campos: nombre, email, teléfono, cumpleaños.
  • Métricas por cliente: n_compras, total_consumido.
  • Paginación server-side con búsqueda.

7. Métricas (/api/metricas)

  • Ventas del día y del mes, ticket promedio, clientes activos.
  • Health score: actividad de ventas, inventario, márgenes.
  • Gráfico de ventas de los últimos 7 días.

8. Marketing (/api/marketing)

  • Campañas con tipo de alcance, producto asociado, meta de ventas, duración y avance.
  • Insights automatizados: cliente top, mejor producto, rentabilidad, riesgo de stock, ticket promedio.

9. Calendario (/api/calendario)

  • Órdenes del portal (cotizaciones tipo=portal).
  • Detalle de órdenes: productos o reservas.
  • Actualización de estado con conversión automática a venta al confirmar.

10. Disponibilidad (/api/disponibilidad)

  • Configuración de horarios de atención por día.
  • Acceso público y privado.

11. Equipo (/api/equipo)

  • CRUD de miembros del equipo (límite 3 por negocio).
  • Roles: ADMIN, VENDEDOR, CONTADOR, PERSONALIZADO.
  • Permisos granulares en campo JSONB por usuario.

12. Panel Admin Global (/api/admin)

  • Métricas de plataforma: total negocios, usuarios activos, ingresos, tasas de crecimiento.
  • Logs de auditoría globales.
  • Debug de conteos de tablas.
  • Acceso restringido a BIJAO_ADMIN.

13. CRM (/api/crm)

  • Resumen: crédito pendiente total, clientes en mora, pipeline de cotizaciones.
  • CRUD de créditos con tasa de interés, monto pagado y fecha límite.
  • Registro de abonos parciales con método de pago.
  • Historial de pagos por crédito.

14. Pasarela de Pago (/api/pagos)

  • Webhook de confirmación ePayco (POST /pagos/confirmar).
  • Manejo de estados: Aceptada / Rechazada.

15. Plantillas de Factura (/api/plantillas)

  • CRUD de plantillas HTML personalizadas (logo, colores, header, footer, texto).
  • Soporte de plantilla predeterminada por negocio.

16. Portal Público (/api/publico)

  • Información pública del negocio, catálogo de productos, disponibilidad.
  • Registro de clientes y creación de reservas desde el portal.
  • Solicitud de cotizaciones públicas.
  • Consulta de horas ocupadas por fecha.

17. Asistente IA — WebSocket (/ws/chat/{negocio_id})

  • Canal WebSocket con autenticación por token en el header del protocolo.
  • Streaming de respuestas chunk a chunk.
  • Gestión de historial de sesión con opción de limpiar.

Agente de IA — Keren

Agente conversacional basado en Gemini 2.5 Flash con streaming y function calling. Nombre: Keren — asistora financiera virtual de Bijao.

Configuración del modelo:

  • Temperature: 0.5 | top_p: 0.95 | max_output_tokens: 2048
  • System prompt con inyección dinámica de fecha/hora y contexto de negocio.

21 Herramientas Disponibles

Categoría Herramienta Descripción
Consulta get_financial_summary Ingresos mensuales, costo inventario, métricas de clientes
Consulta get_sales_data Últimas 100 ventas
Consulta get_sales_details Detalle por ID o nombre + fecha
Consulta get_products_data Catálogo completo
Consulta get_clients_data Clientes con historial de compras
Consulta get_rentability_analysis Ingresos, costos, márgenes, utilidad
Consulta get_cotizaciones Últimas 100 cotizaciones
Consulta get_cotizaciones_detalle Ítems de una cotización
Modificación crear_producto Nuevo producto/servicio
Modificación actualizar_producto Actualizar por nombre
Modificación crear_cliente Nuevo cliente
Modificación actualizar_cliente Actualizar por nombre
Modificación crear_cotizacion Nueva cotización con ítems
Modificación ajustar_cotizacion Actualizar estado
Modificación registrar_venta Crear factura (requiere confirmación previa)
Modificación buscar_productos Búsqueda fuzzy antes de registrar venta
Marketing crear_campana_marketing Nueva campaña
Marketing obtener_campanas_marketing Listar campañas
Marketing actualizar_campana_marketing Actualizar campaña
Analítica generar_recomendaciones 3 recomendaciones estratégicas IA
Analítica redactar_about Texto "about" del negocio generado por IA

Módulos del Frontend

Autenticación

  • /login — Email/contraseña + Google OAuth + CAPTCHA Turnstile.
  • /registro — Registro con flujo de confirmación.
  • /auth/callback — Handler de OAuth.

Onboarding (4 pasos)

  1. Tipo de negocio: PRODUCTO / SERVICIO / MIXTO.
  2. Selección de categoría (14 opciones por tipo).
  3. Personalización: nombre, logo, colores.
  4. Completado y redirección al dashboard.

Dashboard Principal

  • Saludo contextual por hora del día.
  • Métricas clave: ventas hoy/mes, ticket promedio, clientes activos, health score.
  • Gráfico de barras de ventas 7 días.
  • Próximas reservas (5 siguientes).
  • Órdenes pendientes del portal.
  • Notificaciones CRM: créditos vencidos y morosos.
  • Recomendaciones estratégicas de IA.
  • Botón de copia del enlace a tienda pública.

POS — Punto de Venta (/dashboard/pos)

  • Carrito en tiempo real: búsqueda de productos, cantidad, descuento por ítem, descuento global.
  • Selección o creación rápida de cliente.
  • Cálculo de totales, registro de venta, generación y descarga de PDF.
  • Selector de plantillas de factura.
  • Vista optimizada para móvil.

Ventas / Facturación (/dashboard/ventas)

  • Historial con filtros: cliente, número, rango de fechas, estado.
  • Descarga de PDF por factura.
  • Editor de plantillas de factura inline.
  • Anulación y eliminación con confirmación.
  • Vista móvil separada.

Cotizaciones (/dashboard/cotizaciones)

  • Creación con líneas de producto, descuentos y cliente.
  • Historial filtrable por estado.
  • Conversión a venta al confirmar.
  • Impresión/descarga de PDF.

Inventario (/dashboard/inventario)

  • Lista con búsqueda, filtro por categoría y estado.
  • Alertas de stock bajo (stock_actual < stock_minimo).
  • CRUD con modal de formulario.
  • Importación masiva CSV/Excel.

Clientes (/dashboard/clientes)

  • Lista paginada con búsqueda por nombre.
  • Campos: nombre, email, teléfono, cumpleaños, compras totales, monto consumido.
  • CRUD completo.

CRM (/dashboard/crm)

  • Dashboard: monto pendiente, clientes en deuda, créditos vencidos, pipeline.
  • Gestión de créditos: crear, listar, editar (recalcula interés), eliminar.
  • Registro de abonos parciales con método de pago.
  • Historial de pagos y timeline de abonos por crédito.

Marketing (/dashboard/marketing)

  • Campañas: crear, listar con progreso, editar, eliminar.
  • Insights automáticos: cliente top, mejor producto, rentabilidad, riesgo de stock, ticket promedio.

Calendario y Reservas (/dashboard/calendario)

  • Pestaña de órdenes del portal (quotations tipo=portal).
  • Pestaña de reservas con vista de calendario.
  • Creación de nuevas reservas con selector de fecha/hora.
  • Gestión de estado de reservas.

Asistente IA Keren (/dashboard/asistente)

  • Interfaz de chat WebSocket con streaming en tiempo real.
  • Notificaciones de tool calls ("Consultando...").
  • Formato Markdown en respuestas (negrita, cursiva, bloques de código).
  • Historial de mensajes con opción de limpiar.
  • Menú de acciones rápidas.
  • Cards de confirmación de producto (resultado de buscar_productos).

Ajustes (/dashboard/ajustes)

  • Negocio: nombre, email, categoría, tipo, logo (base64).
  • Apariencia: tema claro/oscuro, color de acento, preview de logo.
  • Integraciones: WhatsApp (código de país + número), texto "about", duración de servicios.
  • Seguridad: cambio de contraseña, cierre de sesión.

Panel Administrador Global (/admin)

  • Métricas de plataforma: negocios totales, usuarios activos, ventas totales, clientes, MRR estimado, crecimiento.
  • Lista de negocios con detalle y edición.
  • Log de auditoría global filtrable.

Tienda Pública (/tienda/[negocio_id])

  • Perfil del negocio: logo, nombre, descripción, badge de tipo.
  • Catálogo de productos con grilla, imágenes, categorías y precios.
  • Agendamiento de servicios: calendario, horas disponibles, formulario de cliente.
  • Solicitud de cotización con selección de productos y datos de contacto.
  • Botón de WhatsApp (si configurado) y enlace de email.

Base de Datos

Tablas Principales

Tabla Descripción
negocios Perfil del negocio (nombre, rubro, tipo, tema, logo, colores, onboarding)
usuarios Usuarios (rol, is_bijao_admin, permisos JSONB)
productos Inventario (tipo, precio, costo, stock_actual, stock_minimo, imagen)
clientes Clientes (email, celular, cumpleaños, n_compras, total_consumido)
ventas Facturas (numero_factura, subtotal, descuento_global, total, estado)
venta_detalles Ítems de factura (producto_id, cantidad, precio, costo, descuento)
cotizaciones Cotizaciones (numero_cotizacion, estado, tipo)
cotizacion_detalles Ítems de cotización
campanas_marketing Campañas (tipo_alcance, meta_ventas, avance_actual, duracion_dias)
disponibilidad Horarios por día (activo, hora_inicio, hora_fin)
reservas Citas (fecha, hora, estado, datos de cliente)
auditoria Log de acciones (accion, entidad, detalles JSONB)
creditos_clientes Créditos (monto, tasa_interes, monto_pagado, estado, fecha_limite)
abonos_credito Abonos parciales (monto, metodo_pago)
plantillas_factura Plantillas HTML de factura (es_predeterminada)

Migraciones SQL

Ubicadas en /backend/migrations/:

  1. create_trigger_handle_new_user.sql — Auto-crear registro de usuario al registrarse.
  2. migration_rbac_admin.sql — Tablas de roles y permisos.
  3. migration_disponibilidad_reservas.sql — Tablas de disponibilidad y reservas.
  4. migration_crm_creditos.sql — Créditos y abonos.
  5. migration_plantillas.sql — Plantillas de factura.
  6. migration_portal_features.sql — Tablas del portal público.
  7. migration_auth_security.sql — Mejoras de seguridad en autenticación.
  8. create_extension_busqueda.sql — Búsqueda full-text y fuzzy.

Variables de Entorno

Backend (.env)

SUPABASE_URL=
SUPABASE_SERVICE_ROLE_KEY=
SUPABASE_ANON_KEY=
GEMINI_API_KEY=
ID_ENCRYPTION_KEY=              # Fernet key para enmascaramiento de IDs
CLOUDFLARE_TURNSTILE_SECRET=    # Opcional (dev: omitir)

Frontend (.env.local)

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
NEXT_PUBLIC_CLOUDFLARE_TURNSTILE_SITE_KEY=

Convenciones de API

  • Auth: Authorization: Bearer {token} en headers (token del localStorage).
  • Paginación: ?offset=0&limit=20 (server-side).
  • Formato de respuesta: 
    {
  "data": [...],
  "total": 100,
  "offset": 0,
  "limit": 20,
  "mensaje": "ok",
  "error": null
}
  • Errores: HTTPException con status_code y detail.
  • IDs: Siempre enmascarados en respuestas; el frontend nunca maneja UUIDs directos.

Roadmap (Pendiente / En Progreso)

  • Integración bancaria completa (reconciliación automática).
  • ePayco — cableado completo de frontend con checkout.
  • Reportes financieros exportables (P&L, Flujo de Caja) en PDF/Excel.
  • Notificaciones automáticas por WhatsApp/Email (confirmación de reserva, cobros de crédito).
  • Rate limiting en Redis para producción.
  • Restricción de CORS en producción al dominio del frontend.

About

Repositorio oficial de la empresa Bijao / Turbaco, Colombia

bijao.app

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages