1# Plan maestro — Nakui como ERP profesional
2
3Estado: 2026-05-21 · **PLAN COMPLETADO — 7/7 fases.** Subproyecto:
4`nakui` + la metainterfaz `nahual` (meta-schema / meta-runtime /
5meta-form) + `nakui-ui`.
6
7## 1 · Visión
8
9Un ERP **dirigido por datos**: cada módulo de negocio es un manifiesto
10declarativo (entities + morfismos + UI), sin código compilado por
11módulo. El kernel garantiza integridad (validación Nickel, event-log
12con replay, morfismos verificados). La metainterfaz lo presenta como un
13ERP de verdad: tableros, listas, fichas, formularios.
14
15Hoy el kernel está sólido. Lo que falta es subir la metainterfaz de
16"listas y formularios que funcionan" a "ERP terminado".
17
18## 2 · Estado actual
19
20**Kernel (`nakui-core`)** — maduro. Event-log + replay + snapshots,
21morfismos Rhai, validación Nickel pre/post, drift, persistencia
22SurrealDB opcional. Módulos: `inventory`, `sales`, `treasury`, `crm`.
23
24**Metainterfaz (`nahual` meta-*)** — funcional, base:
25- `meta-schema`: `Module` → `entities` + `menu` + `views` (`List`/`Form`).
26  `FieldKind`: text/multiline/number/boolean/date/entity_ref.
27  `Action`: open_view / seed_entity / morphism.
28- `meta-runtime`: trait `MetaBackend` (list/load/seed/update/delete/
29  morphism), parse, delta, format, validación de refs.
30- `meta-form` (widget GPUI): sidebar + list/form, **edit** y **delete**
31  ya implementados, selector de `entity_ref`.
32- `nakui-ui`: shell + `NakuiBackend` (event-log + store + executors).
33
34**Brechas hacia "ERP profesional"** — capturar datos tiene fricción
35(UUIDs a mano, enums como texto libre); las relaciones se muestran como
36UUID crudo; no hay ficha de detalle, ni tablero, ni orden/filtros en
37listas, ni formato de moneda/fecha, ni reportes.
38
39## 3 · Hoja de ruta por fases
40
41Ordenadas por dependencia y por impacto visible. Cada fase toca
42`meta-schema` (constructo declarativo nuevo) → `meta-runtime` (helper
43puro) → `meta-form` (render) → módulos de ejemplo + tests.
44
45### Fase 1 · Captura sin fricción — HECHA
46
47- `FieldKind::Select` — campos enumerados como desplegable/chips, con
48  `options` (valor + etiqueta) declaradas.
49- `FieldKind::AutoId` — UUIDs de idempotencia autogenerados; el usuario
50  no los teclea.
51- `NakuiBackend::seed` inyecta el `id` de la entity = clave del store
52  (hoy quedan desacoplados).
53- **Resultado**: ningún formulario pide un UUID a mano; etapa, canal y
54  similares son selects. El CRM se siente correcto al cargar datos.
55
56### Fase 2 · Relaciones legibles + formato — HECHA
57
58- Columnas con `ref_entity` muestran el **label** del record referido
59  (vía `human_label_for_record`), no el UUID. El campo `entity_ref` en
60  formularios muestra el record elegido, no el UUID crudo.
61- Formato declarable por columna: `ValueFormat::{Number, Currency}` —
62  separador de miles + símbolo (`12000` → `$12,000`).
63- **Resultado**: las listas se leen como un ERP, no como un volcado.
64
65### Fase 3 · Ficha de detalle — HECHA
66
67- `View::Detail` — el botón 👁 de una fila abre la ficha del record:
68  sus campos + listas de records relacionados (back-refs: las
69  oportunidades e interacciones de un cliente) + botones Volver/Editar.
70- `ListView.row_detail` enlaza lista → ficha; `RelatedList` declara los
71  back-references por `via_field`.
72- **Resultado**: navegación de ERP — lista → ficha → relacionados.
73
74### Fase 4 · Listas profesionales — HECHA
75
76- Orden por columna: clic en el header cicla ascendente → descendente →
77  sin orden, con indicador ▲/▼.
78- Búsqueda en vivo: caja que filtra por substring contra las columnas
79  de `search_in` mientras se teclea.
80- Paginación: 25 filas por página, controles ◀ ▶ y «página N/M».
81- **Resultado**: listas usables con cientos/miles de registros.
82- Pendiente menor (a futuro): filtros por columna, columnas computadas.
83
84### Fase 5 · Tablero y KPIs — HECHA
85
86- `View::Dashboard` — grilla de tarjetas de agregados: `Count`, `Sum`
87  (con formato de moneda) y `GroupBy` (breakdown con barras de texto),
88  cada una con filtro opcional. `compute_metric` en `meta-runtime`.
89- **Resultado**: panorama ejecutivo al abrir el módulo.
90- Pendiente menor (a futuro): reemplazar las barras de texto por los
91  charts de `pineal`.
92
93### Fase 6 · Reportes y exportación — HECHA
94
95- Export CSV de cualquier lista: botón «⬇ CSV» que vuelca las filas
96  filtradas/ordenadas (con refs resueltas y montos formateados) a un
97  archivo. Serializador `to_csv` (RFC 4180) en `meta-runtime`.
98- Pendiente menor (a futuro): impresión / export PDF (los temas
99  `Print` de `nahual-theme` ya existen).
100
101### Fase 7 · Pulido de producto — HECHA
102
103- Validación inline: al fallar un submit, los campos `required` vacíos
104  se marcan en color destructivo con un mensaje debajo del campo — no
105  sólo un toast genérico.
106- Secciones de formulario: `FieldSpec.section` agrupa campos
107  consecutivos bajo un encabezado.
108- Scope-out consciente: «campos condicionales» y el pulido puramente
109  visual quedan fuera — ningún módulo actual los necesita y el schema
110  los soporta agregar sin fricción si emergen.
111
112### Fase 8 · Operación (futuro)
113
114- Persistencia SurrealDB por defecto, multiusuario, permisos, auditoría
115  (el event-log ya es la base de la pista de auditoría).
116
117## 4 · Criterios de "terminado"
118
119- Cargar un módulo nuevo = escribir un `module.json`; cero recompilado.
120- El CRM (y un segundo módulo no trivial) operables de punta a punta:
121  alta, edición, pipeline, ficha, tablero — sin tocar un UUID.
122- Listas con orden/filtro/paginación; valores formateados.
123- Tablero con KPIs reales por módulo.
124- Cobertura de tests en cada crate meta-*; el render se verifica en
125  máquina con pantalla.
126
127## 5 · Cronograma indicativo
128
129```
130Fase 1   Fase 2   Fase 3      Fase 4   Fase 5   Fase 6-7
131[hoy ]   [~3-4d]  [~1 sem]    [~3-4d]  [~1 sem] [~1 sem]
132```
133
134~4-6 semanas en solitario para Fases 1-7. La Fase 8 es trabajo aparte.