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 — EN CURSO

• 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

• Columnas/campos entity_ref muestran el label del record referido (vía human_label_for_record), no el UUID.
• Formato de valores declarable: moneda (12000 → $12,000.00), fecha, número con separadores. FieldSpec.format / Column.format.
• Resultado: las listas se leen como un ERP, no como un volcado.

Fase 3 · Ficha de detalle

• View::Detail — clic en una fila abre la ficha del record: todos sus campos + records relacionados (back-refs: las oportunidades e interacciones de un cliente) + acciones contextuales.
• Resultado: navegación de ERP — lista → ficha → relacionados.

Fase 4 · Listas profesionales

• Orden por columna (clic en header), filtros por columna, paginación.
• Columnas computadas / agregadas.
• Resultado: listas usables con cientos/miles de registros.

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.