Casillero — App de envíos a Cuba¶

Documentación funcional, técnica y operativa del proyecto IslaBox. Cubre el producto, la arquitectura, los datos, los flujos, las pantallas, las reglas de negocio y el código del prototipo Android.

Estado del proyecto — 2026-07-11

La documentación vigente se reorganizó el 2026-07-11 tras la auditoría cruzada entre el código y la documentación previa.

Decisiones de negocio viven en producto/decisiones-vigentes.md.
Estados canónicos siguen en datos/estados.md.
Estado real del prototipo se documenta con hash de código en apk/estado-actual-prototipo.md.
Documentos históricos viven en _archivo/ y no deben usarse como referencia.

Qué es este proyecto¶

Una aplicación para personas que viven en Estados Unidos, compran en marketplaces (Amazon, SHEIN, Temu, otros), usan la dirección del casillero en Miami para recibir sus pedidos y luego reportan esos pedidos en la app para enviarlos a destinatarios en Cuba.

IslaBox opera como intermediario digital: recibe paquetes en su casillero propio y los entrega a una agencia aliada que es quien realiza el transporte internacional y la entrega final. IslaBox no realiza transporte internacional.

flowchart LR
    A["🛒 Compro online"] --> B["📌 Copio dirección del casillero"]
    B --> C["📦 Reporto mi compra"]
    C --> D["📊 Veo estado del paquete"]
    D --> E["💳 Pago envío + consolidación"]
    E --> F["🚚 IslaBox entrega a la agencia aliada"]
    F --> G["💛 Aduana Cuba + entrega a domicilio"]

Cómo navegar la documentación¶

Quiero saber...	Empezar por
Qué ha decidido producto	`producto/decisiones-vigentes.md`
Qué entra y qué no en cada fase	`producto/matriz-funcionalidad-fase.md`
Recorrido completo del cliente	`flujos/flujo-end-to-end-cliente.md`
Pantallas del prototipo Android	`apk/catalogo-pantallas.md`
Qué funciona hoy en el prototipo	`apk/estado-actual-prototipo.md`
Estados canónicos de cualquier entidad	`datos/estados.md`
Reglas de negocio vigentes	`datos/reglas-negocio.md`
Política de almacenaje	`datos/politica-almacenamiento.md`
Sistema visual y microcopy	`diseno/sistema-diseno.md`
Próximos pasos priorizados	`roadmap/proximos-pasos.md`
Documentos históricos archivados	`_archivo/`

Stack actual¶

Capa	Tecnología
App cliente	Android nativo (Kotlin + Jetpack Compose)
Backend (lógica y admin)	Django + Django ORM
API expuesta al cliente	FastAPI + Pydantic
Base de datos	PostgreSQL
Cache / jobs / locks	Redis
Almacenamiento de archivos	MinIO (S3-compatible)
Pasarela MVP	Registro manual por operador (Fase 2: Stripe)
Notificaciones	Push (FCM) + email

Reglas innegociables¶

Solo se registran personas radicadas en EE.UU. con teléfono +1 (D-101).
Almacenaje gratis: 15 días / Costo extra: $0.50 USD/día / Aviso: 3 días antes (D-102 a D-104).
Tarifa de envío: $2.40/lb marítimo, $3.35/lb aéreo (D-105, D-106).
Pago MVP: registro manual del operador (D-107).
KYC bloquea consolidar, pagar y despachar; no bloquea la prealerta (D-108).
Cada función visible al usuario lleva etiqueta de madurez obligatoria (D-116).

Para cualquier cambio de estas reglas, abrir una decisión en producto/decisiones-vigentes.md siguiendo el formato ADR corto.

Convenciones¶

Front matter: todo documento canónico declara estado, owner, ultima_revision, alcance y, cuando aplica, fuentes / reemplaza / reemplazado_por.
Estados de documento: vigente | borrador | historico | reemplazado.
Estados de funcionalidad: ✅ Implementado / 🧪 Simulado / 🔌 Integración pendiente / 📝 Especificado / 🚫 Fuera de alcance / ❓ Decisión requerida.
Estados UI: ver diseno/estados-ui.md.
Microcopy: ver diseno/microcopy.md.

Changelog y auditorías¶

Cambios en esta ola: CHANGELOG_DOCUMENTACION.md (raíz del repo).
Auditoría previa (2026-06-07): _archivo/auditorias/2026-06-07-apk/.
Auditoría que detonó esta reorganización (2026-07-11): entregable que originó el plan y cuya carpeta se elimina una vez aplicados los cambios en el repositorio.