# Arquitectura — Zeitune Logística

Stack aceptado (decisiones `0002` y `0003`). Motivos de cada elección en
`docs/decisiones/`.

## Stack

| Capa | Elección | Decisión |
|---|---|---|
| Framework | Next.js (App Router) + TypeScript | `0003` (Next.js lo fija el cliente) |
| Runtime | Node.js 24 LTS | `0003` |
| Base de datos | MariaDB 10.11 | `0003` (la fija el cliente) |
| Acceso a datos y migraciones | Drizzle ORM (dialecto MySQL, driver `mysql2`) y drizzle-kit | `0003` |
| Interfaz | Mantine, PWA instalable | `0003` |
| Escaneo EAN13 | `@zxing/browser` (cámara); lector USB/Bluetooth como teclado | `0003` |
| Autenticación | Sesión propia en la base, cookie `httpOnly`, bcrypt | `0003` |
| Permisos | Pantallas y acciones agrupadas en roles, más adicionales por usuario | `0002` |
| Validación | Zod | `0003` |
| Correo | SMTP (`PT-08`); librería a elegir en la Etapa 6 | — |
| Tests | Vitest (reglas de negocio), Playwright (flujos) | `0003` |

## Servidor

AlmaLinux 9.8 · Apache 2.4.62 · MariaDB 10.11.18 · SELinux enforcing.
Sin Node.js (`PT-03`). Relevado el 11/11/2026. Desarrollo y producción
corren en el mismo servidor.

## Entornos

| | Desarrollo | Producción |
|---|---|---|
| Base | `logistica_dev` | `logistica_prod` |
| Puerto Node | 3001 | 3000 |
| Servicio systemd | `logistica-dev` | `logistica-prod` |
| Dominio | INCIERTO (`PT-05`) | INCIERTO (`PT-05`) |
| Quién opera | Agente y mantenedor | Solo el mantenedor |

Apache hace de reverse proxy hacia cada puerto, con HTTPS (`PT-06`).
Variables de entorno en `.env.local`; `.env.example` las lista sin valores.

## Modelo de datos (propuesta)

Nombres de tabla tentativos; el diccionario definitivo va en
`docs/modelo_datos.md` con la primera migración.

```
sucursal ─┬─< deposito
          └─< usuario ─┬─< usuario_deposito >─ deposito   (uno marcado por defecto)
                       ├─< usuario_rol >─ rol ─< rol_permiso
                       ├─< usuario_permiso                 (adicionales)
                       └─< sesion

proveedor   departamento   empresa_transporte   configuracion

hoja_ruta ─< orden_preparacion ─< bulto
    │                                 │
    └── despacho (1:1) ─< remito_carga └─< recepcion_item >─ recepcion

historial_estado   (tipo de documento, id, estado anterior y nuevo, motivo, usuario, fecha)
numerador          (tipo de documento, prefijo, último número)
```

- **Usuario:** pertenece a una sucursal; `usuario_deposito` solo admite
  depósitos de esa sucursal (`RN-02`).
- **Herencia sin copias:** el bulto no guarda proveedor, departamento ni
  depósitos; los lee de su OP. Los bultos de una HR son los de sus OP.
- **`recepcion_item`:** cada escaneo en una RC, con el resultado
  (recibido, abierto, dañado, ajeno, rechazado) y el código leído. Así se
  registran también códigos ajenos o inexistentes (`RN-28`, `RN-29`). Las
  observaciones de la RC se arman con estos ítems más un texto libre.
- **Unicidad del bulto** (`RN-11`): índice único sobre el código; dos
  escaneos simultáneos del mismo código no pueden crear dos bultos.
- **Numeradores** (`RN-14`, `RN-19`, DS, RC): tabla `numerador` bloqueada con
  `SELECT … FOR UPDATE` dentro de la transacción que crea el documento.
- **Permisos:** el catálogo de pantallas y acciones vive en el código
  (`src/server/permisos/catalogo.ts`); la base guarda solo las claves
  asignadas (`0002`).

## Estados

Un módulo común en `src/server/estados/` define, para cada tipo de documento,
la lista numerada de estados, las transiciones permitidas, el permiso que
exige cada una y sus condiciones (por ejemplo, `RN-21` para cerrar una HR).

- La lista desplegable (`RF-25`) se arma desde el servidor con el estado
  anterior y el siguiente permitidos para ese usuario.
- Retroceder exige motivo (`RN-06`); todo cambio queda en
  `historial_estado`, en la misma transacción.
- Las transiciones automáticas (HR a Recepción, Recibida u Observada; OP a
  Asignada) ocurren en la misma transacción que el escaneo o la asignación
  que las dispara.
- **Cancelación automática** (`RN-32`): un script del proyecto
  (`npm run tarea:cancelar-hr`) que corre con un timer de systemd a las 23:55.
  El agente deja la unidad en `deploy/`; el mantenedor la instala (`PT-09`).
- **Correo al despachar** (`RF-31`): se envía después de confirmar la
  transacción; si el envío falla, la HR queda Despachada igual y el error se
  registra para reintentarlo.

## Escaneo

Un componente único de escaneo sirve para OP, Carga y RC:

- Campo de texto con foco permanente: recibe lo que escribe el lector (que
  termina con Enter) o lo que tipea el usuario.
- Botón de cámara: abre el visor de `@zxing/browser`, limitado a EAN13.
- Validación del dígito verificador en el cliente para avisar al instante, y
  validación completa en el servidor (`RN-09` a `RN-11`, `RN-23`, `RN-28`,
  `RN-29`).
- Respuesta visible y sonora: verde si se aceptó, rojo con el motivo si no.
  Evita lecturas dobles del mismo código en menos de 2 segundos.

## Estructura del código

```
logistica/
├─ drizzle/                  # migraciones SQL generadas por drizzle-kit (versionadas)
├─ drizzle.config.ts
├─ src/
│  ├─ db/
│  │  ├─ schema/             # esquema de Drizzle, un archivo por área
│  │  └─ seed.ts             # maestros de prueba, 5 roles, catálogo de permisos
│  ├─ app/
│  │  ├─ (auth)/ingreso
│  │  ├─ (app)/ordenes, armado, hojas-ruta, despacho, recepcion, paneles, perfil
│  │  └─ (app)/admin/sucursales, depositos, usuarios, roles, permisos, proveedores, departamentos, transportes, configuracion
│  ├─ server/                # lógica de negocio: estados, numeradores, permisos, bultos, visibilidad
│  └─ components/            # interfaz reutilizable, incluido el escáner
├─ scripts/                  # tareas programadas (cancelación de HR) y utilidades (db:estado)
├─ tests/                    # e2e de Playwright
├─ deploy/                   # systemd, vhosts de Apache, script de despliegue
├─ maqueta/                  # maqueta navegable estática para el cliente (no es parte de la aplicación; ver su README)
└─ docs/
```

## Despliegue

Lo ejecuta el mantenedor, nunca el agente:

```
git pull → npm ci → npm run build → npx drizzle-kit migrate → systemctl restart logistica-prod
```

El script y la configuración van en `deploy/`. Backup de producción en
`PT-07`.
