Vision y principios
SPPD debe entenderse como una plataforma de promociones y folios comerciales con tres responsabilidades dominantes:
- orquestar reglas y operaciones de negocio,
- controlar aprobaciones y estados,
- integrarse con servicios corporativos y canales digitales sin romper trazabilidad.
Objetivo arquitectonico
Construir una plataforma desacoplada, observable y gobernable que permita operar promociones y folios de forma segura, auditable y escalable.
Drivers de arquitectura
| Driver | Implicacion para la solucion |
|---|---|
| Trazabilidad de promociones | Cada folio y aprobacion requiere un historial verificable. |
| Integracion corporativa | El backend debe interoperar con APIs Alpura, mensajeria y catalogos empresariales. |
| Seguridad empresarial | Keycloak y OAuth2/OIDC son parte del contrato base, no una capa opcional. |
| Escalabilidad funcional | El frontend debe crecer por capacidades sin convertir el sistema en un monolito UI. |
| Gobierno de datos | La persistencia debe distinguir entre core SPPD, omnicanal y maquina de estados. |
Alcance HLD
En alcance
- Microfrontend
alpura-sppd-front-main - Microservicio
alpura-sppd-main - Microservicio
alpura-sppd-statemachine-main - Integraciones corporativas principales
- Persistencia operativa y estados
- Riesgos tecnicos y decisiones recomendadas
Fuera de alcance
- Detalle linea por linea de todos los endpoints
- Evidencia forense completa por archivo
- Manuales operativos de desarrollo
- Contratos internos no confirmados por codigo
Principios de diseno
- Separar claramente canal, negocio y orquestacion de estados.
- Tratar la seguridad y los secretos como capacidades de plataforma.
- Diseñar integraciones con contratos explicitamente documentados.
- Priorizar componentes reusables y dominios funcionales sobre listados tecnicos dispersos.
- Mantener el HLD corto y mover el detalle excesivo a anexos tecnicos.
Dominios funcionales
| Dominio | Responsabilidad primaria | Componentes dominantes |
|---|---|---|
| Configuracion comercial | Catalogos, clientes, parametros y maestros | Frontend + alpura-sppd-main |
| Gestion de folios | Captura, edicion, consulta y reportes | Frontend + alpura-sppd-main |
| Aprobaciones | Rutas de decision, autorizadores, reemplazos e historico | Frontend + alpura-sppd-main |
| Orquestacion | Cambios de estado y procesamiento asincrono | alpura-sppd-statemachine-main |
| Integracion | Consumo de APIs corporativas, notificaciones y sync | Ambos backends |
| Seguridad y acceso | Roles, menu, autenticacion y contratos del portal | Frontend + Keycloak |
Decisiones de arquitectura recomendadas
Direccion recomendada
SPPD debe documentarse y evolucionar como una solucion por capacidades, no por carpetas tecnologicas.
- Consolidar el backend principal como API de dominio.
- Reservar state machine para transiciones, eventos y validacion de ciclo de vida.
- Reducir la dependencia de endpoints no documentados o no trazados.
- Formalizar un contrato de integracion entre frontend, API principal y state machine.
- Sustituir configuraciones sensibles embebidas por secretos gestionados externamente.