El esquema de ArccNova v2 es un diseño PostgreSQL 17 greenfield que refleja directamente los bounded contexts del monolito modular. El archivo fuenteDocumentation 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.
Referencias/esquema-bd/arccnova-schema.sql contiene las 91 tablas con su DDL completo, convenciones de nomenclatura y comentarios de trazabilidad a los requisitos. Esta página resume los grupos de entidades principales y los patrones transversales; para definiciones exactas de columnas siempre consultar el archivo SQL.
El archivo SQL es la fuente de verdad del esquema. Esta página es un resumen de orientación; cualquier discrepancia entre esta página y el SQL debe resolverse a favor del SQL.
Convenciones globales del esquema
| Convención | Detalle |
|---|---|
| PK interna | "Id" bigint GENERATED ALWAYS AS IDENTITY |
| PK pública | "PublicId" uuid UNIQUE DEFAULT gen_random_uuid() — en entidades expuestas al cliente |
| Nomenclatura | Tablas en PascalCase plural; columnas en PascalCase (quoted) |
| Timestamps | "CreatedAtUtc" / "UpdatedAtUtc" como timestamptz DEFAULT timezone('utc', now()) |
| Estados de flujo | varchar para estados simples; tablas catálogo para datos administrables |
| Tokens | uuid como PK (ej. RefreshTokens, PasswordResetTokens) |
Patrones transversales
Cada tabla operacional lleva un subconjunto de estos campos. No son opcionales — son invariantes de diseño aplicados por los interceptores de EF Core enShared.Database.
- Multi-tenancy
- Soft delete
- Auditoría
TenantIdestá en todas las tablas operacionales, sin excepción.BranchIdestá en las entidades con ámbito de proyecto. Las entidades de ámbito solo-empresa (módulo Hr, catálogos de tenant) no llevanBranchId(ADR-010).- Ambos valores vienen siempre del JWT — nunca del body de la petición.
Jerarquía Tenant → Branch
La jerarquía principal del sistema es: una empresa (Tenant) tiene uno o más proyectos inmobiliarios (Branch). Todo el inventario, los contactos, las ventas y los cobros pertenecen a un Branch.
Entidades de Tenants
Tenants, planes y suscripción SaaS
Tenants, planes y suscripción SaaS
Tenants — empresa raíz del multi-tenancy.| Campo | Tipo | Notas |
|---|---|---|
Id | bigint | PK interna |
PublicId | uuid | Expuesto al cliente |
Name | varchar(200) | Nombre de la empresa |
Slug | varchar(100) | Identificador URL único |
IsActive | boolean | Estado de la cuenta |
BillingMode | varchar(20) | 'internal' por defecto |
StripeCustomerId | varchar(100) | ID de cliente en Stripe (suscripción SaaS) |
StripeSubscriptionId | varchar(100) | Suscripción activa |
SubscriptionStatus | varchar(50) | Estado de la suscripción |
TrialEndsAtUtc | timestamptz | Fin del período de prueba |
PricingPlans — planes del SaaS con su precio de Stripe.TenantPlans — relación activa/histórica entre un tenant y sus planes.PendingRegistrations — registro pendiente de pago: guarda los datos del CEO, empresa y plan seleccionado antes de confirmar la sesión de checkout de Stripe.PlanResourceLimits / TenantResourceUsages — cuotas de recursos por plan (número de proyectos, lotes, usuarios, etc.) y su consumo actual por tenant.Entidades de Identity y RBAC
Usuarios, roles y permisos
Usuarios, roles y permisos
Users — usuario del sistema.| Campo | Tipo | Notas |
|---|---|---|
Id / PublicId | bigint / uuid | PK interna y pública |
TenantId | bigint | Empresa a la que pertenece |
Email | varchar(200) | UNIQUE en toda la tabla |
PasswordHash | varchar(500) | BCrypt |
FirstName / LastName | varchar(100) | — |
FailedLoginAttempts | integer | Contador de bloqueo |
LockedUntilUtc | timestamptz | Bloqueo temporal |
IsActive | boolean | Estado de la cuenta |
Role | varchar(50) | Rol base (legado; se extiende con Roles) |
ActionPasswordHash | varchar(500) | Contraseña de acción del v1 (C34; flag 6 pendiente) |
RefreshTokens — tokens de refresco rotativos (PK uuid).PasswordResetTokens — tokens de restablecimiento con expiración.EmailConfirmationTokens — confirmación de correo, vigencia 72 h con reenvío (C05).Roles — roles personalizados por tenant. El rol CEO tiene IsProtected = true.Permissions — catálogo de permisos: matriz ModuleGroup × Submodule × Action. Los 18 permisos protegidos confirmados cubren 5 áreas (cobros, ventas, contratos, usuarios, conceptos de mora).RolePermissions — asignación de permisos a roles (tabla puente).UserPermissions — permisos individuales por usuario, por encima de su rol.ProtectedActions — los 18 permisos protegidos (lista cerrada, C33).TenantProtectedActions — configuración por empresa: qué permisos protegidos están activos.UserProtectedActions — otorgamiento de permisos protegidos a usuarios específicos.PermissionAuditLogs — auditoría de uso de permisos, retención permanente.Entidades de Branches (Proyectos)
Proyectos y membresías de usuario
Proyectos y membresías de usuario
Branches — proyecto inmobiliario. Un tenant puede tener múltiples branches.| Campo clave | Notas |
|---|---|
Name / DisplayName | Nombre interno y nombre de presentación |
SiteId | Sede de la empresa (catálogo Sites) |
CountryId / StateId / MunicipalityId / LocalityId | Geografía del proyecto (Geo) |
CurrencyId | Moneda del proyecto |
AnnualInterestRate | Tasa de interés anual del proyecto |
DefaultDelinquencyRate | Tasa de mora por defecto para ventas de este proyecto |
GraceDays | Días de gracia por defecto |
ContractCorrelative / ReceiptCorrelative | Folios correlativos |
IsDeleted / DeletedAtUtc | Soft delete (C11) |
UserBranches — membresía usuario-proyecto con rol propio (RoleId). Un usuario puede tener roles distintos en proyectos distintos.Catálogos Geográficos (Módulo Geo)
TenantId.
Inventario de Propiedades (Módulo Properties)
Manzanas y lotes
Manzanas y lotes
Blocks — manzana (agrupación de lotes dentro de un proyecto).| Campo | Notas |
|---|---|
BranchId | Proyecto al que pertenece |
Name | Nombre único dentro del branch |
Lots — lote individual.| Campo | Tipo | Notas |
|---|---|---|
BlockId | bigint | Manzana contenedora |
Name | varchar(100) | Nombre único dentro de la manzana |
Area | varchar(50) | Superficie (texto con unidad) |
Price | numeric(18,2) | Precio de venta |
Status | varchar(20) | Active / Reserved / Sold |
BoundaryNorth/South/East/West | varchar(300) | Colindancias |
MeasureNorth/South/East/West | varchar(50) | Medidas por colindancia |
Contactos (Módulo Contacts)
La tablaContacts concentra el expediente del cliente final (comprador de lote).
| Campo | Notas |
|---|---|
Name | Nombre completo |
CurpRfc | CURP o RFC (MX) |
DateOfBirth / GenderId / MaritalStatusId | Datos personales |
Occupation / Address | Ocupación y dirección |
CountryId → LocalityId | Geografía |
SpouseName / SpouseCurp / SpouseDateOfBirth | Cónyuge (opcional; contratos usan bloques condicionales) |
BeneficiaryName / BeneficiaryGenderId / BeneficiaryDateOfBirth | Beneficiario |
Documentos Legales (Módulo LegalDocs)
Plantillas, documentos y firmas
Plantillas, documentos y firmas
DocumentTemplates — plantillas versionadas en plano. El campo IsCurrent marca la versión activa. Los tokens {{variable}} se resuelven contra el catálogo SystemVariables.LegalDocuments — instancia generada con variables resueltas (snapshot HTML). Origen polimórfico: SourceEntityType + SourceEntityId apunta a una venta o contrato laboral. El PDF final se genera con QuestPDF, se calcula su FinalPdfHash (SHA-256) y se almacena en el área aislada de S3.Estados: Draft → PendingSignatures → Signed / Cancelled / Expired.DocumentSignatures — firmantes: cliente final (ContactId), usuario del sistema (UserId), empleado (EmployeeId) o externo. Incluye token único con expiración para firma remota, imagen del trazo y dirección IP.Ciclo Comercial (Módulos Sales + Financing)
Cotizaciones, reservas y ventas
Cotizaciones, reservas y ventas
Quotes — cotización informativa. NO está ligada a reserva ni venta (C13/C19). Calcula el plan de pagos sin comprometer el lote.Reservations — reserva del lote con monto y fecha de vencimiento. Al vencer, el lote vuelve a Active y el anticipo se pierde. Estados: Active / Expired / Converted.Sales — venta confirmada.| Campo clave | Notas |
|---|---|
Folio | Número único de venta por tenant |
ContactId | Comprador |
ManagerUserId | Asesor responsable |
TotalSale / RemainingAmount | Monto total y saldo pendiente |
DelinquencyRate | Tasa de mora propia (default: la del proyecto) |
Status | Pending / Conform / Settled / Cancelled (C17) |
LegalDocumentId | Contrato generado |
ClientLots — tabla de trazabilidad cliente-lote-venta-reserva.Planes de financiamiento (4 tipos)
Planes de financiamiento (4 tipos)
Los 4 tipos de plan de financiamiento tienen cada uno su propia tabla con los mismos atributos clave:
Todos comparten campos de
| Tabla | Plan |
|---|---|
SalePrincipals | Capital principal (crédito a plazo) |
SaleHitches | Enganche |
SaleAdditionals | Adicionales |
SaleServicePlans | Plan de servicio |
ModalityTypeId, Installments, FirstPaymentDate, InterestRate y PeriodInterest (con precisión 8 decimales según C22).Cobranza (Módulo Collections)
Las cuotas nacen al cobrar — no se materializa una tabla de amortización previa (Flag 2 del arquitecto, fiel al diseño del v1).Cobros, cuotas y métodos de pago
Cobros, cuotas y métodos de pago
Collections — el cobro (recibo). Un cobro con SaleId = NULL y ContactId = NULL es un cobro no identificado (C29), que se notifica en tiempo real vía SSE.| Campo clave | Notas |
|---|---|
Folio | Número de recibo |
ReceiptTypeId | Tipo de recibo con folio correlativo |
AmountReceived / TotalToPay / Change | Montos del cobro |
ArrearsAmount | Monto de mora incluido en el cobro |
IsMultiplePayment | Cobro con múltiples formas de pago |
PaymentDate | Fecha y hora del cobro |
MultipleInstallments — cuota generada al cobrar. Campos principales:| Campo | Notas |
|---|---|
InstallmentNumber | Número de cuota del plan |
PaymentAmount | Monto de la cuota |
IsPaymentCompleted | Si la cuota está pagada |
LastRemainingAmount | Saldo restante después del cobro |
InterestPayment / PrincipalPayment | Desglose interés/capital |
NextPaymentDate / GracePeriodDueDate | Fechas de vencimiento |
CollectionInstallments — tabla puente cobro-cuota: cuánto del cobro fue a interés, capital y capital extra.ConceptCollections — conceptos del cobro (mora, descuento, etc.). La mora viaja como concepto con IsDelinquentPayer = true.MultiplePayments — formas de pago múltiples de un mismo cobro (ej. parte en efectivo, parte en transferencia).VoucherImages — comprobantes adjuntos del cobro (actualizables).Tesorería (Módulo Treasury)
Recibos, gastos y resumen financiero
Recibos, gastos y resumen financiero
TreasuryReceipts — recibo de tesorería (E.RECIBO). El tipo del concepto (ConceptId → Concepts.FlowType) define si es entrada o salida (C40). Incluye tipo de cuenta de destino, tercero y folio.ProjectExpenses — gastos asociados a un proyecto específico. Vinculados a un ConceptId y BranchId.GeneralExpenses — gastos generales de la empresa sin proyecto asociado. Solo TenantId, sin BranchId.El resumen financiero del proyecto se compone calculando la diferencia entre los cobros (Collections) y los gastos (ProjectExpenses + GeneralExpenses) por período.Pagos en Línea (Módulo Payments)
| Tabla | Propósito |
|---|---|
StripeConnectAccounts | Cuenta Stripe Express por tenant; una por empresa |
OnlinePayments | Registro de cada PaymentIntent; vincula con Collections al confirmarse |
Recursos Humanos (Módulo Hr)
El módulo Hr tiene ámbito solo-TenantId (sin BranchId en sus entidades principales). La razón social pagadora (HrLegalEntities) es el punto de anclaje de nómina, no el Branch.
Org: áreas, departamentos y puestos
Org: áreas, departamentos y puestos
HrLegalEntities — razón social pagadora (placeholder; modelado definitivo pendiente, R20). Campos clave: TenantId, LegalName, TaxId, CountryId.Areas — áreas de la empresa con HrLegalEntityId.Departments — departamentos dentro de un área.Positions — puestos dentro de un departamento.Employees: expediente del empleado
Employees: expediente del empleado
Employees — empleado. Campos clave:| Campo | Notas |
|---|---|
EmployeeCode | Código único por entidad legal |
UserId | Vinculación con el usuario de Identity (puede ser null para empleados sin acceso al sistema) |
PositionId | Puesto actual |
HireDate / TerminationDate | Fechas de alta y baja |
GenderId / MaritalStatusId / EducationLevelId | Datos demográficos |
Curp / Rfc / Nss | Identificadores fiscales MX |
IsActive / IsDeleted | Estado y soft delete |
EmployeePhones — teléfonos del empleado (polimórfico por PhoneTypeId).EmployeeEmergencyContacts — contactos de emergencia.Schedules: horarios y turnos
Schedules: horarios y turnos
Schedules — horario de trabajo con HrLegalEntityId, nombre y descripción.ScheduleDays — días del horario con entrada/salida esperadas, descanso y tolerancias.Attendance: asistencia y checadas
Attendance: asistencia y checadas
ClockRecords — checadas brutas: timestamp, tipo de registro (RecordTypeId), fuente (ClockRecordSourceId: web con ubicación/IP, o kiosko con PIN), validez y coordenadas GPS.Attendances — registro procesado diario: una fila por empleado y día. Campos clave: WorkedMinutes, LateMinutes, EarlyOutMinutes, OvertimeMinutes, AbsentMinutes. IsLocked = true cuando el período está cerrado para prenómina.Payroll: grupos, nómina y conceptos
Payroll: grupos, nómina y conceptos
PayrollGroups — grupo de nómina con frecuencia de pago (PayrollFrequencyId).PayrollConcepts — conceptos de nómina configurables: tipo (PayrollConceptTypeId), cálculo (PayrollCalculationTypeId), monto/porcentaje fijo o fórmula de expresión. Las fórmulas se validan contra el catálogo PayrollFormulaVariables al guardar (ADR-020).PayrollPeriods — período de nómina (año + número de período).PayrollRuns — ejecución de nómina para un período. El estado vive en PayrollRunStatusId (referencia al catálogo PayrollRunStatuses). ClosedAtUtc y ClosedByUserId registran el cierre; una vez cerrada es inmutable (R05).PayrollRunDetails — resultado por empleado: TotalEarnings, TotalDeductions, NetPay.PayrollRunDetailConcepts — desglose por concepto con snapshot inmutable del concepto al momento del cálculo (integridad histórica).EmployeeDocs: expediente documental
EmployeeDocs: expediente documental
DocumentTypes — tipos de documento por entidad legal con vigencia por defecto.EmployeeDocuments — documento subido con dueño polimórfico (DocumentOwnerTypeId + OwnerEntityId). IsCurrent para el historial de renovaciones.RequiredDocuments — documentos requeridos por entidad legal.Vacations y solicitudes
Vacations y solicitudes
VacationPolicies / VacationPolicyRules — tabuladores de vacaciones configurables con reglas por rango de años de antigüedad.VacationRequests / CommissionRequests / OvertimeRequests — solicitudes tipadas cuyo estado vive en ApprovalRequests (motor compartido).Incidents — registro manual de incidencias (sin efecto en nómina, R10).Motor de Aprobaciones (Shared.Approvals)
ApprovalEntityTypes — catálogo de tipos de entidad que pueden requerir aprobación (ej. eliminación de cobros, solicitudes de vacaciones).
ApprovalRequests — solicitud de aprobación polimórica por ApprovalEntityTypeId + EntityId. Estado: Pending / Approved / Rejected / Cancelled. Un solo nivel binario (R14).
Módulos sin tablas propias
| Módulo | Razón |
|---|---|
Reports | Solo consultas — no persiste datos propios; el render ocurre en el WebClient |
Financing | Motor de cálculo sobre los planes de Sales — sin tablas propias |
Tax / Rentals / Materials | Fuera del alcance de esta versión |