feat(template): stable fieldId per field — custom_fields keyed by UUID, not label slug

backend/src/routes/experiments.js

@@ -3,7 +3,8 @@ const { body } = require('express-validator');
 const prisma = require('../lib/prisma');
 const auditMiddleware = require('../middleware/auditMiddleware');
 const { validateRequest } = require('../middleware/errorHandler');
-const { resolveTemplate, DEFAULT_TEMPLATE } = require('../lib/defaultTemplate');
+const { v4: uuidv4 } = require('uuid');
+const { resolveTemplate, DEFAULT_TEMPLATE, UUID_RE } = require('../lib/defaultTemplate');
 
 const experimentValidation = [
   body('title').trim().notEmpty().withMessage('Title is required').isLength({ max: 255 }).withMessage('Title must be ≤255 characters'),
@@ -11,30 +12,45 @@ const experimentValidation = [
 
 // ── Template validation helpers ────────────────────────────────────────────────
 
-const BUILTIN_KEYS = new Set(DEFAULT_TEMPLATE.map((f) => f.key));
-const VALID_TYPES  = new Set(['text', 'textarea']);
+const BUILTIN_FIELD_IDS = new Set(DEFAULT_TEMPLATE.map((f) => f.fieldId));
+const BUILTIN_KEYS      = new Set(DEFAULT_TEMPLATE.map((f) => f.key));
+const VALID_TYPES       = new Set(['text', 'textarea']);
 
 function validateTemplate(template) {
   if (!Array.isArray(template)) return 'template must be an array';
   if (template.length > 50) return 'template may have at most 50 fields';
 
-  const keys = new Set();
+  const seenFieldIds = new Set();
+  const seenKeys     = new Set();
+
   for (const field of template) {
+    // ── fieldId ────────────────────────────────────────────────────────────────
+    if (!field.fieldId || !UUID_RE.test(field.fieldId))
+      return `each field must have a valid UUID fieldId (got: ${field.fieldId})`;
+    if (seenFieldIds.has(field.fieldId))
+      return `duplicate fieldId "${field.fieldId}"`;
+    seenFieldIds.add(field.fieldId);
+
+    // Builtin fields must keep their original fieldIds
+    if (BUILTIN_KEYS.has(field.key) && !BUILTIN_FIELD_IDS.has(field.fieldId))
+      return `builtin field "${field.key}" must keep its original fieldId`;
+
+    // ── key ────────────────────────────────────────────────────────────────────
     if (!field.key || typeof field.key !== 'string') return 'each field must have a string key';
     if (!/^[a-z0-9_]+$/.test(field.key)) return `key "${field.key}" must be lowercase alphanumeric/underscore only`;
     if (field.key.length > 64) return `key "${field.key}" must be ≤64 characters`;
-    if (keys.has(field.key)) return `duplicate key "${field.key}"`;
-    keys.add(field.key);
+    if (seenKeys.has(field.key)) return `duplicate key "${field.key}"`;
+    seenKeys.add(field.key);
 
+    // ── label ──────────────────────────────────────────────────────────────────
     if (!field.label || typeof field.label !== 'string' || !field.label.trim())
       return `field "${field.key}" must have a non-empty label`;
     if (field.label.length > 128) return `label for "${field.key}" must be ≤128 characters`;
 
+    // ── type / active / builtin ────────────────────────────────────────────────
     if (!VALID_TYPES.has(field.type)) return `field "${field.key}" type must be "text" or "textarea"`;
-
     if (typeof field.active !== 'boolean') return `field "${field.key}" must have a boolean active flag`;
 
-    // Builtin keys cannot change their builtin status
     if (BUILTIN_KEYS.has(field.key) && field.builtin !== true)
       return `field "${field.key}" is a builtin field and cannot be made non-builtin`;
     if (!BUILTIN_KEYS.has(field.key) && field.builtin !== false)
@@ -43,6 +59,18 @@ function validateTemplate(template) {
   return null;
 }
 
+/**
+ * Back-fill any missing fieldIds (handles records saved before this feature).
+ * Builtin fields get their canonical IDs; custom fields get fresh UUIDs.
+ */
+function ensureFieldIds(template) {
+  const builtinById = Object.fromEntries(DEFAULT_TEMPLATE.map((f) => [f.key, f.fieldId]));
+  return template.map((f) => ({
+    ...f,
+    fieldId: f.fieldId || (f.builtin ? builtinById[f.key] : uuidv4()),
+  }));
+}
+
 // ── Experiment CRUD ────────────────────────────────────────────────────────────
 
 // GET /api/experiments
@@ -64,8 +92,7 @@ router.get('/:id', async (req, res, next) => {
       include: { animals: true },
     });
     if (!experiment) return res.status(404).json({ error: 'Experiment not found' });
-    // Always return resolved template (never raw [])
-    experiment.template = resolveTemplate(experiment.template);
+    experiment.template = ensureFieldIds(resolveTemplate(experiment.template));
     res.json(experiment);
   } catch (err) { next(err); }
 });
@@ -78,7 +105,7 @@ router.post('/', experimentValidation, validateRequest, async (req, res, next) =
     await prisma.auditLog.create({
       data: { table_name: 'experiments', record_id: experiment.id, action: 'CREATE', changes: { before: null, after: experiment } },
     });
-    experiment.template = resolveTemplate(experiment.template);
+    experiment.template = ensureFieldIds(resolveTemplate(experiment.template));
     res.status(201).json(experiment);
   } catch (err) { next(err); }
 });
@@ -93,7 +120,7 @@ router.put(
     try {
       const { title } = req.body;
       const experiment = await prisma.experiment.update({ where: { id: req.params.id }, data: { title } });
-      experiment.template = resolveTemplate(experiment.template);
+      experiment.template = ensureFieldIds(resolveTemplate(experiment.template));
       res.json(experiment);
     } catch (err) { next(err); }
   }
@@ -121,7 +148,7 @@ router.get('/:id/template', async (req, res, next) => {
       select: { id: true, template: true },
     });
     if (!experiment) return res.status(404).json({ error: 'Experiment not found' });
-    res.json(resolveTemplate(experiment.template));
+    res.json(ensureFieldIds(resolveTemplate(experiment.template)));
   } catch (err) { next(err); }
 });
 
@@ -135,7 +162,7 @@ router.put('/:id/template', async (req, res, next) => {
     const validationError = validateTemplate(template);
     if (validationError) return res.status(422).json({ error: validationError });
 
-    const before = resolveTemplate(experiment.template);
+    const before = ensureFieldIds(resolveTemplate(experiment.template));
     const updated = await prisma.experiment.update({
       where: { id: req.params.id },
       data: { template },