gufi-cli 0.1.49 → 0.1.51

package/docs/dev-guide/1-03-column-types.md

@@ -0,0 +1,594 @@
+---
+id: column-types
+title: "Column Types Reference"
+description: "Complete guide to Gufi field types"
+icon: List
+category: dev
+part: 1
+---
+
+# Column Types Reference
+
+Complete guide to Gufi field types
+
+## Overview
+
+Column types define how data is stored, validated, and displayed. Each type maps to specific PostgreSQL types and frontend components.
+
+## Type Mapping
+
+| Gufi Type | PostgreSQL Type | Frontend Component |
+|---|---|---|
+| text | VARCHAR(255) | TextInput |
+| longtext | TEXT | TextArea |
+| number | NUMERIC | NumberInput |
+| integer | INTEGER | NumberInput |
+| currency | JSONB | CurrencyInput |
+| percentage | NUMERIC(5,2) | PercentageInput |
+| date | TIMESTAMP | DatePicker (+ includeTime para hora) |
+| time | TIME | TimePicker |
+| select | VARCHAR(100) | SelectDropdown |
+| multiselect | JSONB | MultiSelect |
+| checkbox | BOOLEAN | Checkbox |
+| ref | INTEGER + FK | RelationPicker |
+| multiref | JSONB | MultiRelationPicker |
+| user | INTEGER + FK | UserPicker |
+| file | JSONB | FileUpload |
+| image | JSONB | ImageUpload |
+| phone | JSONB | PhoneInput |
+| email | VARCHAR(255) | EmailInput |
+| url | VARCHAR(500) | UrlInput |
+| location | JSONB | LocationInput |
+| formula | (computed) | FormulaDisplay |
+| autonumber | SERIAL | AutoNumber |
+| rating | SMALLINT | RatingStars |
+
+## Text Types
+
+### text
+
+Standard single-line text.
+
+```json
+{
+  "name": "product_name",
+  "type": "text",
+  "label": "Product Name",
+  "required": true,
+  "maxLength": 255,
+  "unique": false
+}
+```
+
+**PostgreSQL:**
+```sql
+product_name VARCHAR(255)
+```
+
+### longtext
+
+Multi-line text for descriptions.
+
+```json
+{
+  "name": "description",
+  "type": "longtext",
+  "label": "Description",
+  "maxLength": 10000
+}
+```
+
+**PostgreSQL:**
+```sql
+description TEXT
+```
+
+### email
+
+Email with validation.
+
+```json
+{
+  "name": "contact_email",
+  "type": "email",
+  "label": "Email",
+  "unique": true
+}
+```
+
+**Validation:** Regex pattern for valid email format.
+
+### url
+
+URL with validation.
+
+```json
+{
+  "name": "website",
+  "type": "url",
+  "label": "Website"
+}
+```
+
+**Validation:** Must be valid URL format.
+
+## Numeric Types
+
+### number
+
+Decimal numbers.
+
+```json
+{
+  "name": "price",
+  "type": "number",
+  "label": "Price",
+  "decimalPlaces": 2,
+  "min": 0,
+  "max": 999999
+}
+```
+
+**PostgreSQL:**
+```sql
+price NUMERIC(12, 2)
+```
+
+### number_int
+
+Whole numbers only.
+
+```json
+{
+  "name": "quantity",
+  "type": "number_int",
+  "label": "Quantity",
+  "min": 0
+}
+```
+
+**PostgreSQL:**
+```sql
+quantity INTEGER
+```
+
+### currency
+
+Dinero. El código de moneda se define en el schema del campo.
+
+```json
+{
+  "name": "total",
+  "type": "currency",
+  "label": "Total",
+  "currency": "EUR"
+}
+```
+
+**PostgreSQL:**
+```sql
+total NUMERIC  -- Solo el número, currency code en schema
+```
+
+**Storage:** `150.00` (número, NO objeto JSONB)
+
+**Usar CB.currency():**
+```javascript
+gufi.CB.currency(150)  // → 150
+```
+
+**Display:** "€ 150.00" (el símbolo se obtiene del schema)
+
+### percentage
+
+Percentage values.
+
+```json
+{
+  "name": "discount",
+  "type": "percentage",
+  "label": "Discount"
+}
+```
+
+**Storage:** Stored as decimal (15% = 0.15)
+
+**Display:** "15%"
+
+### rating
+
+Star rating.
+
+```json
+{
+  "name": "customer_rating",
+  "type": "rating",
+  "label": "Rating",
+  "maxStars": 5
+}
+```
+
+**PostgreSQL:**
+```sql
+customer_rating SMALLINT CHECK (customer_rating >= 0 AND customer_rating <= 5)
+```
+
+## Date/Time Types
+
+### date
+
+Fecha. Siempre se almacena como TIMESTAMP en PostgreSQL.
+
+```json
+{
+  "name": "due_date",
+  "type": "date",
+  "label": "Due Date"
+}
+```
+
+**Con hora (includeTime: true):**
+```json
+{
+  "name": "appointment",
+  "type": "date",
+  "includeTime": true,
+  "label": "Appointment"
+}
+```
+
+**PostgreSQL:**
+```sql
+due_date TIMESTAMP  -- Siempre TIMESTAMP, no DATE
+```
+
+**API Format:** `"2024-01-15T00:00:00.000Z"` (ISO 8601 completo)
+
+**Usar CB.date():**
+```javascript
+gufi.CB.date()                    // Hoy medianoche: "2024-01-15T00:00:00.000Z"
+gufi.CB.date('2024-06-15')        // Fecha específica: "2024-06-15T00:00:00.000Z"
+gufi.CB.date(new Date())          // Ahora con hora: "2024-01-15T14:30:00.000Z"
+```
+
+**Display:** Si `includeTime: true`, muestra fecha y hora. Si no, solo fecha.
+
+### time
+
+Time of day only.
+
+```json
+{
+  "name": "opening_time",
+  "type": "time",
+  "label": "Opens At"
+}
+```
+
+**PostgreSQL:**
+```sql
+opening_time TIME
+```
+
+**API Format:** "14:30:00"
+
+## Selection Types
+
+### select
+
+Single choice from options.
+
+```json
+{
+  "name": "status",
+  "type": "select",
+  "label": "Status",
+  "options": [
+    { "value": "draft", "label": "Draft", "color": "gray" },
+    { "value": "active", "label": "Active", "color": "green" },
+    { "value": "archived", "label": "Archived", "color": "red" }
+  ],
+  "default": "draft"
+}
+```
+
+**PostgreSQL:**
+```sql
+status VARCHAR(100)
+```
+
+### multiselect
+
+Multiple choices.
+
+```json
+{
+  "name": "tags",
+  "type": "multiselect",
+  "label": "Tags",
+  "options": [
+    { "value": "urgent", "label": "Urgent" },
+    { "value": "featured", "label": "Featured" },
+    { "value": "new", "label": "New" }
+  ]
+}
+```
+
+**Storage Format (JSONB):**
+```json
+["urgent", "featured"]
+```
+
+### checkbox
+
+Boolean yes/no.
+
+```json
+{
+  "name": "is_active",
+  "type": "checkbox",
+  "label": "Active",
+  "default": true
+}
+```
+
+**PostgreSQL:**
+```sql
+is_active BOOLEAN DEFAULT true
+```
+
+## Relationship Types
+
+### ref
+
+Single relation to another entity.
+
+```json
+{
+  "name": "category",
+  "type": "ref",
+  "label": "Category",
+  "ref": "inventory.categories"
+}
+```
+
+**PostgreSQL:**
+```sql
+category INTEGER REFERENCES m360_t4590(id)
+```
+
+**Important:** Always use full format `module.entity` for the ref value.
+
+### multiref
+
+Multiple relations.
+
+```json
+{
+  "name": "suppliers",
+  "type": "multiref",
+  "label": "Suppliers",
+  "ref": "inventory.suppliers"
+}
+```
+
+**Storage Format (JSONB):**
+```json
+[1, 5, 12]
+```
+
+### user
+
+Relation to Gufi user.
+
+```json
+{
+  "name": "assigned_to",
+  "type": "user",
+  "label": "Assigned To"
+}
+```
+
+**PostgreSQL:**
+```sql
+assigned_to INTEGER REFERENCES core.users(id)
+```
+
+## File Types
+
+### file
+
+Document attachments.
+
+```json
+{
+  "name": "contract",
+  "type": "file",
+  "label": "Contract",
+  "allowedTypes": ["pdf", "doc", "docx"],
+  "maxSize": 10485760
+}
+```
+
+**Storage Format (JSONB):**
+```json
+{
+  "url": "https://storage.gufi.com/...",
+  "name": "contract.pdf",
+  "mime": "application/pdf",
+  "size": 245678
+}
+```
+
+### image
+
+Image attachments with thumbnails.
+
+```json
+{
+  "name": "photo",
+  "type": "image",
+  "label": "Photo",
+  "multiple": true
+}
+```
+
+**Storage Format (JSONB) - Multiple:**
+```json
+[
+  {
+    "url": "https://storage.gufi.com/...",
+    "name": "photo1.jpg",
+    "mime": "image/jpeg",
+    "size": 123456,
+    "thumbnail": "https://storage.gufi.com/thumb/..."
+  }
+]
+```
+
+## Location Types
+
+### phone
+
+Phone number with country code.
+
+```json
+{
+  "name": "phone",
+  "type": "phone",
+  "label": "Phone"
+}
+```
+
+**Storage Format (JSONB):**
+```json
+{
+  "prefix": "+34",
+  "number": "612345678"
+}
+```
+
+**Display:** "+34 612 345 678"
+
+### location
+
+Address with optional geocoding.
+
+```json
+{
+  "name": "address",
+  "type": "location",
+  "label": "Address",
+  "geocode": true
+}
+```
+
+**Storage Format (JSONB):**
+```json
+{
+  "street": "Calle Mayor",
+  "number": "15",
+  "city": "Madrid",
+  "state": "Madrid",
+  "country": "Spain",
+  "postal_code": "28013",
+  "lat": 40.4168,
+  "lng": -3.7038
+}
+```
+
+## Special Types
+
+### formula
+
+Calculated field (not stored, computed on read).
+
+```json
+{
+  "name": "total",
+  "type": "formula",
+  "label": "Total",
+  "formula": "price * quantity",
+  "resultType": "number"
+}
+```
+
+**Note:** Formula fields don't create database columns. They're computed at query time.
+
+### autonumber
+
+Auto-incrementing identifier.
+
+```json
+{
+  "name": "invoice_number",
+  "type": "autonumber",
+  "label": "Invoice #",
+  "prefix": "INV-",
+  "padding": 5
+}
+```
+
+**Display:** "INV-00001", "INV-00002", ...
+
+## Field Properties
+
+### Common Properties
+
+All field types support:
+
+| Property | Type | Description |
+|---|---|---|
+| name | string | Internal field name |
+| type | string | Column type |
+| label | string/object | Display label |
+| required | boolean | Must have value |
+| unique | boolean | No duplicates |
+| default | any | Default value |
+| hidden | boolean | Hide from UI |
+| readonly | boolean | Cannot edit |
+| help | string | Help text |
+
+### Label Localization
+
+Labels can be localized:
+
+```json
+{
+  "name": "status",
+  "type": "select",
+  "label": {
+    "es": "Estado",
+    "en": "Status"
+  }
+}
+```
+
+## Creating Fields via API
+
+```javascript
+// Add field to entity
+POST /api/entities/:entityId/fields
+{
+  "name": "new_field",
+  "type": "text",
+  "label": "New Field",
+  "required": false
+}
+```
+
+## Type Validation
+
+Each type has built-in validation:
+
+| Type | Validation |
+|---|---|
+| email | Valid email format |
+| url | Valid URL format |
+| phone | Valid phone format |
+| number | Within min/max range |
+| date | Valid date |
+| select | Value in options |
+| ref | Referenced record exists |
+
+Custom validation can be added via automations.