feat(5.20): Custom Fields — plugin-defined fields in Contact UI

- Add CustomFieldDefinition to PluginManifest (text/number/date/select/multiselect/boolean)
- Add GET/PATCH /api/v1/contacts/{id}/custom-fields routes
- Merge plugin definitions with stored values in contacts.custom JSONB
- Add CustomFieldRenderer component (read + edit modes)
- Integrate into ContactDetail (read-only) and ContactEditModal (editable)
- Add custom_fields to pluginStore and active manifests API
- Add useCustomFields/useUpdateCustomFields React Query hooks
- Tests: test_custom_fields.py (9 tests) + CustomFieldRenderer.test.tsx (5 tests)
- i18n keys already present (contacts.customFields)

app/main.py

@@ -47,6 +47,7 @@ from app.routes import (
     sequences,
     system_settings,
     attachments,
+    custom_fields,
 )
 
 
@@ -304,6 +305,7 @@ def create_app() -> FastAPI:
     app.include_router(attachments.router)
     app.include_router(addresses.router)
     app.include_router(audit.router)
+    app.include_router(custom_fields.router)
 
     # ── Register plugin routes (before SPA catch-all) ──────────────────
     registry = get_registry()

app/plugins/manifest.py

@@ -138,6 +138,21 @@ class FrontendDashboardWidget(BaseModel):
     permission: str = Field(default="", description="Optional permission required")
 
 
+class CustomFieldDefinition(BaseModel):
+    """A custom field definition contributed by a plugin manifest."""
+
+    name: str = Field(..., min_length=1, max_length=80, description="Unique field name (snake_case)")
+    label: str = Field(default="", description="Human-readable label (fallback if i18n key missing)")
+    label_key: str = Field(default="", description="i18n key for the field label")
+    field_type: str = Field(
+        ..., pattern="^(text|number|date|select|multiselect|boolean)$", description="Field type"
+    )
+    options: list[str] = Field(default_factory=list, description="Options for select/multiselect types")
+    default_value: Any = Field(default=None, description="Default value for the field")
+    required: bool = Field(default=False, description="Whether the field is required")
+    entity: str = Field(default="contact", description="Entity type this field applies to (contact/file/etc)")
+
+
 class MiniAppContribution(BaseModel):
     """A MiniApp contributed by a plugin manifest."""
 
@@ -214,6 +229,9 @@ class PluginManifest(BaseModel):
     miniapps: list[MiniAppContribution] = Field(
         default_factory=list, description="MiniApps contributed by this plugin"
     )
+    custom_fields: list[CustomFieldDefinition] = Field(
+        default_factory=list, description="Custom field definitions contributed by this plugin"
+    )
 
 
     @field_validator("name")

app/plugins/registry.py

@@ -760,6 +760,7 @@ class PluginRegistry:
                     "detail_tabs": [tab.model_dump() for tab in m.detail_tabs],
                     "settings_pages": [page.model_dump() for page in m.settings_pages],
                     "dashboard_widgets": [widget.model_dump() for widget in m.dashboard_widgets],
+                    "custom_fields": [cf.model_dump() for cf in m.custom_fields],
                 }
             )
         return manifests

app/routes/custom_fields.py

@@ -0,0 +1,158 @@
+"""Custom fields routes — merge plugin definitions with stored values."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Body
+from pydantic import BaseModel
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.db import get_db
+from app.deps import get_current_user, require_permission
+from app.models.contact import Contact
+from app.plugins.registry import get_registry
+
+router = APIRouter(prefix="/api/v1/contacts", tags=["custom-fields"])
+
+
+class CustomFieldUpdateRequest(BaseModel):
+    """Request body for updating custom field values."""
+
+    values: dict[str, Any] = {}
+
+
+def _collect_custom_field_definitions(entity: str = "contact") -> list[dict[str, Any]]:
+    """Collect all custom field definitions from active plugin manifests."""
+    definitions: list[dict[str, Any]] = []
+    seen_names: set[str] = set()
+    registry = get_registry()
+    for plugin in registry._plugins.values():
+        manifest = plugin.manifest
+        for cf in manifest.custom_fields:
+            if cf.entity != entity:
+                continue
+            if cf.name in seen_names:
+                continue
+            seen_names.add(cf.name)
+            definitions.append(
+                {
+                    "name": cf.name,
+                    "label": cf.label,
+                    "label_key": cf.label_key,
+                    "field_type": cf.field_type,
+                    "options": cf.options,
+                    "default_value": cf.default_value,
+                    "required": cf.required,
+                    "entity": cf.entity,
+                    "plugin": manifest.name,
+                }
+            )
+    return definitions
+
+
+def _merge_definitions_with_values(
+    definitions: list[dict[str, Any]], stored: dict[str, Any] | None
+) -> list[dict[str, Any]]:
+    """Merge field definitions with stored values, applying defaults."""
+    stored = stored or {}
+    result: list[dict[str, Any]] = []
+    for d in definitions:
+        name = d["name"]
+        value = stored.get(name, d.get("default_value"))
+        entry = {**d, "value": value}
+        result.append(entry)
+    return result
+
+
+@router.get("/{contact_id}/custom-fields", dependencies=[Depends(require_permission("contacts:read"))])
+async def get_custom_fields(
+    contact_id: str,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Get all custom fields for a contact (merged definitions + stored values)."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    try:
+        cid = uuid.UUID(contact_id)
+    except (ValueError, TypeError):
+        raise HTTPException(400, detail={"detail": "Invalid contact_id", "code": "invalid_id"}) from None
+
+    result = await db.execute(
+        select(Contact).where(Contact.id == cid, Contact.tenant_id == tenant_id)
+    )
+    contact = result.scalar_one_or_none()
+    if contact is None:
+        raise HTTPException(404, detail={"detail": "Contact not found", "code": "not_found"})
+
+    definitions = _collect_custom_field_definitions("contact")
+    merged = _merge_definitions_with_values(definitions, contact.custom)
+    return {"fields": merged}
+
+
+@router.patch("/{contact_id}/custom-fields", dependencies=[Depends(require_permission("contacts:write"))])
+async def update_custom_fields(
+    contact_id: str,
+    body: CustomFieldUpdateRequest,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Update custom field values for a contact (stored in contacts.custom JSONB)."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    try:
+        cid = uuid.UUID(contact_id)
+    except (ValueError, TypeError):
+        raise HTTPException(400, detail={"detail": "Invalid contact_id", "code": "invalid_id"}) from None
+
+    result = await db.execute(
+        select(Contact).where(Contact.id == cid, Contact.tenant_id == tenant_id)
+    )
+    contact = result.scalar_one_or_none()
+    if contact is None:
+        raise HTTPException(404, detail={"detail": "Contact not found", "code": "not_found"})
+
+    # Validate against definitions
+    definitions = _collect_custom_field_definitions("contact")
+    def_map = {d["name"]: d for d in definitions}
+
+    current_custom = dict(contact.custom or {})
+    for name, value in body.values.items():
+        if name not in def_map:
+            raise HTTPException(
+                400,
+                detail={"detail": f"Unknown custom field: {name}", "code": "unknown_field"},
+            )
+        field_def = def_map[name]
+        # Validate required
+        if field_def["required"] and (value is None or value == ""):
+            raise HTTPException(
+                400,
+                detail={"detail": f"Field '{name}' is required", "code": "required_field"},
+            )
+        # Validate select/multiselect options
+        if field_def["field_type"] == "select" and value is not None:
+            if value not in field_def["options"]:
+                raise HTTPException(
+                    400,
+                    detail={"detail": f"Invalid option for field '{name}'", "code": "invalid_option"},
+                )
+        if field_def["field_type"] == "multiselect" and value is not None:
+            if not isinstance(value, list):
+                raise HTTPException(
+                    400,
+                    detail={"detail": f"Field '{name}' must be a list", "code": "invalid_type"},
+                )
+            for v in value:
+                if v not in field_def["options"]:
+                    raise HTTPException(
+                        400,
+                        detail={"detail": f"Invalid option '{v}' for field '{name}'", "code": "invalid_option"},
+                    )
+        current_custom[name] = value
+
+    contact.custom = current_custom
+    await db.flush()
+    merged = _merge_definitions_with_values(definitions, contact.custom)
+    return {"fields": merged}