ADRs — Registro de decisiones

Historial curado de decisiones de arquitectura y puntos clave del proyecto. Es la fuente única para recuperar contexto de decisiones — no hace falta consultar tareas archivadas del dueño.

Cómo agregar una: al cerrar una tarea que tomó una decisión no obvia (modelado, regla de negocio, tradeoff técnico), agrega un ADR nuevo aquí con el próximo número y súmalo a la tabla.

#	Decisión
0001	Multi-tenant por organizationId
0002	Tres clientes desacoplados: backend, admin web, mobile
0003	Captura única del dato; el reporte semanal se genera, no se llena
0004	Polyrepo con rama compartida por tarea
0005	Módulos de negocio se implementan backend → admin → mobile
0006	Envelope de respuesta uniforme {data, message, statusCode}
0007	organizationId siempre se lee del JWT
0008	Config tipada y validación fail-fast (Joi)
0009	Hashing con argon2, no bcrypt
0010	Tabla única verification_tokens para todos los tipos de token
0011	Jobs y crons centralizados en src/jobs/
0012	Swagger obligatorio en cada endpoint
0013	Registro de cuenta en 3 fases (solo admin web) — superseded por 0050
0014	Refresh token en cookie httpOnly / Drift; access solo en memoria; nunca localStorage
0015	Los permisos no viajan en el JWT
0016	backfillDefaultPermissions es conservador
0017	Admin: arquitectura feature-based, cada feature es isla
0018	Admin: TanStack Query para servidor, Zustand solo para sesión
0019	Admin: estado del menú lateral vive en AppLayout, no en NavContent
0020	Admin: Shadcn + tokens semánticos, prohibido hardcodear colores
0021	Mobile: patrón offline-read + online-write
0022	Mobile: derivados y summaries del backend se cachean en Drift
0023	Mobile: Drift fijado a >=2.28 <2.31
0024	Gates de cierre: qué corre automático y qué queda excluido a propósito
0025	CI por repo, lint después de prisma generate
0026	Mobile: CI pinnea la versión de Flutter, no usa channel: stable
0027	Piscinas: tope lb/ha único por piscina
0028	Ciclos: apertura por siembra o transferencia; invariante de una activa por piscina
0029	Muestreos: biomasa solo existe si hay Population el mismo día que el Sampling
0030	Alimentación: FCR usa la biomasa del último muestreo disponible
0031	Parámetros de agua: se registran por PISCINA, no por ciclo
0032	Eventos: piscina obligatoria, ciclo opcional; onDelete SetNull
0033	Raleos y cosecha final: una sola entidad Harvest con type
0034	La documentación se muda a camaroneras_docs (VitePress)
0035	El spec OpenAPI cubre solo bodies de request, no responses (superada por 0036)
0036	El spec OpenAPI cubre también los responses (DTOs de respuesta en el backend)
0037	CI backend: cache de node_modules/Prisma con actions/cache, no job+artifact
0038	Capa de plataforma (superadmin) cross-tenant con superficie de auth aislada
0039	Panel de plataforma en repo propio + enforcement server-side de mustChangePassword
0039	Tests e2e: base aislada y desechable, reset por SQL directo (no migrate reset)
0040	Tests e2e: bootstrap compartido y bind explícito en IPv4 loopback
0041	Seed de demo: idempotencia por piscina y guard de entorno por nombre de base
0042	Guía de alimentación: unidades del factor de la curva (kg = c/m² × ha × factor)
0043	Raleos: extender Harvest con estado planificado/ejecutado (no un modelo aparte)
0044	Reporte semanal: ventana móvil de 7 días (no pestañas de calendario), sin export en v1
0045	Paginación server-side opcional con meta global en el envelope
0046	Dashboard de producción: ruta /produccion (no /dashboard) y kpis no filtrables
0047	No extraer un componente de tabla compartido para ResumenTable/SectorTable
0048	RBAC de plataforma con tablas propias (no reuso del modelo de tenant)
0049	Alta delegada de tenants: reusar /auth/onboarding, no reimplementarlo
0050	Alta de cuentas solo por invitación: retiro del signup público
0051	Gestión cross-tenant de usuarios y roles de tenant desde plataforma
0052	Operator pasa de solo-lectura a operador de soporte
0053	Hardening del invariante "último administrador" con advisory locks
0054	Mobile: sync de catálogos (sectores, piscinas, tipos de equipo) usa hard replace, no upsert
0055	Mobile: cola de escrituras offline (outbox) con idempotencia best-effort en backend
0056	Mobile: política de reintentos del outbox y preservación entre sesiones
0057	Motor de scoring KPI: umbrales configurables en BD, "sin dato" uniforme y recomendación por reglas
0058	Cycle gana seasonYear/seasonNumber: temporada por orden cronológico, no por conteo al crear
0059	FCA por talla reusa los tramos del criterio FCA; Prioridades es página propia con endpoint dedicado
0060	Sobrevivencia estimada: censo por consumo con el factor crudo, no kgSugeridosDia
0061	Las fórmulas de valores calculados viven en referencia/, no en los *-flow.md
0062	Topología de despliegue: Railway para el runtime, Cloudflare Pages para los estáticos
0063	Redis se configura con una connection string (REDIS_URL), no con host y puerto