INSIGHT MOBILE — Guía de la Aplicación Android

Paso 00

Resumen del Proyecto

Qué es la app móvil de INSIGHT, qué incluye el paquete descargable y cómo se conecta con tu sistema web actual.

App Android nativa

React Native + Expo SDK 52 + TypeScript + NativeWind. 17 pantallas: POS con escáner, inventario, caja, SUNAT, dashboard.

API Go dedicada

insight_mobile_api (Gin + pgx): REST + SSE. Lee y escribe en la MISMA base de datos PostgreSQL db_kora del sistema web.

Tiempo real web ↔ móvil

PostgreSQL LISTEN/NOTIFY → broker Go (canaliza insight_dashboard_events) → SSE. Una venta desde el móvil actualiza la web al instante.

Offline + idempotente

Cola de ventas offline con reintento y client_request_id: sin duplicados al recuperar la conexión. JWT con refresh.

Qué contiene el archivo `mobile_insight.zip`

estructura del proyecto

mobile_kora/
├── app/                          # Expo Router — pantallas (rutas por archivo)
│   ├── _layout.tsx               # Raíz: providers, gate de autenticación
│   ├── (auth)/login.tsx          # Login (credenciales del sistema web)
│   ├── (tabs)/                   # Tabs inferiores: Inicio · Inventario · Ventas · Reportes
│   │   ├── _layout.tsx
│   │   └── index.tsx             # Home: saludo + accesos + módulos
│   ├── inventario/               # Productos · [id] · Categorías · Almacenes · Kardex
│   ├── ventas/                   # Nueva (POS) · Caja · Historial · [id] ·
│   │                             # Facturación SUNAT · Clientes
│   ├── reportes/dashboard.tsx    # Dashboard KPI en tiempo real (SSE)
│   └── +not-found.tsx
├── src/
│   ├── api/client.ts             # Cliente HTTP tipado (fetch + JWT)
│   ├── api/schema.d.ts           # Tipos TS 1:1 con openapi.yaml
│   ├── components/               # ListCard expandible, Pagination, KpiTile,
│   │   │                         # ScannerOverlay (cámara), PaymentEditor, charts/
│   ├── features/                 # Hooks TanStack Query por dominio
│   ├── hooks/                    # useSSE (tiempo real), useOfflineQueue, useAuth
│   ├── lib/                      # format (S/), constants (IGV 18%), uuid
│   └── store/                    # zustand: sesión + carrito POS
├── server/                       # kora_mobile_api — backend Go (Gin + pgx)
│   ├── cmd/api/main.go
│   ├── internal/                 # config · db · auth(JWT) · handlers ·
│   │                             # services · realtime(LISTEN/NOTIFY + SSE)
│   ├── migrations/30_mobile_client_request_id.sql
│   ├── Dockerfile
│   └── go.mod
├── infra/                        # docker-compose.mobile.yml · nginx · deploy
├── openapi.yaml                  # Contrato API único (Go + TS)
├── app.config.ts                 # com.sandaliaskora.app
├── eas.json                      # Perfiles build APK
└── package.json

app/ + src/

Aplicación Expo (UI móvil en español)

server/

Backend Go compilable (probado con go build + go vet)

infra/ + openapi.yaml

Despliegue Docker/nginx y contrato de API

La app usa las mismas credenciales y roles que el sistema web (tablacredentials), descuenta stock del almacén principal, valida caja abierta y respeta la regla IGV incluido en precios (INDECOPI).

Probador en vivo de la regla IGV

18% · INDECOPI

En INSIGHT los precios ya incluyen el IGV. Esta es exactamente la fórmula que aplica insight_mobile_api al grabar cada venta: elige un modo, escribe un monto y mira el desglose que saldrá en la BOLETA.

S/

Ejemplos:

base = total ÷ 1.18 · igv = total − base

Base imponible

S/ 0.00

IGV 18%

S/ 0.00

Total a pagar

S/ 0.00

Una venta de S/ 132.70 se graba como base S/ 112.46 + IGV S/ 20.24 — lo verás en el endpoint POST /sales del explorador de la API o, completa con carrito y pagos, en el .

Paso ★

Módulos de la App

Explora pantalla por pantalla lo que la app puede hacer. Cambia de pestaña para ver el detalle de cada módulo, sus funciones y los endpoints que consume.

POS — punto de venta con escáner

El corazón de la app: busca por descripción o dispara la cámara para escanear códigos EAN-13/EAN-8/UPC/Code128. Carrito con descuentos por línea, cliente (o «Cliente Varios»), comprobante BOLETA/FACTURA/TICKET, canal TIENDA/ONLINE y pagos divididos en varios métodos con cálculo de vuelto. Totales con IGV 18% incluido (norma INDECOPI).

Escáner de barras con linterna y overlay guía
Descuentos por línea + cliente + comprobante
Pagos múltiples con vuelto calculado
Cobro idempotente (client_request_id)
Comprobante PDF 80mm/A4 + WhatsApp al cliente
Cola offline: vende sin señal y sincroniza solo

Endpoints principales

POST /v1/salesGET /v1/products?per_page=10GET /v1/clients

Web vs Móvil — misma datos, más formas de trabajar

→ Desliza la tabla horizontalmente para ver las tres columnas.

Funcionalidad	Web	Móvil
Ventas POS	Sí	Sí, táctil + escáner
Escáner de código de barras	Lector USB (opcional)	Cámara del teléfono
Inventario + kardex	Sí	Sí, ListCards expandibles
Caja (apertura/cierre)	Sí	Sí, con esperado vs real
Facturación SUNAT	Sí (completa)	Envío + estado + reenvío
Comprobante por WhatsApp	Sí	Sí, desde el detalle
Dashboard KPI en vivo	Sí (SSE)	Sí (SSE + fallback polling)
Clientes CRUD	Sí	Sí, con validación DNI/RUC
Venta sin internet	—No	Sí — cola offline idempotente
Uso en piso de tienda	—Requiere PC	Bolsillo, listo en 1 toque

Mapa de pantallas de la app

Mapa de navegación de la app INSIGHT: login, tabs principales (Inicio, Inventario, Ventas, Reportes) y sus subpantallas — Mapa de navegación de las 17 pantallas de la app· pulsa para ampliar

Paso ★

Galería de Pantallas

Las pantallas clave de la app recreadas al detalle. Pulsa cualquier teléfono para ampliarlo, leer qué hace y ver qué endpoints consume.

Atajo de teclado: pulsagy luego1…6para abrir una pantalla directamente desde cualquier punto de la guía.

Productos — lista

Listado paginado de 10 en 10 con búsqueda por nombre y filtros por categoría. Cada producto es un ListCard expandible que despliega sus ejemplares (talla · color) con precio y stock por variante.

GET /v1/products?page=1&searc…GET /v1/products/{id}

Producto — detalle

La ficha del producto: foto/placeholder, categoría, precio con IGV desglosado y la tabla de ejemplares con SKU y stock por almacén. Desde aquí se salta directo a Vender (POS) o al Kardex del ejemplar.

GET /v1/products/{id}GET /v1/samples/{id}

Caja — apertura y movimientos

Estado de la caja del vendedor logueado: apertura con monto inicial, esperado vs real en tiempo real y el movimiento del día (ventas, ingresos y gastos). El cierre calcula la diferencia automáticamente.

GET /v1/cash/statusPOST /v1/cash/close

Historial de ventas

Todas las ventas con filtros por estado, canal y rango de fechas. El detalle muestra items, pagos múltiples y comprobante; desde ahí se puede anular (devuelve stock) o reenviar por WhatsApp/PDF.

GET /v1/sales?status=&channel=POST /v1/sales/{id}/void

Clientes

CRUD completo de clientes con búsqueda por nombre o documento. Valida DNI (8 dígitos) y RUC (11 dígitos). En el POS, si no eliges cliente se usa «Cliente General» (id 1), igual que el sistema web.

GET /v1/clients?search=POST /v1/clients

Kardex por ejemplar

El kardex clásico del calzado: entradas, salidas y saldo por ejemplar en un rango de fechas. Cada fila es un movimiento (compra, venta o ajuste) con su signo y el saldo va acumulándose.

GET /v1/kardex?id_sample=&fro…GET /v1/stock-movements

Paso 01

Descargar y Descomprimir el Proyecto

Obtén el .zip en tu PC con Windows y extráelo en una ruta simple.

1Pulsa el botón verde «Descargar Proyecto (.zip)» de esta página.
2Guarda mobile_insight.zip en tu Escritorio (o C:\Projects).
3Clic derecho sobre el zip → «Extraer todo…».
4Elige una ruta SIN espacios ni tildes, p. ej. C:\Projects\mobile_insight. Evita carpetas de OneDrive / iCloud.
5Dentro debes ver: app/, src/, server/, infra/, openapi.yaml, package.json.
6Descarga también la documentación Word (botón del pie de página) para el detalle técnico completo.

mobile_insight.zip

App Expo + API Go + infra + contrato OpenAPI

Descargar Proyecto (.zip)Documentación Word (.docx)

Paso 02

Instalar Prerrequisitos

Herramientas necesarias en tu PC para compilar la app Android. Solo se instalan una vez.

2.1Node.js 20 LTSinsight · guía

1Abre https://nodejs.org/ en tu navegador.
2Descarga la versión «LTS» (20.x o superior) — instalador .msi para Windows.
3Doble clic → Next → Next → Install (deja las opciones por defecto).
4Abre el Símbolo del sistema (tecla Win → escribe «cmd» → Enter).
5Verifica con el comando de la derecha.

Símbolo del sistema

node -v
npm -v
# Esperado: v20.x.x  y  10.x.x

2.2JDK 17 (Java)insight · guía

1Descarga Eclipse Temurin 17 (JDK) desde https://adoptium.net/temurin/releases/?version=17.
2Instala el .msi para Windows x64. Marca la opción «Set JAVA_HOME» si el instalador la ofrece.
3Reabre el Símbolo del sistema y verifica con el comando de la derecha.
4Si java no aparece: agrega C:\Program Files\Eclipse Adoptium\jdk-17.x\bin a la variable de entorno PATH.

Símbolo del sistema

java -version
# Esperado: openjdk version "17.x.x"

2.3Android Studio (SDK + emulador)insight · guía

1Descarga Android Studio desde https://developer.android.com/studio e instala con los valores por defecto.
2En el asistente inicial (o en Tools → SDK Manager) instala: Android SDK Platform 34, SDK Platform-Tools, Android Emulator y (recomendado) un system image API 34 x86_64.
3Crea un dispositivo virtual: Device Manager → «+» → Create Virtual Device → Pixel 7 → API 34 → Finish.
4Configura las variables de entorno ANDROID_HOME (comandos de la derecha).
5CIERRA y reabre el Símbolo del sistema tras ejecutar setx.

Símbolo del sistema

setx ANDROID_HOME "%LOCALAPPDATA%\Android\Sdk"
setx JAVA_HOME "C:\Program Files\Eclipse Adoptium\jdk-17.x.x-hotspot"
 
# IMPORTANTE: cierra y reabre la terminal después de estos comandos.
# Verificación:
adb --version

2.4Opcional: Go 1.22 (solo si correrás el backend en tu PC)insight · guía

1Solo necesitas Go si ejecutarás insight_mobile_api localmente (Paso 05). Para apuntar la app al servidor de producción este paso NO es necesario.
2Descarga el instalador desde https://go.dev/dl/ (go1.22.x.windows-amd64.msi) e instala con valores por defecto.
3Verifica con: go version (esperado: go version go1.22.x windows/amd64).

La app puede probarse apuntando directamente a https://kora.insight-platforms.com/v1 (producción). El backend local es útil para desarrollar sin depender del VPS.

Paso 03

Preparar el Proyecto

Instala las dependencias de la app y crea el archivo .env con la URL de la API.

1Abre una terminal en la carpeta del proyecto: Win + R → cmd → Enter, luego: cd C:\Projects\mobile_insight.
2Ejecuta npm install (tarda 1–3 min la primera vez; descarga ~600 MB en node_modules).
3Crea el archivo .env en la RAÍZ del proyecto con el contenido de la derecha.
4Si compilarás el APK para uso interno, agrega los iconos: assets/icon.png (1024×1024) y assets/splash.png — ver assets/README.md dentro del proyecto.
5Revisa que package.json tenga el script "start": "expo start".

mobile_insight/.env

# mobile_kora/.env  (crea este archivo con un editor de texto)
# Backend de producción (recomendado para probar la app real):
EXPO_PUBLIC_API_BASE=https://kora.insight-platforms.com/v1
 
# --- o, si ejecutas el backend Go en TU PC (ver paso 05) ---
# EXPO_PUBLIC_API_BASE=http://192.168.1.50:8090/v1
# (usa la IP local de tu PC, NO localhost, para que el teléfono llegue)

EXPO_PUBLIC_API_BASE se hornea DENTRO del APK al compilar. Si pruebas con el backend local, recuerda reconstruir el APK cuando cambies de local a producción.

Paso 04

El Backend Go (insight_mobile_api)

La app consume una API REST + SSE escrita en Go que opera sobre la misma base db_kora. Elige: usar producción o ejecutarlo local.

Opción A — Producción (recomendada)

Usa el servicio ya desplegado en el VPS:

EXPO_PUBLIC_API_BASE=https://kora.insight-platforms.com/v1

Requiere haber desplegado insight_mobile_api en el servidor (ver Paso 09 — Producción). Verifica con: curl https://kora.insight-platforms.com/v1/healthz

Opción B — Backend local

Ejecuta la API en tu PC conectada a la BD (local o del VPS por túnel SSH):

Instala Go 1.22 (paso 2.4)
Crea server/.env con DATABASE_URL + JWT_SECRET
go run ./cmd/api

mobile_insight/server/.env

# mobile_kora/server/.env  (copia de server/.env.example)
DATABASE_URL=postgres://postgres:TU_PASSWORD@localhost:5434/db_kora_v4
JWT_SECRET=genera_un_secreto_largo_aleatorio_aqui
LISTEN_CHANNEL=kora_dashboard_events
EVOLUTION_URL=http://localhost:8081
PORT=8090

Símbolo del sistema

cd mobile_kora/server
 
# 1) (Opcional) aplicar migración de idempotencia de ventas:
#    docker exec -i kora_postgres psql -U postgres -d db_kora_v4 \
#      < migrations/30_mobile_client_request_id.sql
 
# 2) Instalar dependencias y ejecutar:
go mod tidy
go run ./cmd/api
 
# Verificar (en otra terminal):
curl http://localhost:8090/healthz
# {"status":"ok","db":"ok","listen":"ok","version":"1.0.0"}

Para probar contra la BD de producción desde tu PC puedes abrir un túnel SSH: ssh -L 5434:127.0.0.1:5434 usuario@tu-vps y usar DATABASE_URL=postgres://…@localhost:5434/db_kora.

Paso 05

Ejecutar la App en Desarrollo

Con Expo no necesitas compilar para probar: recarga instantánea en tu teléfono o emulador.

1En la terminal, dentro de C:\Projects\mobile_insight, ejecuta el comando de la derecha.
2Se abre el «Metro Bundler» en http://localhost:8081 con un código QR.
3TELEFONO FÍSICO: instala «Expo Go» desde Play Store, ábrela y escanea el QR (mismo Wi-Fi que tu PC).
4EMULADOR: presiona la tecla «a» en la terminal para abrir la app en el emulador de Android Studio.
5La app abre en la pantalla de Login. Ingresa con las MISMAS credenciales del sistema web INSIGHT.
6Cualquier cambio en el código se refleja al instante (Fast Refresh).

Símbolo del sistema

cd mobile_kora
npm install
 
npx expo start
 
# Terminal interactivo:
#   presiona  a  → abre en el emulador de Android Studio
#   presiona  w  → abre en el navegador (modo web)
#   escanea el QR con la app "Expo Go" (instálala de Play Store)

Emulador → backend local

# Si la app del emulador no alcanza tu backend local:
adb reverse tcp:8090 tcp:8090
# Ahora http://localhost:8090/v1 funciona DENTRO del emulador

Si el teléfono no está en la misma red que el PC, usa modo túnel: npx expo start --tunnel (instala ngrok automáticamente).

Paso 06

Generar el APK Instalable

Dos caminos: EAS Build (en la nube de Expo, el más fácil) o compilación local con Gradle (sin cuenta).

6.1Camino A — EAS Build (nube de Expo)insight · guía

1Crea una cuenta gratuita en https://expo.dev/signup.
2Asegúrate de haber agregado assets/icon.png y assets/splash.png (el build falla sin icono).
3Ejecuta los comandos de la derecha dentro de la carpeta del proyecto.
4EAS compila en la nube (15–30 min). Al terminar imprime un enlace de descarga del .apk.
5Descarga el .apk desde ese enlace en tu teléfono (o PC y pásalo por USB).

Símbolo del sistema

cd mobile_kora
npm install -g eas-cli
 
eas login                      # cuenta gratuita en expo.dev
eas build:configure            # genera eas.json (ya incluido)
 
# Construcción del APK en la nube de Expo (15–30 min aprox.):
eas build -p android --profile preview
# Al terminar, EAS imprime un enlace https://expo.dev/artifacts/...
# descarga ahí el archivo .apk e instálalo en el teléfono

6.2Camino B — Compilación local con Gradleinsight · guía

1Requisitos: JDK 17 y ANDROID_HOME configurados (pasos 2.2 y 2.3).
2Ejecuta los comandos de la derecha. La primera compilación tarda 10–25 min (descarga dependencias Gradle).
3El APK queda en android/app/build/outputs/apk/release/app-release.apk.
4Si aparece error de firma, usa assembleDebug (APK de depuración, válido para uso interno) o genera un keystore.

Símbolo del sistema

cd mobile_kora
npm install
 
# Genera el proyecto nativo android/ (Gradle):
npx expo prebuild -p android
 
# Compilar el APK de producción localmente (requiere JDK 17 + SDK):
cd android
./gradlew assembleRelease          # Windows: gradlew.bat assembleRelease
 
# APK resultante:
#   android/app/build/outputs/apk/release/app-release.apk
 
# Alternativa en un solo comando:
# npx expo run:android --variant release

Para publicar en Play Store necesitas firmar con un keystore propio (keytool -genkey -v -keystore insight.keystore) y configurarlo en android/app/build.gradle. Para distribución interna (WhatsApp/enlace) el APK sin firma es suficiente.

6.3Apuntar el APK a produccióninsight · guía

Antes de compilar el APK definitivo, fija la URL de producción en el .env (o crea .env.production):

mobile_insight/.env

EXPO_PUBLIC_API_BASE=https://kora.insight-platforms.com/v1

Paso 07

Instalar y Probar el APK

En el emulador o en tu teléfono físico.

7.1Emulador de Android Studioinsight · guía

1Abre Android Studio → Device Manager (icono de teléfono arriba a la derecha) → ▶ para lanzar el emulador.
2Arrastra el archivo .apk desde el Explorador de Windows directamente sobre la ventana del emulador.
3Aparece «App installed». Desliza hacia arriba en el emulador y busca la app «INSIGHT» (icono ámbar).
4Alternativa por terminal: adb install app-release.apk.

Símbolo del sistema

adb install android/app/build/outputs/apk/release/app-release.apk

7.2Teléfono físicoinsight · guía

1Pasa el .apk al teléfono (USB, WhatsApp a ti mismo, o descarga directa desde el enlace de EAS).
2Toca el archivo .apk → si pide permiso, habilita «Instalar apps desconocidas» para tu navegador/administrador de archivos.
3Instala → abre «INSIGHT» → acepta el permiso de Cámara (se usa para el escáner de códigos de barras).
4Inicia sesión con tu usuario del sistema web.
5PRUEBA CLAVE: Inicio → Ventas → Nueva Venta → pulsa «Cod. Barras» → escanea un EAN-13 de una etiqueta INSIGHT → el ejemplar se carga con su stock.

7.3Ver logs de la app (opcional)insight · guía

Símbolo del sistema

adb logcat -s ReactNativeJS Expo
# Ver peticiones y errores JS de la app en tiempo real

Paso 08

Puesta en Producción (VPS Hostinger Ubuntu)

Despliega insight_mobile_api junto al stack actual de Docker: mismo dominio, mismo certificado SSL, misma base de datos.

1Sube la carpeta mobile_insight/ al VPS (scp -r mobile_insight usuario@tu-vps:/opt/insight/ o git clone).
2Agrega INSIGHT_MOBILE_JWT_SECRET (y opcionalmente INSIGHT_WEB_API_URL/TOKEN) al .env de producción.
3Aplica la migración 30 (columna client_request_id para idempotencia de ventas).
4Levanta el servicio con el overlay de docker compose incluido.
5Inserta el bloque /v1/ de nginx y recarga la configuración.
6Ejecuta las pruebas de humo (healthz + login) y verifica el LISTEN en los logs.
7Todo lo anterior automatizado: bash mobile_insight/infra/scripts/deploy_mobile.sh

SSH — terminal del VPS

# ===== En el VPS Hostinger (SSH) =====
 
# 1) Sube la carpeta mobile_kora/ al servidor (scp o git), por ejemplo a /opt/kora
 
# 2) Agrega las variables móviles al .env de producción:
cat /opt/kora/mobile_kora/infra/envs/.env.mobile.example >> ~/kora/infra_kora/envs/.env
nano ~/kora/infra_kora/envs/.env      # ajusta KORA_MOBILE_JWT_SECRET (openssl rand -hex 32)
 
# 3) Migración de idempotencia:
docker exec -i kora_postgres psql -U postgres -d db_kora_v4 \
  < /opt/kora/mobile_kora/server/migrations/30_mobile_client_request_id.sql
 
# 4) Levanta el servicio kora_mobile_api (overlay sobre el compose existente):
cd ~/kora/infra_kora/deploy_kora
docker compose -f docker-compose.yml \
  -f /opt/kora/mobile_kora/infra/docker-compose.mobile.yml \
  up -d --build kora_mobile_api
 
# 5) nginx: inserta el bloque /v1/ en ~/nginx/conf/default.conf
#    (usa el snippet mobile_kora/infra/nginx/kora-mobile.conf) y recarga:
docker exec nginx_proxy nginx -s reload
 
# 6) Pruebas de humo:
curl https://kora.insight-platforms.com/v1/healthz
docker logs kora_mobile_api 2>&1 | grep -i "LISTEN"
#   → "LISTEN established on kora_dashboard_events"
 
# --- o simplemente ejecuta el script incluido ---
# bash /opt/kora/mobile_kora/infra/scripts/deploy_mobile.sh

Misma BD

insight_mobile_api se une a insight_network y consulta kora_postgres directamente

Mismo dominio

https://kora.insight-platforms.com/v1 con el SSL Let's Encrypt existente

Sin secretos en el APK

JWT + HTTPS; credenciales solo en el .env del servidor

El canal SSE (/v1/stream) exige proxy_buffering off en nginx — el snippet incluido (mobile_insight/infra/nginx/insight-mobile.conf) ya lo configura. Sin eso el dashboard en vivo no refresca.

Paso 09

Verificación Web ↔ Móvil en Tiempo Real

La prueba cruzada que confirma que ambos sistemas comparten la misma fuente de verdad.

1En el PC abre el dashboard web: https://kora.insight-platforms.com/dashboard.
2En el teléfono abre la app → pestaña «Reportes» → Dashboard KPI (verás el punto verde «En vivo»).
3En la MÓVIL: Ventas → Nueva Venta → agrega un producto de prueba → COBRAR.
4Mira las DOS pantallas: KPIs y gráficos se actualizan en ambas al instante (≤ 1 s).
5El camino del dato: venta → PostgreSQL (trigger pg_notify insight_dashboard_events) → broker Go (400 ms) → SSE → web y app invalidan y recargan.
6Verifica también el stock: Inventario → el current_stock del ejemplar bajó en ambas vistas.
7Anula la venta de prueba (Historial → detalle → Anular) para dejar la BD limpia: el stock se devuelve automáticamente.

¿Cómo funciona?

1La app envía POST /v1/sales al API Go (JWT).

2Go valida caja abierta + stock y escribe SALE + DETALLE + PAGOS + MOVIMIENTOS en UNA transacción.

3Los triggers de la migración 27 emiten pg_notify al canal insight_dashboard_events.

4El listener Go Y el broker web reciben el evento, coalescen 400 ms y lo emiten por SSE.

5App móvil y navegador invalidan sus queries y refrescan KPIs — mismos datos, mismo segundo.

Paso ★

Arquitectura y Estructura del Código

Cómo se organiza el ecosistema: app, API Go, base de datos y servicios externos.

diagrama del ecosistema

Navegador (web Gentelella)      App Android (mobile_insight)
        │ HTTPS                            │ HTTPS REST + SSE
        ▼                                  ▼
   nginx (SSL, kora.insight-platforms.com) ── /v1/ ──► insight_mobile_api (Go, puerto 8080)
        │                                             │
        ▼                                             ▼
   kora_app (Flask + Gunicorn)                 pgx pool ──┐
        │                                             │    │
        └────────────► kora_postgres (db_kora) ◄───┘    │ LISTEN insight_dashboard_events
                    triggers pg_notify ────────────────────┘
        │
        ├──► Evolution API (WhatsApp) ◄── también usada por Go (whatsapp_config)
        └──► SUNAT (facturación electrónica, reutilizada vía sunat_config)

Diagrama de arquitectura del ecosistema INSIGHT: navegador web, app Android, nginx, insight_app Flask, insight_mobile_api Go, PostgreSQL, Evolution API y SUNAT — Arquitectura del ecosistema INSIGHT (misma base de datos, dos clientes)· pulsa para ampliar

Explora el código antes de descomprimir

Cada archivo y carpeta del zip con su propósito. En la impresión el árbol sale completo y anotado.

25Explorador del proyecto

pulsa un archivo para ver su propósito

Selecciona un archivo o carpeta del árbol para leer qué hace dentro del proyecto.

Módulos implementados en la app

🏠 Home — saludo, accesos rápidos, descripción de módulos
📦 Inventario — Productos + ejemplares, Categorías/Marcas/Tallas/Colores/Géneros (CRUD), Almacenes + stock + movimientos, Kardex con saldo
🛒 Ventas — POS con escáner EAN-13/8/UPC/Code128, carrito, cliente, BOLETA/FACTURA/TICKET, pagos múltiples + vuelto; Caja (abrir/cerrar); Historial + detalle + Anular; Facturación SUNAT + WhatsApp; Clientes CRUD
📊 Reportes — Dashboard KPI en vivo: 8 tiles, vistas Mensual/Semanal/Semestral/Diaria, gastos por categoría, métodos de pago, canales

Patrones de UX móvil

🗂️ ListCard expandible: lista compacta (2–3 datos + badge) → al pulsar se despliega el detalle completo con acciones (efecto drop-down animado)
📄 Paginación de 10 en TODAS las listas (◀ Página i de N ▶)
⬇️ Pull-to-refresh, esqueletos de carga, estados vacíos y de error con reintento
📴 Modo offline: cola de ventas con reintento idempotente al recuperar red
🔴 SSE: indicador «En vivo», reconexión con backoff, resync por hueco de secuencia

Paso ★

Explorador de la API REST

Los 43 endpoints de insight_mobile_api agrupados por módulo. Busca, filtra por método y copia el curl listo para probar.

Base:https://kora.insight-platforms.com/v1·http://localhost:8090/v143/43 endpoints

3Autenticación

9Catálogos

9Inventario

6Ventas POS

5Caja

5Clientes

3Facturación SUNAT

2Dashboard & Tiempo real

1Operación

Pulsa una fila para ver el detalle y el curl listo para probar · El icono copia METHOD ruta · «Probar» muestra una respuesta de ejemplo.

Las respuestas simuladas usan el envelope real de la API — éxito: { "data": … } · error: {…

Paso ⌘

Chuleta de Comandos

Todos los comandos de la guía en una sola vista, agrupados por fase. Filtra por palabra clave, copia un bloque concreto o llévatelos todos de golpe.

6 bloques · 22 comandos listos para copiar y pegar en tu terminal — pulsa el icono de cada línea, o Ctrl+K para buscar uno concreto.

Preparar el proyecto

Instalar dependencias de la app

2 cmds

preparar el proyecto

cd C:\Projects\mobile_kora

npm install

Backend Go local

Levantar kora_mobile_api en tu PC

4 cmds

backend go local

cd mobile_kora/server

go mod tidy

go run ./cmd/api

curl http://localhost:8090/healthz

Ejecutar la app (Expo)

Desarrollo con recarga instantánea

3 cmds

ejecutar la app (expo)

cd mobile_kora

npx expo start

# teléfono en otra red → npx expo start --tunnel

# emulador → backend local:

adb reverse tcp:8090 tcp:8090

Compilar el APK

EAS (nube) o Gradle (local)

4 cmds

compilar el apk

eas build -p android --profile preview

# o local:

npx expo prebuild -p android

cd android

gradlew.bat assembleRelease

Producción (VPS)

Desplegar junto al stack actual

4 cmds

producción (vps)

docker compose -f docker-compose.yml

-f /opt/kora/mobile_kora/infra/docker-compose.mobile.yml

up -d --build kora_mobile_api

docker exec nginx_proxy nginx -s reload

curl https://kora.insight-platforms.com/v1/healthz

docker logs kora_mobile_api 2>&1 | grep -i LISTEN

Diagnóstico

Cuando algo no funciona

5 cmds

diagnóstico

node -v && npm -v

java -version

adb --version

adb logcat -s ReactNativeJS Expo

npx expo start -c

Los comandos asumen la ruta C:\Projects\mobile_insight y el VPS accesible por SSH. El script deploy_mobile.sh incluido en el proyecto ejecuta el bloque de producción completo de una sola vez.

Paso ?

Preguntas Frecuentes

Las dudas más comunes al adoptar la app móvil, respondidas en lenguaje llano.

¿No encuentras tu duda? La documentación Word incluida en la descarga contiene el detalle técnico completo, y la sección de Problemas cubre errores concretos de instalación y compilación.

Paso Aa

Infraestructura

Servicio de DNS dinámico gratuito usado por varios dominios del ecosistema (*.duckdns.org). El dominio principal de producción es kora.insight-platforms.com (DNS gestionado por Insight Platforms), con certificado HTTPS gestionado por el proxy.

Cada término enlaza con la sección donde se usa en la práctica. Si buscas la definición de un comando concreto, recuerda que el buscador global ⌘K también indexa el glosario completo.

Paso →

Hoja de Ruta

Lo que ya está entregado y las mejoras planificadas para las próximas versiones de la app.

v1.0Entregado disponible en el zip
Ecosistema móvil completo
- POS con escáner + inventario + caja
- Historial, SUNAT, WhatsApp, PDF
- Dashboard KPI en vivo (SSE)
- Cola offline idempotente
v1.1
v1.1Próximo
Notificaciones push
- FCM: stock bajo por ejemplar
- Alerta de cierre de caja pendiente
- Resumen diario de ventas al gerente
v1.2
v1.2Planificado
Modo oscuro + reportes exportables
- Tema oscuro NativeWind en toda la app
- Exportar reportes a Excel/CSV desde el móvil
- Filtro por vendedor en historial
v1.3
v1.3Planificado
Catálogo offline total
- Descarga incremental de productos a SQLite
- Creación de clientes offline
- Sincronización diferencial por timestamp
v2.0
v2.0Visión
Multi-tienda y biometría
- Selector de sede/almacén al iniciar
- Login con huella / rostro
- Roles granulares por pantalla

La arquitectura ya contempla estas extensiones: el contrato openapi.yaml y el API Go están listos para sumar notificaciones push y sincronización offline avanzada sin reescribir el cliente.

Paso !

Problemas Comunes y Soluciones

Si algo falla, revisa aquí primero.

"npx: command not found" o "expo" no arranca

Node no está en PATH. Reinstala Node 20 LTS (paso 2.1) o reabre la terminal. Verifica con node -v.

Metro se queda cargando / pantallas blancas

Limpia la caché del bundler: npx expo start -c. Si persiste, borra node_modules y .expo y repite npm install.

Gradle: «SDK location not found»

ANDROID_HOME no está definido. Repite el paso 2.3 (setx ANDROID_HOME ...) y REABRE la terminal antes de ./gradlew.

Gradle: error de versión de Java

Necesitas JDK 17 exactamente. java -version debe decir 17.x. Revisa JAVA_HOME (paso 2.2).

La app (emulador) no conecta con el backend local

El localhost del emulador no es tu PC. Usa adb reverse tcp:8090 tcp:8090 y EXPO_PUBLIC_API_BASE=http://localhost:8090/v1.

Expo Go del teléfono no abre la app (otra red)

Usa el modo túnel: npx expo start --tunnel. También revisa el firewall de Windows (permitir Node).

Login rechazado (401)

Usa el usuario/contraseña del sistema web (tabla credentials). Si el backend es local, confirma que DATABASE_URL apunta a la BD correcta.

Dashboard no se actualiza «En vivo»

1) ¿El log de insight_mobile_api muestra LISTEN established? 2) nginx debe tener proxy_buffering off en /v1/ (usa el snippet incluido). 3) Si el teléfono pierde el SSE, la app cae a polling 10 s.

EAS build falla por icono

Agrega assets/icon.png (1024×1024) y assets/splash.png antes de construir; se declaran en app.config.ts.

«Stock insuficiente» al vender

Regla del sistema: el current_stock del ejemplar debe cubrir la cantidad. Verifica en Inventario → producto → ejemplar. La venta exige caja abierta (Ventas → Caja).

Aplicación Móvil Android de INSIGHT

Tu progreso de instalación

Resumen del Proyecto

App Android nativa

API Go dedicada

Tiempo real web ↔ móvil

Offline + idempotente

Qué contiene el archivo mobile_insight.zip

Probador en vivo de la regla IGV

Módulos de la App

POS — punto de venta con escáner

Web vs Móvil — misma datos, más formas de trabajar

Mapa de pantallas de la app

Galería de Pantallas

Simulador de Venta

Simulador del Punto de Venta

Descargar y Descomprimir el Proyecto

Instalar Prerrequisitos

Preparar el Proyecto

El Backend Go (insight_mobile_api)

Ejecutar la App en Desarrollo

Generar el APK Instalable

Instalar y Probar el APK

Puesta en Producción (VPS Hostinger Ubuntu)

Verificación Web ↔ Móvil en Tiempo Real

¿Cómo funciona?

Arquitectura y Estructura del Código

Explora el código antes de descomprimir

Módulos implementados en la app

Patrones de UX móvil

Explorador de la API REST

Chuleta de Comandos

Preguntas Frecuentes

1¿Necesito modificar mi sistema web actual?

2¿La app crea una base de datos aparte?

3¿Qué credenciales usa la app para iniciar sesión?

4¿Puedo probarla sin compilar el APK?

5¿Cuánto cuesta compilar el APK?

6¿Funciona sin internet?

7¿El escáner funciona en cualquier teléfono?

8¿Se puede llevar a iOS?

9¿Se emiten boletas a SUNAT desde el móvil?

10¿Cómo actualizo la app cuando cambie?

11¿Es seguro? ¿Dónde quedan las contraseñas?

12¿Puedo usar el emulador sin teléfono Android?

Glosario del Proyecto

IGV

BOLETA

FACTURA

SUNAT

Kardex

Idempotencia

Ejemplar

Caja

Cliente General

SSE

LISTEN/NOTIFY

Coalescing

JWT

Gin

pgx

Transacción ACID

OpenAPI

EAN-13

/healthz

Migración 30

Expo

Expo Router

EAS Build

APK

AAB

Metro

prebuild

adb reverse

NativeWind

TanStack Query

Zustand

Tunnel

Docker Compose

nginx (proxy inverso)

Qué contiene el archivo `mobile_insight.zip`