Índice de Documentación — Patio Abierto
Última actualización: 2026-07-09 Fuente de verdad de roles/permisos:
lib/auth/roles.ts| módulos:lib/modules.tsEste índice verifica existencia de archivos; no sustituye las fuentes de verdad en código.
1. Inventario de documentación
1.1 Manual de usuario y gobernanza
| Documento | Ruta relativa desde docs/ | Qué contiene |
|---|---|---|
| Manual de Usuario | MANUAL-USUARIO-PATIO.md | Guía operativa completa: roles, permisos, módulo por módulo, glosario, gobernanza operativa |
| Gobernanza Agéntica | governance/GOBERNANZA-AGENTICA.md | Gates formales (D-011/D-015/D-016/D-017), semáforo de autonomía, Puerta 2, flujo de trabajo del sistema multi-agente |
| Manual de Organización | governance/MANUAL-ORGANIZACION.md | Estructura organizacional, equipo de desarrollo, stack, seguridad, onboarding de sesión, SOPs embed (deploy/rollback/DB) |
| Referencia — Estructura de Repos | governance/REFERENCIA-estructura-repos.md | Mapa de repositorios relacionados (md-design-system, aduanamx, crece-v2) y sus aportes |
1.2 SOPs — Procedimientos Operativos Estándar
| SOP | Ruta relativa desde docs/ | Módulo / Ámbito | Secciones clave |
|---|---|---|---|
| Garita | sops/garita.sop.md | /garita | C1 ingreso, C2 cola salida, EIR, bloqueo/desbloqueo, checklist de turno |
| Citas | sops/citas.sop.md | /citas | Agendar cita, consultar cola, reglas e invariantes, checklist |
| Malla | sops/malla.sop.md | /malla | Consulta (lectura), asignación de posición, reglas de ocupación |
| Pipeline (Proceso + Kanban) | sops/proceso-pipeline.sop.md | /proceso y /kanban | Vista pipeline, avance de etapa, drag-and-drop, asignación de personal (ILUSTRATIVO), máquina de estados |
| Facturación | sops/facturacion.sop.md | /facturacion | Estado de cuenta, lectura, método de cobro, CFDI via Facturapi |
| Integraciones | sops/integraciones.sop.md | /integraciones | API REST v1, webhooks (ILUSTRATIVO), ERP simulado |
| Deploy | sops/deploy.sop.md | Infraestructura | Vercel, entornos, variables de entorno, activación Postgres (CEO-gated), checklist |
| Rollback | sops/rollback.sop.md | Infraestructura | Instant rollback, rollback por git, rollback con DB, checklist de incidente |
1.3 Documentación de plataforma, diseño, datos y producto
| Carpeta | Archivos representativos | Propósito |
|---|---|---|
platform/ | database.md, db-activation.md, dci-5-setbloqueo-design.md | Arquitectura de datos, activación de DB, diseño de operación setBloqueo |
design/ | MD-design-language.md, UX-audit.md | Sistema de diseño MD, auditoría UX |
data/ | demo-coverage-audit.md, WIRING-DRAFT.md | Auditoría de cobertura demo, borrador de wiring de datos reales |
research/ | gates-produccion.md, edi-baplie.md, tarifario-recintos-manzanillo.md | Gates para producción, EDI BAPLIE, tarifario de referencia |
product/ | 3d-flagship-blueprint.md, 3d-flagship-assets-manifest-*.md | Blueprints del módulo 3D, manifiestos de assets |
quality/ | integration-audit-2026-06-20.md | Auditoría de integración del sprint |
2. ¿Por dónde empiezo? — Guía por rol
admin
Acceso total: administración + todas las operaciones.
- Lee tu perfil de rol → Manual §2.1 Rol: admin
- Revisa la matriz completa de permisos → Manual §2 Matriz rol × permiso
- SOPs que necesitas dominar: todos los operativos + los de infraestructura:
- SOP Garita — supervisión de operación en garita
- SOP Facturación — estados de cuenta y CFDI
- SOP Integraciones — API REST y webhooks
- SOP Deploy — alta de versiones a Vercel
- SOP Rollback — recuperación ante incidentes
- Gates de gobernanza → Gobernanza §3 Gates formales
supervisor
Operación completa del patio (sin administración de usuarios/config).
- Lee tu perfil → Manual §2.2 Rol: supervisor
- SOPs de operación diaria:
- SOP Garita — registrar ingreso, pasar garita, bloquear/desbloquear
- SOP Citas — programar y consultar cola de citas
- SOP Malla — asignación de posiciones en el patio
- SOP Pipeline / Kanban — avanzar etapas de contenedores
- Módulos que ves en el sidebar → Manual §2.2 — Módulos que ve en el sidebar
- Permisos que tienes:
patio:ver,ingreso:registrar,garita:operar,salida:registrar,descarga:registrar,modulacion:operar,bloqueo:gestionar
operador_garita
Garita: registra salidas y opera el cruce de garita.
- Lee tu perfil → Manual §2.3 Rol: operador_garita
- SOP principal: SOP Garita
- §3 Registrar ingreso (no aplica — no tienes
ingreso:registrar) - §4 Cola de salida / pasar garita
- §5 Descargar EIR
- §3 Registrar ingreso (no aplica — no tienes
- SOP de consulta: SOP Citas §4 — consultar cola (lectura; no puedes agendar)
- Permisos que tienes:
patio:ver,garita:operar,salida:registrar
operador_patio
Patio: registra ingresos y movimientos físicos.
- Lee tu perfil → Manual §2.4 Rol: operador_patio
- SOPs de tu operación:
- SOP Garita §3 — registrar ingreso de contenedor
- SOP Malla §4 — asignar posición (usa
modulacion:operar) - SOP Pipeline / Kanban §3.2 — avanzar etapa desde Kanban
- SOP Citas §3 — agendar citas (tienes
ingreso:registrar)
- Permisos que tienes:
patio:ver,ingreso:registrar,descarga:registrar,modulacion:operar
cliente_readonly
Acceso de solo lectura al inventario del patio del tenant.
- Lee tu perfil → Manual §2.5 Rol: cliente_readonly
- Módulos visibles: Inventario, Malla, Citas, Indicadores, Operaciones, Kanban, Mapa de proceso, Almacén
- No tienes acceso a Garita, Facturación, Integraciones ni Admin
- Permiso que tienes:
patio:ver(solo lectura, sin formularios de escritura)
3. Tabla módulo → SOP → permisos
Fuente de verdad de las columnas de permiso: lib/auth/roles.ts (PERMISO, PERMISOS_POR_ROL).
Fuente de verdad de rutas: lib/modules.ts (MODULO_POR_RUTA).
| Módulo | Ruta | SOP | Permiso para ver (sidebar) | Permiso de escritura |
|---|---|---|---|---|
| Inventario | / | — (sin SOP; solo lectura) | patio:ver | — |
| Malla | /malla | malla.sop.md | patio:ver | modulacion:operar (asignar posición) |
| Garita | /garita | garita.sop.md | ingreso:registrar o garita:operar | ingreso:registrar, garita:operar, salida:registrar, bloqueo:gestionar |
| Citas | /citas | citas.sop.md | patio:ver | ingreso:registrar (agendar) |
| Indicadores | /indicadores | — (sin SOP; solo lectura) | patio:ver | — |
| Operaciones | /operaciones | — (sin SOP; solo lectura) | patio:ver | — |
| Kanban | /kanban | proceso-pipeline.sop.md | patio:ver | Según evento del pipeline (PERMISO_DE_EVENTO en lib/auth/roles.ts) |
| Mapa de proceso | /proceso | proceso-pipeline.sop.md | patio:ver | — (visualización) |
| Almacén 3D | /almacen | — (sin SOP; visualización) | patio:ver | — |
| Facturación | /facturacion | facturacion.sop.md | admin:gestionar | admin:gestionar |
Nota Kanban / evento:
PERMISO_DE_EVENTOenlib/auth/roles.tsmapea cadaTipoEventoPatioa su permiso: DESCARGA →descarga:registrar| INGRESO_PATIO →ingreso:registrar| MODULACION →modulacion:operar| GARITA_SALIDA →garita:operar| SALIDA →salida:registrar| BUQUE_ETA →null(sin permiso requerido).
4. Notas de consistencia
Revisión automática ejecutada el 2026-07-09 comparando lib/auth/roles.ts, lib/modules.ts, MANUAL-USUARIO-PATIO.md, governance/GOBERNANZA-AGENTICA.md y los 8 SOPs en docs/sops/.
C-01 — /verticales no está en MODULO_POR_RUTA (hueco menor)
Documentos afectados: MANUAL-USUARIO-PATIO.md §3.10, lib/modules.ts
El manual documenta /verticales como pantalla navegable visible a todos los roles. Sin embargo, MODULO_POR_RUTA en lib/modules.ts no incluye /verticales: la ruta devuelve null en moduloDeRuta() → el guard la trata como ruta utilitaria (default-allow). No existe constante MODULO.VERTICALES.
- Si la página es puramente informativa y sin datos de tenant: el comportamiento actual es correcto por diseño (no requiere módulo). El manual debería indicar explícitamente que es "página informativa sin guard de módulo".
- Si en el futuro se agrega lógica por tenant (p. ej. configuración activa de vertical): habrá que agregar
VERTICALESalib/modules.tsy al mapa de rutas.
Acción recomendada: Agregar una nota en el manual §3.10 aclarando que /verticales es una ruta sin módulo-guard por diseño.
C-02 — SOPs faltantes para 4 módulos de solo lectura
Documentos afectados: docs/sops/ (ausencia)
Los módulos inventario (/), indicadores (/indicadores), operaciones (/operaciones) y almacen_mapa (/almacen) están documentados en el manual (§§3.1, 3.5, 3.6, 3.9) pero no tienen SOP dedicado. Dado que son módulos de solo lectura (ninguno tiene permiso de escritura propio más allá de patio:ver), la ausencia de SOP es aceptable en el estado actual. Si se agregan acciones de escritura en el futuro, deberán crearse.
Acción recomendada: Documentar explícitamente en cada sección del manual que estos módulos son de solo lectura y no requieren SOP operativo.
C-03 — Duplicación deploy/rollback entre MANUAL-ORGANIZACION.md y SOPs
Documentos afectados: governance/MANUAL-ORGANIZACION.md §§10.1–10.2, sops/deploy.sop.md, sops/rollback.sop.md
El manual de organización reproduce los procedimientos de deploy y rollback en sus secciones §10.1 y §10.2, mientras que los SOPs dedicados existen como fuentes separadas. Si se actualiza uno, el otro no se actualiza automáticamente → riesgo de drift entre versiones.
Acción recomendada: Que MANUAL-ORGANIZACION.md §§10.1–10.2 referencie los SOPs en lugar de reproducirlos (ver docs/sops/deploy.sop.md / ver docs/sops/rollback.sop.md).
C-04 — modulacion:operar gatea tanto Kanban como asignación en Malla
Documentos afectados: sops/malla.sop.md §4, lib/auth/roles.ts PERMISO_DE_EVENTO
El permiso modulacion:operar se reutiliza para dos operaciones distintas: (a) avanzar la etapa MODULACION en el Kanban y (b) asignar una posición física en la Malla. El nombre del permiso no hace referencia explícita a la malla, lo que puede generar confusión en revisiones futuras. No es un bug — la asignación de posición IS el paso de modulación del pipeline — pero es una deuda de nomenclatura.
Acción recomendada: Agregar un comentario en lib/auth/roles.ts junto a MODULAR que explique explícitamente que este permiso gatea tanto el avance de etapa en Kanban como la asignación de posición en la Malla.
C-05 — Todo lo demás cuadra correctamente
Los siguientes elementos son consistentes entre el código y la documentación:
- 5 roles (
admin,supervisor,operador_garita,operador_patio,cliente_readonly) presentes en código y manual sin discrepancias. - 8 permisos en
PERMISOcoinciden 1:1 con los permisos descritos en el manual §2. - Matriz
PERMISOS_POR_ROLen código coincide exactamente con la matriz del manual §2 (tabla "Permisos por rol"). - Tabla "Módulos visibles en el sidebar por rol" del manual §2 es consistente con la lógica de doble filtro (módulo ∧ permiso any-of) de
lib/modules.ts. - Garita para
cliente_readonly: código y manual coinciden en quecliente_readonlyNO ve el módulo Garita (no tieneingreso:registrarnigarita:operar). - Facturación e Integraciones: solo
adminaccede (ambos gateados poradmin:gestionar); consistente entre manual, SOPs y código. PERMISO_DE_EVENTOcubre todos losTipoEventoPatiode forma exhaustiva (forzado por TypeScript); ningún evento queda sin permiso asignado o asignado incorrectamente.- Gates D-011, D-015, D-016, D-017 son descritos de forma consistente entre
GOBERNANZA-AGENTICA.md §3y el manual §5. - Los 8 SOPs verificados existen en disco en
docs/sops/. Ningún SOP referenciado en este índice apunta a un archivo inexistente.