gufi-cli 0.1.50 → 0.1.52

package/docs/dev-guide/1-04-json-config.md

@@ -0,0 +1,442 @@
+---
+id: json-config
+title: "Module JSON Configuration"
+description: "Define modules, entities, and fields"
+icon: Code
+category: dev
+part: 1
+---
+
+# Module JSON Configuration
+
+Define modules, entities, and fields
+
+## Overview
+
+Modules in Gufi are defined using JSON configuration. This declarative approach makes it easy to:
+
+- Create complex data structures without SQL
+- Version control your schema
+- Share modules across companies
+- Import/export configurations
+
+## Module Structure
+
+### Basic Module
+
+```json
+{
+  "id": 360,
+  "name": "inventory",
+  "label": "Inventory",
+  "icon": "Package",
+  "description": "Manage products and stock",
+  "entities": [
+    {
+      "id": 4589,
+      "name": "products",
+      "label": "Products",
+      "kind": "table",
+      "icon": "Box",
+      "fields": [...]
+    }
+  ]
+}
+```
+
+### Module Properties
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| id | number | Yes | Unique module ID |
+| name | string | Yes | Internal name (lowercase, no spaces) |
+| label | string/i18n | Yes | Display name |
+| icon | string | No | Lucide icon name |
+| description | string | No | Module description |
+| entities | array | Yes | Array of entity definitions |
+
+### Label Localization
+
+```json
+{
+  "label": {
+    "es": "Inventario",
+    "en": "Inventory"
+  }
+}
+```
+
+## Entity Definition
+
+### Basic Entity
+
+```json
+{
+  "id": 4589,
+  "name": "products",
+  "label": "Products",
+  "kind": "table",
+  "icon": "Box",
+  "primaryField": "name",
+  "secondaryField": "sku",
+  "fields": [...]
+}
+```
+
+### Entity Properties
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| id | number | Yes | Unique entity ID |
+| name | string | Yes | Internal name |
+| label | string/i18n | Yes | Display name |
+| kind | string | Yes | Entity type (see below) |
+| icon | string | No | Lucide icon name |
+| primaryField | string | No | Main display field |
+| secondaryField | string | No | Secondary display field |
+| fields | array | Yes | Array of field definitions |
+| webhook | object | No | Webhook configuration |
+
+### Entity Kinds
+
+| Kind | Description |
+|---|---|
+| table | Standard data table |
+| calendar | Calendar view |
+| kanban | Kanban board view |
+| dashboard | Custom dashboard |
+
+## Field Definition
+
+### Basic Field
+
+```json
+{
+  "name": "product_name",
+  "type": "text",
+  "label": "Product Name",
+  "required": true
+}
+```
+
+### All Field Properties
+
+```json
+{
+  "name": "price",
+  "type": "currency",
+  "label": {
+    "es": "Precio",
+    "en": "Price"
+  },
+  "required": true,
+  "unique": false,
+  "default": { "currency": "EUR", "amount": 0 },
+  "hidden": false,
+  "readonly": false,
+  "help": "Enter the product price",
+
+  // Type-specific options
+  "options": [...],       // For select/multiselect
+  "ref": "module.entity", // For ref/multiref
+  "formula": "...",       // For formula
+  "maxLength": 255,       // For text
+  "min": 0,               // For number
+  "max": 99999,           // For number
+  "decimalPlaces": 2      // For number
+}
+```
+
+## Complete Example
+
+### CRM Module
+
+```json
+{
+  "id": 100,
+  "name": "crm",
+  "label": {
+    "es": "CRM",
+    "en": "CRM"
+  },
+  "icon": "Users",
+  "description": "Customer Relationship Management",
+  "entities": [
+    {
+      "id": 1001,
+      "name": "contacts",
+      "label": {
+        "es": "Contactos",
+        "en": "Contacts"
+      },
+      "kind": "table",
+      "icon": "User",
+      "primaryField": "name",
+      "secondaryField": "email",
+      "fields": [
+        {
+          "name": "name",
+          "type": "text",
+          "label": { "es": "Nombre", "en": "Name" },
+          "required": true
+        },
+        {
+          "name": "email",
+          "type": "email",
+          "label": { "es": "Email", "en": "Email" },
+          "unique": true
+        },
+        {
+          "name": "phone",
+          "type": "phone",
+          "label": { "es": "Teléfono", "en": "Phone" }
+        },
+        {
+          "name": "company",
+          "type": "ref",
+          "label": { "es": "Empresa", "en": "Company" },
+          "ref": "crm.companies"
+        },
+        {
+          "name": "status",
+          "type": "select",
+          "label": { "es": "Estado", "en": "Status" },
+          "options": [
+            { "value": "lead", "label": { "es": "Lead", "en": "Lead" }, "color": "blue" },
+            { "value": "customer", "label": { "es": "Cliente", "en": "Customer" }, "color": "green" },
+            { "value": "churned", "label": { "es": "Perdido", "en": "Churned" }, "color": "red" }
+          ],
+          "default": "lead"
+        },
+        {
+          "name": "notes",
+          "type": "longtext",
+          "label": { "es": "Notas", "en": "Notes" }
+        },
+        {
+          "name": "assigned_to",
+          "type": "user",
+          "label": { "es": "Asignado a", "en": "Assigned To" }
+        }
+      ]
+    },
+    {
+      "id": 1002,
+      "name": "companies",
+      "label": {
+        "es": "Empresas",
+        "en": "Companies"
+      },
+      "kind": "table",
+      "icon": "Building2",
+      "primaryField": "name",
+      "fields": [
+        {
+          "name": "name",
+          "type": "text",
+          "label": { "es": "Nombre", "en": "Name" },
+          "required": true
+        },
+        {
+          "name": "website",
+          "type": "url",
+          "label": { "es": "Web", "en": "Website" }
+        },
+        {
+          "name": "industry",
+          "type": "select",
+          "label": { "es": "Industria", "en": "Industry" },
+          "options": [
+            { "value": "tech", "label": "Technology" },
+            { "value": "retail", "label": "Retail" },
+            { "value": "services", "label": "Services" },
+            { "value": "manufacturing", "label": "Manufacturing" }
+          ]
+        },
+        {
+          "name": "annual_revenue",
+          "type": "currency",
+          "label": { "es": "Facturación anual", "en": "Annual Revenue" }
+        },
+        {
+          "name": "address",
+          "type": "location",
+          "label": { "es": "Dirección", "en": "Address" }
+        }
+      ]
+    },
+    {
+      "id": 1003,
+      "name": "deals",
+      "label": {
+        "es": "Oportunidades",
+        "en": "Deals"
+      },
+      "kind": "kanban",
+      "icon": "DollarSign",
+      "primaryField": "title",
+      "fields": [
+        {
+          "name": "title",
+          "type": "text",
+          "label": { "es": "Título", "en": "Title" },
+          "required": true
+        },
+        {
+          "name": "contact",
+          "type": "ref",
+          "label": { "es": "Contacto", "en": "Contact" },
+          "ref": "crm.contacts"
+        },
+        {
+          "name": "value",
+          "type": "currency",
+          "label": { "es": "Valor", "en": "Value" },
+          "required": true
+        },
+        {
+          "name": "stage",
+          "type": "select",
+          "label": { "es": "Etapa", "en": "Stage" },
+          "options": [
+            { "value": "qualified", "label": "Qualified", "color": "blue" },
+            { "value": "proposal", "label": "Proposal", "color": "yellow" },
+            { "value": "negotiation", "label": "Negotiation", "color": "orange" },
+            { "value": "won", "label": "Won", "color": "green" },
+            { "value": "lost", "label": "Lost", "color": "red" }
+          ]
+        },
+        {
+          "name": "expected_close",
+          "type": "date",
+          "label": { "es": "Cierre esperado", "en": "Expected Close" }
+        },
+        {
+          "name": "probability",
+          "type": "percentage",
+          "label": { "es": "Probabilidad", "en": "Probability" }
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Webhook Configuration
+
+Enable API access for an entity:
+
+```json
+{
+  "name": "products",
+  "webhook": {
+    "enabled": true
+  },
+  "fields": [...]
+}
+```
+
+This adds an "API" button in the UI that generates webhook URLs.
+
+## Validation Rules
+
+### Module Name
+
+- Lowercase letters and underscores only
+- Must start with letter
+- Max 50 characters
+
+### Entity Name
+
+- Lowercase letters and underscores only
+- Unique within module
+- Max 50 characters
+
+### Field Name
+
+- Lowercase letters, numbers, underscores
+- Must start with letter
+- Unique within entity
+- Max 50 characters
+- Cannot be: id, created_at, updated_at, created_by, updated_by
+
+## CLI Management
+
+### View Module
+
+```bash
+gufi module 360
+```
+
+### Edit Module
+
+```bash
+gufi module 360 --edit
+```
+
+Opens in $EDITOR, saves changes on close.
+
+### Create Module
+
+```bash
+gufi module:create config.json -c 146
+```
+
+### Update Module
+
+```bash
+gufi module:update 360 config.json
+```
+
+## Best Practices
+
+### Naming Conventions
+
+```json
+// Good
+"name": "purchase_orders"
+"name": "product_categories"
+"name": "customer_notes"
+
+// Bad
+"name": "PurchaseOrders"  // No camelCase
+"name": "po"              // Too short
+"name": "product-cats"    // No hyphens
+```
+
+### Field Organization
+
+Order fields logically:
+
+1. Primary identifier fields
+2. Main data fields
+3. Status/type fields
+4. Relationships
+5. Metadata fields
+6. Notes/comments
+
+### Use Proper Types
+
+```json
+// Good
+{ "type": "currency", "name": "price" }
+{ "type": "email", "name": "contact_email" }
+{ "type": "phone", "name": "phone" }
+
+// Bad
+{ "type": "text", "name": "price" }      // Use currency
+{ "type": "text", "name": "email" }      // Use email
+{ "type": "number", "name": "phone" }    // Use phone
+```
+
+### Always Use Full Refs
+
+```json
+// Good
+"ref": "inventory.products"
+"ref": "crm.contacts"
+
+// Bad
+"ref": "products"    // Missing module
+"ref": "4589"        // Using ID instead of name
+```