Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DevCarlosRodriguez/Documentacion-Arccnova-2.0/llms.txt

Use this file to discover all available pages before exploring further.

ArccNova v2 es una plataforma SaaS multi-tenant donde cada empresa cliente administra sus propios proyectos inmobiliarios de forma completamente aislada. Entender la jerarquía de datos —y la regla de oro de que los identificadores de empresa y proyecto provienen siempre del JWT— es el punto de partida para trabajar con cualquier módulo del sistema.

​
La jerarquía de tres niveles

La cadena operativa completa de ArccNova v2 parte de la empresa y desciende hasta el lote individual: 
Empresa (Tenant)
  └── Proyecto inmobiliario (Branch)       ← lotificación
        └── Manzanas → Lotes              ← inventario
              └── Contactos (clientes finales)
                    └── Cotizaciones (informativas)
                    └── Reservas → Ventas ← ciclo comercial
                          └── Financiamientos
                                └── Cuotas → Cobros → Mora
                                └── Contratos firmados
        └── Tesorería
  └── RH y Nómina (ámbito empresa, no proyecto)
  └── Suscripción del SaaS
Branch ≠ Sucursal. El término técnico Branch en el código fuente significa proyecto inmobiliario (una lotificación concreta), NO una sucursal física. Confundir estos conceptos es el error más frecuente al leer el código o los ADRs.

​
Mapa de conceptos

Término técnicoTérmino de negocioNotas
TenantEmpresa cliente del SaaSLa cuenta raíz; p. ej. “Constructora Acme”
BranchProyecto inmobiliarioUna lotificación concreta. NO es sucursal física (ADR-007)
Property / LoteLoteLa unidad mínima vendible; en v1 la manzana se llamaba “Apple”
ContactCliente finalEl comprador de lotes; no confundir con la empresa cliente del SaaS

​
Reglas de multi-tenancy (RT-01 a RT-04)

Todo dato operativo pertenece a una empresa (TenantId) y, salvo las excepciones de RT-02, a un proyecto (BranchId). Ambos identificadores provienen siempre del JWT de la sesión, nunca del body de la petición (ADR-007).El backend extrae estos valores del token de acceso y los aplica automáticamente a cada operación de escritura y lectura. Enviarlos en el cuerpo de la petición no tiene ningún efecto: el backend los ignora.
Existen entidades que pertenecen a la empresa pero no a un proyecto específico. Estas entidades llevan solo TenantId:
  • Recursos Humanos (estructura organizacional, empleados, nómina)
  • Catálogo de días festivos
  • Catálogos de configuración de empresa: tipos de pago, monedas, tipos de recibo, sedes
Estas entidades se soportan con query filters condicionales en el ORM (ADR-010).
El personal corporativo configurado a nivel raíz de la empresa tiene visibilidad transversal a todos los proyectos (decisión 15). Esto permite a roles como CEO supervisar indicadores consolidados sin estar asignado a cada proyecto individualmente.
El usuario opera con un proyecto activo en sesión. Puede cambiarlo desde el catálogo de proyectos (C11 segunda ronda), que se presenta como una vista de tarjetas con portada, ubicación, moneda y estado de cada proyecto.Al entrar a un proyecto diferente, los permisos efectivos del usuario pasan a ser los del rol que tiene en ese proyecto. El mismo usuario puede ser Admin en el proyecto A y tener solo lectura en el proyecto B (C12).

​
Alta de empresa y onboarding

1

Registro público con Stripe Checkout

El CEO (futuro dueño de la cuenta) se registra en la plataforma. El sistema crea el usuario, la empresa y el rol CEO en todos los casos, aunque nunca se complete el pago (C04). A continuación redirige al usuario a Stripe Checkout para seleccionar un plan.
2

Confirmación de correo electrónico

Tras el registro, el sistema envía un correo de confirmación. El enlace tiene vigencia de 72 horas y puede reenviarse (C05 segunda ronda). El correo confirmado es obligatorio para iniciar sesión (RequireConfirmedEmail).
3

Activación de la suscripción

Una vez completado Stripe Checkout, el webhook de Stripe notifica al backend, que activa la suscripción. El estado de la suscripción es lo que gobierna el acceso operativo al sistema.
4

Creación del primer proyecto

El CEO crea su primer proyecto inmobiliario (Branch) capturando los campos obligatorios: nombre, sede, área total, estado, propietario del predio, ubicación, país/estado/municipio, moneda y TEA. El proyecto queda operativo de inmediato — no hay un paso de “configuración completa” adicional (C10).
El SysAdmin de la plataforma también puede crear empresas directamente mediante POST /api/system/tenants, sin necesidad de pasar por el flujo de registro público.

​
Planes y límites de recursos (BillingSaas)

El módulo BillingSaas aplica cuotas por recurso a cada empresa según su plan contratado. Toda acción que crea un recurso limitable pasa por el control de cuota antes de ejecutarse (RT-35, patrón ExecuteWithQuotaAsync):
  1. Consultar el límite efectivo (base del plan + add-ons activos)
  2. Consumir la cuota de forma atómica si hay disponible
  3. Rechazar con error de validación si se alcanzó el límite
  4. Liberar el consumo si la acción falla después de haberlo consumido
Los recursos limitables (proyectos, y otros que define el módulo BillingSaas) se consultan antes de cada creación de ese tipo de entidad.

​
Pantalla de paywall

Cuando la suscripción está vencida o impaga, el comportamiento depende del rol del usuario:
UsuarioComportamiento
CEOVe la pantalla de paywall con CTAs de pago hacia Stripe
No-CEOVe una pantalla genérica con el mensaje “contacta al administrador del proyecto”
El sistema no notifica automáticamente al CEO cuando un usuario no-CEO intenta acceder con suscripción vencida (C07). El CEO solo se entera si el usuario lo contacta directamente.

​
Campos del proyecto (Branch)

​
Campos obligatorios

CampoDescripción
Nombre del proyecto
SedeCatálogo de la empresa
Área total del proyecto
Estado (status del proyecto)
Propietario del predio
Ubicación del proyecto
País, Estado, Municipio y LocalidadCatálogos Geo
MonedaCatálogo de la empresa
TEATasa de interés anual; default para los planes de financiamiento

​
Campos opcionales relevantes

CampoDescripción
Número de contrato correlativoFolio de contratos del proyecto (RT-33)
Número de recibo correlativoFolio de recibos del proyecto (RT-33)
Tasa de incumplimientoDefault del porcentaje de mora de las ventas (C23)
Días de graciaPeríodo de gracia para vencimientos (C24)
Los correlativos de contrato y recibo son opcionales al crear el proyecto, pero una vez que hay ventas o cobros registrados, el correlativo de recibo se incrementa automáticamente con cada cobro identificado.

​
Patrones de datos transversales

Estos patrones aplican a todas las entidades operativas del sistema:

Soft Delete

Todos los registros eliminados se conservan en base de datos. Campos: IsDeleted, DeletedBy, DeletedAt. El registro desaparece de catálogos y selectores, pero se conserva para trazabilidad (RT-31).

Auditoría

Toda tabla operativa lleva campos de auditoría: CreatedBy, CreatedAt, UpdatedBy, UpdatedAt (RT-32).

Folios secuenciales

El proyecto define los correlativos de contrato y de recibo. El correlativo de recibo se incrementa al registrar un cobro identificado (RT-33, C09).
IsActive es un concepto distinto a IsDeleted: IsActive = false pausa el registro sin eliminarlo, mientras que el soft delete lo marca como eliminado pero conserva toda la información.

Build docs developers (and LLMs) love

Get started for freeTalk to us