# Contexto del Proyecto: Zeitune Logística

## Rol del Agente

Sos un desarrollador Senior que construye **desde cero** una aplicación web
responsiva para el despacho y seguimiento de bultos entre los depósitos de una
empresa: hojas de ruta, órdenes de preparación, bultos, despacho y recepción.

**Etapa actual y avance:** ver `docs/seguimiento.md`. Este archivo contiene
reglas estables; el estado del proyecto **no** se anota acá.

**ALCANCE:** trabajás ÚNICAMENTE sobre el entorno de desarrollo. Producción
corre en **el mismo servidor**, así que la separación depende de vos: nunca
ejecutás comandos, consultas, migraciones ni reinicios contra la base, el
servicio o los archivos de producción. Si una tarea parece requerirlo,
detenete y preguntá.

---

## Idioma

Respondé siempre en español (Argentina). Los comentarios en el código, los
mensajes de commit y la documentación también van en español. Los
identificadores del código (variables, funciones, tablas, campos) van en
español sin acentos ni ñ, en `camelCase` para TypeScript y `snake_case` para
la base, salvo que una decisión (`docs/decisiones/`) diga otra cosa.

---

## Documentación del proyecto

Mapa completo en `docs/README.md`. Resumen de qué va dónde:

| Archivo / carpeta | Qué contiene | Cuándo se actualiza |
|---|---|---|
| `CLAUDE.md` | Reglas estables para el agente | Cuando cambia una regla o una decisión de fondo |
| `docs/seguimiento.md` | Etapas, avance por módulo, próximos pasos | Al cerrar cada tarea que mueva el avance |
| `docs/pendientes.md` | Preguntas al cliente (`PR-NN`) y pendientes técnicos (`PT-NN`) | Al abrir o resolver un pendiente |
| `docs/requerimientos/requerimientos.md` | Requerimientos (`RF-NN`) y reglas de negocio (`RN-NN`) consolidados | Cuando el cliente define o cambia algo |
| `docs/decisiones/NNNN-tema.md` | Decisiones de arquitectura y diseño (ADR) | Al tomar una decisión que no es obvia por el código |
| `docs/arquitectura.md` | Stack, entornos, estructura del código, despliegue | Cuando cambia alguno de esos puntos |
| `docs/modelo_datos.md` | Diccionario de datos: qué significa cada tabla y campo | Con cada migración que cambie el modelo |
| `docs/revisiones/AAAAMMDD-NN_tema.md` | Registro de cada tarea | Al terminar cada tarea (skill `registro-trabajo`) |

### Reglas de documentación

- **Una sola fuente por dato.** Si algo ya está en un documento, los demás lo
  referencian por archivo e ID; no lo copian.
- **IDs estables.** `RF-`, `RN-`, `PR-`, `PT-` y los números de decisión no se
  reutilizan ni se renumeran. Lo que se descarta se marca como tal y queda.
- **Lo no definido se marca `INCIERTO`** y se abre un `PR-NN` en
  `docs/pendientes.md`. No inventes una regla de negocio para destrabar el
  código: si hace falta avanzar, implementá la opción más fácil de cambiar,
  anotala como supuesto en el registro y dejá el `PR-NN` abierto.
- **Decisiones:** toda elección entre alternativas razonables (librería,
  modelo de datos, criterio de negocio confirmado por el cliente) lleva un
  archivo en `docs/decisiones/` con contexto, opciones, decisión y
  consecuencias. Una decisión no se edita: si cambia, se crea otra que la
  reemplaza y se marca la vieja como `Reemplazada por NNNN`.
- **Fuentes originales** del cliente (la definición en `docs/borradores/`)
  no se editan: son el punto de partida.
  `docs/requerimientos/requerimientos.md` es la versión consolidada y viva.

---

## Stack Tecnológico

Detalle y motivos en `docs/arquitectura.md` y `docs/decisiones/`.

- **Aplicación:** Next.js (App Router) + TypeScript, un solo proyecto para
  frontend y backend.
- **Base de datos:** MariaDB 10.11 (instalada en el servidor), con Drizzle
  ORM y drizzle-kit.
- **Interfaz:** responsiva, PWA, escaneo de EAN13 por cámara y lector.
- **Servidor:** AlmaLinux 9.8, Apache 2.4 como reverse proxy con HTTPS.

No agregues dependencias sin motivo: cada librería nueva se justifica en el
registro de la tarea, y si es estructural (UI, auth, ORM, estado), en una
decisión.

---

## Base de Datos

| Base | Entorno | Quién la toca |
|---|---|---|
| `logistica_dev` | Desarrollo | El agente, con el usuario de desarrollo |
| `logistica_prod` | Producción | **Solo el mantenedor** |

- **Cambios de estructura solo por migraciones de drizzle-kit**
  (`drizzle/`), generadas con `drizzle-kit generate` y revisadas antes de
  aplicarse. Nunca `ALTER` / `CREATE` a mano ni `drizzle-kit push`.
- El agente puede ejecutar `drizzle-kit migrate` **únicamente contra
  `logistica_dev`**. A producción las aplica el mantenedor durante el
  despliegue.
- Una migración ya aplicada en producción **no se edita**: se corrige con una
  migración nueva.
- Cada migración que cambie el modelo actualiza `docs/modelo_datos.md` en la
  misma tarea.
- Tablas InnoDB, `utf8mb4` / `utf8mb4_unicode_ci`, con claves foráneas.
- **No hay bajas físicas** de maestros ni documentos: se deshabilitan
  (campo `activo`) o cambian de estado. Las hojas de ruta no se eliminan.
- Los datos de prueba se crean con el seed (`src/db/seed.ts`), no a mano. Si
  hace falta cargar algo a mano, se documenta en el registro.

---

## Forma de trabajo

- **Por tarea chica y verificable.** Cada tarea termina con: código, tests,
  verificación, registro de trabajo y actualización de `docs/seguimiento.md`
  y `docs/pendientes.md` si corresponde.
- **Un commit por tarea** (o varios si mezcla tipos de cambio), en español:
  título corto en imperativo o sustantivo, cuerpo que explique el porqué y
  nombre el registro. El registro se commitea junto con el código que
  documenta. Solo se commitea cuando el usuario lo pide.
- **Reglas de negocio con test.** Toda regla `RN-NN` implementada tiene al
  menos un test que la nombra (`it('RN-07: …')`), para poder rastrearla.
- La lógica de negocio (estados, numeradores, permisos, cálculos) vive en
  `src/server/`, no en componentes ni en route handlers.
- Toda acción del servidor valida sesión, rol y sucursal/depósito del
  usuario. No confíes en lo que oculta la interfaz.

### Comandos de verificación

```bash
npm run lint          # ESLint
npm run typecheck     # tsc --noEmit
npm test              # Vitest: reglas de negocio
npm run test:e2e      # Playwright: flujos en el navegador
npm run db:estado     # migraciones aplicadas en dev
```

Antes de dar una tarea por terminada: `lint`, `typecheck` y `test` sin
errores. Si algo no se pudo verificar, se dice en el registro.

### Verificación en el navegador

- Playwright con Firefox o Chromium sin ventana, contra la instancia de
  desarrollo. Las capturas van al scratchpad, nunca al repositorio.
- Probar siempre en ancho de celular (390 px) y de escritorio: la aplicación
  se usa mayormente desde el celular en los depósitos.

---

## Entorno de Desarrollo

- **Permisos:** el árbol `/home/html` usa setgid + ACL para el grupo `apache`.
  Si aparece un `Permission denied`, revisá `getfacl` y el contexto de
  SELinux. **Nunca propongas `chmod 777` ni ejecutar el editor con sudo.**
- **SELinux** está en enforcing. Un 403 o un proxy que no conecta suele ser
  `restorecon` o un booleano (`httpd_can_network_connect`), no permisos.
- **Credenciales:** en `.env.local` y `.claude/credenciales.local.md`, fuera
  del control de versiones. No las transcribas en respuestas, registros ni
  archivos versionados. `.env.example` lista las variables sin valores.
- Configuración de servidor (systemd, Apache, Node) que requiera `sudo`: el
  agente la escribe en `deploy/` y **el mantenedor la aplica**.

---

## Registro de trabajo

Al terminar cada tarea, dejá un registro en `docs/revisiones/AAAAMMDD-NN_tema.md`
siguiendo la skill `registro-trabajo` (`.claude/skills/registro-trabajo/SKILL.md`).

Es documentación para el mantenedor, no un transcript: tiene que servir dentro
de un año.

---

## Resumen de prohibiciones

1. Tocar la base, el servicio, la configuración o los archivos de producción.
2. Cambiar la estructura de la base fuera de una migración de drizzle-kit, o
   editar una migración ya aplicada en producción.
3. Borrar físicamente maestros o documentos (hojas de ruta, órdenes, bultos).
4. Inventar reglas de negocio no definidas: se marcan `INCIERTO` con su
   `PR-NN`.
5. Editar las fuentes originales del cliente.
6. Commitear credenciales o datos reales, o hacer commit sin que se pida.
7. Usar `chmod 777` o sudo para resolver problemas de permisos.
