ADUANASOFT/CRM_AGENTES_CARGA
10
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
feature/crm-solicitud-cotizacion-ciclo
CRM_AGENTES_CARGA/docs/ARCHITECTURE.md

25 KiB
Raw Permalink Blame History

Anexo76 - Resumen de Arquitectura Técnica

📋 Índice

  1. Visión General
  2. Stack Tecnológico
  3. Arquitectura del Sistema
  4. Arquitectura de Schemas y Módulos
  5. Estructura del Proyecto
  6. Flujos Principales
  7. Seguridad
  8. Base de Datos
  9. API Reference

Visión General

Anexo76 es una aplicación SaaS multi-tenant para gestión de comercio exterior en México, enfocada en cumplir con los Anexos 24, 31 y 22 del SAT.

Objetivos de Negocio

  • Gestión de inventarios para maquilas e IMMEX
  • Control de pedimentos aduanales
  • Manejo de facturas de importación/exportación
  • Cumplimiento normativo SAT
  • Licenciamiento flexible por planes

Stack Tecnológico

Backend

  • Framework: FastAPI 0.110+ (Python 3.11+)
  • ORM: SQLAlchemy 2.0
  • Autenticación: Keycloak (OpenID Connect)
  • Base de Datos: PostgreSQL 15+
  • Validación: Pydantic 2.6+
  • Testing: Pytest

Frontend

  • Framework: SvelteKit 2.0+ (Svelte 5)
  • Lenguaje: TypeScript
  • Auth Client: keycloak-js
  • Estilos: TailwindCSS 4.1+
  • Build: Vite 7+

Infraestructura

  • Containerización: Docker / Docker Compose
  • Orquestación: Kubernetes (futuro)
  • CI/CD: GitHub Actions / GitLab CI
  • Monitoreo: Prometheus + Grafana

Arquitectura del Sistema

Patrón Arquitectónico: Modular Layered (estilo NestJS)

┌─────────────────────────────────────────────────────────┐
│                     FRONTEND                            │
│  SvelteKit + Keycloak-js + TailwindCSS                 │
└────────────────┬────────────────────────────────────────┘
                 │ HTTP/REST + JWT
┌────────────────▼────────────────────────────────────────┐
│                  API GATEWAY (FastAPI)                  │
│  Middleware: Tenant | License | Logging | CORS         │
└────────────────┬────────────────────────────────────────┘
                 │
        ┌────────┴────────┐
        │                 │
┌───────▼──────┐  ┌──────▼────────┐
│   MODULES    │  │  CORE LAYER   │
│              │  │               │
│ • auth       │  │ • config.py   │
│ • tenants    │  │ • database.py │
│ • licenses   │  │ • security.py │
│ • ...        │  │ • middleware  │
└───────┬──────┘  └───────────────┘
        │
┌───────▼──────────────────────────┐
│  DATABASE LAYER (Multi-tenant)   │
│                                  │
│  ┌──────────┐  ┌──────────────┐  │
│  │ Core DB  │  │ Tenant 1 DB  │  │
│  │ (shared) │  │ (dedicated)  │  │
│  └──────────┘  └──────────────┘  │
└──────────────────────────────────┘

Estructura Modular (por módulo)

Cada módulo sigue el patrón:

modules/{module_name}/
├── models.py      # ORM Models (SQLAlchemy)
├── dto.py         # Data Transfer Objects (Pydantic)
├── service.py     # Business Logic Layer
├── routes.py      # API Endpoints (FastAPI)
└── __init__.py    # Module exports

Responsabilidades por Capa

  1. models.py: Representación de entidades en BD

    • Define tablas con SQLAlchemy
    • Relaciones entre entidades
    • Constraints y validaciones a nivel DB

  2. dto.py: Contratos de entrada/salida de datos

    • DTOs de request (CreateDTO, UpdateDTO)
    • DTOs de response (ResponseDTO)
    • Validaciones de Pydantic

  3. service.py: Lógica de negocio

    • Operaciones CRUD
    • Validaciones de negocio
    • Orquestación de operaciones complejas

  4. routes.py: Exposición HTTP

    • Definición de endpoints
    • Documentación OpenAPI automática
    • Manejo de dependencias (auth, db)

Arquitectura de Schemas y Módulos

Estructura de Schemas en Base de Datos

La aplicación utiliza una arquitectura de schemas para organizar lógicamente las tablas según su funcionalidad y alcance:

Schema a24 (Anexo 24)

Contiene todas las tablas relacionadas con el Anexo 24 del SAT (control de inventarios para empresas IMMEX):

  • Gestión de inventarios
  • Control de entradas y salidas de mercancías
  • Reportes de existencias
  • Cumplimiento de obligaciones fiscales del Anexo 24

Schema a76 (Anexo 76)

Contiene todas las tablas relacionadas con el Anexo 76 del SAT (comercio exterior):

  • Pedimentos aduanales
  • Facturas de importación/exportación
  • Documentación de comercio exterior
  • Cumplimiento normativo de comercio exterior

Schema public (Catálogos Fijos)

Contiene catálogos compartidos y datos de referencia que no cambian frecuentemente:

  • Catálogos del SAT (tipos de material, unidades de medida, etc.)
  • Códigos de país
  • Catálogos de aduanas
  • Tipos de documento
  • Datos maestros compartidos entre módulos

Convención de Prefijos de Tablas

Para mantener claridad y trazabilidad, las tablas utilizan prefijos que identifican su módulo funcional:

Prefijo inv_ (Inventarios)

Tablas relacionadas con el control de inventarios:

  • inv_products: Productos en inventario
  • inv_movements: Movimientos de entrada/salida
  • inv_warehouses: Almacenes
  • inv_balances: Saldos de inventario

Nota histórica: Anteriormente se utilizaba el prefijo s (SCAII - Sistema de aduanas e Inventarios).

Prefijo fa_ (Fixed Assets / Activos Fijos)

Tablas relacionadas con la gestión de activos fijos:

  • fa_assets: Registro de activos fijos
  • fa_depreciation: Depreciación de activos
  • fa_maintenance: Mantenimiento de activos
  • fa_transfers: Transferencias de activos

Nota histórica: Anteriormente se utilizaba el prefijo q (SCAF - Sistema de Control de Activos Fijos).

Diagrama de Arquitectura de Schemas

┌─────────────────────────────────────────────────────────────┐
│                    DATABASE: anexo76_db                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌────────────────┐  ┌────────────────┐  ┌───────────────┐  │
│  │  Schema: a24   │  │  Schema: a76   │  │Schema: public │  │
│  │  (Anexo 24)    │  │  (Anexo 76)    │  │ (Catálogos)   │  │
│  ├────────────────┤  ├────────────────┤  ├───────────────┤  │
│  │                │  │                │  │               │  │
│  │ inv_products   │  │ pedimentos     │  │ material_types│  │
│  │ inv_movements  │  │ facturas       │  │ uom_codes     │  │
│  │ inv_warehouses │  │ customs_docs   │  │ countries     │  │
│  │ inv_balances   │  │ export_ops     │  │ customs_list  │  │
│  │                │  │                │  │ document_types│  │
│  │ fa_assets      │  │                │  │               │  │
│  │ fa_depreciation│  │                │  │               │  │
│  │ fa_maintenance │  │                │  │               │  │
│  │ fa_transfers   │  │                │  │               │  │
│  │                │  │                │  │               │  │
│  └────────────────┘  └────────────────┘  └───────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Ventajas de esta Arquitectura

  1. Separación Lógica: Cada schema representa un dominio específico del negocio
  2. Escalabilidad: Facilita la adición de nuevos módulos sin afectar los existentes
  3. Seguridad: Permite aplicar permisos a nivel de schema
  4. Mantenibilidad: Código y migraciones organizados por dominio
  5. Claridad: Los prefijos hacen evidente la funcionalidad de cada tabla
  6. Migración Gradual: Permite actualizar sistemas legados (SCAII/SCAF) sin interrupciones

Mapeo de Sistemas Legados

Sistema Legacy Prefijo Antiguo Sistema Nuevo Prefijo Nuevo Schema
SCAII (Inventarios) s Inventarios inv_ a24
SCAF (Activos Fijos) q Fixed Assets fa_ a24
Winsaii (Pedimentos) w - - a22
- g Comercio Exterior - a76
- g Catálogos SAT - public

Estructura del Proyecto

anexo76/
├── backend/
│   ├── main.py                    # Aplicación FastAPI principal
│   ├── requirements.txt           # Dependencias
│   ├── init_db.py                # Script de inicialización
│   ├── Dockerfile
│   │
│   ├── core/                     # Capa core (shared)
│   │   ├── config.py             # Configuración (Pydantic Settings)
│   │   ├── database.py           # Gestión de BD multi-tenant
│   │   ├── security.py           # Auth Keycloak + JWT
│   │   ├── middleware.py         # Middlewares personalizados
│   │   └── __init__.py
│   │
│   └── api/
│       └── v1/
│           ├── router.py         # Router principal v1
│           ├── common/           # Utilidades compartidas
│           │   ├── base_models.py
│           │   ├── crud_routes.py
│           │   ├── dto_mixins.py
│           │   └── tenant_crud_routes.py
│           │
│           └── modules/          # Módulos de negocio por schema
│               ├── a24/          # Módulo Anexo 24 (Inventarios)
│               │   ├── inventarios/
│               │   └── activos_fijos/
│               │
│               ├── a76/          # Módulo Anexo 76 (Comercio Exterior)
│               │   ├── pedimentos/
│               │   └── facturas/
│               │
│               └── public/       # Catálogos compartidos
│                   ├── material_types/
│                   ├── uom_codes/
│                   └── countries/
│
├── frontend/
│   ├── src/
│   │   ├── routes/               # Páginas SvelteKit
│   │   │   ├── +layout.svelte   # Layout global con Keycloak
│   │   │   ├── +page.svelte     # Dashboard principal
│   │   │   └── callback/        # OAuth callback
│   │   │
│   │   └── lib/
│   │       ├── auth.ts           # Servicio de autenticación
│   │       └── api.ts            # Cliente API
│   │
│   ├── static/
│   │   └── silent-check-sso.html
│   ├── package.json
│   └── Dockerfile
│
├── docs/
│   ├── KEYCLOAK_SETUP.md        # Guía de configuración
│   └── ARCHITECTURE.md          # Este documento
│
├── docker-compose.yml            # Orquestación completa
├── start.sh                      # Script de inicio rápido
├── README.md                     # Documentación principal
└── .gitignore

Flujos Principales

1. Flujo de Autenticación

┌──────────┐                  ┌──────────┐                ┌──────────┐
│ Frontend │                  │ Keycloak │                │ Backend  │
└────┬─────┘                  └────┬─────┘                └────┬─────┘
     │                             │                           │
     │ 1. Clic "Login"             │                           │
     ├────────────────────────────>│                           │
     │                             │                           │
     │ 2. Formulario de login      │                           │
     │<────────────────────────────┤                           │
     │                             │                           │
     │ 3. Credenciales             │                           │
     ├────────────────────────────>│                           │
     │                             │                           │
     │ 4. Redirigir + auth code    │                           │
     │<────────────────────────────┤                           │
     │                             │                           │
     │ 5. Intercambiar code x token│                           │
     ├────────────────────────────>│                           │
     │                             │                           │
     │ 6. JWT (access + refresh)   │                           │
     │<────────────────────────────┤                           │
     │                             │                           │
     │ 7. Request con Bearer token │                           │
     ├─────────────────────────────┼──────────────────────────>│
     │                             │                           │
     │                             │ 8. Validar token          │
     │                             │<──────────────────────────┤
     │                             │                           │
     │                             │ 9. Public key             │
     │                             ├──────────────────────────>│
     │                             │                           │
     │ 10. Respuesta con datos     │                           │
     │<─────────────────────────────┼───────────────────────────┤
     │                             │                           │

2. Flujo de Request Multi-tenant

Request con JWT
     ↓
TenantMiddleware
├─ Extrae tenant_id del token
├─ Valida tenant existe y está activo
└─ Agrega tenant_id a request.state
     ↓
LicenseValidationMiddleware
├─ Consulta licencia del tenant
├─ Valida estado (active/expired)
├─ Valida fecha de vigencia
└─ Agrega license_info a request.state
     ↓
Endpoint Handler
├─ Obtiene tenant_id de request.state
├─ Selecciona BD (shared o dedicated)
└─ Procesa request
     ↓
Response

3. Flujo de Selección de Base de Datos

# Pseudocódigo
tenant_id = request.state.tenant_id

tenant = db.query(Tenant).filter(Tenant.id == tenant_id).first()

if tenant.type == "SHARED":
    # Usar BD compartida (core_db)
    db_session = CoreSessionLocal()
    # Queries incluyen tenant_id en WHERE
    
elif tenant.type == "DEDICATED":
    # Usar BD dedicada del tenant
    db_config = json.loads(tenant.db_config)
    db_session = get_tenant_db(tenant_id, db_config)
    # No necesita filtrar por tenant_id

Seguridad

Autenticación

  • Keycloak como Identity Provider
  • OpenID Connect (OIDC)
  • JWT con RS256 (firma asimétrica)
  • Refresh tokens para renovación

Autorización

  • RBAC (Role-Based Access Control)
  • Roles: admin, user, auditor, system
  • Middleware has_role() para proteger endpoints

Multi-tenancy

  • Aislamiento por tenant_id en JWT
  • Row-level security en BD compartida
  • BD dedicada para mayor aislamiento (enterprise)

Row-Level Security (RLS) en BD compartida

Convención alineada al skill aduanasoft-dev-standards (sección 10). La capa API sigue siendo responsable del control fino (roles/permisos con Keycloak + PermissionService); RLS añade defensa en profundidad a nivel de BD para que un bug en un WHERE no permita salirse del tenant.

Variables de sesión (SET LOCAL)

GUC Origen Comportamiento RLS
app.tenant_id JWT (TenantMiddleware) → request.state.tenant_id Obligatoria. Si está vacía, app.current_tenant_id() retorna NULL y las políticas devuelven 0 filas (fail-closed).
app.company_id Header X-Company-Id o cookie active_company_id Opcional. Si está vacía, el tenant ve todas sus compañías (útil para selectores de compañía y bootstrap).

Ambas se fijan con SET LOCAL al inicio de cada transacción — nunca con SET global, para no contaminar conexiones del pool.

Helpers SQL definidos por la migración d1a2b3c4e5f6_enable_rls_tenant_company:

CREATE FUNCTION app.current_tenant_id()  RETURNS INTEGER LANGUAGE sql STABLE AS
$$ SELECT NULLIF(current_setting('app.tenant_id',  true), '')::INTEGER $$;
CREATE FUNCTION app.current_company_id() RETURNS INTEGER LANGUAGE sql STABLE AS
$$ SELECT NULLIF(current_setting('app.company_id', true), '')::INTEGER $$;

Tipos de política

  1. Solo tenant_id (p.ej. a76.company, core.licenses): tenant_id = app.current_tenant_id().
  2. tenant_id + company_id (TenantScopedMixin, mayoría de tablas a24/a76/core): además exige company_id = app.current_company_id() cuando esa GUC está fijada.
  3. Solo company_id (algunas tablas a76.company_*): valida el tenant_id indirectamente vía EXISTS contra a76.company.

Todas las tablas usan FORCE ROW LEVEL SECURITY para que la política aplique también al owner. Las únicas tablas core excluidas son core.tenants y core.user_tenants — necesarias para el bootstrap del selector de tenant antes de tener contexto fijado.

Propagación del contexto

Camino Cómo se fija el contexto
HTTP request TenantMiddleware rellena request.state.tenant_id/company_id; get_core_db / get_async_core_db leen esos valores y los guardan en Session.info. Un listener after_begin ejecuta SET LOCAL por transacción.
LicenseValidationMiddleware Usa scoped_core_db(tenant_id=...) para que la consulta de licencia entre con contexto RLS válido.
Tareas Celery track_and_dispatch inyecta rls_tenant_id / rls_company_id en los headers del task; los signals task_prerun/task_postrun los copian a ContextVars del worker, que el listener after_begin consume como fallback. Tareas críticas (imports/exports de invoices, expediente) abren la sesión con scoped_core_db(tenant_id=..., company_id=...).
Tests Las suites de pytest pueden usar scoped_core_db(...) o emular el flujo con set_config('app.tenant_id', ...) antes del query. Hay un set de tests en backend/tests/integration/test_rls_tenant_company.py que valida aislamiento A vs B usando un rol sin BYPASSRLS.

Reparto de responsabilidades

Capa Decide
API (FastAPI + Keycloak + PermissionService) Roles, permisos por compañía, accesos a recursos concretos (validate_access_to_resource), reglas de negocio.
RLS (PostgreSQL) Límite estructural duro: tenant_id y company_id. No modela roles/permisos para evitar duplicar lógica fina con la API.

Operación / DevOps

  • En producción la API debe conectar con un rol sin BYPASSRLS (postgres superusuario lo bypassea por diseño). El docker-compose.yml de desarrollo usa postgres deliberadamente para no romper migraciones; los tests crean un rol anexo76_rls_test para ejercitar las políticas.
  • Los jobs/ETL/migraciones que necesiten ver todos los tenants deben usar un rol técnico explícito con BYPASSRLS o fijar app.tenant_id por iteración — nunca asumir que la sesión global "ve todo".
  • La migración d1a2b3c4e5f6_enable_rls_tenant_company tiene downgrade() completo (drop policies + DISABLE ROW LEVEL SECURITY) para revertir.

Validación de Licencias

  • Middleware verifica en cada request:
    • ✓ Licencia activa
    • ✓ No expirada
    • ✓ Límites no excedidos

Base de Datos

Modelo Híbrido Multi-tenant

BD Core (Compartida)

Tablas principales:

  • tenants: Información de clientes
  • licenses: Control de licencias por tenant
  • license_usage: Métricas de uso
  • users (futuro): Usuarios por tenant

Todas las tablas operacionales incluyen tenant_id para segmentación.

BD Dedicadas (Enterprise)

  • Una BD PostgreSQL por tenant
  • Configuración almacenada en tenants.db_config
  • Migración automática desde BD compartida

Ejemplo de Tabla Multi-tenant

CREATE TABLE inventories (
    id SERIAL PRIMARY KEY,
    tenant_id INTEGER NOT NULL REFERENCES tenants(id),
    product_code VARCHAR(50) NOT NULL,
    quantity INTEGER NOT NULL,
    created_at TIMESTAMP DEFAULT NOW(),
    
    -- Índice compuesto para queries eficientes
    INDEX idx_tenant_product (tenant_id, product_code)
);

Migración y Upgrade

# Tenant en BD compartida → BD dedicada
tenant_service.upgrade_to_dedicated(
    tenant_id=123,
    db_config={
        "host": "dedicated-postgres.example.com",
        "port": 5432,
        "name": "tenant_123_db",
        "user": "tenant_123_user",
        "password": "secure_password"
    }
)

API Reference

Módulo: Authentication (/v1/auth)

Endpoint Método Descripción Auth
/auth/login POST Login con Keycloak Público
/auth/refresh POST Renovar access token Público
/auth/me GET Info del usuario actual Bearer
/auth/logout POST Cerrar sesión Bearer
/auth/health GET Health check Público

Módulo: Tenants (/v1/tenants)

Endpoint Método Descripción Rol Requerido
/tenants POST Crear tenant admin
/tenants GET Listar tenants admin
/tenants/{id} GET Obtener tenant user
/tenants/{id} PUT Actualizar tenant admin
/tenants/{id} DELETE Eliminar tenant admin
/tenants/slug/{slug} GET Obtener por slug user

Módulo: Licenses (/v1/licenses)

Endpoint Método Descripción Rol Requerido
/licenses POST Crear licencia admin
/licenses/tenant/{id} GET Obtener licencia user
/licenses/tenant/{id} PUT Actualizar licencia admin
/licenses/validate/{id} GET Validar licencia user
/licenses/usage/{id} GET Uso de licencia user
/licenses/my-license GET Mi licencia user

Planes de Licencia

Plan Usuarios Storage Operaciones/mes Features
Free 5 10 GB 1,000 API básica
Basic 20 50 GB 10,000 + Reportes
Professional 100 200 GB 50,000 + Integraciones
Enterprise ∞ ∞ ∞ + Soporte + BD dedicada

Próximas Implementaciones

Backend

  • Módulo de inventarios
  • Módulo de pedimentos
  • Módulo de facturas
  • Webhooks para integraciones
  • Reportes avanzados
  • Export/Import de datos

Frontend

  • Dashboard con gráficas
  • Gestión de inventarios UI
  • Formularios de pedimentos
  • Panel de administración
  • Reportes interactivos

DevOps

  • CI/CD pipeline
  • Tests automatizados
  • Monitoreo con Prometheus
  • Dashboards de Grafana
  • Deploy a Kubernetes
  • Backup automatizado

Última actualización: Octubre 2025
Versión del documento: 1.0