====== Documentación del Proyecto PAE ====== ===== Propósito ===== 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. ===== Tabla de contenidos rápida ===== ^ Pregunta ^ Documento ^ | 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) ===== ==== Fundamentals (4 archivos) ==== * [[overview|overview.md]] - Visión general, módulos, flujos principales * [[architecture|architecture.md]] - Estructura modular, 3 capas, dependencias * [[layers|layers.md]] - Responsabilidades de cada capa * [[module-interactions|module-interactions.md]] - Grafo de dependencias, casos de uso ==== Arquitectura y Diseño (4 archivos) ==== * [[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) ==== * [[environment-setup|environment-setup.md]] - JDK 17, Android Studio, SDK, emulator, ADB * [[dependencies|dependencies.md]] - Gestión de versiones, matriz de librerías, conflictos * [[build-and-deployment|build-and-deployment.md]] - Gradle, signing, ProGuard/R8, CI/CD, release APKs ==== Desarrollo (4 archivos) ==== * [[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) ==== * [[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) ==== * [[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) ==== * [[troubleshooting|troubleshooting.md]] - 20+ errores comunes y soluciones * [[faq|faq.md]] - Preguntas frecuentes por tema (¡Ver primero!) ===== Rutas de aprendizaje por rol ===== ==== 🆕 Nuevos Desarrolladores ==== Entender proyecto en 1-2 horas: - [[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]] ==== 🏛️ Arquitectos de Software ==== Entender decisiones y trade-offs: - [[adr-architecture-decisions|adr-architecture-decisions.md]] - Las decisiones (30 min) - [[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]] ==== 💻 Feature Developers ==== Implementar funcionalidades nuevas: - [[developer-guide|developer-guide.md]] - APIs disponibles (20 min) - [[best-practices|best-practices.md]] - Cómo escribir código (20 min) - [[patterns|patterns.md]] - Patterns a usar (15 min) - [[api-reference|api-reference.md]] - Firmas de API específicas (15 min) - [[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]] → Si usas P2P: [[p2p-flow|p2p-flow.md]] ==== ⚙️ DevOps / Build Engineers ==== Deployment, CI/CD, versionado: - [[build-and-deployment|build-and-deployment.md]] - Compilation, signing, release (30 min) - [[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 ==== 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) ---- ===== Índice alfabético de archivos ===== ==== A-D ==== * **[[adr-architecture-decisions|adr-architecture-decisions.md]]** - ADRs: decisiones arquitectónicas justificadas (13 records) * **[[api-reference|api-reference.md]]** - APIs públicas: StateManager, P2PManager, Services, Hardware * **[[architecture|architecture.md]]** - Estructura de módulos, 3 capas, dependencias, versionado * **[[best-practices|best-practices.md]]** - Convenciones, patterns/anti-patterns, quality gates * **[[build-and-deployment|build-and-deployment.md]]** - Gradle, ProGuard, keystore, signing, CI/CD, APKs * **[[delivery-service-flow|delivery-service-flow.md]]** - StateManager: 8 estados del flujo de entrega ==== D-L ==== * **[[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 ==== * **[[layers|layers.md]]** - Presentación/Dominio/Datos: responsabilidades, comunicación, ejemplos * **[[local-storage|local-storage.md]]** - SQLite, VectorDB ORM, persistencia, migración, limpieza * **[[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 P2P: descoberta, conexión, sincronizació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 ---- ===== Estadísticas de documentación ===== * **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 ---- ===== Cómo contribuir documentación ===== Cada documento debe tener: - **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: - Crear archivo en ''docs/'' - Agregar a la matriz de "Índice de documentos" - Update README.md con nueva entrada - Asegurar cross-links a documentos relacionados ---- ===== Cambios recientes ===== **Fase 5 (Actual)**: Agregados 9 archivos faltantes * 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!) ---- ===== Links útiles ===== * [[https://github.com/your-org/PAE|Proyecto GitHub]] * [[troubleshooting|Reporte de errores]] * [[adr-architecture-decisions|Decisiones arquitectónicas]] * [[testing-guide|Guía de testing]]