# Requerimientos — Zeitune Logística

Versión consolidada y viva de los requerimientos. Versión 4 — 11/11/2026.

- **Fuentes** (en `docs/borradores/`, no se editan): `Aplicación Zeitune
  Logística.md` (en adelante, "el principal"), `Bultos.md`,
  `OP - OrdenDePreparacion.md`, `HR - HojasDeRuta.md`, `DS - Despacho.md`,
  `RC - Recepcion.md`, `RoldeUsuarios.md` y `EAN_ejemplo.png`. En la columna
  "Fuente" se citan como principal, Bultos, OP, HR, DS, RC y Roles. Las
  respuestas del cliente se citan con su `PR` (resueltos en
  `docs/pendientes.md`); cuando contradicen a un borrador, manda la respuesta.
- **INCIERTO:** lo que las fuentes no definen o definen de forma
  contradictoria. Cada uno remite a su pregunta en `docs/pendientes.md`.
- **(Propuesta técnica):** regla agregada por el equipo, no pedida por el
  cliente. Se aplica salvo que el cliente diga otra cosa.
- **Supuesto:** lo que se implementa mientras el `PR` esté abierto, elegido
  por ser lo más fácil de cambiar.

## 1. Objetivo

Aplicación web responsiva (navegador y celular) para el despacho y
seguimiento de bultos que la empresa envía entre sus depósitos. Usa la cámara
del dispositivo o un lector para leer los códigos EAN13 de los bultos. Incluye
el armado de los documentos (OP, HR, DS, RC), su seguimiento y paneles con
indicadores para seguir los envíos y el estado de cada bulto. Funciona con
conexión (`PR-22`).

Glosario:

| Sigla | Documento | Qué es |
|---|---|---|
| OP | Orden de preparación | Bultos de un proveedor y departamento para un depósito de destino. Es donde nacen los bultos. |
| HR | Hoja de ruta | Las OP (y por lo tanto los bultos) que viajan en un mismo camión, de un depósito de origen a uno de destino. |
| DS | Despacho | Datos del despacho de una HR: transporte, patente y remitos de carga. |
| RC | Recepción | Bultos recibidos en un depósito de destino, con su estado y observaciones. |
| CD | Código de departamento | Código de 3 dígitos del departamento (`PR-11`). |

## 2. Requerimientos funcionales

### Configuración y administración

| ID | Requerimiento | Fuente | Notas |
|---|---|---|---|
| `RF-01` | Alta y modificación de sucursales: código, nombre, correo para la información de envíos a sus depósitos y marca "ve todas las sucursales". | principal, `PR-21` | Ver `RN-04` |
| `RF-02` | Alta y modificación de depósitos: código, nombre y sucursal (de las existentes). | principal | Código: `RN-03` |
| `RF-03` | Alta y modificación de usuarios: código, nombre, contraseña, sucursal, uno o más depósitos de esa sucursal (uno por defecto) y uno o más roles. | principal, `PR-01`, `PR-03` | `RN-02` |
| `RF-04` | Alta y modificación de roles: código, pantallas (ítems de menú) y acciones a los que da acceso. | principal, `PR-02` | `RN-30`, decisión `0002` |
| `RF-05` | Pantalla de permisos: se elige un usuario y, en un panel lateral, las pantallas y acciones a las que accede: las de sus roles más otras adicionales. | principal, `PR-02` | |
| `RF-06` | Alta y modificación de empresas transportistas. | Roles, `PR-11` | Campos: supuesto código y nombre |
| `RF-07` | Configuración del sistema: prefijo del remito de carga. | DS | |
| `RF-08` | Ingreso con código de usuario y contraseña. Se trabaja en el depósito por defecto del usuario, y puede cambiarse a otro de sus depósitos. | `PR-01`, `PR-03` | |
| `RF-32` | Alta y modificación de proveedores: código de 4 dígitos numéricos y nombre. | `PR-11` | Nombre: supuesto |
| `RF-33` | Alta y modificación de departamentos: código (CD) de 3 dígitos y nombre. | `PR-11` | Nombre: supuesto |

### Órdenes de preparación

| ID | Requerimiento | Fuente | Notas |
|---|---|---|---|
| `RF-09` | Crear una OP: depósito de origen (por defecto el de trabajo del usuario, modificable entre sus depósitos), depósito de destino, proveedor, departamento, cantidad inicial de bultos, usuario asignado (opcional) y HR (opcional). | principal, OP, `PR-04` | |
| `RF-10` | Pantalla de armado: el usuario de Preparación ve las OP pendientes sin asignar o asignadas a él, y las que tiene en preparación. Al tomar una, queda como usuario asignado y la OP pasa a Preparación. | principal, OP, Roles, `PR-23` | `RN-17` |
| `RF-11` | Cargar bultos en una OP escaneando el EAN13 con la cámara o un lector, o tipeándolo; quitar bultos de la OP. | principal, Bultos | |
| `RF-12` | Pasar la OP a Terminada al finalizar la carga. | principal, OP | `RN-31` |

### Hojas de ruta

| ID | Requerimiento | Fuente | Notas |
|---|---|---|---|
| `RF-13` | Crear una HR con calendario: fecha, horario (mañana / tarde), depósito de origen (por defecto el de trabajo del usuario) y depósito de destino. Puede haber varias para la misma fecha y horario. | principal, HR | |
| `RF-14` | Agregar OP a una HR, quitarlas y pasarlas a otra HR. | principal | `RN-15`, `RN-16` |
| `RF-15` | Cancelar una HR vacía a mano, y automáticamente a las 23:55 de su fecha. | principal, HR, `PR-09` | `RN-32` |
| `RF-16` | Listado de HR con sus OP y bultos, y los bultos que faltan escanear en cada etapa. | Roles | |

### Despacho

| ID | Requerimiento | Fuente | Notas |
|---|---|---|---|
| `RF-17` | Despacho: el usuario elige el destino, ve las HR cerradas, toma una (pasa a Carga) y escanea sus bultos, viendo cuáles faltan. | principal, HR, Roles | |
| `RF-18` | Crear el DS de una HR en Carga con todos sus bultos escaneados: empresa transportista, patente y uno o más remitos de carga, cada uno con prefijo, número y valor declarado. | principal, DS, `PR-12`, `PR-25` | `RN-27` |
| `RF-19` | Imprimir el remito de carga sobre un formulario preimpreso. | principal | Formato pendiente: `PR-13` |

### Recepción

| ID | Requerimiento | Fuente | Notas |
|---|---|---|---|
| `RF-20` | Crear una RC en el depósito de trabajo y escanear los bultos que llegan, de una o varias HR. | principal, RC | |
| `RF-21` | Al escanear, marcar el bulto como recibido, abierto o dañado. | principal | |
| `RF-22` | Registrar en las observaciones de la RC los bultos que no corresponden al depósito, los códigos rechazados y los abiertos o dañados. | principal, `PR-15` | `RN-28`, `RN-29` |
| `RF-23` | Cerrar la RC. | RC | |
| `RF-24` | ~~Marcar una HR como Observada a mano.~~ **Descartado:** Observada es solo automática (`RN-25`). | HR | `PR-24` |
| `RF-35` | Un supervisor marca como Incompleta una HR en Recepción a la que le faltan bultos que no van a llegar. | mantenedor (11/11/2026) | `RN-37` |

### Cambios de estado

| ID | Requerimiento | Fuente | Notas |
|---|---|---|---|
| `RF-25` | Cambio de estado con una lista que ofrece el estado anterior y el siguiente, con el siguiente preseleccionado. | principal | `RN-05`, `RN-06` |
| `RF-26` | Historial de estados de cada documento: estado anterior y nuevo, usuario, fecha y hora, y motivo si fue un retroceso. | principal (motivo) | Resto: (Propuesta técnica) |

### Paneles de seguimiento y avisos

| ID | Requerimiento | Fuente | Notas |
|---|---|---|---|
| `RF-27` | Panel "Estado de HR y OP": OP generadas en la sucursal; HR generadas en la sucursal y HR con destino en la sucursal desde Despachada en adelante, sin las Canceladas. Roles: Despacho, Recepción, Supervisor. Filtros: tipo, depósito de origen, estado. | principal | |
| `RF-28` | Panel "Detalle de RC": RC de la sucursal, con sus HR y bultos. Roles: Recepción, Supervisor. Filtros: tipo, depósito de origen, estado. | principal | |
| `RF-29` | Panel "Detalle de DS": DS de la sucursal, con su HR y bultos. Roles: Despacho, Supervisor. Filtros: tipo, depósito de origen. | principal, `PR-16` | Sin filtro por estado: el DS no tiene estados |
| `RF-30` | Panel "Bultos abiertos o dañados", con los datos de su HR. Rol: Supervisor. Filtros: RC, depósito de origen, HR. | principal | |
| `RF-31` | Al pasar una HR a Despachada, enviar un correo a la sucursal del depósito de destino con los datos del DS y el número de HR. | principal, `PR-14` | SMTP: `PT-08` |
| `RF-34` | Indicadores de seguimiento: además de los paneles `RF-27` a `RF-30`, los que el equipo proponga por su valor, validados con el cliente en la Etapa 6. | `PR-19`, `PR-26` | |

## 3. Reglas de negocio

### Generales

| ID | Regla | Fuente |
|---|---|---|
| `RN-01` | No hay bajas físicas: los maestros se deshabilitan; las HR sin usar se cancelan. | HR; resto (Propuesta técnica, y `CLAUDE.md`) |
| `RN-02` | Un usuario pertenece a una sucursal y tiene uno o más depósitos de esa sucursal, uno de ellos por defecto, y al menos un rol. Opera solo en sus depósitos. | `PR-03` (reemplaza "una o más sucursales" del principal) |
| `RN-03` | El código de depósito es numérico, de 01 a 99: va en las 2 primeras posiciones del EAN13 y, completado a 5 dígitos, es el prefijo de la HR. | HR, Bultos, `PR-05` |
| `RN-04` | Cada usuario ve los documentos de su sucursal y de sus depósitos según cada pantalla. Los usuarios con el permiso "ver todas las sucursales" cuya sucursal tenga la marca "ve todas" ven todo sin límite de sucursal. | principal, `PR-21`; el seed da ese permiso al rol Supervisor |

### Estados

| ID | Regla | Fuente |
|---|---|---|
| `RN-05` | Cada tipo de documento tiene sus estados numerados; se avanza al siguiente sin saltear estados. | principal |
| `RN-06` | Volver al estado anterior exige confirmación y un motivo obligatorio, que queda en el historial. | principal |
| `RN-07` | Excepciones a la secuencia: HR a Cancelada (vacía, a mano o automática); HR a Recepción, Recibida u Observada (automáticas, `RN-25`); HR a Incompleta (`RN-37`); OP a Asignada (automática, `RN-36`). | HR, `PR-10`, `PR-24` |

### Bultos

| ID | Regla | Fuente |
|---|---|---|
| `RN-08` | El bulto nace al cargarse en una OP; su código es el EAN13 de la etiqueta. | Bultos |
| `RN-09` | El código debe ser un EAN13 válido (dígito verificador). | Bultos |
| `RN-10` | Las 2 primeras posiciones del código son el depósito de destino y deben coincidir con el depósito de destino de la OP. | Bultos, `PR-05` |
| `RN-11` | El código es único en todo el sistema: si ya existe, se avisa claramente y no se ingresa. | Bultos |
| `RN-12` | Proveedor, departamento, depósitos de origen y destino y usuario del bulto son los de su OP. | Bultos |
| `RN-13` | Los bultos se agregan o quitan de una OP solo mientras está en Preparación. | principal ("armado"), Roles |

### Órdenes de preparación

| ID | Regla | Fuente |
|---|---|---|
| `RN-14` | El número de OP es secuencial de 8 dígitos y lo genera el sistema. | OP |
| `RN-15` | Una OP, en cualquier estado, se agrega a una HR solo si la HR está Abierta o en Preparación y tiene el mismo depósito de origen y de destino. Puede hacerse al crear la OP. | principal, `PR-07` (a), `PR-27`; mismos depósitos: (Propuesta técnica) |
| `RN-16` | Una OP se pasa a otra HR solo si ambas están en Preparación. | principal |
| `RN-17` | Al tomar una OP pendiente, el usuario de Preparación queda como usuario asignado y la OP pasa a Preparación. | OP, `PR-23` |
| `RN-31` | Si al terminar una OP la cantidad de bultos difiere de la inicial, se avisa y se pide confirmar que la diferencia es correcta. | `PR-06` |
| `RN-36` | La OP pasa a Asignada automáticamente cuando está Terminada y pertenece a una HR: al terminarla, si ya tenía HR, o al agregarla después a una HR. Asignar un usuario no cambia el estado. | OP, `PR-23` (reemplaza `PR-07` (b)) |

### Hojas de ruta

| ID | Regla | Fuente |
|---|---|---|
| `RN-18` | El prefijo de la HR es el código del depósito de origen, 5 dígitos completados con ceros (depósito 1 → `00001`). | HR |
| `RN-19` | El número de HR es consecutivo dentro de cada prefijo. | HR |
| `RN-20` | Una HR solo se cancela si no tiene ninguna OP. | principal, HR |
| `RN-21` | Para cerrar una HR, todas sus OP deben estar Terminadas (por `RN-36`, ya Asignadas). | `PR-07` (c) |
| `RN-22` | Para modificar una HR Cerrada, un supervisor la vuelve a Preparación (`RN-06`). Desde Despachada no se modifica. | principal |
| `RN-23` | En Carga, solo se pueden escanear bultos de la HR; si el bulto no corresponde, se avisa y no cambia de estado. | principal |
| `RN-24` | La HR pasa a Despachada solo si todos sus bultos están despachados y existe su DS. | principal, HR |
| `RN-25` | Al escanearse en recepción el primer bulto de una HR Despachada, la HR pasa a Recepción. Cuando todos sus bultos fueron recibidos (contando abiertos y dañados), pasa a Recibida, o a Observada si alguno llegó abierto o dañado. | HR, `PR-08`, `PR-10` |
| `RN-32` | A las 23:55 de cada día, las HR sin OP en estado Abierta o Preparación con fecha de ese día o anterior pasan a Cancelada. | `PR-09`; fechas anteriores: (Propuesta técnica) |
| `RN-33` | El usuario que confirma la HR es el que la cierra; si se reabre y se vuelve a cerrar, queda el último. | `PR-18`; reapertura: supuesto |
| `RN-35` | Si una HR vuelve de Carga a Cerrada, sus bultos despachados vuelven a Preparado. | `PR-20` |
| `RN-37` | Solo un supervisor pasa una HR a Incompleta, y solo desde Recepción (con bultos sin recibir). Exige un motivo. Los bultos que faltan quedan Despachados. | mantenedor (11/11/2026); estado de origen y número: supuesto (`PR-28`); motivo: (Propuesta técnica) |

### Despacho y recepción

| ID | Regla | Fuente |
|---|---|---|
| `RN-26` | Un DS por HR; se crea solo con la HR en Carga y todos sus bultos escaneados. | DS, principal |
| `RN-27` | En cada remito de carga, el sistema propone el prefijo de la configuración y sugiere como número el último más uno; el usuario puede cambiar ambos y se admiten saltos. | DS; sugerencia del número: (Propuesta técnica) |
| `RN-28` | En recepción, el bulto debe estar destinado al depósito de la RC; si no, se avisa, no cambia de estado y queda en las observaciones de la RC. | principal |
| `RN-29` | Solo se reciben bultos de HR Despachadas o en Recepción. Un código inexistente o de una HR no despachada se avisa y queda en las observaciones de la RC. | `PR-15` |

## 4. Estados

### Hoja de ruta (HR)

| N.º | Estado | Lo hace | Cuándo |
|---|---|---|---|
| 1 | Abierta | Supervisor | Al crearla. |
| 2 | Preparación | Supervisor | Habilita la carga de OP. |
| 3 | Cerrada | Supervisor | Terminó el agregado de bultos (`RN-21`); queda como usuario que confirma (`RN-33`). |
| 4 | Carga | Despacho | Toma la HR para escanear los bultos que suben al camión. |
| 5 | Despachada | Despacho | Todos los bultos despachados y DS creado (`RN-24`); se envía el correo (`RF-31`). |
| 6 | Recepción | Automático | Primer bulto escaneado en destino. |
| 7 | Recibida | Automático | Todos los bultos recibidos, ninguno abierto ni dañado. |
| 8 | Observada | Automático | Todos los bultos recibidos y alguno abierto o dañado (`RN-25`). No se marca a mano (`PR-24`). |
| 9 | Cancelada | Supervisor o automático (23:55) | No se usó; debe estar vacía (`RN-20`, `RN-32`). |
| 10 | Incompleta | Supervisor | En Recepción, faltan bultos que no van a llegar (`RN-37`). Número: supuesto (`PR-28`). |

### Orden de preparación (OP)

Numeración de las fuentes, confirmada en `PR-23`.

| N.º | Estado | Cuándo |
|---|---|---|
| 1 | Pendiente | Al crearla, con o sin usuario asignado y con o sin HR. |
| 2 | Preparación | El usuario empezó a cargar bultos; al tomar una OP pendiente pasa a este estado (`RN-17`). |
| 3 | Terminada | Lista y en el sector de carga (`RN-31`). |
| 4 | Asignada | Terminada y en una HR; automático (`RN-36`). |

### Recepción (RC)

| N.º | Estado | Cuándo |
|---|---|---|
| 1 | Abierta | Al crearla. |
| 2 | Cerrada | Terminó el escaneo (`PR-16`). |

El DS no tiene estados (`PR-16`).

### Bulto

| Estado | Cuándo |
|---|---|
| Preparado | Al cargarse en una OP. |
| Despachado | Al escanearse en la Carga de su HR. La fuente dice "cuando la OP esté despachada", pero la OP no tiene ese estado; se sigue el proceso del principal. |
| Recepcionado | Al escanearse en una RC del depósito de destino. |
| Abierto | Recibido abierto. |
| Dañado | Recibido dañado o mojado. |

## 5. Roles y permisos

| Rol | Trabaja con | Puede ver |
|---|---|---|
| Preparación | OP | OP, HR (solo Abiertas o en Preparación, `RN-34`) |
| Despacho | DS | OP, HR, DS |
| Recepción | HR, RC | HR, DS, RC |
| Supervisor | OP, HR, DS, RC | OP, HR, DS, RC, US |
| Administrador | OP, HR, DS, RC, US, CF | OP, HR, DS, RC, US, CF |

US: usuarios; CF: configuración. Fuente: Roles. Es la carga inicial de
permisos del seed; el administrador puede cambiarla (decisión `0002`).

| ID | Regla | Fuente |
|---|---|---|
| `RN-30` | Las pantallas (ítems de menú) y las acciones se habilitan por permisos: un rol es un conjunto de permisos y a un usuario se le pueden sumar permisos adicionales. El servidor verifica el permiso, no el nombre del rol. | principal, `PR-02`, decisión `0002` |
| `RN-34` | El rol Preparación consulta las HR en estado Abierta o Preparación. | `PR-17` |

## 6. Datos de los documentos

Los campos heredados no se copian: se leen del documento del que vienen.

| Documento | Campos propios | Heredados |
|---|---|---|
| Bulto | Código EAN13, estado | De la OP: proveedor, departamento, depósitos de origen y destino, usuario |
| OP | Número (8 dígitos), depósito de origen, depósito de destino, proveedor, departamento, usuario asignado, usuario creador, cantidad inicial de bultos, HR, estado | — |
| HR | Fecha, horario, depósito de origen, prefijo, número, depósito de destino, usuario creador, usuario que confirma (`RN-33`), estado | Sucursal de destino (del depósito); bultos (de sus OP) |
| DS | Número (automático), fecha, empresa transportista, patente, usuario | De la HR: prefijo y número, cantidad de bultos, depósito de destino |
| Remito de carga | Prefijo, número, valor declarado (`PR-25`, `RN-27`) | Del DS al que pertenece (varios por DS, `PR-12`) |
| RC | Número (automático), fecha, depósito de recepción, usuario, observaciones, estado | Por bulto: código, depósito de origen |

Maestros: proveedor (4 dígitos numéricos), departamento (CD, 3 dígitos) y
empresa transportista se eligen de tablas (`PR-11`).

## 7. Historial de cambios

| Versión | Fecha | Cambio | Registro |
|---|---|---|---|
| 1 | 11/11/2026 | Consolidación inicial de `docs/borradores/` | `20261111-02` |
| 2 | 11/11/2026 | Respuestas del cliente a `PR-01` a `PR-12` y `PR-14` a `PR-22`: usuario con depósitos de una sucursal, EAN con depósito de destino, maestros de proveedores y departamentos, varios remitos por DS, Observada automática, cancelación a las 23:55, correo al despachar, estados de OP y RC. Nuevos `RF-32` a `RF-34` y `RN-31` a `RN-36`. | `20261111-03` |
| 3 | 11/11/2026 | Respuestas a `PR-23` a `PR-27`: estados de la OP con la numeración original, OP asignable a HR Abierta, Observada solo automática (`RF-24` descartado), valor declarado por remito, indicadores a proponer. | `20261111-03` |
| 4 | 11/11/2026 | Estado 10-Incompleta de la HR, definido por el mantenedor: `RF-35`, `RN-37`, `PR-28`. | `20261111-03` |
