Add documentation and SPEC

- Update README with full project documentation - Add docs/SPEC.md with complete technical specification 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-21 18:11:43 +01:00
parent dac0c51483
commit c9d7127ee2
2 changed files with 674 additions and 10 deletions
--- a/README.md
+++ b/README.md
@@ -1,16 +1,115 @@
-# packet
+# Packet

-A new Flutter project.
+App móvil multiplataforma (iOS/Android) para capturar contenido multimedia, etiquetarlo con hashes y enviarlo a backends configurables.

-## Getting Started
+## Principios

-This project is a starting point for a Flutter application.
+| Principio | Descripción |
+|-----------|-------------|
+| Zero-retention | Los archivos nunca se almacenan en disco, solo en RAM hasta envío |
+| Hash-first | Todo contenedor tiene hash SHA-256 único generado localmente |
+| Contenedor cerrado | Una vez montado, no se inspecciona. Solo enviar o desmontar |
+| App tonta | No valida coherencia de etiquetas, solo formato. El backend decide |
+| Offline-capable | Captura sin conexión, cola de reintentos cuando hay red |

-A few resources to get you started if this is your first Flutter project:
+## Stack Tecnológico

- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)
+| Componente | Tecnología |
+|------------|------------|
+| Framework | Flutter 3.x |
+| Lenguaje | Dart |
+| Estado | flutter_bloc |
+| DB Local | sqflite |
+| HTTP | dio |
+| Crypto | crypto (SHA-256) |
+| Media | image_picker, record |
+| Location | geolocator |
+| Permisos | permission_handler |

-For help getting started with Flutter development, view the
-[online documentation](https://docs.flutter.dev/), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
+## Pantallas
+
+```
+┌─────────────────────────────────────────┐
+│  [Mi DECK ▼] [CORP] [+Ext]              │  ← Destinos (superior)
+├─────────────────────────────────────────┤
+│           CONTENIDO PANTALLA            │
+├─────────────────────────────────────────┤
+│  📷      🏷️      📦      ⏳      ⚙️     │  ← Navegación (inferior)
+│ Captura  Tags   Packs  Pend.  Config   │
+└─────────────────────────────────────────┘
+```
+
+### Captura
+Montar contenedor con contenido multimedia: título, descripción, archivos, GPS, etiquetas.
+
+### Etiquetas
+Seleccionar etiquetas de bibliotecas HST/DECK y añadir hashes externos.
+
+### Packs
+Conjuntos predefinidos de etiquetas para aplicar con 1 tap.
+
+### Pendientes
+Cola de contenedores fallidos (máx 20). App se bloquea si se llena.
+
+### Config
+URLs, llaves de autenticación y bibliotecas de iconos.
+
+## Estructura del Proyecto
+
+```
+lib/
+├── core/
+│   ├── constants/    # Constantes de la app
+│   ├── errors/       # Excepciones personalizadas
+│   ├── utils/        # Utilidades (hash, retry)
+│   └── theme/        # Tema de la app
+├── data/
+│   ├── datasources/  # APIs y BD local
+│   └── repositories/ # Repositorios
+├── domain/
+│   └── entities/     # Modelos de dominio
+└── presentation/
+    ├── bloc/         # Cubits de estado
+    ├── pages/        # Pantallas
+    └── widgets/      # Widgets reutilizables
+```
+
+## Build
+
+```bash
+# Instalar dependencias
+flutter pub get
+
+# Build APK
+flutter build apk --release
+
+# Build iOS (requiere Xcode)
+flutter build ios --release
+```
+
+## APIs
+
+### Backend (envío)
+```http
+POST {destino.url}/ingest
+X-Auth-Key: {destino.hash}
+Content-Type: application/json
+```
+
+### Bibliotecas (etiquetas)
+```http
+GET {biblioteca.url}/api/tags
+```
+
+## Lógica de Reintentos
+
+20 intentos en 72 horas con backoff exponencial (1min → 8h).
+
+## Referencias
+
+- Biblioteca HST: https://tzrtech.org
+- Especificación completa: [docs/SPEC.md](docs/SPEC.md)
+
+---
+
+v1.0.0