DOCUMENTO TÉCNICO DE REFERENCIA

Arquitectura Técnica y de Misión Crítica

Diseñado para sostener el ecosistema económico nacional. ODXIS no es un simple CRUD web; es una infraestructura transaccional distribuida que adopta patrones de ingeniería financiera, garantizando inmutabilidad, seguridad Zero-Trust y latencia predecible.

Pilares de la Infraestructura

Arquitectura Zero-Trust (Confianza Cero)

En un entorno multi-tenant, la seguridad perimetral es insuficiente. ODXIS asume que la red hostil ya está comprometida. Aplicamos autorización estricta en cada capa:

Row-Level Security (RLS): Aislamiento de tenants directamente en PostgreSQL.
Validación tRPC: Tipado fuerte e inyección de contexto de sesión en cada endpoint.
Auditoría Completa: Tracking de mutaciones en tablas paralelas.

Inmutabilidad Transaccional (Ledger)

Para integraciones con la DIAN y contabilidad, la alteración de datos históricos es inaceptable. Implementamos un modelo Append-Only inspirado en Grafos Acíclicos Dirigidos (DAG):

Event Sourcing Parcial: Los cambios de estado de inventario y facturas se derivan de un historial inmutable.
Evidencia Criptográfica: Hashing en cadena para garantizar que las facturas no hayan sido manipuladas.
Trazabilidad Regulatoria: Listo para auditorías forenses instantáneas.

Motor de Costeo y Procesamiento Pesado

El recálculo de costos (Promedio Ponderado, PEPS) en un municipio entero requiere poder de cómputo significativo. ODXIS aísla estas cargas:

Microservicios en Rust/C++: Procesamiento asíncrono con control explícito de memoria para colas de trabajo pesadas.
Workers Desacoplados: El frontend y la API principal (Node.js/Edge) nunca se bloquean por tareas analíticas.

Data Layer & Concurrencia (PostgreSQL 16+)

El corazón de persistencia es un clúster relacional optimizado para un entorno SaaS multi-tenant:

Índices GIN y Parciales: Búsqueda ultra-rápida en catálogo de productos y metadatos JSONB para el POS.
Connection Pooling: Gestión eficiente en la capa Edge usando Prisma/PgBouncer para soportar picos transaccionales.

Implementación Técnica y Seguridad de Tipos

src/server/api/routers/invoice.ts

tRPC + Zod (TypeScript)

import { z } from "zod";
import { createTRPCRouter, protectedProcedure } from "~/server/api/trpc";
import { DianIntegrationService } from "~/server/services/dian";

export const invoiceRouter = createTRPCRouter({
  create: protectedProcedure
    // 1. Validación de Contrato Estricto con Zod
    .input(z.object({
      customerId: z.string().uuid(),
      items: z.array(z.object({
        productId: z.string().uuid(),
        quantity: z.number().positive(),
        unitPrice: z.number().positive(),
      })).min(1),
      paymentMethod: z.enum(["CASH", "TRANSFER", "CREDIT"]),
    }))
    .mutation(async ({ ctx, input }) => {
      // 2. Aislamiento Multi-Tenant Automático (ctx.organizationId)
      // Prisma está configurado para filtrar por tenant a nivel middleware
      
      const transactionResult = await ctx.db.$transaction(async (tx) => {
        // 3. Deducción de Inventario con Bloqueo Optimista (Previene Race Conditions)
        const inventoryUpdate = await tx.product.updateMany({
           where: { id: { in: input.items.map(i => i.productId) }, organizationId: ctx.organizationId },
           data: { stock: { decrement: input.quantity } }
        });

        // 4. Creación Inmutable del Registro
        const invoice = await tx.invoice.create({
           data: {
             ...input,
             organizationId: ctx.organizationId,
             createdBy: ctx.session.user.id,
           }
        });
        
        return invoice;
      });

      // 5. Workers Desacoplados (Rust Microservice / DIAN API)
      await DianIntegrationService.dispatchElectronicInvoice(transactionResult.id);

      return transactionResult;
    }),
});