Profesional
StarHub | Gestión de bodega
Recepción de contenedores línea por línea, con la posición de cada tarima y foto de la mercancía dañada. Lee el ERP por SQL y escribe solo por su API.
- Full Stack
- Móvil
- Organización
- Star Cargo Service
- Rol
- API y capa de seguridad
- Periodo
- 2026-08 — Actualidad
Stack
- TypeScript
- Node.js
- MySQL
- Google Cloud Run
- Docker
- Kotlin
Contexto
El bodeguero registra la recepción de un contenedor desde el teléfono. Escanea el código del recibo, anota cada línea que descarga, indica la posición de cada tarima y fotografía la mercancía dañada.
Este servicio es el backend de esa app Android. El cliente Android lo llevó otra persona del equipo, con aportes míos.
Problema
El registro de recepción se hacía en papel y alguien lo transcribía al ERP después. Hasta que esa transcripción ocurría, el inventario del sistema no correspondía con lo que había en bodega.
El servicio existe para que la recepción entre al ERP en el momento en que el bodeguero la anota.
Decisiones técnicas
El ERP genera los números de recibo con fórmulas propias que no toman bloqueo. Dos bodegueros trabajando a la vez habrían recibido el mismo consecutivo. También tiene notificaciones y acciones automáticas sobre esas tablas, que un INSERT directo no habría disparado.
Las lecturas van por SQL directo contra la base del ERP. Las escrituras van por su API, que es más lento pero respeta esas fórmulas y esos disparadores.
Ninguna ruta del servicio escribe por SQL. Todas las escrituras salen por un único cliente del API, que es el solo punto del código que las emite.
Arquitectura
Un teléfono no puede autenticarse con la identidad de la plataforma, porque el alta ocurre antes de que el aparato tenga credencial alguna. Esa es la compuerta del servicio: un solo endpoint público, con cuatro reglas aplicadas a la vez.
El alta usa un código que caduca y se liga al identificador del dispositivo. El registro guarda su hash, nunca el valor, y el código no vuelve a servir después del primer uso.
El endpoint de alta es público, así que está acotado por origen y por dispositivo. Un intento repetido de adivinar el código se detiene antes de recorrer el espacio de posibilidades.
El token da lectura por SQL y escritura solo a través del API del ERP. En la superficie del servicio no existe una operación de escritura directa contra la base.
Cada consulta se limita a la bodega del dispositivo enrolado. Un teléfono dado de alta en una bodega no alcanza el inventario de otra.
El registro de altas vive en el propio proceso, así que el servicio se despliega en una sola instancia.
Resultado
La recepción entra al ERP en el momento en que el bodeguero la anota, con sus líneas, la posición de cada tarima y las fotos de la mercancía dañada.
Una prueba de humo arranca el servidor y le hace peticiones reales. Cubre TLS, credenciales, filtrado por bodega, consulta y mapeo de la respuesta. No usa dobles de prueba ni escribe datos.
Junto a ella hay 30 casos de node:test sobre paginación y sobre el ciclo de vida de los dispositivos.
Lo que aprendí
El estado de enrolamiento quedó dentro del proceso, así que el servicio no admite una segunda instancia hasta moverlo a almacenamiento compartido. Ese traslado está anotado como el siguiente cambio.