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.

Las reglas transversales son acuerdos de diseño que aplican a todos los módulos de ArccNova v2. En lugar de repetirlas en cada especificación de módulo, los módulos las referencian por número de regla (RT-XX). Esta guía es la fuente única de verdad de todas ellas, organizadas por área temática.

​
1. Fechas y zona horaria (RT-16, RT-17)

El sistema mantiene una separación clara entre el almacenamiento en UTC y la presentación en hora local:
CapaResponsabilidad
BackendGuarda todas las marcas de tiempo en UTC
FrontendConvierte a hora local para mostrar al usuario
Los vencimientos de cuotas son fechas (día calendario), no instantes de tiempo. La gracia y la mora se calculan por día según la regla de días hábiles, tomando en cuenta el calendario de festivos del proyecto.
Punto abierto (flag 7): los cortes de caja y el “día” de los vencimientos deben anclarse a la zona horaria del proyecto. El campo TimeZone en el proyecto y el detalle de diseño lo define el arquitecto; no bloquea el arranque.

​
2. Monedas y tipo de cambio (RT-18, RT-19, RT-20)

Una venta pactada en una moneda puede cobrarse en otra. El sistema convierte automáticamente usando el tipo de cambio del día del pago (C32), no el tipo de cambio de la fecha de la venta ni un promedio.

​
3. Archivos adjuntos (RT-12, RT-13)

​
Tipos y límites

ParámetroValor
Tipos permitidosjpg, png, webp, pdf, docx, xlsx
Tamaño máximo por archivo10 MB
Cantidad por registroSin límite
RetenciónIndefinida (T06)

​
Flujo técnico (decisión 8)

El binario nunca transita por la API. El flujo es el siguiente:
1

El frontend solicita una URL prefirmada

El frontend llama al backend para obtener una URL prefirmada de S3 (o MinIO en desarrollo) para el archivo que va a subir.
2

El frontend sube el binario directamente a S3

Con la URL prefirmada recibida, el frontend realiza un PUT directamente contra S3, enviando el archivo con el Content-Type correcto. La API no interviene en esta transferencia.
3

El frontend confirma la metadata al backend

Una vez completada la subida, el frontend notifica al backend con los metadatos del archivo. El backend registra la referencia en base de datos.
Este flujo reduce la carga del servidor API al eliminar la transferencia de binarios, mejora la velocidad de subida para el usuario y permite escalar el almacenamiento de forma independiente al backend.

​
4. Notificaciones (RT-14, RT-15)

La lista de eventos que generan notificaciones es cerrada y exhaustiva para esta versión (T05). No se prevé ampliarla sin un cambio de especificación.

​
Eventos que notifican

#Evento
1Cobro no identificado recibido
2Solicitud de RH pendiente de aprobar
3Pago en línea recibido

​
Eventos que explícitamente NO notifican

  • Cuota vencida
  • Reserva por vencer
  • Documento de empleado por vencer

​
Canal de entrega

Cada notificación se entrega por ambos canales simultáneamente:
  • Notificación dentro del sistema (in-app)
  • Correo electrónico

​
5. Días festivos (RT-21, RT-22)

El sistema mantiene un único catálogo de festivos con un campo discriminador de ámbito, en lugar de catálogos separados por nivel (decisión 17, ADR-021):
ÁmbitoDescripción
GlobalFestivos aplicables a todas las empresas del sistema
EmpresaFestivos configurados por y para una empresa específica
ProyectoFestivos aplicables a un proyecto específico
La gestión operativa es por empresa: cada empresa administra su propio calendario anual de festivos (C44).

​
Consumidores del catálogo de festivos

Módulo Collections (Cobros)

Los festivos extienden los días de gracia de los vencimientos de cuotas (C24). Si una fecha de vencimiento cae en un día festivo, el sistema la desplaza al siguiente día hábil.

Módulo HR (Nómina)

Los festivos se usan para calcular la prima de nómina. Cada festivo lleva dos multiplicadores: uno para horas normales y otro para horas extra. Un multiplicador de 1.00 significa festivo sin prima (R22).

​
6. Motor de aprobaciones (RT-23, RT-24, RT-25)

El módulo Shared.Approvals provee un motor de aprobaciones compartido para todos los módulos que lo necesiten (decisión 18, ADR-018).

​
Características del motor

CaracterísticaValor
NivelesUn solo nivel (no hay cadenas ni jerarquía de jefe directo)
ResultadoBinario: aprobar o rechazar
Quién resuelveCualquier usuario con el permiso requerido por el tipo de entidad aprobable

​
Estados de una solicitud

Pendiente → Aprobada
          → Rechazada
          → Cancelada

​
Consumidores en esta versión

  • RH: vacaciones, comisiones, tiempo extra
Las cancelaciones de cobros y ventas utilizan el mecanismo de permisos protegidos (sección de RBAC), no este motor de aprobaciones. Son dos mecanismos distintos para casos de uso distintos.

​
7. Firma electrónica (RT-26, RT-27, RT-28)

La estrategia de firma electrónica está diseñada en 4 fases. Esta versión implementa únicamente la fase 1:
Trazo simple dibujado en pantalla + capa de transparencia.El flujo incluye:
  • Aviso informativo antes de firmar
  • Cláusula de aceptación expresa en el contrato
  • Casilla de confirmación previa al trazo
  • Aviso en el acuse final

​
Reglas de la firma híbrida (C20, R18)

Una firma híbrida ocurre cuando un contrato tiene una firma digital y otra manuscrita. Las reglas son:
ReglaDescripción
Dos firmantesCliente y responsable
Orden en firma híbridaSi hay una firma digital y una manuscrita, la digital va primero
Ambas digitalesSi ambas son digitales, no hay orden obligatorio
Marca de agua en previewMientras las firmas digitales estén incompletas, el documento muestra marca de agua. Se retira al completarse, dejando el documento listo para la firma manuscrita
Enlace remotoEl enlace de firma remota expira; el vencimiento es configurable por token
RechazoUn firmante puede rechazar la firma (R18)

​
8. Render y generación de documentos (RT-29, RT-30)

ArccNova distingue dos categorías de documentos con estrategias de generación completamente diferentes:

Documentos operativos

Reportes, vistas, recibos informativosEl backend expone los datos; el frontend genera el documento (PDF, Excel, etc.) en el lado del cliente (decisión 9). Ejemplos: reportes de ventas, estados de cuenta informativos.

Documentos con valor legal

Contratos, hoja de liquidación, recibos de nóminaEl backend los genera con QuestPDF, calcula el hash SHA-256 como registro de auditoría, y persiste el PDF en un bucket de S3 aislado (decisión 10, ADR-014). Ese binario inmutable es el único descargable.
El hash SHA-256 de los documentos legales garantiza que cualquier descarga posterior sea bit a bit idéntica al original firmado. No existe forma de regenerar el documento; el binario almacenado es la única fuente de verdad.

​
9. Patrones de datos (RT-31, RT-32, RT-33)

Estos tres patrones aplican sin excepción a todas las entidades operativas del sistema:
Los registros eliminados nunca se borran físicamente. Se conservan en base de datos con los siguientes campos:
CampoDescripción
IsDeletedtrue si el registro está eliminado
DeletedByIdentificador del usuario que eliminó
DeletedAtMarca de tiempo UTC de la eliminación
Los registros eliminados desaparecen de catálogos y selectores de la UI, pero se conservan para trazabilidad (C11).IsActive es un concepto distinto: pausa el registro sin eliminarlo. Un registro puede tener IsActive = false e IsDeleted = false simultáneamente.
Toda tabla operativa lleva cuatro campos de auditoría:
CampoDescripción
CreatedByIdentificador del usuario creador
CreatedAtMarca de tiempo UTC de creación
UpdatedByIdentificador del último usuario que modificó
UpdatedAtMarca de tiempo UTC de la última modificación
El proyecto define y mantiene dos correlativos secuenciales:
  • Correlativo de contrato: se asigna al firmar un nuevo contrato de venta (C09).
  • Correlativo de recibo: se incrementa automáticamente al registrar un cobro identificado (Cobros-Flujos §5).
Cada proyecto tiene sus propios correlativos independientes. El número de contrato y el número de recibo son únicos dentro del proyecto, no en toda la empresa.

​
10. Tiempo real (RT-34)

El sistema utiliza Server-Sent Events (SSE) para las actualizaciones en tiempo real, no SignalR (decisión 19, ADR-019).
Evento en tiempo realDescripción
Cobros no identificadosContador y lista se actualizan cuando llega un cobro sin identificar
Confirmación de pago en líneaWebhook de Stripe → backend → retransmisión por SSE al navegador
La elección de SSE sobre SignalR responde a la simplicidad del protocolo y a que los casos de uso de tiempo real en esta versión son todos unidireccionales (servidor → cliente). No se usa WebSockets bidireccionales.

​
11. Límites del plan (RT-35)

Toda acción que crea un recurso limitable pasa por el control de cuota del módulo BillingSaas antes de ejecutarse, siguiendo el patrón ExecuteWithQuotaAsync: 
1. Consultar límite efectivo (base del plan + add-ons activos)
2. Consumir cuota de forma atómica si hay disponible
   └── Si no hay cuota → rechazar con error de validación
3. Ejecutar la acción de negocio
   └── Si la acción falla → liberar el consumo (rollback de cuota)
Los recursos limitables se definen en el módulo BillingSaas. La lógica de paywall asociada a planes vencidos o agotados se documenta en la guía de Multi-Tenancy y Proyectos.

Build docs developers (and LLMs) love

Get started for freeTalk to us