Herramientas de usuario

Herramientas del sitio


ada:howto:sicoferp:factory:new-migracion-sicoferp:machine

Diferencias

Muestra las diferencias entre dos versiones de la página.

Enlace a la vista de comparación

Próxima revisión
Revisión previa
ada:howto:sicoferp:factory:new-migracion-sicoferp:machine [2026/04/07 19:37]
10.1.61.45 creado
ada:howto:sicoferp:factory:new-migracion-sicoferp:machine [2026/05/07 20:09] (actual)
192.168.175.130
Línea 1: Línea 1:
-====== ​Documentación del Proyecto ​PAE ======+====== ​Índice de documentación de PAE ======
  
-===== Propósito ​=====+===== Qué es este repo =====
  
-Este directorio contiene documentación técnica y arquitectónica del proyecto ​PAE (Plataforma de Análisis de Entregas), incluyendo guías de desarrollo, arquitectura sistema, patrones de diseño, deployment y troubleshooting.+PAE es un monorepo Android multi-módulo con dos aplicaciones coordinadas:​
  
-===== Tabla de contenidos rápida =====+  * ''​Machine'':​ ejecuta entregas en campo con validaciones ​de peso, evidencia por cámara, verificación facial y persistencia local. 
 +  * ''​RutaPAE'':​ coordina operación de ruta, visibilidad de máquinas, integración P2P y soporte de sincronización con backend.
  
-^ Pregunta ^ Documento ^ +Objetivo principal: mantener ​una operación confiable y auditable bajo conectividad intermitente y variabilidad ​de hardware.
-| Tengo una pregunta rápida | [[faq|faq.md]] | +
-| ¿Por dónde empiezo? | [[#​nuevos_desarrolladores|newdev]] | +
-| ¿Cómo funciona la arquitectura?​ | [[architecture|architecture.md]] | +
-| ¿Cuál es el flujo de entrega? | [[delivery-service-flow|delivery-service-flow.md]] | +
-| ¿Cómo funciona Machine online/​offline?​ | [[machine-online-offline|machine-online-offline.md]] | +
-| ¿Cómo compilo y depliego? | [[build-and-deployment|build-and-deployment.md]] | +
-| ¿Tiene solución mi error? | [[troubleshooting|troubleshooting.md]] | +
-| ¿Cómo hago tests? | [[testing-guide|testing-guide.md]] | +
-| ¿Cuáles son las APIs disponibles?​ | [[api-reference|api-reference.md]] | +
-| ¿Qué significa este término? | [[glossary|glossary.md]] |+
  
-===== Estructura de documentos (23 archivos) ​=====+===== Stack =====
  
-==== Fundamentals ​(4 archivos==== +  * Android + Kotlin + Gradle ​(KTS
-  * [[overview|overview.md]] - Visión general, módulos, flujos principales +  * Jetpack Compose 
-  * [[architecture|architecture.md]] - Estructura modular, 3 capas, dependencias +  * Coroutines + WorkManager 
-  * [[layers|layers.md]] - Responsabilidades de cada capa +  * CameraX + ML Kit + ONNX Runtime 
-  * [[module-interactions|module-interactions.md]] - Grafo de dependenciascasos de uso+  * Persistencia local basada en SQLite (+ capacidades vectoriales en ''​VectorialDB''​) 
 +  * Comunicación P2P guiada por contrato (''​Contract''​''​DirectLink''​) 
 +  * Servicios ​de sincronización HTTP (''​MachineDomain'',​ ''​RutaPAEDomain''​)
  
-==== Arquitectura y Diseño (4 archivos) ​==== +===== Ambientes =====
-  * [[patterns|patterns.md]] - Patrones de diseño, convenciones,​ SOLID +
-  * [[adr-architecture-decisions|adr-architecture-decisions.md]] - 13 decisiones arquitectónicas con justificación +
-  * [[best-practices|best-practices.md]] - Convenciones de código, patterns vs anti-patterns,​ quality gates +
-  * [[module-interactions|module-interactions.md]] - Flujos de datos, casos de uso, error handling+
  
-==== Configuración e Instalación (3 archivos) ==== +  ​''​development''​ 
-  ​[[environment-setup|environment-setup.md]] - JDK 17, Android Studio, SDK, emulator, ADB +  * ''​qa''​ 
-  * [[dependencies|dependencies.md]] - Gestión de versiones, matriz de librerías, conflictos +  * ''​production''​ (actualmente mapeado a dominio preproductivo en la configuración vigente)
-  * [[build-and-deployment|build-and-deployment.md]] - Gradle, signing, ProGuard/​R8,​ CI/CD, release APKs+
  
-==== Desarrollo (4 archivos) ==== +La selección de host/​ambiente se define por configuración de runtime y variables de build.
-  * [[developer-guide|developer-guide.md]] - APIs clave, componentes,​ tareas comunes +
-  * [[testing-guide|testing-guide.md]] - Test pyramid, JUnit 4, Mockito, Espresso, fixtures, coverage +
-  * [[api-reference|api-reference.md]] - APIs públicas con tipo signatures +
-  * [[glossary|glossary.md]] - Glosario técnico, siglas, acrónimos PAE+
  
-==== Funcionalidad específica (5 archivos) ​==== +===== Mapa de documentación =====
-  * [[delivery-service-flow|delivery-service-flow.md]] - StateManager con 8 estados +
-  * [[p2p-architecture|p2p-architecture.md]] - P2P contracts, models, P2PGestor +
-  * [[p2p-flow|p2p-flow.md]] - Workflows P2P con diagramas Mermaid +
-  * [[local-storage|local-storage.md]] - SQLite, VectorDB, persistencia +
-  * [[machine-online-offline|machine-online-offline.md]] - Funcionamiento online/​offline de Machine+
  
-==== Seguridad y Operaciones (2 archivos) ​==== +==== ''​arquitectura/'' ​====
-  * [[security-and-privacy|security-and-privacy.md]] - Permisos, encriptación,​ HTTPS, GDPR, compliance +
-  * [[hardware-integration|hardware-integration.md]] - Camera2, Bluetooth scale, GPIO LED, mocking+
  
-==== Soporte y Referencia (1 archivo) ==== +  ​* [[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​arquitectura:​vision-general|Vision General]] 
-  ​* [[troubleshooting|troubleshooting.md]] - 20+ errores comunes ​soluciones +  * [[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​arquitectura:​capas-y-modulos|Capas Y Modulos]] 
-  * [[faq|faq.md]] - Preguntas frecuentes por tema (¡Ver primero!)+  * [[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​arquitectura:​ciclo-de-vida-de-datos|Ciclo De Vida De Datos]]
  
-===== Rutas de aprendizaje por rol =====+==== ''​dispositivos/'' ​====
  
-==== 🆕 Nuevos Desarrolladores ==== +  * [[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​dispositivos:​bascula|Bascula]] 
-Entender proyecto en 1-2 horas: +  ​[[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​dispositivos:​camara|Camara]]
-  - [[overview|overview.md]] ​El qué y por qué (15 min) +
-  ​[[architecture|architecture.md]] - Estructura general (20 min) +
-  ​[[layers|layers.md]] ​Cómo se comunican (15 min) +
-  ​[[environment-setup|environment-setup.md]] - Instalar todo (30 min) +
-  - [[developer-guide|developer-guide.md]] - Componentes clave (20 min) +
-  - [[build-and-deployment|build-and-deployment.md]] - Primer build (15 min) +
-  - [[faq|faq.md]] - Preguntas rápidas (según necesidad)+
  
-→ Profundizar:​ [[best-practices|best-practices.md]] → [[patterns|patterns.md]]+==== ''​operacion-sin-conexion/''​ ====
  
-==== 🏛️ Arquitectos de Software ==== +  * [[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​operacion-sin-conexion:​estados-de-maquina|Estados De Maquina]] 
-Entender decisiones y trade-offs:​ +  ​[[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​operacion-sin-conexion:​arquitectura-p2p|Arquitectura P2p]] 
-  - [[adr-architecture-decisions|adr-architecture-decisions.md]] ​Las decisiones (30 min) +  ​[[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​operacion-sin-conexion:​estrategia-de-sincronizacion|Estrategia De Sincronizacion]]
-  ​[[architecture|architecture.md]] - Cómo se conecta todo (20 min) +
-  ​[[module-interactions|module-interactions.md]] ​Flujos de datos (20 min) +
-  ​[[patterns|patterns.md]] - Qué patterns usamos (15 min) +
-  ​[[layers|layers.md]] - Boundaries entre capas (15 min)+
  
-→ Profundizar:​ [[p2p-architecture|p2p-architecture.md]] → [[security-and-privacy|security-and-privacy.md]]+==== ''​flujos-clave/''​ ====
  
-==== 💻 Feature Developers ==== +  * [[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​flujos-clave:​flujo-de-entrega|Flujo De Entrega]] 
-Implementar funcionalidades nuevas: +  ​[[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​flujos-clave:​flujo-de-generacion-de-embedding|Flujo De Generacion De Embedding]] 
-  - [[developer-guide|developer-guide.md]] - APIs disponibles (20 min) +  ​[[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​flujos-clave:​flujo-del-gestor-de-estados|Flujo Del Gestor De Estados]] 
-  ​[[best-practices|best-practices.md]] - Cómo escribir código (20 min) +  ​[[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​flujos-clave:​ciclo-de-vida-de-jornada|Ciclo De Vida De Jornada]] 
-  ​[[patterns|patterns.md]] - Patterns a usar (15 min) +  ​[[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​flujos-clave:​flujo-de-sincronizacion-http|Flujo De Sincronizacion Http]] 
-  ​[[api-reference|api-reference.md]] ​Firmas ​de API específicas (15 min) +  ​[[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​flujos-clave:​filtrado-de-jornadas-en-shift-selection|Filtrado De Jornadas En Shift Selection]]
-  ​[[testing-guide|testing-guide.md]] - Escribir tests (20 min) +
-  ​[[faq|faq.md]] - Problemas rápidos (según necesidad)+
  
-→ Si trabajas con entregas: [[delivery-service-flow|delivery-service-flow.md]] +==== ''​api/''​ ====
-→ Si usas P2P: [[p2p-flow|p2p-flow.md]]+
  
-==== ⚙️ DevOps / Build Engineers ==== +  * [[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​api:​puntos-finales|Puntos Finales]] 
-Deployment, CI/CD, versionado:​ +  ​[[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​api:​contratos-p2p|Contratos P2p]] 
-  - [[build-and-deployment|build-and-deployment.md]] - Compilation,​ signing, release (30 min) +  ​[[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​api:​modelo-de-errores|Modelo De Errores]]
-  ​[[dependencies|dependencies.md]] ​Versiones, conflictos, transitividad (20 min) +
-  ​[[environment-setup|environment-setup.md]] - Build environment (20 min) +
-  ​[[troubleshooting|troubleshooting.md]] ​Build failures (20 min) +
-  ​[[faq|faq.md]] - "How to compile?"​ (según necesidad)+
  
-==== 🧪 QA Testing ​==== +==== ''​decisiones/'' ​====
-Testing strategy y coverage: +
-  - [[testing-guide|testing-guide.md]] - Test pyramid, fixtures, mocking (40 min) +
-  - [[best-practices|best-practices.md]] - Code review checklist (20 min) +
-  - [[api-reference|api-reference.md]] - APIs to mock (20 min) +
-  - [[troubleshooting|troubleshooting.md]] - Common test failures (15 min) +
-  - [[faq|faq.md]] - Test help (según necesidad)+
  
-----+  * [[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​decisiones:​adr-0001-secuencia-del-gestor-de-estados|Adr 0001 Secuencia Del Gestor De Estados]] 
 +  * [[ada:​howto:​sicoferp:​factory:​new-migracion-sicoferp:​machine:​decisiones:​adr-0002-persistencia-primero-local|Adr 0002 Persistencia Primero Local]]
  
-===== Índice alfabético ​de archivos ​=====+===== Fuentes ​de verdad ​=====
  
-==== A-D ==== +  ​''​settings.gradle.kts''​ para límites y composición de módulos
-  ​**[[adr-architecture-decisions|adr-architecture-decisions.md]]** - ADRs: decisiones arquitectónicas justificadas (13 records) +  * ''​gradle/​libs.versions.toml''​ para versiones ​de dependencias. 
-  * **[[api-reference|api-reference.md]]** - APIs públicas: StateManager,​ P2PManager, Services, Hardware +  * ''​MachineDomain/​src/​main/​java/​co/​ada/​domain/​DomainManager.kt''​ para armado del flujo y estados. 
-  * **[[architecture|architecture.md]]** - Estructura ​de módulos, 3 capas, ​dependencias, versionado +  ​''​MachineDomain/src/​main/​java/​co/​ada/​domain/​state/​StateManager.kt''​ para orquestación y recuperación. 
-  * **[[best-practices|best-practices.md]]*- Convenciones,​ patterns/anti-patterns,​ quality gates +  * ''​MachineDomain/​src/​main/​java/​co/​ada/​domain/​state/​states/​*.kt''​ para comportamiento de cada estado. 
-  * **[[build-and-deployment|build-and-deployment.md]]** - Gradle, ProGuard, keystore, signing, CI/CD, APKs +  ​''​MachineData/​src/​main/​java/​co/​ada/​data/​emitters/​*''​ para señales de estado/mensaje. 
-  * **[[delivery-service-flow|delivery-service-flow.md]]** - StateManager:​ 8 estados del flujo de entrega+  * ''​MachineData/​src/​main/​java/​co/​ada/​data/​local/​Server.kt''​ para hosts por ambiente.
  
-==== D-L ==== +===== Ultima verificacion =====
-  * **[[dependencies|dependencies.md]]** - Librerias, versiones, matriz módulos, conflictos, exclusiones +
-  * **[[developer-guide|developer-guide.md]]** - APIs clave, componentes,​ servicios, modelos, tareas comunes +
-  * **[[environment-setup|environment-setup.md]]** - JDK 17, Android Studio, AndroidSDK, emulator, ADB, variables +
-  * **[[faq|faq.md]]** - Preguntas frecuentes por categoría (setup, build, dev, P2P, hardware, etc.) +
-  * **[[glossary|glossary.md]]** - Glosario técnico, siglas, acrónimos específicos PAE +
-  * **[[hardware-integration|hardware-integration.md]]** - Camera2, Bluetooth scale, GPIO LED, power management+
  
-==== L-T ==== +  ​Fecha''​2026-04-23''​ 
-  ​**[[layers|layers.md]]** - Presentación/​Dominio/​Datosresponsabilidades,​ comunicación,​ ejemplos +  * Método: revisión manual ​de código ​reconciliación de documentación
-  * **[[local-storage|local-storage.md]]** - SQLite, VectorDB ORM, persistencia,​ migración, limpieza +  * Alcanceestructura de docsflujo de estadosstack base y mapeo de ambientes.
-  * **[[machine-online-offline|machine-online-offline.md]]** - Funcionamiento online/​offline ​de Machine: conectividad,​ P2P, sincronización +
-  * **[[module-interactions|module-interactions.md]]** - Grafo dependencias,​ casos uso, ciclo vida, error handling +
-  * **[[overview|overview.md]]** - Visión, módulos (11 core 13 integrados),​ flujos principales +
-  * **[[p2p-architecture|p2p-architecture.md]]** - P2P contracts, modelos, P2PGestor, P2PManager interface +
-  * **[[p2p-flow|p2p-flow.md]]** - Workflows P2Pdescobertaconexiónsincronización (con diagramas Mermaid) +
-  * **[[patterns|patterns.md]]** - 5 patrones (State, Repository, Observer, Factory, Singleton), SOLID, convenciones +
-  * **[[security-and-privacy|security-and-privacy.md]]** - Permisos runtime, encriptación,​ HTTPS/​pinning,​ GDPR, sanitización +
-  * **[[testing-guide|testing-guide.md]]** - Test pyramid, JUnit 4, Mockito, Espresso, fixtures, parametrized,​ coverage +
-  * **[[troubleshooting|troubleshooting.md]]** - 20+ errores comunes: Gradle, permisos, P2P, BD, OutOfMemory,​ tests+
  
-----+===== Nota =====
  
-===== Estadísticas de documentación =====+Las carpetas legadas (''​explicaciones/'',​ ''​referencia/'',​ ''​guias/'',​ ''​producto/''​) se mantienen para compatibilidad mientras se consolida la nueva estructura.
  
-  * **Total archivos**: 23 markdown files 
-  * **Tamaño total**: ~120KB de contenido 
-  * **Tiempo lectura completa**: 8-10 horas 
-  * **Rutas onboarding rápido**: 1-2 horas por rol 
-  * **Cobertura**:​ Arquitectura,​ desarrollo, testing, deployment, seguridad, hardware, troubleshooting,​ FAQ 
  
-----+====== PAE | Solución Comercial para Gestión de Entregas en Campo ======
  
-===== Cómo contribuir documentación ​=====+===== Entregas con evidencia, control y continuidad operativa ​=====
  
-Cada documento debe tener: +**PAE** es una plataforma ​para organizaciones que ejecutan entregas en territorio y necesitan operar con orden, trazabilidad y velocidad, incluso en contextos ​de conectividad intermitente.
-  - **Tabla de contenidos** al inicio (para docs > 500 líneas) +
-  - **Ejemplos ​de código** para conceptos complejos +
-  - **Links internos** a documentos relacionados +
-  - **Diagramas Mermaid** para flujos/​grafos +
-  - **Time estimate** para lectura (ej: "​⏱️ 15 min")+
  
-Agregar nuevo doc: +Su enfoque es simpleconvertir procesos manuales y dispersos ​en un flujo digital confiable, medible y auditable.
-  - Crear archivo ​en ''​docs/''​ +
-  - Agregar a la matriz de "​Índice de documentos"​  +
-  - Update README.md con nueva entrada +
-  - Asegurar cross-links a documentos relacionados+
  
-----+===== El problema que resuelve =====
  
-===== Cambios recientes =====+La jornada empieza bien, pero a mitad del día aparece el riesgo real: una ruta sin señal, registros incompletos y coordinación por llamadas o mensajes dispersos. ​  
 +Al final, surge la pregunta crítica: **¿qué se entregó, a quién y con qué evidencia?​**
  
-**Fase 5 (Actual)**Agregados 9 archivos faltantes +Cuando esa respuesta no es inmediata, la operación entra en tensión:
-  * build-and-deployment.md +
-  * testing-guide.md +
-  * security-and-privacy.md +
-  * hardware-integration.md +
-  * dependencies.md +
-  * best-practices.md +
-  * troubleshooting.md +
-  * api-reference.md +
-  * glossary.md +
-  * **faq.md** (nuevo!)+
  
-----+  * se pierde visibilidad del avance por ruta y sede 
 +  * aumentan errores y retrabajo administrativo 
 +  * crece el riesgo de incumplimiento ante auditoría 
 +  * las decisiones llegan tarde, cuando el problema ya impactó la jornada 
 +  * las confirmaciones de entrega se basan en confianza de boca a boca, no en evidencia verificable
  
-===== Links útiles ​=====+**Ese es el problema de fondo:** no solo falta digitalización;​ falta control operativo confiable en tiempo real. 
 + 
 +==== Qué resuelve PAE de forma concreta ​==== 
 + 
 +PAE resuelve tres brechas críticas:​ 
 + 
 +  - **Brecha de continuidad:​** evita detener la operación por conectividad (modelo offline-first). 
 +  - **Brecha de confianza en datos:** asegura evidencia y trazabilidad verificable por entrega. 
 +  - **Brecha de control diario:** entrega visibilidad accionable para corregir desvíos durante la ejecución. 
 + 
 +===== Qué cambia con PAE ===== 
 + 
 +PAE estandariza la ejecución de cada entrega y asegura evidencia operativa desde el punto de atención. 
 + 
 +==== Flujo operativo ==== 
 + 
 +  - **Inicio de atención:​** se identifica y abre la entrega. 
 +  - **Captura de evidencia:​** se registran datos críticos de la atención. 
 +  - **Validación de reglas:** se verifica integridad y consistencia. 
 +  - **Confirmación de entrega:** la atención queda cerrada y trazable. 
 +  - **Actualización de avance:** el estado de la jornada se consolida automáticamente. 
 +  - **Sincronización inteligente:​** con internet se sincroniza al momento; sin internet, continúa offline y sincroniza después. 
 + 
 +===== Beneficios de negocio ===== 
 + 
 +  * **Trazabilidad completa:** evidencia por entrega para control interno y auditoría. 
 +  * **Continuidad operativa real:** el equipo no se detiene por fallas de red. 
 +  * **Mayor productividad:​** menos pasos manuales y menos reprocesos. 
 +  * **Decisiones con datos diarios:** visibilidad clara de metas, pendientes y cumplimiento. 
 +  * **Base para mejora continua:** información estructurada para análisis y optimización. 
 + 
 +===== Organizaciones para las que encaja mejor ===== 
 + 
 +PAE aporta alto valor en: 
 + 
 +  * programas sociales o alimentarios con cobertura territorial 
 +  * operaciones de campo multisede o multiruta 
 +  * procesos con alto volumen diario de entregas 
 +  * entornos con exigencia de evidencia y cumplimiento 
 + 
 +===== Propuesta de valor ===== 
 + 
 +PAE se diferencia por tres pilares de valor: 
 + 
 +  - **Continuidad operativa offline-first** ​  
 +   La operación no se detiene por fallas de conectividad;​ el equipo continúa en campo y sincroniza cuando hay red. 
 +  - **Cumplimiento y defensa ante auditoría** ​  
 +   Cada entrega queda trazada con evidencia verificable,​ reduciendo riesgos de incumplimiento y discusiones operativas. 
 +  - **Control operativo accionable** ​  
 +   ​Consolida avance, pendientes y desempeño por ruta/sede para corregir desvíos durante la jornada y no al final del mes. 
 + 
 +===== Implementación recomendada ===== 
 + 
 +  - **Diagnóstico operativo:​** sedes, volumen, flujo actual y brechas. 
 +  - **Piloto controlado:​** operación en entorno real con KPIs definidos. 
 +  - **Escalamiento progresivo:​** despliegue por sedes o regiones. 
 +  - **Acompañamiento continuo:** soporte, ajustes y evolución funcional. 
 + 
 +===== KPIs sugeridos ===== 
 + 
 +  * ''​% de entregas con evidencia completa''​ 
 +  * ''​% de sincronizaciones exitosas''​ 
 +  * ''​tiempo promedio por entrega''​ 
 +  * ''​reducción de reprocesos administrativos''​ 
 +  * ''​% de cumplimiento diario por ruta/​sede''​ 
 + 
 +===== Mensaje comercial clave ===== 
 + 
 +**PAE no es solo una app de campo.** ​  
 +Es un sistema de ejecución operativa que transforma entregas en resultados medibles, auditables y escalables.
  
-  * [[https://​github.com/​your-org/​PAE|Proyecto GitHub]] 
-  * [[troubleshooting|Reporte de errores]] 
-  * [[adr-architecture-decisions|Decisiones arquitectónicas]] 
-  * [[testing-guide|Guía de testing]] 
  
ada/howto/sicoferp/factory/new-migracion-sicoferp/machine.1775590663.txt.gz · Última modificación: 2026/04/07 19:37 por 10.1.61.45