6ed7f9e2ec
- Updated docs and inventory files - Added new architecture docs Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
327 lines
10 KiB
Markdown
327 lines
10 KiB
Markdown
# US-MAI006-019: Capturar Firma POD Offline
|
|
|
|
**Modulo:** MAI-006-tracking
|
|
**Version:** 1.0.0
|
|
**Fecha:** 2026-01-27
|
|
**Story Points:** 5
|
|
**Prioridad:** ALTA
|
|
|
|
---
|
|
|
|
## Descripcion
|
|
|
|
**Como** conductor,
|
|
**Quiero** poder capturar la firma del receptor para el Proof of Delivery (POD) incluso sin conexion a internet,
|
|
**Para** completar la entrega de manera oficial y cumplir con los requisitos de documentacion aunque este en una zona sin cobertura.
|
|
|
|
---
|
|
|
|
## Actor Principal
|
|
|
|
**Operador / Conductor**
|
|
|
|
Actor Secundario: Receptor de mercancia (firmante)
|
|
|
|
---
|
|
|
|
## Precondiciones
|
|
|
|
1. El conductor tiene un viaje en estado "EN_DESTINO" o "EN_DESCARGA"
|
|
2. La mercancia ha sido entregada o esta siendo entregada
|
|
3. El dispositivo tiene la pantalla tactil funcional
|
|
4. Hay suficiente almacenamiento local (>10 MB)
|
|
|
|
---
|
|
|
|
## Criterios de Aceptacion
|
|
|
|
### CA-1: Acceso a captura de firma sin conexion
|
|
|
|
**Given** el conductor esta en una entrega
|
|
**And** no tiene conexion a internet
|
|
**When** selecciona "Capturar firma POD"
|
|
**Then** la pantalla de captura de firma se muestra correctamente
|
|
**And** no hay mensaje de error por falta de conexion
|
|
**And** puede proceder con la captura
|
|
|
|
### CA-2: Canvas de firma funcional
|
|
|
|
**Given** el conductor esta en la pantalla de captura de firma
|
|
**When** el receptor dibuja su firma con el dedo
|
|
**Then** el trazo aparece en tiempo real
|
|
**And** el trazo es suave sin latencia perceptible
|
|
**And** el grosor del trazo es legible (2-3px)
|
|
**And** el color del trazo es negro sobre fondo blanco
|
|
|
|
### CA-3: Datos del receptor obligatorios
|
|
|
|
**Given** el receptor ha firmado
|
|
**When** el conductor intenta guardar la firma
|
|
**Then** el sistema solicita los siguientes datos obligatorios:
|
|
- Nombre del receptor (texto, minimo 3 caracteres)
|
|
- Identificacion/ID (opcional pero recomendado)
|
|
- Cargo/Puesto (opcional)
|
|
**And** no permite guardar sin nombre del receptor
|
|
|
|
### CA-4: Captura automatica de metadata
|
|
|
|
**Given** el receptor firma y el conductor guarda
|
|
**When** el sistema almacena la firma
|
|
**Then** captura automaticamente:
|
|
- Timestamp del dispositivo (con timezone)
|
|
- Coordenadas GPS actuales (si disponibles)
|
|
- ID del viaje asociado
|
|
- ID del conductor
|
|
- ID de la parada/destino
|
|
**And** esta metadata es inmutable (no editable posteriormente)
|
|
|
|
### CA-5: Opciones de corregir firma
|
|
|
|
**Given** el receptor ha dibujado una firma
|
|
**When** la firma no quedo bien
|
|
**Then** puede tocar "Borrar" para limpiar el canvas
|
|
**And** volver a firmar desde cero
|
|
**And** no hay limite de intentos
|
|
|
|
### CA-6: Confirmacion visual y almacenamiento
|
|
|
|
**Given** el conductor presiona "Guardar firma"
|
|
**And** los datos obligatorios estan completos
|
|
**When** el sistema procesa la firma
|
|
**Then** muestra preview de la firma capturada
|
|
**And** muestra mensaje "Firma guardada localmente"
|
|
**And** incrementa contador de "pendientes de sync"
|
|
**And** permite continuar con el cierre de entrega
|
|
|
|
### CA-7: Prioridad critica en sincronizacion
|
|
|
|
**Given** hay una firma POD pendiente de sincronizar
|
|
**When** se restablece la conexion a internet
|
|
**Then** la firma se envia con prioridad CRITICA (antes que eventos y fotos)
|
|
**And** el sistema intenta hasta 10 veces antes de marcar como fallido
|
|
**And** notifica al usuario si falla despues de todos los reintentos
|
|
|
|
---
|
|
|
|
## Flujo Principal
|
|
|
|
1. Conductor llega al destino
|
|
2. Conductor descarga mercancia
|
|
3. Conductor selecciona "Capturar POD"
|
|
4. Sistema abre pantalla de firma
|
|
5. Receptor dibuja firma en canvas
|
|
6. Conductor ingresa nombre del receptor
|
|
7. Conductor confirma y guarda
|
|
8. Sistema almacena firma localmente
|
|
9. Sistema actualiza estado de entrega a "POD_CAPTURADO"
|
|
10. Sistema agenda sync de alta prioridad
|
|
|
|
---
|
|
|
|
## Flujo Alternativo: Receptor se Niega a Firmar
|
|
|
|
1. Conductor intenta obtener firma
|
|
2. Receptor se niega a firmar
|
|
3. Conductor selecciona "Entrega sin firma"
|
|
4. Sistema solicita motivo (seleccion):
|
|
- Receptor ausente
|
|
- Rechazo de mercancia
|
|
- Entrega parcial
|
|
- Otro (especificar)
|
|
5. Sistema captura motivo como texto
|
|
6. Sistema toma foto de evidencia obligatoria
|
|
7. Sistema registra evento "ENTREGA_SIN_FIRMA"
|
|
|
|
---
|
|
|
|
## Wireframe ASCII de Pantalla de Firma
|
|
|
|
```
|
|
+----------------------------------------------------------+
|
|
| < Volver CAPTURAR FIRMA POD |
|
|
+----------------------------------------------------------+
|
|
| |
|
|
| Entrega #12345 |
|
|
| Destino: Almacen Central |
|
|
| |
|
|
+----------------------------------------------------------+
|
|
| |
|
|
| +-------------------------------------------------+ |
|
|
| | | |
|
|
| | | |
|
|
| | | |
|
|
| | [Area de firma - Canvas] | |
|
|
| | | |
|
|
| | | |
|
|
| | | |
|
|
| | ~~~~~~~~~~ | |
|
|
| +-------------------------------------------------+ |
|
|
| |
|
|
| [BORRAR] |
|
|
| |
|
|
+----------------------------------------------------------+
|
|
| |
|
|
| Nombre del receptor: * |
|
|
| +----------------------------------------------------+ |
|
|
| | Juan Perez Garcia | |
|
|
| +----------------------------------------------------+ |
|
|
| |
|
|
| ID / Credencial: (opcional) |
|
|
| +----------------------------------------------------+ |
|
|
| | INE 12345678 | |
|
|
| +----------------------------------------------------+ |
|
|
| |
|
|
| Cargo: (opcional) |
|
|
| +----------------------------------------------------+ |
|
|
| | Jefe de Almacen | |
|
|
| +----------------------------------------------------+ |
|
|
| |
|
|
+----------------------------------------------------------+
|
|
| |
|
|
| [=============== GUARDAR FIRMA ===============] |
|
|
| |
|
|
| [ Entrega sin firma ] |
|
|
| |
|
|
+----------------------------------------------------------+
|
|
```
|
|
|
|
---
|
|
|
|
## Notas Tecnicas
|
|
|
|
### Tecnologias Involucradas
|
|
|
|
| Componente | Tecnologia | Proposito |
|
|
|------------|------------|-----------|
|
|
| Canvas | react-native-signature-canvas | Captura de firma |
|
|
| Storage | IndexedDB | Almacenamiento de imagen |
|
|
| Compression | pako | Compresion de datos |
|
|
| Format | SVG Path | Formato vectorial ligero |
|
|
|
|
### Estructura de Firma Local
|
|
|
|
```typescript
|
|
interface FirmaPOD {
|
|
id: string; // UUID generado localmente
|
|
viajeId: string; // ID del viaje
|
|
paradaId: string | null; // ID de la parada (si aplica)
|
|
|
|
// Datos de la firma
|
|
signatureData: string; // SVG path o base64
|
|
signatureFormat: 'SVG' | 'PNG';
|
|
|
|
// Datos del receptor
|
|
receptorNombre: string; // Obligatorio
|
|
receptorId: string | null; // Opcional
|
|
receptorCargo: string | null; // Opcional
|
|
|
|
// Metadata inmutable
|
|
capturedAt: Date; // Timestamp de captura
|
|
timezone: string; // Timezone del dispositivo
|
|
lat: number | null; // Latitud GPS
|
|
lng: number | null; // Longitud GPS
|
|
gpsAccuracy: number | null; // Precision en metros
|
|
|
|
// Metadata del conductor
|
|
operadorId: string;
|
|
dispositivoId: string;
|
|
|
|
// Estado de sync
|
|
syncStatus: 'PENDING' | 'SENT' | 'FAILED';
|
|
syncAttempts: number;
|
|
lastSyncError: string | null;
|
|
|
|
// Timestamps
|
|
createdAt: Date;
|
|
updatedAt: Date;
|
|
syncedAt: Date | null;
|
|
}
|
|
```
|
|
|
|
### Formato SVG Path (Recomendado)
|
|
|
|
```typescript
|
|
// Ventajas de SVG Path:
|
|
// - Menor tamano (~10-50 KB vs 200-500 KB PNG)
|
|
// - Escalable sin perdida
|
|
// - Facil de renderizar
|
|
|
|
interface SignaturePath {
|
|
paths: Array<{
|
|
d: string; // SVG path data (M, L, Q commands)
|
|
strokeWidth: number;
|
|
strokeColor: string;
|
|
}>;
|
|
viewBox: {
|
|
width: number;
|
|
height: number;
|
|
};
|
|
}
|
|
|
|
// Ejemplo de path
|
|
// "M 50,50 L 100,100 Q 150,50 200,100"
|
|
```
|
|
|
|
### Validaciones
|
|
|
|
```typescript
|
|
const FIRMA_VALIDATIONS = {
|
|
minPathLength: 100, // Minimo de puntos para ser valida
|
|
minNameLength: 3, // Minimo caracteres en nombre
|
|
maxStorageSize: 500 * 1024, // 500 KB max por firma
|
|
requiredGPS: false // GPS recomendado pero no obligatorio
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## Dependencias
|
|
|
|
| Dependencia | Tipo | Descripcion |
|
|
|-------------|------|-------------|
|
|
| US-MAI006-016 | Funcional | Operar sin conexion |
|
|
| US-MAI006-017 | Funcional | Sincronizar al reconectar |
|
|
| US-MAI007-001 | Funcional | Proceso de cierre POD |
|
|
| react-native-signature-canvas | Tecnica | Libreria de captura |
|
|
|
|
---
|
|
|
|
## Consideraciones de Seguridad
|
|
|
|
| Aspecto | Implementacion |
|
|
|---------|----------------|
|
|
| Integridad | Hash SHA-256 de la firma |
|
|
| No repudio | Metadata inmutable (GPS, timestamp) |
|
|
| Cifrado | Firma cifrada en reposo |
|
|
| Auditoria | Log de acceso y modificacion |
|
|
|
|
---
|
|
|
|
## Riesgos y Mitigaciones
|
|
|
|
| Riesgo | Probabilidad | Impacto | Mitigacion |
|
|
|--------|--------------|---------|------------|
|
|
| Firma ilegible | Media | Bajo | Boton "Borrar" para reintentar |
|
|
| Pantalla danada | Baja | Alto | Opcion "Sin firma" con evidencia |
|
|
| GPS no disponible | Media | Bajo | Permitir sin GPS, marcar en metadata |
|
|
| Almacenamiento lleno | Baja | Alto | Validar espacio antes de captura |
|
|
|
|
---
|
|
|
|
## Definition of Done
|
|
|
|
- [ ] Canvas de firma funciona sin conexion
|
|
- [ ] Nombre del receptor es obligatorio
|
|
- [ ] Metadata automatica capturada correctamente
|
|
- [ ] Firma se almacena en formato SVG/PNG
|
|
- [ ] Firma comprimida si excede limite
|
|
- [ ] Prioridad critica en sincronizacion
|
|
- [ ] Opcion "Sin firma" con motivo implementada
|
|
- [ ] Preview de firma antes de guardar
|
|
- [ ] Pruebas de usabilidad con conductores reales
|
|
- [ ] Pruebas offline completadas
|
|
|
|
---
|
|
|
|
*US-MAI006-019 v1.0.0 - erp-transportistas - Sistema SIMCO v4.0.0*
|