You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
⚠️Regla para el agente: NO proponer infraestructura de pago ni servicios fuera de este stack sin aprobación explícita.
8. Alcance del MVP
✅ Incluido en MVP
Autenticación (Auth)
Workspaces (multi-tenant)
Creación y gestión de Propuestas
Envío de propuestas por link
Tracking (viewed / accepted)
❌ Excluido del MVP (no implementar ahora)
Pagos avanzados
IA compleja
Automatizaciones
Webhooks externos
9. Filosofía del Producto
Principio
Regla
Simplicidad > Complejidad
Si una feature complica el sistema, se descarta.
Velocidad > Perfección
Lanzar pronto, iterar después.
Valor inmediato > Features
Cada feature debe generar valor de uso desde el día 1.
10. Riesgos Principales
Riesgo
Mitigación
Falta de diferenciación vs competidores
UX superior, flujo sin fricción
Usuarios no pagan
Límites claros y estrictos en el plan Free
Complejidad técnica fuera de control
Arquitectura modular, separación de responsabilidades
11. Estrategia de Lanzamiento
Fase 1 — Core
Construir funcionalidades core del MVP.
Validar con usuarios reales (beta cerrada).
Fase 2 — Crecimiento
Mejorar UX basado en feedback.
Añadir sistema de pagos.
Expandir funcionalidades según demanda validada.
12. Definición del Sistema
Tipo: SaaS multi-tenant B2B con:
Gestión de propuestas.
Sistema de equipos (workspaces + miembros).
Sistema de suscripciones y límites por plan.
Tracking de eventos por propuesta.
Sistema público de visualización para clientes finales.
Objetivo principal:
Permitir a negocios crear propuestas profesionales, enviarlas, saber cuándo se ven, saber cuándo se aceptan, gestionar equipos y escalar con suscripciones.
13. Stack Tecnológico
Capa
Tecnología
Frontend
Next.js (App Router)
Backend / DB
Supabase (PostgreSQL + Auth + RLS)
Hosting
Vercel
Email
API externa (async)
Observabilidad
Logs + manejo de errores
14. Arquitectura General
Client → API Layer → Services → Repositories → DB
Principios de arquitectura
Multi-tenant obligatorio — todo dato pertenece a un workspace.
Backend-driven validation — nunca confiar en el frontend para validar reglas de negocio.
Event-driven parcial — eventos para tracking y jobs.
Separación de responsabilidades — capas bien definidas, sin acoplamiento.
15. Modelo Multi-Tenant
Regla fundamental
TODO pertenece a un workspace. Sin excepción.
Definiciones
Entidad
Descripción
Usuario
Entidad autenticada (persona física).
Workspace
Entidad que representa un negocio o cuenta.
Reglas de multi-tenancy
Un usuario puede pertenecer a múltiples workspaces.
Cada request debe incluir workspace_id.
Los datos nunca se mezclan entre workspaces.
Siempre debe existir un active_workspace_id en el contexto de sesión.
⚠️Regla para el agente: NUNCA escribir queries sin filtro por workspace_id. Cualquier acceso a datos debe estar aislado por workspace.
16. Roles y Permisos (RBAC)
Roles disponibles
Rol
Permisos
owner
Eliminar workspace, transferir ownership, gestionar billing, todo lo de admin.
admin
Gestionar usuarios del workspace, crear propuestas.
member
Crear propuestas. NO puede gestionar usuarios.
Regla crítica de integridad
Un workspace SIEMPRE debe tener al menos 1 owner. Esta condición no puede romperse bajo ninguna operación.
17. Modelo de Datos
Entidades del sistema
Entidad
Propósito
profiles
Datos del usuario autenticado.
workspaces
Cuenta / negocio principal.
workspace_members
Relación usuario ↔ workspace con rol.
invitations
Invitaciones pendientes a un workspace.
customers
Clientes del workspace.
proposals
Propuestas generadas.
proposal_items
Ítems / líneas de cada propuesta.
proposal_versions
Snapshots inmutables por cada envío.
proposal_events
Eventos de tracking (sent, viewed, accepted).
subscriptions
Plan activo del workspace.
usage_records
Conteo de uso por métrica (e.g., proposals_created).
workspace_settings
Configuración visual del workspace.
feature_flags
Flags de funcionalidades por workspace o global.
jobs
Cola de trabajos asincrónicos (email, retry, cleanup).
Reglas de integridad referencial
Regla
Detalle
proposal
Requiere un customer válido.
customer
Requiere un workspace válido.
proposal_items
Mínimo 1 ítem por propuesta.
workspace
Siempre debe tener al menos 1 owner.
18. Propuestas — Core del Negocio
Estados posibles
draft → sent → viewed → accepted
→ rejected
ANY → expired (cuando now > expires_at)
Máquina de estados
Transición
¿Válida?
draft → sent
✅
sent → viewed
✅
viewed → accepted
✅
viewed → rejected
✅
ANY → expired
✅ (automático por fecha)
draft → accepted
❌ Inválida
accepted → draft
❌ Inválida
rejected → sent
❌ Inválida
⚠️Regla para el agente: NUNCA permitir transiciones de estado inválidas. Validar el estado actual antes de cualquier cambio.
19. Flujo de Propuesta
Crear propuesta
Validar que el workspace está dentro del límite de su plan.
Validar que el customer existe y pertenece al workspace.
Crear el registro proposal.
Crear al menos 1 proposal_item.
Enviar propuesta
Validar que el estado actual es draft.
Generar un token seguro (aleatorio, alta entropía, no secuencial).
Crear un snapshot inmutable en proposal_versions.
Registrar evento proposal_sent en proposal_events.
Encolar job de envío de email (async).
Ver propuesta (cliente final)
Acceso solo por token válido.
Registrar evento proposal_viewed — solo una vez (idempotente).
Aceptar propuesta
Validar que la propuesta no está expirada (now <= expires_at).
Cambiar estado a accepted.
Bloquear cualquier edición posterior.
20. Versionado
Cada envío de una propuesta crea un snapshot inmutable en proposal_versions.
Regla absoluta: Las versiones anteriores NUNCA se modifican.
El snapshot captura el estado completo de la propuesta y sus ítems en el momento del envío.
21. Billing y Planes
Planes disponibles
Plan
Ejemplo de límite
FREE
5 propuestas
STARTER
(definir)
PRO
100 propuestas
BUSINESS
(definir)
Reglas de billing
Situación
Comportamiento
usage >= limit al crear propuesta
Bloquear creación
Upgrade de plan
Efecto inmediato
Downgrade de plan
NO elimina datos, bloquea nuevas creaciones si excede el nuevo límite
Cancelación
Respeta el periodo pagado actual
Pago fallido
Estado pasa a past_due → periodo de gracia → restricción total
22. Usage Tracking
Métrica principal:proposals_created
Regla: El contador se incrementa al crear la propuesta, NO al enviarla.
23. Seguridad
Capa
Regla
RLS (Row Level Security)
Los usuarios solo ven datos de su workspace activo. Configurado en Supabase.
Validaciones
Siempre en el backend. Nunca confiar en datos del frontend.
Tokens públicos
Aleatorios, no secuenciales, alta entropía criptográfica.
⚠️Regla para el agente: NUNCA omitir validaciones de backend asumiendo que el frontend ya validó. Toda validación de negocio va en el backend.
24. Concurrencia e Idempotencia
Problemas a prevenir
Doble envío de una misma propuesta.
Numeración duplicada de propuestas.
Solución
Usar transacciones de base de datos para operaciones críticas.
Implementar idempotencia en operaciones sensibles.
Casos que requieren idempotencia obligatoria
Operación
Resultado esperado
Enviar propuesta (doble click)
Solo se envía una vez
Aceptar propuesta (doble request)
Estado cambia una sola vez
25. Email y Jobs
Reglas de email
El envío de email es siempre asíncrono.
Implementar retry automático en caso de fallo.
Si falla definitivamente → estado del job: failed.
Tipos de jobs
Tipo
Propósito
email_send
Envío de propuesta al cliente.
retry
Reintentos de jobs fallidos.
cleanup
Limpieza de datos expirados o temporales.
Estados de un job
pending → processing → done
→ failed
26. Sistema de Eventos
Tipos de eventos registrados
Evento
Cuándo se registra
proposal_sent
Al enviar la propuesta.
proposal_viewed
Al abrir el link público — solo una vez.
proposal_accepted
Al aceptar la propuesta.
⚠️Regla crítica:proposal_viewed es idempotente. Si el cliente abre el link múltiples veces, el evento se registra solo en la primera apertura.
27. Edge Cases
Los siguientes casos extremos deben estar cubiertos explícitamente en la implementación:
Edge Case
Manejo esperado
Doble click en "Enviar"
Idempotencia — solo un envío
Token inválido o expirado
Error controlado, no exposición de datos
Cliente eliminado con propuestas activas
Validar integridad antes de eliminar
Downgrade con uso que excede el nuevo límite
Bloquear creaciones, NO eliminar datos existentes
Workspace sin owner
Prohibido — validar antes de cualquier operación de membresía
28. Sistema Público
Ruta de acceso:/p/{token}
Acceso únicamente mediante token válido.
Las rutas públicas no deben ser indexadas por motores de búsqueda (noindex).
No requiere autenticación del cliente final.
29. Impuestos y Moneda
Cada propuesta debe soportar los siguientes campos:
Campo
Descripción
currency
Moneda de la propuesta (ej: USD, EUR).
tax_percentage
Porcentaje de impuesto aplicado.
tax_amount
Monto calculado de impuesto.
30. Personalización de Workspace
Configuraciones disponibles en workspace_settings:
Campo
Descripción
logo
Logo del negocio para las propuestas.
color
Color de marca principal.
company_name
Nombre de la empresa que aparece en propuestas.
31. Expiración de Propuestas
Regla: Si now > expires_at, la propuesta no puede ser aceptada.
La expiración es automática basada en fecha, no requiere job explícito para cambiar el estado (se valida al intentar aceptar).
32. Configuración y Feature Flags
El sistema soporta feature_flags para activar/desactivar funcionalidades por workspace o de forma global.
system_settings para configuración general de la plataforma.
33. Testing
El proyecto debe contar con los siguientes niveles de testing:
Nivel
Alcance
Unit
Lógica de negocio aislada (máquina de estados, validaciones, cálculos).
Integration
Flujos entre capas (service → repository → DB).
E2E
Flujos completos desde la UI hasta la base de datos.
34. Paginación
Estrategia: Cursor-based (no offset).
Aplicar en todos los listados: propuestas, clientes, eventos, etc.
35. Timezone
Regla
Detalle
Almacenamiento
Siempre en UTC.
Visualización
Convertir al timezone local del usuario.
36. Exportación
El sistema debe soportar exportación de datos en los siguientes formatos:
CSV — para datos tabulares (propuestas, clientes).
PDF — para visualización de propuestas individuales.
37. Privacidad
Los usuarios pueden solicitar eliminación de su cuenta y datos.
Los usuarios pueden solicitar exportación de sus datos (cumplimiento GDPR / LOPDP).
38. Webhooks (Futuro)
Fuera del alcance del MVP.
En el futuro: notificaciones a sistemas externos sobre eventos clave (propuesta aceptada, vista, etc.).
39. Observabilidad
El sistema debe implementar:
Capa
Herramienta / Estrategia
Logs
Registro estructurado de operaciones clave.
Métricas
Monitoreo de uso y performance.
Errores
Captura y alerta de errores en producción.
40. Principios Finales para el Agente
Estas reglas son de cumplimiento obligatorio. El agente debe seguirlas sin excepción.
Lo que InstantProposals ES
✅ Una herramienta de ventas.
✅ Un SaaS escalable multi-tenant.
✅ Un producto monetizable con planes y límites claros.
Lo que InstantProposals NO ES
❌ Un CRUD simple.
❌ Un generador de PDFs.
Reglas de comportamiento del agente
Regla
Descripción
NO agregar features no definidas
Si no está en este documento, no se implementa sin aprobación.
NO romper multi-tenancy
Todo acceso a datos debe estar filtrado por workspace_id.
SIEMPRE validar reglas de negocio
En el backend, nunca solo en el frontend.
SIEMPRE respetar la máquina de estados
Validar estado actual antes de cualquier transición.
SIEMPRE aplicar idempotencia
En envío y aceptación de propuestas.
NUNCA modificar versiones anteriores
Los snapshots son inmutables.
NUNCA permitir workspace sin owner
Validar antes de cualquier operación de membresía.
Priorizar seguridad y escalabilidad
Sobre velocidad de implementación.
Seguir la arquitectura definida
Client → API Layer → Services → Repositories → DB.
No improvisar reglas de negocio
Si hay ambigüedad, consultar antes de asumir.
Documento de referencia para el agente de desarrollo — InstantProposals v1.0
About
App para gestionar proformas de forma profesional.