feat(helpdesk): add handover protocol management

Implement handover protocols as a new entity in the helpdesk module,
allowing users to create fillable protocol records from admin-defined
software product schemas.

Key additions:
- DB migration (helpdesk_handovers table) with tenant scope
- HandoverService with status workflow (draft/in_progress/completed/archived)
- Three-tier permissions (view/create/manage)
- Two-step creation wizard (Stripe-style assistant)
- Grid.js list page with search and status filter
- Edit/detail page with aside metadata and status controls
- Reusable core autocomplete lookup component (app-lookup-field)
- Debitor lookup data endpoint for autocomplete
- Dynamic form rendering from schema snapshots
- 11 PHPUnit tests for HandoverService
- DE+EN i18n translations (48 keys each)

Also includes: PHPStan fixes (dead code removal, stale baseline cleanup),
software product edit title improvement, fieldset simplification,
and Stripe-style hover for schema preview.

Workflow: HD-HANDOVERS-001 (.agents/runs/HD-HANDOVERS-001/)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

modules/helpdesk/web/css/helpdesk.css

@@ -2339,7 +2339,7 @@
   /* Handover protocol schema editor — split layout */
   .handover-schema-split {
     display: grid;
-    grid-template-columns: 1fr 1fr;
+    grid-template-columns: 1fr 2fr;
     gap: var(--app-spacing);
     align-items: start;
   }
@@ -2420,15 +2420,20 @@
   }
 
   .handover-schema-preview-form [data-field-index] {
-    transition: background-color 0.2s ease, box-shadow 0.2s ease;
+    transition:
+      background-color 0.15s ease,
+      border-color 0.15s ease;
     border-radius: var(--app-border-radius);
     padding: calc(var(--app-spacing) * 0.3);
+    padding-inline-start: calc(var(--app-spacing) * 0.5);
     margin: calc(var(--app-spacing) * -0.3);
+    margin-inline-start: calc(var(--app-spacing) * -0.5);
+    border-left: 2px solid transparent;
   }
 
   .handover-schema-preview-highlight {
-    background-color: var(--app-secondary-focus);
-    box-shadow: inset 0 0 0 1px var(--app-card-border-color);
+    background-color: color-mix(in srgb, var(--app-primary, #635bff) 5%, transparent);
+    border-left-color: var(--app-primary, #635bff);
   }
 
   .handover-schema-preview-required {
@@ -2454,7 +2459,7 @@
 
   .handover-schema-insert-divider::before,
   .handover-schema-insert-divider::after {
-    content: '';
+    content: "";
     flex: 1;
     height: 1px;
     background: var(--app-card-border-color);
@@ -2470,10 +2475,20 @@
   }
 
   /* Handover protocol schema editor — field cards */
-  .handover-schema-empty {
+  .handover-schema-empty-state {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: calc(var(--app-spacing) * 0.75);
+    padding: calc(var(--app-spacing) * 2) var(--app-spacing);
+    border: 2px dashed var(--app-card-border-color);
+    border-radius: var(--app-border-radius);
+    text-align: center;
+  }
+
+  .handover-schema-empty-state > p {
     color: var(--app-muted-color);
-    font-style: italic;
-    padding: calc(var(--app-spacing) * 0.5) 0;
+    margin: 0;
   }
 
   .handover-schema-list {
@@ -2578,4 +2593,190 @@
     min-width: 0;
   }
 
+  /* ── Wizard (Stripe-style two-step assistant) ───────────────────────── */
+
+  .app-wizard-container {
+    max-width: 42rem;
+    margin: 0 auto;
+    padding: calc(var(--app-spacing) * 2) var(--app-spacing);
+  }
+
+  .app-wizard-header {
+    display: flex;
+    align-items: center;
+    gap: calc(var(--app-spacing) * 0.75);
+    margin-bottom: calc(var(--app-spacing) * 1.5);
+  }
+
+  .app-wizard-back {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 2rem;
+    height: 2rem;
+    border-radius: var(--app-border-radius);
+    color: var(--app-muted-color);
+    text-decoration: none;
+    transition: background 0.15s ease, color 0.15s ease;
+  }
+
+  .app-wizard-back:hover {
+    background: var(--app-background-muted, #f8f9fa);
+    color: var(--app-color);
+  }
+
+  .app-wizard-title {
+    font-size: var(--text-xl, 1.25rem);
+    font-weight: var(--font-semibold, 600);
+    margin: 0;
+  }
+
+  /* Step indicator */
+  .app-wizard-steps ol {
+    display: flex;
+    align-items: center;
+    list-style: none;
+    padding: 0;
+    margin: 0 0 calc(var(--app-spacing) * 1.5);
+    gap: 0;
+  }
+
+  .app-wizard-step {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+  }
+
+  .app-wizard-step-number {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.75rem;
+    height: 1.75rem;
+    border-radius: 50%;
+    font-size: var(--text-sm, 0.875rem);
+    font-weight: var(--font-semibold, 600);
+    border: 2px solid var(--app-border);
+    color: var(--app-muted-color);
+    background: transparent;
+    transition: all 0.2s ease;
+    flex-shrink: 0;
+  }
+
+  .app-wizard-step-label {
+    font-size: var(--text-sm, 0.875rem);
+    color: var(--app-muted-color);
+    white-space: nowrap;
+  }
+
+  .app-wizard-step.is-active .app-wizard-step-number {
+    border-color: var(--app-primary, #635bff);
+    background: var(--app-primary, #635bff);
+    color: #fff;
+  }
+
+  .app-wizard-step.is-active .app-wizard-step-label {
+    color: var(--app-color);
+    font-weight: var(--font-medium, 500);
+  }
+
+  .app-wizard-step.is-completed .app-wizard-step-number {
+    border-color: var(--app-success, #198754);
+    background: var(--app-success, #198754);
+    color: #fff;
+  }
+
+  .app-wizard-step.is-completed .app-wizard-step-label {
+    color: var(--app-muted-color);
+  }
+
+  .app-wizard-step-connector {
+    flex: 1;
+    height: 2px;
+    background: var(--app-border);
+    margin: 0 0.75rem;
+    transition: background 0.2s ease;
+  }
+
+  .app-wizard-step-connector.is-completed {
+    background: var(--app-success, #198754);
+  }
+
+  /* Card */
+  .app-wizard-card {
+    background: var(--app-card-background-color, #fff);
+    border: 1px solid var(--app-card-border-color, #e5e7eb);
+    border-radius: calc(var(--app-border-radius) * 2);
+    padding: calc(var(--app-spacing) * 1.5);
+    box-shadow: 0 1px 3px rgb(0 0 0 / 0.04);
+  }
+
+  .app-wizard-card-heading {
+    font-size: var(--text-lg, 1.125rem);
+    font-weight: var(--font-semibold, 600);
+    margin: 0 0 0.25rem;
+  }
+
+  .app-wizard-card-description {
+    font-size: var(--text-sm, 0.875rem);
+    color: var(--app-muted-color);
+    margin: 0 0 calc(var(--app-spacing) * 1.5);
+  }
+
+  .app-wizard-field-group {
+    margin-bottom: calc(var(--app-spacing) * 1.25);
+  }
+
+  .app-wizard-field-group > label {
+    display: block;
+    margin-bottom: 0.375rem;
+    font-size: var(--text-sm, 0.875rem);
+    font-weight: var(--font-medium, 500);
+  }
+
+  .app-wizard-protocol-form {
+    max-width: 100%;
+  }
+
+  .app-wizard-actions {
+    display: flex;
+    justify-content: flex-end;
+    gap: 0.75rem;
+    margin-top: calc(var(--app-spacing) * 1.5);
+    padding-top: calc(var(--app-spacing) * 1.25);
+    border-top: 1px solid var(--app-card-border-color, #e5e7eb);
+  }
+
+  /* Handover form — shared styles */
+  .handover-form-required {
+    color: var(--app-danger-color, hsl(0 70% 55%));
+  }
+
+  .handover-form-checkbox-label {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    cursor: pointer;
+  }
+
+  .handover-form-checkbox-label input[type="checkbox"] {
+    width: 1.25em;
+    height: 1.25em;
+    flex-shrink: 0;
+    margin-bottom: 0;
+  }
+
+  @media (max-width: 576px) {
+    .app-wizard-container {
+      padding: var(--app-spacing);
+    }
+
+    .app-wizard-step-label {
+      display: none;
+    }
+
+    .app-wizard-card {
+      padding: var(--app-spacing);
+    }
+  }
 }

modules/helpdesk/web/js/handover-schema-editor.js

@@ -46,9 +46,22 @@ function init(root) {
     clearElement(root);
 
     if (fields.length === 0) {
-      const empty = document.createElement('p');
-      empty.className = 'handover-schema-empty';
-      empty.textContent = t.no_fields || 'No fields defined yet.';
+      const empty = document.createElement('div');
+      empty.className = 'handover-schema-empty-state';
+      const emptyText = document.createElement('p');
+      emptyText.textContent = t.no_fields || 'No fields defined yet.';
+      empty.appendChild(emptyText);
+      const addButton = document.createElement('button');
+      addButton.type = 'button';
+      addButton.className = 'secondary outline';
+      addButton.appendChild(createIcon('bi-plus-lg'));
+      addButton.appendChild(document.createTextNode(' ' + (t.add_field || 'Add field')));
+      addButton.addEventListener('click', () => {
+        fields.push({ type: 'text', key: '', label: '', required: false, options: [] });
+        render();
+        notifyChange();
+      });
+      empty.appendChild(addButton);
       root.appendChild(empty);
     } else {
       const list = document.createElement('div');
@@ -60,9 +73,8 @@ function init(root) {
         list.appendChild(buildFieldRow(field, index));
       });
       root.appendChild(list);
+      root.appendChild(buildInsertDivider(fields.length));
     }
-
-    root.appendChild(buildInsertDivider(fields.length));
   }
 
   function buildInsertDivider(insertIndex) {
@@ -314,7 +326,7 @@ function init(root) {
       if (field.type === 'checkbox') {
         const input = document.createElement('input');
         input.type = 'checkbox';
-        input.disabled = true;
+        input.addEventListener('click', (e) => e.preventDefault());
         group.appendChild(input);
         const label = document.createElement('label');
         label.textContent = field.label || '';

modules/helpdesk/web/js/pages/helpdesk-handovers-index.js

@@ -0,0 +1,86 @@
+import { initStandardListPage } from '/js/core/app-grid-factory.js';
+import { readPageConfig } from '/js/core/app-page-config.js';
+import { warnOnce } from '/js/core/app-dom.js';
+import { escapeHtml, getAppBase, withCurrentListReturn } from '/js/pages/app-list-utils.js';
+
+const config = readPageConfig('helpdesk-handovers');
+if (config) {
+  const gridjs = window.gridjs;
+  if (!gridjs) {
+    warnOnce('UI_INIT_FAIL', 'Helpdesk handovers grid init failed: Grid.js missing', { module: 'helpdesk-handovers', component: 'grid' });
+  } else {
+    const appBase = getAppBase();
+    const labels = config.labels || {};
+
+    const editUrlIndex = 6;
+
+    const gridOptions = {
+      gridjs,
+      container: '#helpdesk-handovers-grid',
+      dataUrl: config.dataUrl || 'helpdesk/handovers-data',
+      appBase,
+      columns: [
+        {
+          name: labels.id || 'ID',
+          sort: true,
+          width: '80px',
+          formatter: (cell) => {
+            const id = escapeHtml(String(cell?.id || ''));
+            const editUrl = String(cell?.url || '').trim();
+            if (editUrl === '') {
+              return gridjs.html(id);
+            }
+            const href = escapeHtml(withCurrentListReturn(editUrl));
+            return gridjs.html(`<a href="${href}">#${id}</a>`);
+          },
+        },
+        { name: labels.debitorName || 'Customer', sort: true },
+        { name: labels.productCode || 'Software product', sort: true },
+        {
+          name: labels.status || 'Status',
+          sort: true,
+          formatter: (cell) => {
+            const label = escapeHtml(cell?.label || '');
+            const variant = cell?.variant || 'neutral';
+            return gridjs.html(`<span class="badge" data-variant="${escapeHtml(variant)}">${label}</span>`);
+          },
+        },
+        { name: labels.createdAt || 'Created', sort: true },
+        { name: labels.createdBy || 'Created by', sort: true },
+        { name: 'edit_url', hidden: true },
+      ],
+      sortColumns: ['id', 'debitor_name', 'product_code', 'status', 'created_at', 'created_by', null],
+      paginationLimit: 20,
+      language: config.gridLang || {},
+      mapData: (data) => (data.data || []).map((row) => [
+        { id: row.id || '', url: row.edit_url || '' },
+        row.debitor_name || '',
+        row.product_code || '',
+        { label: row.status_label || '', variant: row.status_variant || 'neutral' },
+        row.created_at || '',
+        row.created_by_name || '',
+        row.edit_url || '',
+      ]),
+      search: config.gridSearch || null,
+      filterSchema: config.filterSchema || [],
+      urlSync: true,
+      rowInteraction: { linkColumn: 0 },
+      rowDblClick: {
+        getUrl: (rowData) => rowData?.cells?.[editUrlIndex]?.data || '',
+      },
+    };
+
+    const { gridConfig } = initStandardListPage({
+      grid: gridOptions,
+      filters: {
+        mode: 'drawer',
+        chipMeta: config.filterChipMeta || {},
+        watchInputs: ['#helpdesk-handovers-search-input'],
+      },
+    });
+
+    if (!gridConfig || !gridConfig.grid) {
+      warnOnce('UI_INIT_FAIL', 'Helpdesk handovers grid init failed', { module: 'helpdesk-handovers', component: 'grid' });
+    }
+  }
+}