# Solicitud de software: app de pedidos para una distribuidora

> **Nota:** este documento es un ejemplo generado por el diagnóstico de piloto.dev.
> El negocio, las personas y las cifras son ficticios. Sirve para mostrar cómo
> se ve una solicitud de software completa y lista para usar.

## Cómo usar este documento

Tienes dos caminos:

1. **Pegarlo en un asistente de IA.** Copia todo el texto, desde "Rol y objetivo"
   hasta el final, y pégalo en el chat. La IA tendrá el contexto suficiente para
   proponerte un plan, un modelo de datos y las pantallas de la primera versión.
2. **Enviarlo a un equipo de desarrollo.** Mándalo tal cual a un programador, una
   agencia o un socio técnico. Les ahorra varias reuniones de levantamiento y les
   permite cotizar con menos supuestos.

En ambos casos, revisa primero la sección "Preguntas abiertas para el negocio" y
responde lo que puedas. Cada respuesta reduce el riesgo de construir algo que no
sirve.

## Rol y objetivo

Actúa como un líder técnico con experiencia en productos web para pequeñas y
medianas empresas de América Latina. Tu tarea es planificar la primera versión
(V1) de una aplicación web de toma de pedidos para una distribuidora.

Con la información de este documento, entrégame:

1. **Un plan de implementación** con el enfoque técnico recomendado y su
   justificación, pensado para un equipo pequeño y un presupuesto ajustado.
2. **Un modelo de datos** con entidades, campos clave y relaciones.
3. **Un listado de pantallas** con su propósito, contenido y acciones.
4. **Un desglose de tareas por semanas** para un lanzamiento en 4 a 8 semanas.
5. **Una lista de riesgos** con su probabilidad, impacto y mitigación.

Si algo no está claro, no lo inventes: márcalo como supuesto o agrégalo a las
preguntas abiertas. Prioriza siempre lo más simple que resuelva el problema.

## Contexto del negocio

- **Rubro:** distribuidora mayorista de productos de consumo masivo (abarrotes,
  bebidas, artículos de limpieza e higiene personal).
- **Ubicación:** una ciudad intermedia de Bolivia, con cobertura a la ciudad y a
  zonas periurbanas cercanas.
- **Tamaño:** empresa mediana y familiar. El dueño participa en la operación.
- **Clientes:** tiendas de barrio, minimarkets, kioscos y algunos restaurantes.
  La mayoría compra cada semana o cada quince días.
- **Equipo involucrado:** 12 vendedores en la calle, 2 personas en bodega y el
  dueño, que también hace de administrador.
- **Herramientas actuales:** WhatsApp (grupos y chats individuales) y una planilla
  de Excel compartida en una computadora de la bodega.
- **Catálogo:** varios cientos de productos activos, con presentaciones distintas
  (unidad, paquete, caja). Los precios cambian con cierta frecuencia.

## Problema actual

### Flujo actual, paso a paso

1. El vendedor visita la tienda y anota el pedido en una libreta o en las notas
   del celular.
2. Envía el pedido por WhatsApp a bodega, a veces como texto, a veces como foto
   de la libreta, a veces como audio.
3. En bodega, una persona lee los mensajes del día, en desorden y mezclados con
   otras conversaciones.
4. Transcribe cada pedido a mano en el Excel: cliente, productos, cantidades y
   precios.
5. Imprime o lee el pedido desde el Excel y lo arma en la bodega.
6. Cuando el vendedor o el cliente pregunta por el estado, bodega responde por
   WhatsApp, revisando a mano.

### Dónde falla

- **Pedidos perdidos:** mensajes que quedan enterrados en el chat y nunca se
  cargan al Excel.
- **Errores de carga:** cantidades o productos mal transcritos, sobre todo cuando
  el pedido llega como foto o audio.
- **Precios equivocados:** el vendedor cotiza con una lista vieja y bodega carga
  otro precio.
- **Duplicados:** el vendedor reenvía el pedido "por si acaso" y se arma dos veces.
- **Sin visibilidad:** nadie sabe con certeza en qué estado está un pedido.
- **Cero trazabilidad:** no queda registro de quién cambió qué ni cuándo.

### Tiempo perdido estimado (semanal)

| Actividad | Horas por semana (estimado) |
|-----------|-----------------------------|
| Transcribir pedidos de WhatsApp al Excel | 4 |
| Aclarar pedidos confusos con los vendedores | 1,5 |
| Responder consultas sobre el estado de pedidos | 1 |
| Corregir errores y rearmar pedidos | 1 |
| **Total en bodega** | **7,5** |

A esto se suma el tiempo de los vendedores reenviando y aclarando pedidos, que hoy
no se mide.

## Usuarios y roles

| | Vendedor (12 personas) | Bodega (2 personas) | Administrador / dueño (1 persona) |
|---|---|---|---|
| **Dispositivo** | Celular Android propio, de gama baja o media, con poco espacio libre | Computadora de escritorio en la bodega; opcionalmente un celular o tablet | Celular y computadora portátil |
| **Conectividad** | Datos móviles intermitentes; zonas sin señal durante las visitas | Internet fijo, en general estable | Buena en general |
| **Habilidad digital** | Usa WhatsApp con soltura; poca experiencia con apps de trabajo | Manejo básico de Excel y WhatsApp | Media |
| **Qué necesita** | Tomar el pedido rápido frente al cliente, con precios correctos; saber que llegó y ver su estado sin llamar | Ver los pedidos nuevos al instante, en orden, marcar su avance y no transcribir nada a mano | Mantener catálogo, precios, usuarios y clientes; ver el volumen de pedidos y exportar a Excel |

En resumen: 12 vendedores en la calle, con celular, y 2 personas en bodega que
preparan los pedidos. El dueño administra.

## Objetivos y métricas de éxito

| Métrica | Línea base (hoy) | Meta (3 meses después del lanzamiento) | Cómo se mide |
|---------|------------------|----------------------------------------|--------------|
| Pedidos perdidos por semana | Se estiman 3 a 5 | 0 | Reclamos de clientes por pedidos no entregados, cruzados con los pedidos registrados en la app |
| Horas semanales de bodega en transcripción y aclaraciones | ~7,5 | ~1,5 (6 horas ahorradas) | Registro simple de tiempo de bodega durante 2 semanas antes y 2 semanas después |
| Pedidos con error de producto o cantidad | Sin medir | Menos de 2 % | Pedidos marcados con incidencia en la app sobre el total |
| Pedidos tomados por la app | 0 % | 95 % o más | Pedidos en la app sobre el total de pedidos despachados |
| Tiempo para tomar un pedido de 10 líneas | Sin medir | Menos de 3 minutos | Observación en campo con 3 vendedores |

El objetivo de negocio, en una frase: **cero pedidos perdidos y 6 horas semanales
ahorradas en bodega.**

## Alcance de la primera versión

La V1 tiene tres piezas: **catálogo, toma de pedido y estado del pedido**.
Todo lo demás de esta lista es el soporte mínimo para que esas tres piezas
funcionen, no producto adicional: la gestión básica del administrador, la
exportación a Excel y el borrador sin conexión.

### Dentro del alcance

- **Catálogo:** productos con nombre, código, presentación, categoría y precio
  según la lista de precios. Búsqueda rápida por nombre o código.
- **Toma de pedido:** el vendedor elige el cliente, agrega productos y cantidades,
  ve el total y envía el pedido. Puede guardar un borrador sin conexión.
- **Estado del pedido:** bodega ve los pedidos al instante y cambia su estado; el
  vendedor ve ese estado en su celular.
- **Gestión básica:** alta de usuarios, clientes, productos y listas de precios
  por el administrador.
- **Exportación a Excel** de pedidos, catálogo y clientes.

### Fuera del alcance (explícitamente)

- Cobros, pagos en línea o registro de cuentas por cobrar.
- Facturación electrónica ante el SIN.
- Planificación de rutas o seguimiento GPS de vendedores.
- Control y reserva de inventario (stock) al tomar el pedido.
- Promociones, descuentos automáticos o combos.
- App nativa para Android o iOS. La V1 es una app web.

Todo lo anterior puede evaluarse para versiones siguientes, una vez que la V1
esté en uso y se mida su impacto.

## Historias de usuario

**HU-01. Buscar un producto en el catálogo**

Como vendedor, quiero buscar productos por nombre o código para armar el pedido
rápido.
- Dado que estoy en el catálogo, cuando escribo al menos 2 letras, entonces veo
  los productos que coinciden en menos de 1 segundo.
- Dado que el cliente tiene un tipo asignado, cuando veo un producto, entonces
  el precio mostrado es el de su lista de precios.

**HU-02. Crear un pedido**

Como vendedor, quiero crear un pedido para un cliente frente a él.
- Dado que elegí un cliente, cuando agrego productos y cantidades, entonces veo
  el subtotal por línea y el total del pedido actualizados.
- Dado que el total no alcanza el pedido mínimo, cuando intento enviarlo,
  entonces la app me avisa cuánto falta y no lo envía.

**HU-03. Guardar un pedido sin conexión**

Como vendedor, quiero tomar el pedido aunque no tenga señal.
- Dado que no tengo conexión, cuando guardo el pedido, entonces queda como
  borrador en mi celular con la marca "pendiente de envío".
- Dado que recupero la conexión, cuando abro la app, entonces los borradores
  pendientes se envían y veo la confirmación de cada uno.

**HU-04. Evitar pedidos duplicados**

Como bodega, quiero que un pedido no llegue dos veces.
- Dado que el vendedor envió un pedido, cuando la sincronización se repite por
  un corte de red, entonces bodega ve un solo pedido.

**HU-05. Ver pedidos nuevos en bodega**

Como bodega, quiero ver los pedidos nuevos al instante en una lista.
- Dado que un vendedor envía un pedido, cuando tengo abierta la lista, entonces
  el pedido aparece en menos de 10 segundos sin recargar la página.
- Dado que hay varios pedidos, cuando abro la lista, entonces están ordenados del
  más antiguo al más nuevo y puedo filtrar por estado.

**HU-06. Cambiar el estado de un pedido**

Como bodega, quiero marcar el avance del pedido para que el vendedor lo sepa.
- Dado un pedido "enviado", cuando lo marco "en preparación", entonces el
  vendedor ve el nuevo estado en su celular.
- Dado un pedido "entregado", cuando intento cambiarlo, entonces la app no lo
  permite.

**HU-07. Consultar el estado como vendedor**

Como vendedor, quiero ver en qué estado están mis pedidos.
- Dado que tengo pedidos enviados, cuando abro "Mis pedidos", entonces veo cada
  uno con su estado y la hora del último cambio.

**HU-08. Cancelar un pedido**

Como vendedor, quiero cancelar un pedido si el cliente se arrepiente.
- Dado un pedido "enviado", cuando lo cancelo e indico un motivo, entonces pasa a
  "cancelado" y bodega lo ve marcado.
- Dado un pedido "en preparación", cuando intento cancelarlo, entonces la app me
  indica que debo pedírselo a bodega.

**HU-09. Mantener precios**

Como administrador, quiero actualizar los precios de una lista.
- Dado que edito un precio, cuando guardo, entonces los pedidos nuevos usan el
  precio nuevo y los ya enviados conservan el precio original.

**HU-10. Exportar a Excel**

Como administrador, quiero exportar los pedidos, el catálogo y los clientes.
- Dado que elijo un rango de fechas, cuando exporto los pedidos, entonces
  descargo un archivo de Excel con una fila por línea de pedido.
- Dado que estoy en el catálogo o en los clientes, cuando presiono "Exportar",
  entonces descargo un archivo de Excel con una fila por producto o por cliente.

## Reglas de negocio

### Listas de precios y pedido mínimo

- Cada cliente tiene un **tipo** (por ejemplo: tienda de barrio, minimarket,
  restaurante). Cada tipo tiene su **lista de precios**.
- El precio de cada línea se toma de la lista del cliente al momento de crear el
  pedido y queda **congelado** en el pedido.
- El vendedor **no puede** modificar precios. Solo el administrador cambia listas.
- Cada tipo de cliente tiene un **monto mínimo de pedido** configurable. Un pedido
  por debajo del mínimo no se puede enviar.

### Estados del pedido y transiciones

Estados: **borrador → enviado → en preparación → listo → entregado**, y
**cancelado** como salida.

| Transición | Quién puede hacerla | Condición |
|------------|---------------------|-----------|
| borrador → enviado | Vendedor | Cumple el pedido mínimo y tiene al menos una línea |
| enviado → en preparación | Bodega | Ninguna |
| en preparación → listo | Bodega | Ninguna |
| listo → entregado | Bodega o administrador | Confirmación de entrega |
| borrador → (eliminado) | Vendedor | Solo sus propios borradores |
| enviado → cancelado | Vendedor, bodega o administrador | Motivo obligatorio |
| en preparación → cancelado | Bodega o administrador | Motivo obligatorio |
| listo → cancelado | Administrador | Motivo obligatorio |
| entregado → cualquier otro | Nadie | Estado final |
| cancelado → cualquier otro | Nadie | Estado final |

### Edición y cancelación

- Un **borrador** se edita libremente y vive solo en el celular del vendedor
  hasta que se envía.
- Un pedido **enviado** puede editarlo el vendedor mientras bodega no lo haya
  pasado a "en preparación". Cada edición queda registrada.
- Desde **en preparación**, solo bodega o el administrador pueden ajustar
  cantidades (por ejemplo, por falta de producto), indicando el motivo.
- Toda cancelación exige un motivo y queda en el historial.
- Ningún pedido se borra físicamente una vez enviado.

## Pantallas

| # | Pantalla | Usuario | Qué muestra | Acciones |
|---|----------|---------|-------------|----------|
| P-01 | Inicio de sesión | Todos | Teléfono y contraseña | Entrar; pedir reseteo al administrador |
| P-02 | Inicio del vendedor | Vendedor | Botón "Nuevo pedido", pedidos de hoy con estado, borradores pendientes, estado de conexión | Crear pedido, abrir pedido, forzar sincronización |
| P-03 | Selección de cliente | Vendedor | Sus clientes con búsqueda y tipo de cliente | Elegir cliente |
| P-04 | Toma de pedido | Vendedor | Buscador del catálogo, líneas con cantidad y subtotal, total, aviso de pedido mínimo | Agregar, cambiar o quitar líneas; nota; guardar borrador; enviar |
| P-05 | Mis pedidos | Vendedor | Pedidos por fecha con estado, cliente y total; filtro por estado | Ver detalle, editar si se permite, cancelar con motivo |
| P-06 | Detalle del pedido | Todos | Cliente, líneas, total, notas, estado e historial | Cambiar estado, editar o cancelar según rol y estado |
| P-07 | Tablero de bodega | Bodega | Pedidos por estado con hora, vendedor y cliente; se actualiza solo | Abrir, pasar al siguiente estado, imprimir lista de armado |
| P-08 | Catálogo y precios | Administrador | Productos, categorías, presentaciones y precios por lista | Crear, editar, desactivar; editar precios; importar desde Excel; exportar a Excel |
| P-09 | Clientes | Administrador | Clientes con tipo, vendedor asignado y contacto | Crear, editar, desactivar, reasignar vendedor; exportar a Excel |
| P-10 | Usuarios | Administrador | Usuarios con rol y estado | Crear, desactivar, resetear contraseña |
| P-11 | Reportes y exportación | Administrador | Pedidos por día, vendedor y estado; cancelaciones con motivo | Filtrar por fechas, exportar pedidos a Excel |

## Modelo de datos inicial

| Entidad | Campos clave |
|---------|--------------|
| Usuario | id, nombre, teléfono, rol (vendedor, bodega, administrador), activo, creado_en |
| TipoCliente | id, nombre, pedido_minimo, lista_precios_id |
| Cliente | id, nombre del negocio, contacto, teléfono, dirección o referencia, tipo_cliente_id, vendedor_id, activo |
| Categoria | id, nombre |
| Producto | id, código, nombre, presentación, unidad, categoria_id, activo |
| ListaPrecios | id, nombre, vigente_desde |
| Precio | id, lista_precios_id, producto_id, precio, actualizado_en |
| Pedido | id, id_local (generado en el celular para evitar duplicados), cliente_id, vendedor_id, estado, total, nota, creado_en, enviado_en, actualizado_en, motivo_cancelacion |
| LineaPedido | id, pedido_id, producto_id, cantidad, precio_unitario (congelado), subtotal |
| HistorialPedido | id, pedido_id, usuario_id, acción, estado_anterior, estado_nuevo, detalle, fecha |

Relaciones principales:
- Un Cliente pertenece a un TipoCliente y a un Vendedor (Usuario).
- Un TipoCliente usa una ListaPrecios; una ListaPrecios tiene muchos Precios.
- Un Pedido pertenece a un Cliente y a un Vendedor, y tiene muchas LineaPedido.
- Cada cambio relevante de un Pedido genera un registro en HistorialPedido.

## Requisitos no funcionales

- **Mobile-first:** la experiencia del vendedor se diseña primero para celular.
  Debe funcionar bien en celulares Android de gama baja, con 2 GB de RAM y
  navegadores actualizados.
- **Borrador sin conexión:** el vendedor puede consultar el catálogo descargado y
  guardar pedidos sin señal. Se sincronizan solos al volver la conexión, sin
  duplicar pedidos.
- **Rendimiento:**
  - Primera carga en 3G en menos de 5 segundos; cargas siguientes en menos de 2.
  - Búsqueda en el catálogo en menos de 1 segundo.
  - Pedido visible en bodega en menos de 10 segundos desde su envío.
  - Consumo de datos moderado: el catálogo se actualiza por cambios, no completo.
- **Roles y permisos:** cada rol ve y hace solo lo que le corresponde. Un vendedor
  ve únicamente sus clientes y pedidos.
- **Auditoría:** todo cambio de estado, edición y cancelación queda registrado con
  usuario, fecha y detalle.
- **Exportación a Excel** de pedidos, catálogo y clientes.
- **Respaldos:** copia de seguridad automática diaria de la base de datos, con
  retención mínima de 30 días y una prueba de restauración antes del lanzamiento.
- **Idioma:** toda la interfaz en español, con formato de moneda y fechas local.
- **Seguridad básica:** conexión cifrada (HTTPS), contraseñas protegidas y
  cierre de sesión remoto si se pierde un celular.

## Integraciones

- **V1:** ninguna. La app funciona sola y se conecta con el resto del negocio a
  través de la exportación a Excel.
- **Posibles más adelante:**
  - Notificaciones por WhatsApp al cliente o al vendedor cuando cambia el estado.
  - Integración con el sistema contable o de facturación.

## Restricciones

- **Presupuesto pequeño:** priorizar tecnologías conocidas, hosting económico y
  componentes ya hechos antes que desarrollo a medida.
- **Equipo pequeño:** una o dos personas de desarrollo, con apoyo de diseño
  puntual.
- **Plazo:** lanzamiento en 4 a 8 semanas, con un piloto previo de 1 a 2 semanas
  con un grupo reducido de vendedores.
- **Operación:** el negocio no puede detenerse. Durante la transición, WhatsApp
  sigue como respaldo.

## Riesgos y supuestos

### Riesgos

| Riesgo | Impacto | Mitigación |
|--------|---------|------------|
| Los vendedores siguen usando WhatsApp por costumbre | Alto | Piloto con vendedores referentes, capacitación corta y regla clara de que solo se arman pedidos de la app |
| Sincronización sin conexión con errores o duplicados | Alto | Identificador local por pedido, pruebas en campo con mala señal |
| Catálogo y precios desactualizados al lanzar | Medio | Importación inicial desde el Excel actual y revisión del administrador |
| Celulares muy antiguos o sin espacio | Medio | Pruebas en los modelos reales del equipo antes del lanzamiento |
| El alcance crece durante el desarrollo | Medio | Respetar la lista "fuera del alcance" y anotar lo nuevo para la V2 |
| Dependencia de una sola persona técnica | Medio | Código y despliegue documentados desde la primera semana |

### Supuestos

- Todos los vendedores tienen un celular Android con datos móviles.
- La bodega tiene una computadora con internet durante el horario de trabajo.
- El Excel actual contiene los datos de productos y clientes necesarios para la
  carga inicial.
- El dueño puede dedicar algunas horas por semana a validar avances.

## Preguntas abiertas para el negocio

1. ¿Cuántos pedidos se toman en un día normal y en un día pico?
2. ¿Cuántos productos activos hay en el catálogo y cada cuánto cambian los precios?
3. ¿Cuántos tipos de cliente y listas de precios existen hoy?
4. ¿Cuál es el monto de pedido mínimo actual para cada tipo de cliente?
5. ¿Un cliente puede ser atendido por más de un vendedor?
6. ¿Bodega necesita una lista de armado impresa o le basta verla en pantalla?
7. ¿Quién confirma la entrega: el repartidor, bodega o el vendedor?
8. ¿Qué pasa hoy cuando falta un producto: se entrega incompleto, se reemplaza o
   se espera?
9. ¿Los vendedores aceptan usar su celular personal para la app?
10. ¿Qué datos del Excel actual son confiables para la carga inicial?
11. ¿Quién mantendrá el catálogo y los precios después del lanzamiento?

## Entregables esperados

Hay dos tipos de entregable. No se piden a la misma persona.

### Lo que debe producir la IA

Son los cinco puntos que pide la sección "Rol y objetivo":

1. Plan de implementación con el enfoque técnico y su justificación.
2. Modelo de datos con entidades, campos clave y relaciones.
3. Listado de pantallas con su propósito, contenido y acciones.
4. Desglose de tareas por semana, con hitos de piloto y lanzamiento.
5. Lista de riesgos con su probabilidad, impacto y mitigación.

### Lo que entrega el equipo de desarrollo

Parten del plan anterior y se acuerdan con el negocio antes de empezar:

1. Bocetos o prototipo navegable de las pantallas principales.
2. App web desplegada, con usuarios de prueba y datos iniciales cargados.
3. Guía de uso breve para vendedores y bodega.
4. Procedimiento de respaldo y restauración documentado.
5. Lista de mejoras candidatas para la V2.

---

*Generado como ejemplo por piloto.dev*