Guía de desarrollo de Payment Emulator Lab

Índice / Index · English

Traducción de docs/en/onboarding/development-guide.md, que es el original. Si discrepan, manda el inglés.

#Antes de tocar código

1. Lee .agents/README.md y el enlace de la aplicación que vayas a tocar.
2. Si hay un contrato de proveedor de por medio, lee contracts/<proveedor>/ y docs/en/fidelity/<proveedor>.md antes de implementar.
3. Encuentra el módulo dueño que ya existe y su prueba análoga más cercana.
4. Mira git status --short y conserva los cambios locales que no vengan al caso.

El repositorio es modular pero no es DDD, a propósito. No introduzcas agregados, eventos de dominio, interfaces de repositorio ni una división application/domain/infrastructure para implementar una funcionalidad corriente.

#Elegir el sitio correcto

#Añadir un endpoint al backend

Para el plano de control:

1. Añade o reutiliza un DTO en el dto/ del módulo dueño cuando escriba datos. Los DTO usan class-validator; no repitas a mano en el controlador la misma validación.
2. Añade la ruta al controlador dueño. Declara RolesGuard y ApplicationScopeGuard igual que sus rutas hermanas.
3. El comportamiento, las transacciones y la persistencia van en el servicio.
4. Para un listado, usa ListQueryDto y paginate()/paginateArray(). Declara listas explícitas de sortable, filterable y searchable.
5. Añade una prueba de integración. Si los datos tienen alcance por fila, incluye a alguien de otro inquilino y espera 404.
6. Si la consola lo necesita, añade la ruta de Nitro más estrecha que valga; nunca llames a la API de NestJS desde el navegador.

El controlador comodín de la pasarela se registra el último en AppModule. Los módulos nuevos del plano de control tienen que quedar antes de GatewayModule, o el comodín puede capturar sus rutas.

#Cambiar una operación de un proveedor

Empieza por la especificación oficial del proveedor y su documento de fidelidad. Después:

1. Toca sólo los ficheros de ruta, contrato y traducción de ese proveedor.
2. Mantén las operaciones canónicas dentro de CANONICAL_OPERATIONS. Si el proveedor exige de verdad una operación universal nueva, eso es un cambio de arquitectura: actualiza el contrato y las pruebas compartidas a conciencia.
3. No inyectes servicios en el plugin. Traduce a un IntentCommand y deja que PaymentsService haga la escritura.
4. Actualiza los casos de conformidad estática y de comportamiento, y las pruebas con el SDK oficial donde el SDK pueda apuntar al emulador.
5. Actualiza docs/en/fidelity/<proveedor>.md, incluidas las limitaciones.

Para un proveedor entero nuevo, sigue Añadir un proveedor.

#Añadir o cambiar un escenario

Edita sólo el JSON canónico bajo scenarios/ y luego corre:

npm run scenario:compile

Eso regenera apps/api/src/modules/scenarios/default-scenarios.ts. El build, el typecheck y las pruebas también compilan los escenarios antes, pero correr la orden a mano da un error de validación más claro.

Usa un then.outcome canónico; el vocabulario del proveedor va sólo en then.wire, y sólo cuando el estado exacto de ese proveedor sea el propósito de la prueba. No se admite código arbitrario. Ver Escenarios para el DSL soportado y sus carencias.

#Añadir una entidad o un campo

1. Cambia o añade la entidad en apps/api/src/infrastructure/database/entities/ y expórtala desde entities/index.ts cuando el descubrimiento lo requiera.

2. Añade una migración nueva y ordenada. No reescribas una migración que ya pueda haber corrido.

3. Aplícala contra una base desechable:

   bash Copiar

   npm run migrate
   

4. Ejercita el down: npm run migrate -- --down, y después npm run migrate otra vez. Una vuelta atrás que nadie corre es una vuelta atrás que no funciona.

5. Añade una prueba de integración que dependa del esquema nuevo; que compile no demuestra que la migración y la entidad estén de acuerdo.

Las columnas de dinero usan unidades mínimas enteras. Los cuerpos que varían por proveedor usan JSONB sólo en la frontera del proveedor/recurso o en metadatos declarados. Nunca añadas una columna de saldo mutable.

#Añadir una funcionalidad a la consola

El camino normal es:

página/componente -> modelo y columnas del módulo -> gateway/composable de core
                  -> ruta de Nitro -> endpoint del plano de control

Reutiliza createRestGateway, useEntityCollection y RTable en vez de montar query strings o cachés en una página. Las credenciales se quedan en el servidor, en Nitro. Corre npm run typecheck y npm run build: los problemas de auto-importación y de resolución en SSR de Nuxt a veces sólo se ven en una compilación de verdad.

Lo que posee cada pieza de core/ está en la consola.

#Añadir una funcionalidad al checkout

Decide si es neutral o es identidad de un proveedor:

• El resumen, el desenlace y la disposición del armazón van en apps/checkout/app/components/.
• Los textos, la disposición y el flujo propios de un proveedor van en apps/checkout/providers/<id>/.
• El acceso a la API va por apps/checkout/server/api/ y server/utils/api.ts.

No instales ni reutilices la capa PrimeVue de la consola. Nunca aceptes un identificador de cliente desde el cuerpo de la confirmación para elegir cartera; esa identidad es de la sesión del checkout.

#Añadir una prueba

• Transformación pura o invariante: apps/api/test/*.spec.ts.
• Base de datos, HTTP, autorización o concurrencia: apps/api/test/integration/.
• Garantía para todos los proveedores: parametriza la suite de conformidad.
• Comportamiento de un SDK: un spec propio, con telemetría y red desactivadas.
• Aceptación de producto entero: amplía scripts/stack-smoke.mjs sólo para un camino crítico entre aplicaciones.

Ver Pruebas para las órdenes y cómo se comporta el arnés.

#Definición de terminado

Desde la raíz del repositorio:

npm run typecheck
npm run lint
npm test
npm run build
npm run smoke

Si el cambio toca migraciones, sesiones, rutas de Nitro, el worker o un flujo entre aplicaciones, además:

docker compose up --build --wait
npm run smoke:stack

Antes de entregar, comprueba los enlaces de la documentación y confirma que cada ruta, orden, variable de entorno y endpoint mencionado sigue existiendo.