brahman/docs/nakui-erp-masterplan.md

Plan maestro — Nakui como ERP profesional

Estado: 2026-05-21 · Subproyecto: nakui + la metainterfaz nahual (meta-schema / meta-runtime / meta-form) + nakui-ui.

1 · Visión

Un ERP dirigido por datos: cada módulo de negocio es un manifiesto declarativo (entities + morfismos + UI), sin código compilado por módulo. El kernel garantiza integridad (validación Nickel, event-log con replay, morfismos verificados). La metainterfaz lo presenta como un ERP de verdad: tableros, listas, fichas, formularios.

Hoy el kernel está sólido. Lo que falta es subir la metainterfaz de "listas y formularios que funcionan" a "ERP terminado".

2 · Estado actual

Kernel (nakui-core) — maduro. Event-log + replay + snapshots, morfismos Rhai, validación Nickel pre/post, drift, persistencia SurrealDB opcional. Módulos: inventory, sales, treasury, crm.

Metainterfaz (nahual meta-*) — funcional, base:

• meta-schema: Module → entities + menu + views (List/Form). FieldKind: text/multiline/number/boolean/date/entity_ref. Action: open_view / seed_entity / morphism.
• meta-runtime: trait MetaBackend (list/load/seed/update/delete/ morphism), parse, delta, format, validación de refs.
• meta-form (widget GPUI): sidebar + list/form, edit y delete ya implementados, selector de entity_ref.
• nakui-ui: shell + NakuiBackend (event-log + store + executors).

Brechas hacia "ERP profesional" — capturar datos tiene fricción (UUIDs a mano, enums como texto libre); las relaciones se muestran como UUID crudo; no hay ficha de detalle, ni tablero, ni orden/filtros en listas, ni formato de moneda/fecha, ni reportes.

3 · Hoja de ruta por fases

Ordenadas por dependencia y por impacto visible. Cada fase toca meta-schema (constructo declarativo nuevo) → meta-runtime (helper puro) → meta-form (render) → módulos de ejemplo + tests.

Fase 1 · Captura sin fricción — HECHA

• FieldKind::Select — campos enumerados como desplegable/chips, con options (valor + etiqueta) declaradas.
• FieldKind::AutoId — UUIDs de idempotencia autogenerados; el usuario no los teclea.
• NakuiBackend::seed inyecta el id de la entity = clave del store (hoy quedan desacoplados).
• Resultado: ningún formulario pide un UUID a mano; etapa, canal y similares son selects. El CRM se siente correcto al cargar datos.

Fase 2 · Relaciones legibles + formato — HECHA

• Columnas con ref_entity muestran el label del record referido (vía human_label_for_record), no el UUID. El campo entity_ref en formularios muestra el record elegido, no el UUID crudo.
• Formato declarable por columna: ValueFormat::{Number, Currency} — separador de miles + símbolo (12000 → $12,000).
• Resultado: las listas se leen como un ERP, no como un volcado.

Fase 3 · Ficha de detalle — HECHA

• View::Detail — el botón 👁 de una fila abre la ficha del record: sus campos + listas de records relacionados (back-refs: las oportunidades e interacciones de un cliente) + botones Volver/Editar.
• ListView.row_detail enlaza lista → ficha; RelatedList declara los back-references por via_field.
• Resultado: navegación de ERP — lista → ficha → relacionados.

Fase 4 · Listas profesionales — HECHA

• Orden por columna: clic en el header cicla ascendente → descendente → sin orden, con indicador ▲/▼.
• Búsqueda en vivo: caja que filtra por substring contra las columnas de search_in mientras se teclea.
• Paginación: 25 filas por página, controles ◀ ▶ y «página N/M».
• Resultado: listas usables con cientos/miles de registros.
• Pendiente menor (a futuro): filtros por columna, columnas computadas.

Fase 5 · Tablero y KPIs

• View::Dashboard — tarjetas de agregados: conteos, sumas, breakdown por grupo (oportunidades por etapa, monto en pipeline, ventas del mes). Reusa los charts de pineal.
• Resultado: panorama ejecutivo al abrir el módulo.

Fase 6 · Reportes y exportación

• Export CSV de cualquier lista; impresión (los temas Print de nahual-theme ya existen).

Fase 7 · Pulido de producto

• Validación inline (error por campo, resaltado de requeridos), secciones de formulario, campos condicionales, pulido visual.

Fase 8 · Operación (futuro)

• Persistencia SurrealDB por defecto, multiusuario, permisos, auditoría (el event-log ya es la base de la pista de auditoría).

4 · Criterios de "terminado"

• Cargar un módulo nuevo = escribir un module.json; cero recompilado.
• El CRM (y un segundo módulo no trivial) operables de punta a punta: alta, edición, pipeline, ficha, tablero — sin tocar un UUID.
• Listas con orden/filtro/paginación; valores formateados.
• Tablero con KPIs reales por módulo.
• Cobertura de tests en cada crate meta-*; el render se verifica en máquina con pantalla.

5 · Cronograma indicativo

Fase 1   Fase 2   Fase 3      Fase 4   Fase 5   Fase 6-7
[hoy ]   [~3-4d]  [~1 sem]    [~3-4d]  [~1 sem] [~1 sem]

~4-6 semanas en solitario para Fases 1-7. La Fase 8 es trabajo aparte.