Guía de ingeniería de Driver App
Usa esta guía para desarrollar y mantener la app bare React Native Driver App. El comportamiento en tiendas, API, sistemas operativos y proveedores externos también depende de las versiones y la configuración de cada despliegue.
Arquitectura
La aplicación separa la lógica compartida sin interfaz, la presentación propiedad de la app y la conexión de pantallas nativas:
index.js → App.tsx → src/DeliveryApp.tsx → src/appContainer.tsx
└→ src/navigators/RootNavigator.tsx
src/@/components shared headless controllers, hooks, and API client
src/ui Driver App presentation
src/pages thin screen wrappers
src/navigators authentication, schedule, permissions, push, and delivery navigation
src/context/hooks app-owned permission, theme, and location behavior
ios and android native projects and platform integrations
src/@/components es un submódulo Git. El alias React Native @components resuelve a su punto de
entrada nativo. Coordina los cambios de lógica compartida en el repositorio Components; no edites el
submódulo como si fuera código normal de la app.
El inicio de Driver App puede combinar el estado de sesión restaurado, configuración, estado de red, permisos, registro push, horarios, sockets, gestión de AppState y ubicación en primer y segundo plano. Conserva esos límites de responsabilidad y evita trasladar la autoridad del servidor al código de presentación del cliente.
Mapa del repositorio
| Ruta | Responsabilidad |
|---|---|
App.tsx, src/DeliveryApp.tsx, src/appContainer.tsx | Entrada de la app y composición de proveedores |
src/pages | Conexión de pantallas para repartidores |
src/navigators | Conexión de autenticación, horario, pestañas, flujo de entregas, push, sockets y ciclo de vida |
src/ui | Componentes de interfaz, diseños, proveedores y utilidades de presentación, propiedad de la app |
src/context, src/hooks, src/providers | Comportamiento de permisos, ubicación, tema y almacenamiento, propiedad de la app |
src/@/components | Submódulo Components compartido y fijado |
src/config.json | Ajustes de ejecución versionados que consume la app |
i18n | Herramientas para generar, validar y sincronizar catálogos de traducción |
ios, android | Workspaces nativos, proyectos, extensión de notificaciones, manifests y configuración Gradle |
jest, src/**/__tests__ | Pruebas de la app y sus suites |
Mantén alineados los alias @, @ui y @components en babel.config.js y tsconfig.json.
Requisitos previos y configuración
- Instala los requisitos de React Native del host para la plataforma que vayas a ejecutar: Xcode y CocoaPods para iOS, o Android Studio y un JDK/SDK de Android compatible.
- Usa Yarn.
NODE_VERSION.txtdel repositorio selecciona Node 22, mientras quepackage.jsonacepta Node 20 o posterior. - Clona con submódulos o inicialízalos antes de instalar dependencias.
git clone --recursive <authorized-repository-url>
cd <cloned-repository-directory>
yarn install --frozen-lockfile
Para un clon existente:
git submodule update --init --recursive
yarn install --frozen-lockfile
Para iOS, instala las dependencias Ruby y Pods versionadas la primera vez y después de cambios en dependencias nativas:
bundle install
cd ios
bundle exec pod install
cd ..
Abre ios/deliveryApp.xcworkspace cuando trabajes en Xcode. El scheme compartido es deliveryApp;
el workspace también incluye la extensión de servicio de notificaciones. Usa el wrapper Gradle
versionado para Android en lugar de una versión instalada por separado.
Configuración segura
src/config.json es una entrada versionada de la aplicación, no un lugar para credenciales. Mantén las
No incluyas claves secretas, material de firma, hosts privados, registros de clientes, tokens, pedidos,
datos de pagos, coordenadas precisas, cargas de notificaciones ni credenciales de proveedores en el
código fuente, registros o reportes de errores.
Antes de iniciar la app, confirma que los ajustes empaquetados, la revisión de Components, los entornos de API y socket, el proveedor push, la configuración de ubicación y los entitlements nativos estén configurados para el mismo proyecto. No copies valores de otro proyecto ni sustituyas un endpoint configurado por una suposición.
El inicio normal puede inicializar red, sesión, push, permisos, socket y ubicación antes de seleccionar una acción de entrega. Usa un entorno no productivo y cuentas de prueba durante el desarrollo. Nunca uses la cuenta o ruta de un repartidor de producción solo para verificar que la app se inicia.
El trabajo de traducción debe empezar por la generación y verificación local. yarn i18n:sync es la
prueba en seco documentada; yarn i18n:sync:live puede escribir mediante una integración API autorizada
y no debe usarse como comando exploratorio.
Ejecuta la app
Inicia Metro en una terminal:
yarn start
Ejecuta una plataforma desde otra terminal:
yarn ios
yarn android
Si Metro conserva estado obsoleto de módulos, usa yarn start:reset. Para cambios nativos, de la
extensión de notificaciones, permisos o ubicación en segundo plano, recompila el destino nativo y
valídalo en la plataforma afectada; Fast Refresh no es suficiente.
Prueba y verifica los cambios
Usa el comando de lint que no modifica archivos durante las comprobaciones locales. El script normal
yarn lint aplica correcciones.
npx tsc --noEmit
yarn lint:check
yarn test
yarn i18n:check-generated
yarn i18n:verify
Entre los comandos útiles y acotados están:
yarn test path/to/file.test.tsx
yarn test:coverage
yarn test:coverage:summary
El flujo de CI de la app instala el lockfile congelado de Yarn y ejecuta lint, TypeScript, Jest, comprobaciones de traducción y cobertura. Jest cubre ubicaciones de pruebas propiedad de la app y excluye carpetas nativas y el submódulo Components; valida también los cambios en Components en su propio repositorio. La verificación nativa debe cubrir los permisos pertinentes, los casos denegados o cancelados, las transiciones entre primer y segundo plano, la limpieza de listeners y la recuperación segura, no solo el estado de pantalla correcto.
Usa un entorno no productivo y cuentas de prueba para flujos que modifiquen pedidos, publiquen la ubicación, envíen mensajes, registren notificaciones o eliminen sesiones y cuentas. La respuesta del cliente por sí sola no confirma que la API o el proveedor hayan completado la acción.
Compilación y entrega para publicación
Genera compilaciones nativas de desarrollo con React Native CLI, el workspace de Xcode, la extensión de notificaciones y el wrapper Gradle. La firma, distribución, lanzamiento gradual y reversión se gestionan en el sistema de publicación de tu organización.
Resolución de problemas
| Síntoma | Comprobación |
|---|---|
No se resuelve @components | Confirma que el submódulo esté inicializado y que el alias apunte al punto de entrada nativo. |
| Metro resuelve archivos obsoletos | Detén Metro, ejecuta yarn start:reset y recompila después de cambios nativos. |
| Faltan dependencias o símbolos de iOS o de la extensión | Ejecuta Bundler y bundle exec pod install desde ios; abre el workspace, no el proyecto. |
| La configuración de compilación de Android no coincide con el checkout | Usa android/gradlew y verifica el JDK/SDK instalado frente a los archivos React Native y Gradle versionados. |
| La app se detiene en autenticación, permisos u horario | Identifica el control responsable y revisa su contrato específico antes de cambiar la navegación. |
| Persisten callbacks de ubicación o segundo plano inesperados | Detén el escenario, registra conteos de ciclo de vida no sensibles y sigue los contratos de segundo plano y ubicación. |
| Push y tiempo real discrepan | Diagnostícalos como transportes separados; ninguno demuestra que el otro esté configurado, autorizado o actualizado. |
| Se desconoce el resultado de una acción de pedido | No reintentes. Conserva el escenario sintético e inspecciona la aceptación del servidor, la parcialidad agrupada y los efectos posteriores mediante el contrato de cambios. |
| CI y los resultados locales difieren | Compara Node, instalación desde el lockfile, commit del submódulo, traducciones generadas y variante exacta del comando. |
Seguridad y escalamiento
Confirma que la app, la revisión de Components, el entorno de API, la configuración de proveedores, el propósito de ubicación y los permisos de segundo plano sean adecuados antes de ejecutar flujos que puedan afectar cuentas o dispositivos reales. Al informar un problema, incluye solo los datos necesarios para reproducirlo y elimina los datos de clientes, cuentas, ubicación y credenciales.
Nunca pegues credenciales, valores de configuración sin procesar, tokens de acceso, datos de clientes/negocios/pedidos, coordenadas precisas, datos de pago, contenido multimedia, cargas de notificaciones, identificadores de dispositivo ni material de firma en un ticket. No reintentes un cambio, registro de notificación, mensaje, opinión, transferencia externa o publicación de ubicación con resultado ambiguo solo para ver si funcionó.