Stack tecnológico

Estructura de carpetas

Variables de entorno

VITE_API_URL=https://api.tudominio.com/api/v1
VITE_APP_NAME=GesCartera

Convenciones

Autenticación

Dashboard

Vista única que carga todos los KPIs con una sola llamada a GET /api/v1/dashboard/resumen. Usar skeleton loaders mientras cargan los datos.

Facturas — estados

Pagos — lógica de UI

Reportes — planes

Store Pinia — estructura estándar

export const useClientesStore = defineStore('clientes', {
  state: () => ({
    clientes: [],
    clienteActual: null,
    loading: false,
    error: null,
    pagination: { page: 1, per_page: 20, total: 0 },
  }),
  actions: {
    async fetchClientes(params = {}) {
      this.loading = true
      try {
        const res = await ClientesService.getAll(params)
        this.clientes = res.data.items
        this.pagination = res.data.pagination
      } catch (e) {
        this.error = e.message
      } finally {
        this.loading = false
      }
    }
  }
})

Guards de navegación

router.beforeEach((to, from, next) => {
  const auth = useAuthStore()
  if (!to.meta.public && !auth.isAuthenticated) return next('/login')
  if (to.meta.roles && !to.meta.roles.includes(auth.userRole))
    return next('/dashboard')
  next()
})

Interceptor Axios — refresh automático

api.interceptors.response.use(
  res => res,
  async err => {
    if (err.response?.status === 401) {
      await useAuthStore().refresh()  // POST /auth/refresh
    }
    return Promise.reject(err)
  }
)

Paginación

Todos los listados usan paginación del lado del servidor con parámetros page y per_page. La respuesta incluye el objeto pagination con total y pages.

Control de acceso por plan

// utils/usePlan.js
export function usePlan() {
  const auth = useAuthStore()
  const plan = auth.empresa?.plan  // 'basico' | 'profesional' | 'enterprise'
  return {
    tieneIA:                plan === 'enterprise',
    tieneReportesAvanzados: ['profesional','enterprise'].includes(plan),
    tieneExportacion:       ['profesional','enterprise'].includes(plan),
  }
}

// Uso en componente:
const { tieneIA } = usePlan()
// <SeccionIA v-if="tieneIA" />
// <BannerUpgrade v-else />

Permisos por rol

Stack tecnológico

Estructura de carpetas

Variables de entorno

FLASK_ENV=production
DATABASE_URL=postgresql://user:pass@localhost:5432/cartera_db
JWT_SECRET_KEY=<generado con secrets.token_hex(32)>
JWT_ACCESS_TOKEN_EXPIRES=900       # 15 minutos
JWT_REFRESH_TOKEN_EXPIRES=604800   # 7 días
CORS_ORIGINS=https://app.tudominio.com

Tokens JWT

Decoradores de control de acceso

@jwt_required()
@requiere_roles('admin', 'supervisor', 'analista')
@requiere_plan('enterprise')
def post(self):
    ...

Regla de aislamiento multiempresa

# CORRECTO
Cliente.query.filter_by(id=cliente_id, empresa_id=get_empresa_id()).first()

# INCORRECTO — nunca sin empresa_id
Cliente.query.filter_by(id=cliente_id).first()

Hash de contraseñas (Argon2id)

from argon2 import PasswordHasher
ph = PasswordHasher()
hashear   = lambda pwd: ph.hash(pwd)
verificar = lambda h, pwd: ph.verify(h, pwd)

Acciones auditadas obligatoriamente

Protecciones activas

Variables del modelo de predicción

Niveles de riesgo

Segmentación de clientes

Ejemplo de narrativa generada

Tipos enumerados (ENUMs)

Tablas

Vistas disponibles

Trigger — trg_aplicar_pago

Al insertar en pagos, descuenta el saldo_pendiente de la factura. Si el saldo llega a cero, cambia el estado a pagada. También valida que el pago no exceda el saldo.

Trigger — timestamps automáticos

Las tablas empresas, usuarios, clientes, facturas y acuerdos_pago tienen triggers BEFORE UPDATE que actualizan automáticamente actualizada_en.

Función — marcar_facturas_vencidas()

Marca como vencida toda factura pendiente cuya fecha_vencimiento ya pasó. Debe ejecutarse con un cron job diario.

-- Con pg_cron (instalar extensión)
SELECT cron.schedule('0 1 * * *', 'SELECT marcar_facturas_vencidas()');
-- Se ejecuta todos los días a la 1:00 AM

Índices por tabla

Capacidad esperada

Buenas prácticas