Informe de Arquitectura .
NET
Este documento describe la arquitectura a profundidad del proyecto BSC Portal Comercial API,
generado a través de un escaneo sistemático de su código y dependencias. Se utiliza el enfoque
de Monolito Modular / API de Integración.
1. Topología de la Solución (Dependencies)
La solución .NET se divide lógicamente en tres componentes principales: la API principal (portal-
comercial-api), el Middleware de integración (bsc-middleware) y los servicios de terceros/
comunes (argento-craft-rest-services).
El siguiente diagrama muestra las dependencias entre los proyectos ensamblados de la
solución:
[Link]
Referencia
[Link]
Referencia Referencia Referencia Dep. Dll-Dev
[Link] [Link] ArgentoCraft
Dep. Dll-Dev
Referencia Dep. Dll-Dev Referencia
[Link] [Link] EFCoreUtils / GenericUtils
Análisis Topológico:
[Link] es el punto de entrada (Host). Depende primariamente de Infrastructure. No
permite acceso directo a la lógica de base de datos ni a los DLLs externos, todo lo centraliza
Infrastructure (o debería, según las dependencias fuertes mostradas en el .csproj).
[Link] es el núcleo integrador. Contiene la persistencia (DbContext) y
consume los servicios del [Link] (Middleware) y de ArgentoCraft.
Compartidos: Utilitarios genéricos (EFCoreUtils, GenericUtils) se integran por paquete NuGet.
2. Inyección de Dependencias (DI) & Pipeline HTTP
El proyecto configura sus dependencias mediante métodos de extensión invocados en el archivo
[Link].
2.1 Pipeline de Ejecución (Middlewares)
El ciclo de vida de una petición HTTP ascendente atraviesa el siguiente pipeline:
Petición HTTP
ExceptionMiddleware
WebSocketsMiddleware
CORS Policy
Authentication
Authorization
Controllers / Endpoints
Respuesta HTTP
2.2 Registro de Servicios (DI Containers)
La inyección de dependencias centraliza el registro de las capas inferiores en el método
ConfigureDependencyInjections del proyecto Infrastructure.
Infrastructure Layer -
API Layer Scoped
ILocalExceptionLoggerService, ILocalAuditLogService
IAzureADUserService, IUserLoginProviderDispatcherService
IBizagiProcesosService, IMDWProcesosService
IUserRepository, IRequestRepository, etc.
IAccountService PortalComercialApiDbContext
Análisis de DI:
Inyección por Alcance (Scoped): La mayoría absoluta de los repositorios y servicios están
registrados como Scoped, atando su ciclo de vida y los contextos de base de datos a la
petición HTTP individual.
Entornos Simulados (Fake Services): Mediante el objeto bandera FakeServiceSettings, el
contenedor es capaz de inyectar servicios simulados (FakeBizagiProcesosService,
FakeMDWListasService), habilitando pruebas de entorno aislado sin requerir conectividad
total hacia las APIs del Core Bancario (MDW).
Aislamiento de Lógica Transversal: La inicialización del perfil de usuario (LocalUserInfo) se
inyecta dinámicamente obteniendo la información del HttpContext y el Repositorio de
Usuarios en el mismo contenedor DI.
3. Comunicación y Contratos (Interaction Flow)
El diseño de comunicación interna de la API sigue un patrón estructurado donde los
Controladores son delgados (Thin Controllers) y delegan la lógica pesada a Dispatcher Services
o servicios de orquestación.
3.1 Patrones Críticos Identificados
1. Generic API Controllers: Uso intensivo de clases base como DbQueryApiController<TKey,
TModel, TPagedModel, TService> para proveer automáticamente endpoints CRUD y de
búsqueda (GetWhere, GetPaged) sin reescribir código.
2. Contratos (DTOs): Fuerte tipado de peticiones y respuestas, diferenciando claramente el
modelo de lectura (RequestModel) del modelo de escritura o creación
(RequestByTypeCreateRequestModel).
3. Padrón Result (OperationResult): La comunicación entre la capa de Servicios y el Controlador
nunca devuelve directamente la entidad ni lanza excepciones de negocio. Utiliza un
contenedor de respuesta validable (ej. [Link]).
4. Filtros Automáticos Basados en Roles: Capacidad de sobrescribir consultas (OverrideCriteria)
en el controlador evaluando configuraciones dinámicas ([Link]) y
extrayendo los Claims del usuario autenticado.
3.2 Diagrama de Secuencia (Happy Path - Create Request
By Type)
Este diagrama ilustra el flujo de ejecución estándar y pasaje de DTOs en una operación
asíncrona de creación.
RequestController Authorization Middleware IRequestByTypeDispatcherService IRequestService - Specific PortalComercialApiDbContext
Client
POST /api/Requests/ByType
Validates read:request or read:journey role
CreateAsync model
Route to specific Request Type logic
AddAsync Entity - Auto-Audit
SaveChangesAsync
OperationResult with Payload
alt [IsSuccessfulWithNoErrors == true]
Success Result with Payload
200 OK - RequestByTypeSaveResponseModel
[IsSuccessfulWithNoErrors == false]
Failed Result with Errors
400 Bad Request - ErrorResponse
RequestController Authorization Middleware IRequestByTypeDispatcherService IRequestService - Specific PortalComercialApiDbContext
Client
4. Dominio y Persistencia (Data Layer)
La capa de persistencia se gestiona centralizadamente en PortalComercialApiDbContext,
empleando Entity Framework Core y SQL Server.
4.1 Características de la Persistencia
1. Auditoría Automática: El DbContext hereda de AuditDbContext (propio de la librería
[Link]). Todos los comandos SaveChanges interceptan los eventos de
EF Core y graban el registro del antes/después en la tabla de AuditLogs.
2. Contexto Atado al Log de Excepciones: El DbContext inyecta un IExceptionLoggerService,
sugiriendo que cualquier fallo a nivel de base de datos se registra y notifica sin romper
abruptamente el hilo principal si está configurado como Fire-and-Forget.
3. Mapeo de Entidades Segregado: El método OnModelCreating delega las configuraciones de
los esquemas a clases especializadas [Entity]EFConfiguration (Patrón
IEntityTypeConfiguration), manteniendo el contexto limpio.
4.2 Diagrama de Entidad-Relación Simplificado (ERD)
A continuación se mapean las entidades core identificadas en los DbSet y sus relaciones lógicas
inferidas:
REQUEST
USER ROLE_PROFILE ROLE
int Id PK
int Id PK int Id PK int Id PK
int Type
string Email string Name string Name
string AssignedToEmail
authenticates via
has profile contains roles belongs to tracks history
assigned to user
REQUEST_MOVEMENT
USER_ROLE_PROFILE USER_LOGIN_PROVIDER ROLE_PROFILE_RELATION
int Id PK
int UserId FK int UserId FK int RoleId FK
int RequestId FK
int RoleProfileId FK string Provider int RoleProfileId FK
string Action
5. Flujo de Datos y Modificación de Atributos XML
Una de las particularidades de esta arquitectura radica en su fuerte integración con sistemas
legados o core bancario (MDW / Bizagi) que se comunican nativamente mediante estructuras
XML, mientras que la API principal expone y consume internamente JSON. Cuando es necesario
añadir un nuevo atributo de tipo XML (por ejemplo, para enviar/recibir data compleja al/desde el
Core), la interacción y modificación ocurre en las siguientes capas:
5.1 En la Capa de Transporte (Middleware/Integración)
El sistema evita atar el modelo de dominio de Entity Framework a los formatos de las APIs
externas (Bizagi/MDW).
Serialización MDW (LocalXmlSerializer)
: El Middleware utiliza su propia implementación
LocalXmlSerializer
que hereda de utilidades genéricas de XML. Si necesitas enviar un nuevo campo estructural
hacia el MDW (Core Bancario), debes:
1. Modificar los DTOs del Middleware ([Link]), los cuales no requieren
imperativamente anotaciones [XmlElement], ya que el serializador utiliza un mapeo basado
en nombres de propiedades en un objeto estructurado (ExtremeMsgReplyDto,
ResponseXmlDto).
2. Al llegar la respuesta XMLResponse en crudo, el sistema intercepta el nodo
([Link](rawString)) y deserializa hacia el objeto DTO fuertemente tipado
gestionando automáticamente los nodos RetCode y equivalentes.
Serialización Bizagi (Manual Entity Mapping): Para el envío de solicitudes (ej. Tarjetas,
Cuentas), servicios como [Link] manipulan
directamente clases XElement y XDocument para inyectar nodos al vuelo estableciendo un
prefijo (documentNodePrefixElement: "/Case/Entities/..."). Añadir un campo significa agregar
explícitamente la lógica de construcción de los elementos LINQ to XML en estos Dispatchers.
5.2 En la Capa de API y Contratos (Controller/DTOs)
La comunicación HTTP Frontend <-> API se realiza íntegramente en formato JSON.
Los modelos que reciben la carga útil en los Controladores (RequestModel,
RequestByTypeCreateRequestModel) reciben tipos de datos estándar (string, int, arrays).
Regla: Nunca exponer o recibir strings XML crudos desde el Frontend. El Dispatcher (Capa de
Servicio) es el único responsable de parsear los datos JSON a XML en memoria antes de
pasarlos a LocalXmlSerializer o a los clientes SOAP/XML del Core externo.
5.3 En la Capa de Persistencia (Base de Datos)
El uso de campos de tipo nativo XML puro (ej. [Column(TypeName="xml")]) no está habilitado en
las configuraciones persistentes (EF Core) observadas (no hay rastros en EFConfigurations).
Acercamiento Arquitectónico: Si es necesario persistir un Payload XML por motivos de
auditoría, histórico, o estructura dinámica que no justifique tablas hijas, el sistema lo mapea
como un simple campo string o como NVARCHAR(MAX) en SQL Server, delegando la
manipulación de nodos lógicos a las capas de negocio/orquestación.
Modificación: Para añadir un campo que albergará XML, únicamente se requiere añadir la
propiedad string MiCampoXml a la Entidad (ej. [Link]), añadirla a la clase
RequestEFConfiguration limitando su espacio si es necesario, y aplicar la migración. El
parseo hacia XDocument se realizará on-the-fly durante su consumo en la Capa Services.
6. Conclusión del Análisis
El proyecto BSC Portal Comercial API está diseñado con alta cohesión y bajo acoplamiento
gracias a un uso estricto de Inyección de Dependencias atadas al contexto (Scoped). Actúa
principalmente como una API orquestadora entre frontends y sistemas del back-office (Bizagi y
Middleware Core Bancario), priorizando la auditoría de cada transacción (AuditDbContext), una
profunda transformación entre datos JSON (API) y XML (Integraciones), y una separación clara
de responsabilidades a través de Servicios Despachadores (Dispatchers) y un enrutamiento por
Controladores Genéricos fuertemente tipados.