Documentación

Conceptos

Tipos de requisito (kind)

document · object · money · approval · ingredient · tool · knowledge · person · other

Uso de la app

1. En el inicio: crea en blanco, usa una plantilla cotidiana o abre un demo (destacado: tienda online; técnicos: WordPress, PHP-CRUD-API, dtunnel).
2. En el canvas: clic en un nodo para editar; + en una conexión para insertar pasos; doble clic en sub-flujo para abrirlo.
3. Panel derecho (NDV): pestañas Necesitas / Paso / Obtienes; en Paso verás conexiones de datos del nodo seleccionado.
4. Canvas: botón cable en cada paso para enlazar BD/API/FTP; banda inferior «Recursos conectados»; botón database en la barra flotante para añadir recursos.
5. Barra del editor: ¿Qué necesito? (checklist con pestaña Preparación: credenciales, aprobaciones y accesos pendientes), Datos, Diagramas.
6. Canvas: rueda con Ctrl para zoom; Espacio + arrastrar para mover; botón fit_screen para encajar la vista.
7. Exporta JSON para respaldar; importa para recuperar o cargar un flujo generado por IA.

Checklist de preparación

El botón ¿Qué necesito? abre un modal con dos pestañas. La vista por defecto es Preparación: te dice qué te falta antes de ejecutar el proceso, agrupado por tipo.

Cómo usarlo

1. Abre el proceso → ¿Qué necesito? → pestaña Preparación.
2. Marca con ✓ cada ítem que ya tengas listo. El progreso se guarda por proceso en tu navegador.
3. Activa Solo pendientes para ver únicamente lo que falta.
4. Para quitar un aviso Por documentar, añade la credencial en Necesitas del paso que usa ese recurso (tipo database, api_key, basic_auth, etc.).
5. La pestaña Lista completa muestra el detalle por paso, credenciales y tablas del dataLayer.

Importar y exportar

• Exportar — barra del editor → descarga proceso-desarrollado.json.
• Importar — inicio o editor → elige un .json válido (ver esquema abajo).

Validación mínima al importar: el JSON debe tener rootId y flows con al menos el flujo raíz.

Formato JSON

Esquema de nivel superior (version: 2):

{
  "version": 2,
  "rootId": "f_…",
  "catalog": {
    "versions": [{ "id": "2.0", "label": "v2.0", "summary": "…" }],
    "defaultView": "2.0",
    "defaultCompare": "1.0"
  },
  "dataLayer": {
    "databases": [{ "id": "db_1", "name": "mi_bd", "engine": "mysql", "tables": [] }],
    "connections": []
  },
  "diagrams": { "preferred": "flowchart", "custom": "" },
  "flows": {
    "f_…": { /* flujo raíz */ }
  }
}

Estructura de un flujo

{
  "id": "f_abc",
  "title": "Título del proceso",
  "nodes": {
    "n_start": { "id": "n_start", "kind": "start", "label": "Inicio" },
    "n_paso1": {
      "id": "n_paso1",
      "kind": "step",
      "type": "step",
      "label": "Nombre visible",
      "subflowId": null,
      "spec": { /* ver abajo */ }
    },
    "n_end": { "id": "n_end", "kind": "end", "label": "Fin" }
  },
  "edges": [
    { "id": "e1", "from": "n_start", "to": "n_paso1" },
    { "id": "e2", "from": "n_paso1", "to": "n_end" }
  ]
}

spec de un paso

{
  "description": "Texto explicativo del paso",
  "since": "2.0",
  "until": "",
  "versionNotes": { "2.0": "Nota al comparar versiones" },
  "http": { "method": "GET", "path": "/api/recurso" },
  "requirements": [
    { "name": "Token API", "kind": "document", "required": true, "note": "Bearer …", "since": "2.0", "until": "" }
  ],
  "credentials": [
    { "name": "Stripe API Key", "kind": "api_key", "required": true, "note": "Variable STRIPE_SECRET_KEY", "since": "", "until": "" }
  ],
  "inputs": [
    { "name": "id", "type": "number", "required": true, "example": "42", "since": "", "until": "", "validation": "" }
  ],
  "outputs": [
    { "name": "record", "type": "object", "required": true }
  ],
  "formFields": [
    { "name": "email", "type": "string", "required": true, "example": "user@ejemplo.com", "validation": "email" }
  ],
  "dataRefs": [
    { "databaseId": "db_1", "tableId": "tbl_users", "operation": "read" }
  ],
  "payloadIn": "{\"email\":\"…\"}",
  "payloadOut": ""
}

Nodo documentación (type: "info")

{
  "kind": "step",
  "type": "info",
  "label": "Arquitectura",
  "infoTitle": "Título del panel",
  "infoBody": "Texto multilínea…",
  "structures": [
    { "name": "/health", "since": "1.0", "fields": "status, uptime" }
  ]
}

Sub-flujo

Un paso con subflowId apunta a otro objeto en flows. Al generar JSON manualmente, crea dos entradas en flows y enlaza el id.

Alternativa recomendada para código: usar populateFlow() en un archivo demo-*.js (ver demos WordPress, dtunnel en el repo).

Reglas importantes

• Cada flujo necesita exactamente un nodo start y uno end.
• Las edges forman la cadena principal (inicio → … → fin).
• Los id de nodos y flujos deben ser únicos en todo el documento.
• position en nodos es opcional; la app calcula layout si falta.
• Campos de versión en requisitos/inputs: since, until (strings, ej. "2.6").

Bases de datos, estructuras y conexiones

Además de los flujos, el documento puede incluir una capa de datos (dataLayer) con bases de datos, tablas y enlaces explícitos entre pasos y tablas.

Panel Datos (tres pestañas)

El botón Datos en la barra del editor abre un modal con tres modos. Si el proceso tiene muchas tablas (p. ej. el demo WordPress), se abre por defecto en Mapa ER. Guía visual paso a paso: tutoriales con capturas.

Ir al paso en canvas

En las tarjetas de conexión (pestañas Mapa y Explorar), el botón Ir al paso en canvas cierra el modal, navega al sub-flujo correcto y selecciona el nodo enlazado. Útil en procesos con sub-flujos anidados (WordPress, tienda online).

Texto de relaciones (para el mapa ER)

El campo description de cada tabla (columna Relaciones en Editar) alimenta el mapa. Usa convenciones legibles; la app detecta destinos con estos patrones:

• FK post_author → wp_users.ID — flecha hacia otra tabla
• 1:N wp_usermeta — relación uno-a-muchos
• Varias relaciones en la misma celda separadas por · o espacio

wp_posts     | FK post_author → wp_users.ID
wp_users     | 1:N wp_usermeta, wp_posts
wp_terms     | 1:N wp_term_taxonomy
wp_postmeta  | FK post_id → wp_posts.ID

Esquema JSON (dataLayer)

{
  "dataLayer": {
    "databases": [
      {
        "id": "db_main",
        "label": "MySQL producción",
        "engine": "mysql",
        "description": "Notas, host o DSN",
        "since": "1.0",
        "host": "localhost",
        "tables": [
          {
            "id": "tbl_users",
            "name": "users",
            "fields": "id, email, password_hash",
            "primaryKey": "id",
            "since": "1.0",
            "until": "",
            "description": "FK user_id → wp_users.ID"
          }
        ]
      }
    ],
    "connections": [
      {
        "id": "cx_login",
        "label": "Login valida usuario",
        "flowId": "f_root",
        "nodeId": "n_login",
        "nodeLabel": "Iniciar sesión",
        "databaseId": "db_main",
        "tableId": "tbl_users",
        "operation": "read",
        "fields": "email, password_hash",
        "since": "1.0",
        "note": ""
      }
    ]
  }
}

Motores (engine)

mysql · postgres · sqlite · mssql · mongodb · redis · api · ftp · sftp · s3 · other

Operaciones de conexión (operation)

read · write · update · delete · read_write

En la app

• Datos — mapa ER, exploración interactiva y edición de BD, tablas y conexiones.
• Panel Paso (NDV) — sección «Conexiones de datos» del nodo seleccionado; enlace rápido al modal Datos.
• Canvas — nodos de recurso (BD, API, FTP…) y líneas punteadas hacia pasos; botón cable en cada paso.
• Checklist «¿Qué necesito?» — resume tablas y conexiones al final, con icono por motor.
• Nodos info con structures — si no hay dataLayer, se migra automáticamente al abrir el proceso.
• En cada paso, spec.dataRefs puede referenciar tablas (alternativa ligera a connections). Se conserva al editar el paso; para gestión visual usa Datos.

Demo WordPress

El demo técnico WordPress incluye 10 tablas core (wp_posts, wp_users, comentarios, taxonomías, meta…) con relaciones FK y 17+ conexiones cableadas a pasos en sub-flujos. Ábrelo → Datos → Mapa ER.

Diagramas Mermaid

El botón Diagramas en el editor abre un visor modal con 13 tipos generados automáticamente desde tu proceso. Puedes copiar el código, pegarlo en documentación externa o editar el modo Libre con cualquier sintaxis Mermaid 11.

Las etiquetas con rutas HTTP, llaves ({sku}) o guiones largos se sanitizan al generar timeline, mindmap y classDiagram para evitar errores de sintaxis en Mermaid 11.

En el JSON

{
  "diagrams": {
    "preferred": "flowchart",
    "custom": "gantt\\n  title Mi roadmap\\n  section Fase 1\\n  Tarea A :a1, 2026-01-01, 30d"
  }
}

• preferred — última pestaña activa en el visor.
• custom — código Mermaid del modo Libre (se guarda al editar).

Generar flujos con Cursor

Pega este prompt en Cursor (o cualquier agente) junto con la documentación del sistema que quieres documentar. Pide que entregue un JSON importable o un archivo demo-mi-sistema.js.

Eres un asistente que documenta procesos para la app Necesitas (procesos.desarrollado.com).

OBJETIVO: Crear un flujo documentado sobre [DESCRIBE EL SISTEMA: ej. dtunnel, mi API REST, onboarding de usuarios].

REGLAS:
1. Cada paso debe listar requisitos (qué necesitas ANTES de ejecutarlo): documentos, herramientas, conocimiento, permisos.
2. Usa sub-flujos para agrupar fases (instalación, autenticación, operación diaria).
3. Incluye nodos info para arquitectura, límites o tablas de referencia.
4. Si hay versiones del producto, rellena catalog.versions y since/until en specs.
5. Para pasos HTTP: spec.http = { method, path } y formFields/inputs/outputs coherentes.
6. kinds de requisito: document, object, money, approval, ingredient, tool, knowledge, person, other.
7. Incluye dataLayer con databases (tablas/estructuras) y connections (paso↔tabla, operation: read|write|update|delete|read_write).
8. En cada tabla, usa description para relaciones FK (ej. "FK user_id → users.id" o "1:N orders") — alimentan el mapa ER de la app.

ENTREGA (elige una):
A) Archivo JSON válido con version:2, rootId, flows, dataLayer (importable en Necesitas).
B) Archivo js/demo-[nombre].js con función build[Nombre]Demo(doc) que llame doc.populateFlow(doc.rootId, [...]) siguiendo el patrón de js/demo-dtunnel.js en el repo procesos/web.

El JSON raíz debe verse así:
{ "version": 2, "rootId": "…", "catalog": {…}, "dataLayer": { "databases": [], "connections": [] }, "flows": {…} }

Ejemplo mínimo de paso en populateFlow:
{
  label: "Instalar CLI",
  spec: {
    description: "…",
    since: "2.0",
    requirements: [
      { name: "Node.js 18+", kind: "tool", required: true, note: "…" }
    ],
    http: { method: "GET", path: "https://…" },
    outputs: [{ name: "cli", type: "string", required: true, example: "…" }]
  }
}

Sub-flujo en populateFlow:
{
  label: "Fase autenticación",
  subflowMeta: { startLabel: "Sin sesión", endLabel: "Token listo" },
  subflow: [ { label: "Login", spec: { … } }, … ]
}

Documenta [NÚMERO] pasos principales. Título del proceso: "[TÍTULO]".

Flujo de trabajo sugerido

1. Cursor genera mi-proceso.json o demo-mi-sistema.js.
2. Si es JSON: en Necesitas → Importar → abrir y revisar checklist.
3. Si es JS: añadir al repo, plantilla en demo-templates.js o botón en dashboard (como los demos técnicos).
4. Itera: exporta, pide a Cursor que amplíe requisitos o añada versiones.

Extensión VS Code / Cursor

Trabaja con archivos *.necesitas.json en tu repo: validación, snippets y apertura directa en la app web.

Instalación

1. En el repo: carpeta procesos/extension/.
2. Empaqueta: npx @vscode/vsce package → genera necesitas-0.2.0.vsix.
3. En Cursor/VS Code: Extensions → Install from VSIX.
4. O desarrollo: abre la carpeta extension y pulsa F5.

Comandos

Convención en el repo

docs/procesos/
  onboarding-api.necesitas.json
  deploy-produccion.necesitas.json

Versiona los JSON en git; usa la extensión para validar en CI o al guardar.

Novedades

La versión desplegada aparece en el pie del inicio (v…). Si no coincide, recarga con Ctrl+F5.

Ejemplos descargables

Archivos listos para importar en la app:

ejemplo-minimo.json — dos pasos cotidianos (hacer café). ejemplo-tecnico.json — API con catálogo de versiones y nodo info. ejemplo-tienda.json — ejemplo completo: sub-flujos, HTTP, dataLayer (MySQL+Redis+Stripe), catálogo, diagramas y todos los tipos de requisito.