Guía de ingeniería de Customer App

Usa esta guía al contribuir al repositorio de Customer App. El acceso al repositorio requiere autorización. Esta guía cubre el proyecto bare React Native versionado y sus controles de calidad locales. Las credenciales nativas, los datos de clientes, la firma, el acceso a tiendas y la aprobación de publicación quedan fuera de esta guía.

Arquitectura

Customer App es una aplicación bare React Native 0.81.1 que usa React 19.1. index.js registra la aplicación nativa, App.tsx establece la raíz de safe-area y src/TemplateApp.tsx compone los límites de tema, permisos, sesión, API, configuración, consentimiento y navegación. React Navigation es responsable de la jerarquía de pantallas en src/navigators.

El comportamiento de comercio y la interfaz compartidos están fijados mediante el submódulo Git src/@/components. Los proyectos de plataforma nativa están en ios/ y android/; los cambios de JavaScript también pueden requerir pods nativos, configuración de Gradle, permisos, esquemas de URL o capacidades del proveedor que coincidan.

Mapa del repositorio

Ruta	Responsabilidad
index.js y App.tsx	Registro nativo y raíz de la aplicación.
src/TemplateApp.tsx	Composición de proveedores, controles de ejecución y comportamiento de nivel superior de la app.
src/navigators/	Contenedor de navegación, pilas, pestañas y destinos tipados de la app.
src/screens/ y src/components/	Recorridos de clientes e interfaz propia de la app.
src/contexts/	Estado propiedad de la app, como el consentimiento y el comportamiento de campos de pago.
src/@/components/	Submódulo Components compartido y fijado.
src/config.json, src/config.js y src/theme.json	Valores predeterminados de la app independientes del navegador y configuración del tema.
ios/	Workspace de Xcode, destino de la app, extensión, pods, entitlements y recursos de plataformas Apple.
android/	Proyecto Gradle, manifests, recursos y destino de la aplicación Android.
__tests__/, src/**/*.test.* y jest/	Jest, React Native Testing Library, mocks y configuración de cobertura.
i18n/	Comprobaciones de catálogos de idioma generados y utilidades de traducción.
patches/	Cambios versionados de patch-package aplicados después de la instalación.

Requisitos previos

Instala las herramientas de plataforma para el destino que vayas a ejecutar:

• Git con soporte para submódulos.
• Node.js 20 o posterior, según package.json y CI.
• Yarn Classic con el yarn.lock versionado.
• Android: Android Studio, un SDK compatible con el proyecto Gradle versionado, Java 17 y un emulador o dispositivo conectado.
• iOS: macOS, una instalación compatible de Xcode, Ruby, Bundler, CocoaPods y un runtime de simulador instalado. El Gemfile del repositorio fija CocoaPods y las gemas auxiliares.

Solicita acceso al repositorio a su responsable y utiliza el método de autenticación aprobado. Desde un checkout autorizado, inicializa la revisión fijada de Components e instala las dependencias:

git submodule update --init --recursive
yarn install --frozen-lockfile

Para iOS, instala desde el directorio ios el árbol de dependencias nativas versionado:

bundle install
cd ios
bundle exec pod install
cd ..

No elimines archivos de bloqueo como parte de la configuración rutinaria. Los cambios a yarn.lock, Gemfile.lock, Podfile.lock, el wrapper de Gradle o el puntero del submódulo son cambios de dependencias y deben revisarse como tales.

Configura una compilación de desarrollo segura

src/config.json proporciona valores predeterminados de la app visibles para el cliente y src/config.js los normaliza. Los archivos de proveedores nativos, manifests, esquemas, entitlements y ajustes de firma añaden entradas específicas de cada plataforma.

• Parte de un proyecto de desarrollo autorizado y cuentas no productivas.
• Considera que un usuario final puede extraer la configuración empaquetada en la app.
• Nunca guardes en el repositorio secretos de API, claves privadas, material de firma, archivos de cuentas de servicio, exportaciones de clientes, datos de pago, tokens de sesión ni credenciales reutilizables de proveedores.
• Mantén alineados los identificadores de aplicación, esquemas de URL, configuración de notificaciones y aplicaciones de proveedores con la misma variante de compilación aprobada. La presencia del código fuente no demuestra que un proveedor esté configurado o habilitado.
• No sustituyas archivos de proveedor versionados por copias de producción para conseguir una compilación local.

Revisa Límites de configuración de Customer App y Límites de integración nativa antes de cambiar una superficie de integración.

Ejecución local

Inicia Metro en una terminal:

yarn start

Ejecuta la plataforma prevista desde otra terminal:

yarn ios

yarn android

También puedes abrir ios/ReactNativeAppsTemplate5.xcworkspace en Xcode o el proyecto android/ en Android Studio cuando necesites diagnósticos nativos. Selecciona un destino de desarrollo; no reutilices una configuración de firma para distribución en el trabajo local rutinario.

Valida los cambios

El control de CI para pull requests comprueba lint, pruebas unitarias, traducciones generadas, validez de traducciones y cobertura. Ejecuta localmente los comandos pertinentes:

yarn lint:check
yarn test
yarn i18n:check-generated
yarn i18n:verify
yarn test:coverage

Jest excluye el submódulo Components compartido del cálculo de cobertura de este repositorio; los cambios en ese submódulo deben validarse en su repositorio propietario. yarn lint escribe correcciones, mientras que yarn lint:check informa sin reescribir archivos.

Las pruebas de JavaScript no sustituyen una compilación nativa. Para cambios en pods, Gradle, permisos, esquemas, enlaces profundos, notificaciones, pagos, mapas o inicio de sesión social, compila y prueba la plataforma afectada con los efectos de proveedores desactivados o aislados.

Límites de compilación y publicación

Este repositorio no define un script de paquete que publique una versión en las tiendas de apps. Una compilación distribuible requiere revisión del responsable de plataforma sobre configuración nativa, identificadores, firma, metadatos de privacidad, aplicaciones de proveedores, versiones, registros de tienda y revisiones exactas de las fuentes y submódulos.

Iniciar un simulador, crear un archivo local, pasar CI o inicializar un SDK de proveedor no demuestra que se haya compilado, enviado, aprobado o desplegado una versión de App Store o Play Store. Solo un responsable de publicación autorizado debe usar credenciales de firma o sistemas de tiendas externos.

Resolución de problemas

Síntoma	Comprobación
No se resuelven alias compartidos o módulos de comercio	Ejecuta git submodule status y luego inicializa el submódulo fijado. Confirma que Babel y Jest siguen apuntando a los alias mantenidos.
Metro sirve módulos obsoletos o duplicados	Detén Metro, confirma que solo se usa un repositorio y un árbol de dependencias y reinicia con el script del repositorio antes de limpiar cachés más amplias.
CocoaPods no puede resolver o compilar	Usa las restricciones de Ruby y archivos de bloqueo del repositorio, ejecuta bundle exec pod install y abre el .xcworkspace, no el .xcodeproj. Revisa el primer error del compilador nativo.
Android no encuentra el SDK o la cadena de herramientas Java	Confirma las rutas del SDK de Android Studio, que haya un emulador o dispositivo en ejecución y que Java 17 esté instalado antes de cambiar archivos Gradle.
Falta un botón de proveedor	Comprueba la compilación, plataforma, proyecto, capacidad nativa y control de disponibilidad pública aprobados. No infieras una interrupción del servicio ni añadas credenciales al código fuente.
Un enlace profundo abre un estado incorrecto	Verifica el esquema nativo y el registro de intents, y luego la ruta tipada y los controles actuales de sesión y proyecto. Un enlace nunca concede acceso a un recurso.
Las traducciones generadas fallan en CI	Ejecuta ambas comprobaciones de i18n y actualiza conjuntamente las claves fuente y los catálogos generados.
Pasan las pruebas unitarias, pero falla la compilación del dispositivo	Reproduce en Xcode o Android Studio; las pruebas de JavaScript no compilan dependencias nativas ni entitlements.

Límites de seguridad

• Almacena las sesiones y resultados de proveedores solo mediante el ciclo de vida seguro mantenido. Nunca los imprimas en Metro, registros del dispositivo, analítica, capturas de pantalla ni fixtures de documentación.
• Vuelve a autorizar pedidos, mensajes, wallets, estado de pagos y datos de cuenta después de cada navegación externa o iniciada desde una notificación push. Un enlace profundo o notificación expresa una intención, no demuestra acceso.
• Mantén los datos sin procesar de tarjetas dentro de los componentes compatibles del proveedor de pagos. No guardes tokens de pago en registros, URL, almacenamiento general de la app ni snapshots de pruebas.
• Separa el permiso del sistema operativo, el consentimiento del cliente, el registro del proveedor, la vinculación de Ordering.co, la entrega de mensajes y el estado de apertura de notificaciones.
• Rechaza callbacks tardíos después del cierre de sesión, cambio de cuenta o proyecto, cancelación o un nuevo intento.
• Valida los cambios nativos en ambas plataformas cuando el contrato sea compartido; no deduzcas el comportamiento de Android a partir de un resultado correcto en iOS, ni al revés.
• Usa la referencia de API para los contratos publicados del servidor. El código del cliente y las llamadas al SDK no establecen la autorización del servidor ni las garantías de un proveedor.

---

Referencias relacionadas: Referencia para desarrolladores de Customer App · Límites de configuración · Límites de enlaces de app · Límites de integración nativa