Implementación, riesgos y decisiones de arquitectura

Reúne las fases de implementación, los riesgos conocidos, las cuestiones pendientes de confirmar, los registros de decisiones de arquitectura y las conclusiones de la revisión conjunta.

15. Plan de implementación por fases

Fase 0: congelación de requisitos y modelado de amenazas

Producir línea base de tamaño de comerciantes y tráfico, lista de rutas de plataforma, lista de Scope, lista de regiones, lista de capacidades de idempotencia de backend, restricciones de cumplimiento de datos y modelo de amenazas STRIDE. Sin estas entradas, no se realiza dimensionamiento de producción.

Fase 1: corte vertical de una sola región

Implementar en un entorno que no es de producción el circuito mínimo cerrado del plano de control, ciclo de vida de Key, vinculación Key-IP, autorización Scope, instantánea de configuración regional, auditoría, limitación de tasa y una ruta de plataforma real. Se recomienda priorizar Zero Confirmation como la primera ruta de corte vertical, ya que la reunión indicó explícitamente que su diseño de múltiples bases de datos y multirregional se reutilizará en BPS.

La aceptación de fase se basa en que un cliente real complete de extremo a extremo creación de Key, vinculación de IP, llamada autorizada, rechazo de combinaciones erróneas, rotación y revocación.

Fase 2: acceso unificado de las plataformas iniciales

Integrar en un entorno que no es de producción las rutas de WebPay Inbox, BPS y Zero Confirmation confirmadas por los responsables de cada plataforma; establecer required scope, tiempo de espera, reintento, idempotencia y política de limitación de tasa para cada ruta; completar migración de comerciantes, tráfico sombra y pruebas de compatibilidad.

Fase 3: plano de datos multirregional

Desplegar una segunda región, conectar distribución de configuración, asunción del plano de control con vallado, conciliación regional de versiones, break-glass, los dos puntos de ejecución del centro de política de enrutamiento de tráfico, pertenencia regional de comerciantes y conmutación por fallo de solo lectura, y completar ejercicios de una zona de disponibilidad y a nivel regional. La primera versión de gateway de producción solo puede salir después de que se aprueben todas las puertas de publicación de esta fase.

Fase 4: escritura interregional controlada y expansión de plataforma

Abrir escritura de pagos interregional solo para plataformas que hayan demostrado idempotencia global, restricción única y un mecanismo explícito de cambio de región primaria. Formar una plantilla estándar de incorporación para que futuras plataformas se integren mediante rutas, Scope, registro de servicio y lista de verificación de validación.

16. Riesgos principales y medidas de mitigación

Riesgo	Impacto	Medida de mitigación
Tratar erróneamente una IP de comerciante como IP de Key	Las Key e IP del mismo comerciante pueden mezclarse incorrectamente	El modelo de datos vincula directamente `api_key_id` con `ip_network`, y la matriz de autorización entra en la puerta de publicación
Confiar en encabezados reenviados aportados por el cliente	Se puede falsificar la IP de origen para omitir la vinculación	El perímetro sobrescribe encabezados reenviados y solo confía en cadena de proxy confiable o PROXY Protocol
Consultar la base de datos central en cada solicitud	Se amplifican la latencia interregional y el fallo central	Instantánea de configuración regional versionada, eventos versionados y conciliación periódica
Caché de configuración demasiado antigua	Revocación o reducción de permisos no entra en vigor a tiempo	Eventos de invalidación de alta prioridad, objetivo de propagación de 10 segundos y sondeo de versiones de ciclo corto
No poder revocar una Key filtrada cuando falla el plano de control	Las credenciales atacadas siguen siendo válidas durante la ventana de fallo	Canal regional break-glass de solo denegación, firma por hardware, auditoría local solo de anexado y ejercicios trimestrales
Doble primario o bifurcación de versión del plano de control	La configuración regional no puede determinar orden nuevo y antiguo	Arrendamiento de escritura única con vallado, base de datos activa y de reserva, versión `(epoch, sequence)` y ejercicio de asunción
La respuesta de autenticación revela existencia de Key o ruta	Un atacante puede enumerar credenciales válidas e interfaces de plataforma	Los fallos de identidad e IP devuelven uniformemente `401`; Scope insuficiente y ruta inexistente devuelven uniformemente `404`
El gateway reintenta automáticamente solicitudes de escritura de pagos	Transacción duplicada	Forzar clave de idempotencia; no reintentar automáticamente solicitudes de escritura no idempotentes
El gateway asume escrituras dobles de bases de datos de negocio	Transacciones interbase incoherentes y difíciles de recuperar	El gateway solo enruta a un backend concreto; la replicación y el cambio son responsabilidad de la plataforma
Un único Scope de superusuario tiene permiso excesivo	Una Key filtrada afecta lateralmente a varias plataformas	Dividir Scope por plataforma, recurso y operación, denegar por defecto y revisar periódicamente
El Secret aparece en registros o portal	Filtración de credenciales a largo plazo	Mostrar una vez, ocultar encabezados en registros, almacenar resumen, hacer ejercicio de filtración y rotar periódicamente
La rotación de Pepper invalida todas las Key existentes	Interrupción masiva de solicitudes de comerciantes	Registrar la versión Pepper con el resumen y conservar el Pepper anterior hasta que venzan todos los Secret correspondientes
Repetición de Key estática	Lectura repetida no autorizada u operación de pago repetida	TLS, vinculación IP a nivel de Key, mTLS o firma de solicitud Ed25519 para escrituras de pago e idempotencia global del backend
CIDR operativo demasiado amplio	La vinculación IP pierde su efecto de aislamiento	Por defecto se permiten solo direcciones individuales, redes menores requieren aprobación de dos personas, redes más amplias se rechazan y se prohíben redes solapadas
La entrada multirregional no coincide con la región de datos	Incumplimiento normativo o lectura de datos obsoletos	Política regional explícita de comerciante, sin depender solo de DNS geográfico
Tráfico de negocio desconocido	La capacidad y el SLO no tienen base	Recopilar primero una línea base de tráfico de 30 días y después realizar pruebas de carga y dimensionamiento

17. Pendiente de confirmación por equipos de negocio y plataforma

La siguiente información no aparece en los dos materiales de reunión y actualmente no tiene base factual:

Rutas API completas, protocolos y versiones de WebPay Inbox, BPS y Zero Confirmation.
Semántica real de lectura y escritura, capacidad de idempotencia, límite de tiempo de espera y restricciones de reintento de cada plataforma.
Lista de regiones de producción, zonas de disponibilidad, redes privadas y entradas públicas.
Si las tres bases de datos de Zero Confirmation mencionadas en la transcripción son correctas, junto con su topología, método de replicación, nodo principal de escritura y procedimiento de cambio.
Si BPS ya tiene capacidad de múltiples bases de datos o multirregional.
Número de comerciantes, número de API Key, número de IP por Key, QPS máximo y tamaño de mensajes.
Si todos los comerciantes tienen IP de salida estable y si existen NAT compartido, IP dinámica o proxy de terceros.
Si las API Key las crea personal interno o se permite creación por autoservicio del comerciante, y quién es el responsable de aprobación.
Período legal de retención, residencia de datos y requisitos de privacidad para registros de acceso y auditoría.
Inventario existente de Kubernetes, PostgreSQL, Redis, bus de mensajes, KMS, WAF y productos de gestión de tráfico global; el producto de tráfico global será el punto de ejecución de entrada del centro de política de enrutamiento de tráfico.
Dominio externo, sistema de certificados y período de compatibilidad de migración de entrada antigua.
Si son aceptables el SLO recomendado, vigencia de Key, ventana de rotación de 24 horas y estrategia de instantánea sin conexión de 15 minutos.
Si TLS externo termina en WAF o pasa al gateway, y responsabilidades de registros, claves y control de acceso en cada punto de terminación.
Si las solicitudes de escritura de pagos usan mTLS o firma de solicitud Ed25519, y si las interfaces de solo lectura aceptan el riesgo residual de repetición bajo TLS y vinculación IP.
Nivel de coherencia de lectura de cada plataforma, origen de señal de retraso de réplica, vigencia de señal y umbral de conmutación automática de lectura.
Mecanismo de indicación de ruta disponible antes de autenticación para seleccionar región de entrada, además de límites de prevención de enumeración y privacidad de esa indicación.
Qué comerciantes, plataformas y tipos de solicitud aplican a preferencia fija, conmutación principal-reserva y enrutamiento por peso o proximidad, respectivamente.

Los asuntos anteriores no bloquean la revisión de arquitectura lógica, pero bloquearán dimensionamiento de producción, contrato de interfaz detallado, escritura de pagos interregional y selección técnica final. Los elementos 1, 2, 4, 8, 14, 15, 16 y 17 deben confirmarse antes de iniciar la fase 1.

18. Registro de decisiones de arquitectura

ADR-001: Gateway unificado, autorización de plataforma con granularidad fina

Decisión: todas las plataformas comparten una entrada y modelo de autorización unificados; cada Key y cada ruta mantienen un Scope explícito.
Motivo: satisface la entrada unificada entre plataformas planteada en la reunión y evita que la Key de una plataforma obtenga automáticamente permisos de otras plataformas.
Consecuencia: se requiere un proceso unificado de registro de rutas y Scope; las plataformas no pueden publicar por su cuenta una entrada de comerciante que omita el gateway.

ADR-002: IP vinculada a una API Key concreta

Decisión: los registros de vinculación IP usan api_key_id como clave foránea y no usan una lista blanca implícita de nivel de comerciante.
Motivo: resuelve directamente el problema de mezclar varias Key y varias IP del mismo comerciante.
Consecuencia: al añadir una Key, el comerciante debe configurar explícitamente la IP; reutilizar la misma IP en varias Key requiere varios registros de auditoría.

ADR-003: plano de control centralizado, plano de datos autónomo por región

Decisión: la fuente de verdad de configuración se gestiona de forma centralizada y se distribuye por eventos versionados a las cachés de instantáneas de configuración de cada región; la ruta crítica de solicitudes no accede a una base de datos interregional.
Motivo: equilibra control unificado, baja latencia multirregional y aislamiento ante fallo regional.
Consecuencia: se deben construir propagación fiable de configuración, invalidación de revocación, conciliación de versiones y estrategia de antigüedad acotada.

ADR-004: el gateway no es responsable de escrituras dobles de bases de datos de plataforma

Decisión: el gateway elige un backend concreto para cada solicitud y no escribe directamente en varias bases de datos de negocio.
Motivo: API Gateway no tiene el contexto necesario para resolver transacciones entre bases de datos y conflictos de datos de pagos.
Consecuencia: las escrituras de pagos interregionales requieren que la plataforma proporcione primero idempotencia, replicación y capacidad de cambio de región primaria.

ADR-005: separación entre proxy maduro y servicio independiente de validación de API Key

Decisión: se usa un proxy L7 maduro para red y gobierno de tráfico, y un servicio independiente de validación de API Key para resumen de Secret, estado de Key, entorno y vinculación Key-IP, que devuelve un conjunto de Scope al gateway; la política de permisos del gateway ejecuta visibilidad de ruta y required scope.
Motivo: reduce el riesgo de desarrollar un proxy propio y permite que la validación de credenciales y la decisión de permisos de ruta mantengan cada una capacidad de prueba y evolución.
Consecuencia: el servicio de validación de API Key se vuelve una dependencia crítica y debe desplegarse en varias instancias, usar caché de baja latencia y adoptar una estrategia de fallo cerrado.

ADR-006: prioridad para fallo de autenticación e invisibilidad de ruta

Decisión: los fallos de Key, estado, entorno y vinculación IP devuelven uniformemente 401; la falta de required scope y una ruta inexistente devuelven uniformemente 404.
Motivo: evita utilizar los códigos de estado para detectar Key válidas, vinculaciones de IP de origen y rutas de plataforma no autorizadas.
Consecuencia: los comerciantes solo pueden solicitar al equipo interno de soporte el reason code preciso con request_id; no pueden determinar directamente desde el error externo la configuración de IP o Scope.

ADR-007: recuperación ante desastres de escritura única con vallado del plano de control

Decisión: el plano de control se despliega en modo activo y de reserva entre regiones, utiliza un arrendamiento de escritura única y versión (epoch, sequence), y se prohíbe asumir el control si el primario anterior no ha sido vallado.
Motivo: un número de secuencia monótono ordinario no puede resolver bifurcaciones de versión de doble primario después de una partición de red.
Consecuencia: la asunción del plano de control puede sacrificar parte de la disponibilidad administrativa, pero no permite que dos regiones publiquen configuración conflictiva al mismo tiempo.

ADR-008: añadir prueba de posesión para solicitudes de escritura de pagos

Decisión: además de API Key y vinculación IP, una ruta de escritura de pagos de producción debe usar mTLS o firma de solicitud Ed25519.
Motivo: una Key Bearer estática, incluso transmitida por TLS, sigue sin poder resistir la repetición después de que la credencial se filtre en una red confiable o en un punto de terminación TLS.
Consecuencia: el comerciante necesita gestionar certificados de cliente o claves privadas de firma, y el gateway necesita capacidad de revocación de certificados, ciclo de vida de claves públicas, reloj y estado de Nonce.

ADR-009: la idempotencia de negocio pertenece a la plataforma de backend

Decisión: el gateway solo obliga y transmite Idempotency-Key; no conserva resultados de solicitudes ni decide conflictos de contenido.
Motivo: el estado de deduplicación local de una región no puede garantizar coherencia de escrituras de pagos interregionales.
Consecuencia: la plataforma debe proporcionar idempotencia global y restricción única; el gateway solo transmite el 409 generado por el backend.

19. Registro de revisión de arquitectura entre Codex y Claude

19.1 Método de revisión

Codex formó la primera versión del diseño basándose en los dos materiales de reunión y ejecutó comprobaciones locales de coherencia.
La versión de Claude Code era 2.1.201, el modelo solicitado y el modelo real eran claude-fable-5, y el effort era medium.
Claude solo usó Read, Grep y Glob para leer los materiales de reunión y el documento de diseño; no recibió permisos de escritura ni Shell, y no modificó archivos.
La primera ronda realizó una revisión de arquitectura adversarial, la segunda validó uno por uno el cierre de problemas y la tercera volvió a comprobar únicamente los tres riesgos residuales cerrados tras la revisión.

19.2 Aceptado y corregido

El orden de procesamiento de autenticación y rutas podía revelar por código de estado la existencia de Key o ruta; se cerró mediante ADR-006 y la sección 6.
El plano de control carecía de recuperación ante desastres interregional, vallado de escritura única y versiones sin bifurcación; se cerró mediante la sección 7.5 y ADR-007.
No se podía bloquear de emergencia una Key filtrada cuando fallaba el plano de control; se cerró mediante el canal regional de solo denegación de la sección 10.3.
La rotación de Pepper no podía validar Key existentes; se añadieron pepper_version y reglas de conservación de versiones anteriores.
Las responsabilidades de idempotencia entre gateway y backend no estaban claras; se aclararon mediante la sección 6 y ADR-009.
Se completaron comportamiento de limitación de tasa ante fallo de Redis, aislamiento de entorno, límites CIDR, medición de SLI, protección contra repetición Bearer, señal de coherencia de lectura y solidez de evidencia de transcripción.
La renovación de denegación de emergencia, la cuota de escalado durante fallo de Redis y el ámbito de aplicación de claves de idempotencia pendientes de la segunda ronda se cerraron antes de la revisión final limitada.

19.3 Cuestionamientos rechazados

Cambiar a fallo abierto cuando falla el componente de autorización: rechazado. Una entrada de pagos debe fallar cerrada y no puede intercambiar el objetivo de disponibilidad por omitir autorización.
Simplificar la vinculación IP de Key como lista blanca de nivel de comerciante: rechazado. Esta propuesta contradice directamente el requisito de la reunión de no mezclar varias Key y varias IP.
Hacer que el gateway coordine escrituras en tres bases de datos de backend: rechazado. Las transacciones entre bases de datos y la coherencia contable pertenecen al límite de la plataforma.
Bloquear directamente una pila de producto concreta sin evidencia de infraestructura: rechazado. Este documento solo conserva una línea base tecnológica recomendada y sustituible.

19.4 Conclusión de convergencia

Después de tres rondas de revisión de solo lectura no se encontraron blocker ni contradicciones sustanciales sin cerrar. Este documento puede entrar en revisión de negocio e ingeniería, pero su estado sigue siendo "recomendación de diseño", no "listo para producción". Los vacíos de hechos de la sección 17 deben cerrarse antes de la fase de implementación correspondiente; todos los SLO recomendados, selecciones técnicas y políticas de fallo deben verificarse con infraestructura real, pruebas de carga y ejercicios.

La tercera ronda dejó solo dos asuntos de diseño detallado no bloqueantes: definir la duración de una renovación break-glass y el criterio de auditoría de renovaciones acumuladas; y redactar un manual de gestión manual para la reducción de rendimiento cuando un fallo prolongado de Redis se combine con escalado. Estos dos asuntos no cambian la arquitectura lógica ni la conclusión de entrega actual.

19.5 Revisión especializada del centro de política de enrutamiento de tráfico

La versión de Claude Code era 2.1.201, el modelo solicitado y el real eran claude-fable-5, el effort era medium, y solo utilizó Read, Grep y Glob; no modificó archivos.
La primera ronda especializada encontró dos blocker: se mezclaban la selección de región de entrada y la selección de backend después de autenticación, y la indicación de ruta anterior a autenticación se trataba erróneamente como identidad confiable. Este documento adopta "una política, dos puntos de ejecución" para cerrar ambos problemas.
Se corrigieron los seis problemas sustanciales planteados en la primera ronda: semántica de fallo de entrada, filtrado de conjuntos de candidatos, antigüedad acotada, restricciones de cumplimiento, coherencia terminológica e identificación de opciones recomendadas.
Después de revisar el archivo real en la segunda ronda, se confirmó que no quedaban blocker ni problemas sustanciales, con confianza alta, y puede entrar en revisión de negocio e ingeniería.
Dos mejoras de redacción no bloqueantes propuestas en la revisión final se adoptaron localmente después de la revisión: añadir una salvaguarda de writer para una solicitud de escritura enviada erróneamente antes de autenticar, y aclarar que reason_code se utiliza solo en registros internos y auditoría. Los dos ajustes no cambian la semántica de arquitectura y por eso no se solicitó otra revisión externa.

19.6 Revisión especializada de estratificación abstracta y expansión de nodos

La primera revisión de solo lectura aceptó el enfoque de "vista general de 8 nodos + detalle de 6 nodos abstractos + 1 secuencia entre nodos" y dio 8 modificaciones obligatorias: anclaje del punto de ejecución de entrada, orden de gobierno, limpieza de encabezados de identidad, límite de dos componentes del control de acceso, entrada break-glass, separación de responsabilidad de auditoría, limpieza de entradas colgantes en la vista general y separación de los límites de mTLS y Ed25519.
Este documento aplicó una por una todas las modificaciones obligatorias. La comprobación estática confirmó correspondencia uno a uno entre 8 bloques Mermaid y 8 contenedores Mermaid en HTML, exactamente 8 nodos en la vista general, ubicación de los 6 subapartados de detalle y cero términos ambiguos antiguos relacionados con región.
La segunda revisión de solo lectura comprobó uno por uno 10 hechos y concluyó accept, con confianza alta; no encontró blocker, problemas sustanciales, módulos sin fundamento, responsabilidades duplicadas ni conexiones erróneas.
Dos sugerencias de legibilidad no bloqueantes de la segunda ronda se adoptaron localmente después de la revisión: cambiar la descripción del diagrama de secuencia a "límites abstractos y dependencias clave", y colocar explícitamente el nodo de identidad validada entre los marcos del servicio de validación de API Key y la política de permisos del gateway.
Antes de esta ronda, el HTML original de una sola página no tenía evidencia de aceptación visual a nivel de navegador: la automatización de Chrome rechazaba la URL local file:// y Mermaid CLI no tenía la versión especificada de Headless Chrome. En esta ronda se completó la verificación mediante vista previa HTTP local: la página de resumen, la navegación temática y los 8 diagramas Mermaid se comprobaron con renderizado real en navegador. Esta verificación solo cubre el sitio estático local y no representa preparación para producción; antes de desplegar externamente debe verificarse de nuevo en el entorno de despliegue destino.