${body}
`; +} + +router.get('/:token/:action', async (req, res) => { + const { token, action } = req.params; + if (!['confirm', 'deny'].includes(action)) { + return res.status(400).send(page('Invalid link', 'This confirmation link is not valid.')); + } + try { + const result = await actByToken(token, action); + if (!result.ok && result.reason === 'not_found') { + return res.status(404).send(page('Link not found', 'This confirmation link is invalid or has been revoked.')); + } + if (!result.ok && result.reason === 'expired') { + return res.status(410).send(page('Link expired', 'This confirmation link has expired. Use the workflow inbox in the admin panel instead.')); + } + if (result.already) { + return res.send(page('Already recorded', `This request was already ${result.status}.`)); + } + return res.send(page( + 'Thank you', + action === 'confirm' + ? 'Confirmed — the workflow will continue.' + : 'Recorded — the workflow has been told there is no payment / to stop.', + )); + } catch (e) { + return res.status(500).send(page('Something went wrong', 'We could not record your response. Please try again or use the admin panel.')); + } +}); + +module.exports = router; diff --git a/backend/src/services/workflows/approvals.js b/backend/src/services/workflows/approvals.js new file mode 100644 index 00000000..667478f9 --- /dev/null +++ b/backend/src/services/workflows/approvals.js @@ -0,0 +1,126 @@ +/** + * Workflow approval gates — the human-in-the-loop step. + * + * When the engine hits a `gate` node it calls the registered `gate_setup` + * action, which creates a workflow_approvals row (single-use token stored as a + * SHA-256 hash) and emails the admin a confirm/deny link. The run stays + * `waiting` until the admin acts — via the email link (actByToken) or the + * webview pending-approvals inbox (actById) — at which point the run resumes + * down the matching confirm/deny edge. + * + * Internal/admin mail → sent immediately (respectBusinessHours: false). + */ +const crypto = require('crypto'); +const { db } = require('../../database/db'); +const logger = require('../../utils/logger'); +const registry = require('./registry'); +const engine = require('./engine'); + +function hashToken(raw) { + return crypto.createHash('sha256').update(String(raw)).digest('hex'); +} + +/** + * gate_setup action — create the approval + email the admin. Called by the + * engine when a gate node is reached. Best-effort on the email; the approval + * row (and thus the inbox path) is always created. + */ +async function createApproval(ctx) { + const { run, node } = ctx; + const cfg = node.config || {}; + const raw = crypto.randomBytes(32).toString('hex'); + const expiresAt = cfg.timeoutDays + ? new Date(Date.now() + Number(cfg.timeoutDays) * 86400000).toISOString() + : null; + + await db('workflow_approvals').insert({ + run_id: run.id, + node_key: node.node_key, + type: cfg.type || 'payment_confirm', + status: 'pending', + token_hash: hashToken(raw), + payload: JSON.stringify({ prompt: cfg.prompt || null, vars: ctx.vars || {} }), + expires_at: expiresAt, + created_at: db.fn.now(), + }); + + try { + const { getFrontendBaseUrl } = require('../../utils/frontendUrl'); + const base = (await getFrontendBaseUrl()) || ''; + const confirmUrl = `${base}/api/public/workflow-approvals/${raw}/confirm`; + const denyUrl = `${base}/api/public/workflow-approvals/${raw}/deny`; + + let adminEmail = ctx.vars?.adminEmail || null; + if (!adminEmail) { + const bp = await db('business_profile').where({ id: 1 }).first('email'); + adminEmail = bp?.email || null; + } + if (adminEmail) { + const emailProcessor = require('../emailProcessor'); + await emailProcessor.queueEmail( + ctx.vars?.eventId || null, + adminEmail, + cfg.emailType || 'workflow_approval', + { + prompt: cfg.prompt || 'A workflow needs your confirmation.', + confirm_url: confirmUrl, + deny_url: denyUrl, + ...(ctx.vars?.emailData || {}), + }, + { respectBusinessHours: false }, // internal/admin → immediate + ); + } else { + logger.warn('[workflow] approval created but no admin email to notify', { runId: run.id }); + } + } catch (e) { + logger.error('[workflow] approval email failed', { runId: run.id, error: e.message }); + } + + return { approval: true }; +} + +registry.registerAction('gate_setup', createApproval); + +async function finalizeApproval(approval, decision, actorPatch) { + if (!approval) return { ok: false, reason: 'not_found' }; + if (approval.status !== 'pending') return { ok: true, already: true, status: approval.status }; + if (approval.expires_at && new Date(approval.expires_at).getTime() < Date.now()) { + await db('workflow_approvals').where({ id: approval.id }).update({ status: 'expired' }); + return { ok: false, reason: 'expired' }; + } + const status = decision === 'confirm' ? 'confirmed' : 'denied'; + await db('workflow_approvals').where({ id: approval.id }) + .update({ status, acted_at: db.fn.now(), ...actorPatch }); + // Resume down the matching edge (handles 'confirm' | 'deny'). + await engine.resumeRun(approval.run_id, { decisionHandle: decision }); + return { ok: true, status }; +} + +/** Act on an approval via the emailed single-use token. */ +async function actByToken(rawToken, decision) { + const approval = await db('workflow_approvals').where({ token_hash: hashToken(rawToken) }).first(); + return finalizeApproval(approval, decision, { acted_via: 'email' }); +} + +/** Act on an approval from the admin webview inbox. */ +async function actById(id, decision, adminId) { + const approval = await db('workflow_approvals').where({ id }).first(); + return finalizeApproval(approval, decision, { acted_via: 'web', acted_by: adminId || null }); +} + +/** Pending approvals for the webview inbox, newest first, with workflow name. */ +async function listPending(limit = 100) { + return db('workflow_approvals as a') + .join('workflow_runs as r', 'r.id', 'a.run_id') + .join('workflows as w', 'w.id', 'r.workflow_id') + .where('a.status', 'pending') + .select( + 'a.id', 'a.type', 'a.payload', 'a.created_at', 'a.expires_at', + 'r.id as run_id', 'r.entity_type', 'r.entity_id', + 'w.id as workflow_id', 'w.name as workflow_name', + ) + .orderBy('a.created_at', 'desc') + .limit(limit); +} + +module.exports = { hashToken, createApproval, actByToken, actById, listPending }; diff --git a/backend/src/services/workflows/index.js b/backend/src/services/workflows/index.js index 1c386ed3..e41742bf 100644 --- a/backend/src/services/workflows/index.js +++ b/backend/src/services/workflows/index.js @@ -12,8 +12,11 @@ const registry = require('./registry'); // Side-effect import: registers the data-touching action/condition handlers // (send_email, invoice_paid, prepare_* document actions) onto the registry. require('./actions'); +// Registers the gate_setup action + exposes approval helpers. +const approvals = require('./approvals'); module.exports = { ...engine, + ...approvals, registry, }; From 1a0d6de04d3547ca0e34833befea200c2750e859 Mon Sep 17 00:00:00 2001 From: Luca <102960244+Luca-Timo@users.noreply.github.com> Date: Tue, 23 Jun 2026 02:40:29 +0200 Subject: [PATCH 08/43] feat(workflows): admin CRUD + run-history + approvals-inbox API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GET/POST/PUT/PATCH/DELETE /api/admin/workflows with graph read/write (PUT writes a fresh node/edge set under version+1 and bumps workflows.version so in-flight runs keep their pinned version). Run-history (/:id/runs, /runs/:runId/steps) and the pending-approval inbox (GET /approvals, POST /approvals/:id/:action → actById) round it out. Gated by the workflows flag + RBAC (view for reads, manage for writes); built-in flows refuse delete; graph validated (exactly one trigger, unique keys, edges reference known nodes). Route tests cover CRUD, validation, version bump, toggle, inbox, and the 403 permission gate. --- .../integration/workflowRoutes.test.js | 102 +++++++++ backend/server.js | 1 + backend/src/routes/adminWorkflows.js | 201 ++++++++++++++++++ 3 files changed, 304 insertions(+) create mode 100644 backend/__tests__/integration/workflowRoutes.test.js create mode 100644 backend/src/routes/adminWorkflows.js diff --git a/backend/__tests__/integration/workflowRoutes.test.js b/backend/__tests__/integration/workflowRoutes.test.js new file mode 100644 index 00000000..e0b8024b --- /dev/null +++ b/backend/__tests__/integration/workflowRoutes.test.js @@ -0,0 +1,102 @@ +/** + * Admin workflow API — route tests (CRUD, versioning, RBAC gate, approvals). + */ +const request = require('supertest'); +const { + bootCrmDb, seedMinimal, assignAdminRole, mintAdminToken, buildRouteApp, +} = require('./helpers/crmDb'); + +let db; +let cleanup; +let app; +let token; +let noPermToken; + +const sampleGraph = { + name: 'Test flow', + trigger_type: 'invoice.sent', + enabled: false, + nodes: [ + { node_key: 'n1', type: 'trigger' }, + { node_key: 'n2', type: 'action', config: { action: 'noop' } }, + ], + edges: [{ from_node: 'n1', to_node: 'n2' }], +}; + +beforeAll(async () => { + ({ db, cleanup } = await bootCrmDb()); + const { adminId } = await seedMinimal(db); + await assignAdminRole(db, adminId, 'super_admin'); + token = mintAdminToken(adminId); + + const ins = await db('admin_users').insert({ + username: 'norole', email: 'nr@example.com', password_hash: 'x', + must_change_password: false, created_at: new Date(), + }).returning('id'); + noPermToken = mintAdminToken(ins[0]?.id ?? ins[0]); + + await db('feature_flags').insert({ key: 'workflows', value: true }); + app = buildRouteApp('/api/admin/workflows', require('../../src/routes/adminWorkflows')); +}); + +afterAll(async () => { await cleanup(); }); + +const auth = (t) => ({ Authorization: `Bearer ${t}` }); + +describe('admin workflows API', () => { + let createdId; + + test('create → 201 with id', async () => { + const res = await request(app).post('/api/admin/workflows').set(auth(token)).send(sampleGraph); + expect(res.status).toBe(201); + expect(res.body.id).toBeGreaterThan(0); + createdId = res.body.id; + }); + + test('rejects a graph without exactly one trigger', async () => { + const res = await request(app).post('/api/admin/workflows').set(auth(token)) + .send({ ...sampleGraph, nodes: [{ node_key: 'x', type: 'action' }], edges: [] }); + expect(res.status).toBe(400); + }); + + test('get one returns the graph', async () => { + const res = await request(app).get(`/api/admin/workflows/${createdId}`).set(auth(token)); + expect(res.status).toBe(200); + expect(res.body.nodes).toHaveLength(2); + expect(res.body.edges).toHaveLength(1); + expect(res.body.version).toBe(1); + }); + + test('list includes it', async () => { + const res = await request(app).get('/api/admin/workflows').set(auth(token)); + expect(res.status).toBe(200); + expect(res.body.some((w) => w.id === createdId)).toBe(true); + }); + + test('update bumps the version', async () => { + const res = await request(app).put(`/api/admin/workflows/${createdId}`).set(auth(token)) + .send({ ...sampleGraph, name: 'Renamed' }); + expect(res.status).toBe(200); + expect(res.body.version).toBe(2); + const get = await request(app).get(`/api/admin/workflows/${createdId}`).set(auth(token)); + expect(get.body.name).toBe('Renamed'); + expect(get.body.version).toBe(2); + }); + + test('enable toggle', async () => { + const res = await request(app).patch(`/api/admin/workflows/${createdId}/enabled`).set(auth(token)).send({ enabled: true }); + expect(res.status).toBe(200); + expect(res.body.enabled).toBe(true); + }); + + test('approvals inbox returns an array', async () => { + const res = await request(app).get('/api/admin/workflows/approvals').set(auth(token)); + expect(res.status).toBe(200); + expect(Array.isArray(res.body)).toBe(true); + }); + + test('a role without workflows.manage is forbidden from writing', async () => { + const res = await request(app).post('/api/admin/workflows').set(auth(noPermToken)).send(sampleGraph); + expect(res.status).toBe(403); + }); +}); diff --git a/backend/server.js b/backend/server.js index 9200a1a7..4fd62cb9 100644 --- a/backend/server.js +++ b/backend/server.js @@ -707,6 +707,7 @@ app.use('/api/admin/contracts', require('./src/routes/adminContracts')); app.use('/api/admin/projects', require('./src/routes/adminProjects')); app.use('/api/admin/calendar', require('./src/routes/adminCalendar')); app.use('/api/admin/deals', require('./src/routes/adminDeals')); +app.use('/api/admin/workflows', require('./src/routes/adminWorkflows')); app.use('/api/admin/tax-report', require('./src/routes/adminTaxReport')); app.use('/api/admin/expenses', require('./src/routes/adminExpenses')); app.use('/api/admin/ledger', require('./src/routes/adminLedger')); diff --git a/backend/src/routes/adminWorkflows.js b/backend/src/routes/adminWorkflows.js new file mode 100644 index 00000000..4392fdba --- /dev/null +++ b/backend/src/routes/adminWorkflows.js @@ -0,0 +1,201 @@ +/** + * Admin workflow management API. + * + * GET /api/admin/workflows list + * GET /api/admin/workflows/approvals pending-approval inbox + * POST /api/admin/workflows/approvals/:id/:act confirm|deny (webview) + * GET /api/admin/workflows/runs/:runId/steps run step audit + * GET /api/admin/workflows/:id/runs run history + * GET /api/admin/workflows/:id one workflow + its graph + * POST /api/admin/workflows create + * PUT /api/admin/workflows/:id update (bumps version) + * PATCH /api/admin/workflows/:id/enabled enable/disable + * DELETE /api/admin/workflows/:id delete (built-ins refused) + * + * Versioning: editing writes a fresh node/edge set under version+1 and bumps + * workflows.version; in-flight runs keep executing the version they pinned. + * All endpoints gated by the `workflows` feature flag + RBAC (view/manage). + */ +const express = require('express'); + +const router = express.Router(); +const { db } = require('../database/db'); +const { adminAuth } = require('../middleware/auth'); +const { requirePermission } = require('../middleware/permissions'); +const { requireFeatureFlag } = require('../middleware/requireFeatureFlag'); +const workflows = require('../services/workflows'); + +router.use(adminAuth, requireFeatureFlag('workflows')); + +function parseJson(v, fallback) { + if (v == null) return fallback; + if (typeof v === 'object') return v; + try { return JSON.parse(v); } catch (e) { return fallback; } +} + +function validateGraph(body) { + const nodes = Array.isArray(body.nodes) ? body.nodes : []; + const edges = Array.isArray(body.edges) ? body.edges : []; + const triggers = nodes.filter((n) => n.type === 'trigger'); + if (triggers.length !== 1) return 'A workflow must have exactly one trigger node'; + if (nodes.some((n) => !n.node_key || !n.type)) return 'Every node needs a node_key and type'; + const keys = new Set(nodes.map((n) => n.node_key)); + if (keys.size !== nodes.length) return 'Duplicate node_key in graph'; + for (const e of edges) { + if (!keys.has(e.from_node) || !keys.has(e.to_node)) return 'Edge references an unknown node'; + } + return null; +} + +async function writeGraph(trx, workflowId, version, nodes = [], edges = []) { + for (const n of nodes) { + await trx('workflow_nodes').insert({ + workflow_id: workflowId, version, node_key: n.node_key, type: n.type, + config: JSON.stringify(n.config || {}), pos_x: n.pos_x || 0, pos_y: n.pos_y || 0, + }); + } + for (const e of edges) { + await trx('workflow_edges').insert({ + workflow_id: workflowId, version, from_node: e.from_node, from_handle: e.from_handle || null, + to_node: e.to_node, label: e.label || null, loop_back: !!e.loop_back, + }); + } +} + +// --- Approvals inbox (registered before /:id so 'approvals' isn't an id) --- +router.get('/approvals', requirePermission('workflows.view'), async (req, res, next) => { + try { + const items = await workflows.listPending(); + res.json(items.map((a) => ({ ...a, payload: parseJson(a.payload, {}) }))); + } catch (e) { next(e); } +}); + +router.post('/approvals/:id/:action', requirePermission('workflows.manage'), async (req, res, next) => { + try { + const { action } = req.params; + if (!['confirm', 'deny'].includes(action)) return res.status(400).json({ error: 'Invalid action' }); + const result = await workflows.actById(Number(req.params.id), action, req.admin?.id); + if (!result.ok && result.reason === 'not_found') return res.status(404).json({ error: 'Approval not found' }); + if (!result.ok && result.reason === 'expired') return res.status(410).json({ error: 'Approval expired' }); + res.json(result); + } catch (e) { next(e); } +}); + +// --- Run history --- +router.get('/runs/:runId/steps', requirePermission('workflows.view'), async (req, res, next) => { + try { + const steps = await db('workflow_run_steps').where({ run_id: Number(req.params.runId) }).orderBy('id', 'asc'); + res.json(steps.map((s) => ({ ...s, result: parseJson(s.result, null) }))); + } catch (e) { next(e); } +}); + +router.get('/:id/runs', requirePermission('workflows.view'), async (req, res, next) => { + try { + const runs = await db('workflow_runs').where({ workflow_id: Number(req.params.id) }).orderBy('id', 'desc').limit(200); + res.json(runs.map((r) => ({ ...r, context: parseJson(r.context, {}) }))); + } catch (e) { next(e); } +}); + +// --- List / get --- +router.get('/', requirePermission('workflows.view'), async (req, res, next) => { + try { + const rows = await db('workflows').orderBy('id', 'desc'); + res.json(rows.map((w) => ({ ...w, trigger_config: parseJson(w.trigger_config, null) }))); + } catch (e) { next(e); } +}); + +router.get('/:id', requirePermission('workflows.view'), async (req, res, next) => { + try { + const wf = await db('workflows').where({ id: Number(req.params.id) }).first(); + if (!wf) return res.status(404).json({ error: 'Workflow not found' }); + const nodes = await db('workflow_nodes').where({ workflow_id: wf.id, version: wf.version }); + const edges = await db('workflow_edges').where({ workflow_id: wf.id, version: wf.version }); + res.json({ + ...wf, + trigger_config: parseJson(wf.trigger_config, null), + nodes: nodes.map((n) => ({ ...n, config: parseJson(n.config, {}) })), + edges, + }); + } catch (e) { next(e); } +}); + +// --- Create / update / toggle / delete --- +router.post('/', requirePermission('workflows.manage'), async (req, res, next) => { + try { + const b = req.body || {}; + if (!b.name || !b.trigger_type) return res.status(400).json({ error: 'name and trigger_type are required' }); + const err = validateGraph(b); + if (err) return res.status(400).json({ error: err }); + const id = await db.transaction(async (trx) => { + const ins = await trx('workflows').insert({ + name: b.name, description: b.description || null, enabled: !!b.enabled, version: 1, + trigger_type: b.trigger_type, trigger_config: b.trigger_config ? JSON.stringify(b.trigger_config) : null, + created_by: req.admin?.id || null, + }); + const newId = ins[0]; + await writeGraph(trx, newId, 1, b.nodes, b.edges); + return newId; + }); + res.status(201).json({ id }); + } catch (e) { next(e); } +}); + +router.put('/:id', requirePermission('workflows.manage'), async (req, res, next) => { + try { + const id = Number(req.params.id); + const wf = await db('workflows').where({ id }).first(); + if (!wf) return res.status(404).json({ error: 'Workflow not found' }); + const b = req.body || {}; + const err = validateGraph(b); + if (err) return res.status(400).json({ error: err }); + const newVersion = wf.version + 1; + await db.transaction(async (trx) => { + await trx('workflows').where({ id }).update({ + name: b.name ?? wf.name, + description: b.description ?? wf.description, + enabled: b.enabled != null ? !!b.enabled : wf.enabled, + trigger_type: b.trigger_type ?? wf.trigger_type, + trigger_config: b.trigger_config !== undefined + ? (b.trigger_config ? JSON.stringify(b.trigger_config) : null) + : wf.trigger_config, + version: newVersion, + updated_at: trx.fn.now(), + }); + await writeGraph(trx, id, newVersion, b.nodes, b.edges); + }); + res.json({ id, version: newVersion }); + } catch (e) { next(e); } +}); + +router.patch('/:id/enabled', requirePermission('workflows.manage'), async (req, res, next) => { + try { + const id = Number(req.params.id); + const enabled = !!(req.body && req.body.enabled); + const updated = await db('workflows').where({ id }).update({ enabled, updated_at: db.fn.now() }); + if (!updated) return res.status(404).json({ error: 'Workflow not found' }); + res.json({ id, enabled }); + } catch (e) { next(e); } +}); + +router.delete('/:id', requirePermission('workflows.manage'), async (req, res, next) => { + try { + const id = Number(req.params.id); + const wf = await db('workflows').where({ id }).first(); + if (!wf) return res.status(404).json({ error: 'Workflow not found' }); + if (wf.is_builtin) return res.status(409).json({ error: 'Built-in workflows cannot be deleted' }); + await db.transaction(async (trx) => { + const runIds = (await trx('workflow_runs').where({ workflow_id: id }).select('id')).map((r) => r.id); + if (runIds.length) { + await trx('workflow_run_steps').whereIn('run_id', runIds).del(); + await trx('workflow_approvals').whereIn('run_id', runIds).del(); + } + await trx('workflow_runs').where({ workflow_id: id }).del(); + await trx('workflow_edges').where({ workflow_id: id }).del(); + await trx('workflow_nodes').where({ workflow_id: id }).del(); + await trx('workflows').where({ id }).del(); + }); + res.json({ deleted: true }); + } catch (e) { next(e); } +}); + +module.exports = router; From 9b557efbf347ba585ceac61cfc0b6b3038ef7de6 Mon Sep 17 00:00:00 2001 From: Luca <102960244+Luca-Timo@users.noreply.github.com> Date: Tue, 23 Jun 2026 02:44:05 +0200 Subject: [PATCH 09/43] feat(workflows): seed invoice-dunning ladder as an editable built-in flow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Boot self-heal seeds the corrected gate-in-loop dunning graph (wait→due, grace wait, invoice_paid check, confirm-no-payment gate, bounded reminder loop with re-check, final notice) keyed on builtin_key='invoice_dunning', sized from the reminder_first/second_days settings. Seeded DISABLED and is_builtin: live reminder behaviour is UNCHANGED (the hardcoded scheduler ladder still runs) — enabling it pre-cutover would double-send, so the engine cutover is a deliberate follow-up. Idempotent (preserves admin edits). Built-ins refuse delete (enforced in the CRUD route). Test covers seed shape + idempotency. --- .../integration/workflowEngine.test.js | 19 ++++ backend/server.js | 9 ++ backend/src/services/_workflowSeedBoot.js | 102 ++++++++++++++++++ 3 files changed, 130 insertions(+) create mode 100644 backend/src/services/_workflowSeedBoot.js diff --git a/backend/__tests__/integration/workflowEngine.test.js b/backend/__tests__/integration/workflowEngine.test.js index c57f4939..a038e62e 100644 --- a/backend/__tests__/integration/workflowEngine.test.js +++ b/backend/__tests__/integration/workflowEngine.test.js @@ -233,4 +233,23 @@ describe('workflow engine', () => { const again = await engine.actByToken(rawToken, 'confirm'); expect(again.already).toBe(true); }); + + test('seeds the invoice-dunning built-in flow (disabled, idempotent)', async () => { + const { seedBuiltinWorkflowsAtBoot, DUNNING_KEY } = require('../../src/services/_workflowSeedBoot'); + const noopLogger = { info() {}, warn() {} }; + await seedBuiltinWorkflowsAtBoot(db, noopLogger); + + const wf = await db('workflows').where({ builtin_key: DUNNING_KEY }).first(); + expect(wf).toBeTruthy(); + expect(!!wf.is_builtin).toBe(true); + expect(!!wf.enabled).toBe(false); + + const nodes = await db('workflow_nodes').where({ workflow_id: wf.id, version: 1 }); + expect(nodes.filter((n) => n.type === 'trigger')).toHaveLength(1); + expect(nodes.length).toBeGreaterThanOrEqual(10); + + await seedBuiltinWorkflowsAtBoot(db, noopLogger); // idempotent + const all = await db('workflows').where({ builtin_key: DUNNING_KEY }); + expect(all.length).toBe(1); + }); }); diff --git a/backend/server.js b/backend/server.js index 4fd62cb9..6b71ea3f 100644 --- a/backend/server.js +++ b/backend/server.js @@ -897,6 +897,15 @@ async function startServer() { logger.warn('restore-settings self-heal failed at boot:', err.message); } + // Seed built-in workflows (the editable invoice-dunning flow). Disabled by + // default — live reminder behaviour is unchanged. See _workflowSeedBoot.js. + try { + const { seedBuiltinWorkflowsAtBoot } = require('./src/services/_workflowSeedBoot'); + await seedBuiltinWorkflowsAtBoot(db, logger); + } catch (err) { + logger.warn('built-in workflow seed failed at boot:', err.message); + } + // Install-from-backup trigger. If `RESTORE_ON_INSTALL` (or // `.txt`) exists in the /backup mount AND the DB is empty, run // the restore HERE before any admin UI surfaces. Lets admins diff --git a/backend/src/services/_workflowSeedBoot.js b/backend/src/services/_workflowSeedBoot.js new file mode 100644 index 00000000..01a74175 --- /dev/null +++ b/backend/src/services/_workflowSeedBoot.js @@ -0,0 +1,102 @@ +/** + * Boot-time seed for built-in workflows. + * + * Seeds the invoice-dunning ladder as an EDITABLE built-in flow (the corrected + * gate-in-loop graph), so the canvas has real content and admins can see their + * reminder process as blocks. Seeded from the current reminder settings. + * + * IMPORTANT — seeded DISABLED, and live behaviour is UNCHANGED: the existing + * hardcoded reminder ladder in invoiceService.runScheduledTasks still runs. The + * cutover (drive reminders through the engine + stop the hardcoded ladder) is a + * deliberate follow-up so we never double-send. Enabling this flow before that + * cutover would duplicate reminders — hence default off. + * + * Idempotent: keyed on builtin_key='invoice_dunning'. Once seeded, admin edits + * are preserved (we never overwrite an existing built-in). Self-heal pattern + * per [[feedback_self_heal_pattern]]. + */ +const { getAppSetting } = require('../utils/appSettings'); + +const DUNNING_KEY = 'invoice_dunning'; + +function buildDunningGraph({ firstDays, gapDays, maxReminders }) { + const nodes = [ + { node_key: 't', type: 'trigger', config: {}, pos_x: 240, pos_y: 0 }, + { node_key: 'waitDue', type: 'wait', config: { untilVar: 'dueDate' }, pos_x: 240, pos_y: 110 }, + { node_key: 'waitGrace', type: 'wait', config: { delayDays: firstDays }, pos_x: 240, pos_y: 220 }, + { node_key: 'checkPaid', type: 'condition', config: { condition: 'invoice_paid' }, pos_x: 240, pos_y: 330 }, + { node_key: 'gate', type: 'gate', config: { type: 'payment_confirm', prompt: 'No payment received yet — send a reminder?' }, pos_x: 240, pos_y: 440 }, + { node_key: 'loop', type: 'loop', config: { maxIterations: maxReminders }, pos_x: 240, pos_y: 550 }, + { node_key: 'remind', type: 'action', config: { action: 'send_email', recipientClass: 'customer', emailType: 'invoice_reminder' }, pos_x: 240, pos_y: 660 }, + { node_key: 'waitGap', type: 'wait', config: { delayDays: gapDays }, pos_x: 240, pos_y: 770 }, + { node_key: 'final', type: 'action', config: { action: 'send_email', recipientClass: 'customer', emailType: 'invoice_final_notice' }, pos_x: 520, pos_y: 660 }, + { node_key: 'doneEnd', type: 'action', config: { action: 'noop' }, pos_x: 520, pos_y: 770 }, + { node_key: 'donePaid', type: 'action', config: { action: 'noop' }, pos_x: 520, pos_y: 330 }, + ]; + const edges = [ + { from_node: 't', to_node: 'waitDue' }, + { from_node: 'waitDue', to_node: 'waitGrace' }, + { from_node: 'waitGrace', to_node: 'checkPaid' }, + { from_node: 'checkPaid', from_handle: 'yes', to_node: 'donePaid' }, + { from_node: 'checkPaid', from_handle: 'no', to_node: 'gate' }, + { from_node: 'gate', from_handle: 'confirm', to_node: 'loop' }, + { from_node: 'gate', from_handle: 'deny', to_node: 'donePaid' }, + { from_node: 'loop', from_handle: 'loop', to_node: 'remind' }, + { from_node: 'loop', from_handle: 'exit', to_node: 'final' }, + { from_node: 'remind', to_node: 'waitGap' }, + { from_node: 'waitGap', to_node: 'checkPaid', loop_back: true }, + { from_node: 'final', to_node: 'doneEnd' }, + ]; + return { nodes, edges }; +} + +let booted = false; + +async function seedBuiltinWorkflowsAtBoot(db, logger) { + try { + if (!(await db.schema.hasTable('workflows'))) return; + const existing = await db('workflows').where({ builtin_key: DUNNING_KEY }).first(); + if (existing) { booted = true; return; } + + const firstDays = Number(await getAppSetting('crm_invoices_reminder_first_days')) || 14; + const secondDays = Number(await getAppSetting('crm_invoices_reminder_second_days')) || 30; + const gapDays = Math.max(1, secondDays - firstDays); + const { nodes, edges } = buildDunningGraph({ firstDays, gapDays, maxReminders: 2 }); + + await db.transaction(async (trx) => { + const ins = await trx('workflows').insert({ + name: 'Invoice dunning (built-in)', + description: 'Editable copy of the overdue-reminder ladder: wait to due date, ' + + 'confirm-no-payment gate, then up to two reminders before a final notice. ' + + 'Disabled by default — the live reminder ladder still runs via the scheduler ' + + 'until an explicit cutover, so enabling this without that change would double-send.', + enabled: false, + version: 1, + trigger_type: 'invoice.sent', + trigger_config: null, + is_builtin: true, + builtin_key: DUNNING_KEY, + }); + const workflowId = ins[0]; + for (const n of nodes) { + await trx('workflow_nodes').insert({ + workflow_id: workflowId, version: 1, node_key: n.node_key, type: n.type, + config: JSON.stringify(n.config || {}), pos_x: n.pos_x || 0, pos_y: n.pos_y || 0, + }); + } + for (const e of edges) { + await trx('workflow_edges').insert({ + workflow_id: workflowId, version: 1, from_node: e.from_node, from_handle: e.from_handle || null, + to_node: e.to_node, label: e.label || null, loop_back: !!e.loop_back, + }); + } + }); + + booted = true; + logger?.info?.('Seeded built-in workflow: invoice dunning (disabled)'); + } catch (err) { + logger?.warn?.('Built-in workflow seed failed at boot:', err.message); + } +} + +module.exports = { seedBuiltinWorkflowsAtBoot, buildDunningGraph, DUNNING_KEY }; From 5c0396d0c1bf69ba48b42eacc6d8f145b901a299 Mon Sep 17 00:00:00 2001 From: Luca <102960244+Luca-Timo@users.noreply.github.com> Date: Tue, 23 Jun 2026 02:51:40 +0200 Subject: [PATCH 10/43] feat(workflows): React Flow canvas editor + list + approvals UI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the admin Workflows surface (top-level nav, gated by the workflows flag + workflows.view): a list page (enable toggle, delete, new), a pending-approvals inbox (confirm/deny), and a React Flow (@xyflow/react) canvas editor — palette to add nodes, drag handle→handle to connect (branch/gate/loop expose yes-no / confirm-deny / loop-exit handles), a side-panel JSON config editor, and save (writes a new version). Routes + sidebar entry + workflows.service. Build + tsc clean. NOTE: the workflow page strings render via inline English fallbacks; DE translations for the workflows.* block are still pending native review. --- frontend/package-lock.json | 235 +++++++++++++++++- frontend/package.json | 1 + frontend/src/App.tsx | 11 + .../src/components/admin/AdminSidebar.tsx | 7 + frontend/src/i18n/locales/de.json | 1 + frontend/src/i18n/locales/en.json | 1 + .../admin/workflows/WorkflowApprovalsPage.tsx | 81 ++++++ .../admin/workflows/WorkflowEditorPage.tsx | 229 +++++++++++++++++ .../admin/workflows/WorkflowsListPage.tsx | 135 ++++++++++ frontend/src/services/workflows.service.ts | 92 +++++++ 10 files changed, 791 insertions(+), 2 deletions(-) create mode 100644 frontend/src/pages/admin/workflows/WorkflowApprovalsPage.tsx create mode 100644 frontend/src/pages/admin/workflows/WorkflowEditorPage.tsx create mode 100644 frontend/src/pages/admin/workflows/WorkflowsListPage.tsx create mode 100644 frontend/src/services/workflows.service.ts diff --git a/frontend/package-lock.json b/frontend/package-lock.json index 9aac8719..414aaecb 100644 --- a/frontend/package-lock.json +++ b/frontend/package-lock.json @@ -1,12 +1,12 @@ { "name": "picpeak-frontend", - "version": "3.47.2-beta.0", + "version": "3.69.0-beta.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "picpeak-frontend", - "version": "3.47.2-beta.0", + "version": "3.69.0-beta.0", "dependencies": { "@fullcalendar/core": "^6.1.20", "@fullcalendar/daygrid": "^6.1.20", @@ -25,6 +25,7 @@ "@types/dompurify": "^3.0.5", "@types/lodash": "^4.17.20", "@types/react-google-recaptcha": "^2.1.9", + "@xyflow/react": "^12.11.1", "axios": "1.15.2", "clsx": "^2.0.0", "date-fns": "4.1.0", @@ -3460,6 +3461,55 @@ "assertion-error": "^2.0.1" } }, + "node_modules/@types/d3-color": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/@types/d3-color/-/d3-color-3.1.3.tgz", + "integrity": "sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A==", + "license": "MIT" + }, + "node_modules/@types/d3-drag": { + "version": "3.0.7", + "resolved": "https://registry.npmjs.org/@types/d3-drag/-/d3-drag-3.0.7.tgz", + "integrity": "sha512-HE3jVKlzU9AaMazNufooRJ5ZpWmLIoc90A37WU2JMmeq28w1FQqCZswHZ3xR+SuxYftzHq6WU6KJHvqxKzTxxQ==", + "license": "MIT", + "dependencies": { + "@types/d3-selection": "*" + } + }, + "node_modules/@types/d3-interpolate": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/@types/d3-interpolate/-/d3-interpolate-3.0.4.tgz", + "integrity": "sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA==", + "license": "MIT", + "dependencies": { + "@types/d3-color": "*" + } + }, + "node_modules/@types/d3-selection": { + "version": "3.0.11", + "resolved": "https://registry.npmjs.org/@types/d3-selection/-/d3-selection-3.0.11.tgz", + "integrity": "sha512-bhAXu23DJWsrI45xafYpkQ4NtcKMwWnAC/vKrd2l+nxMFuvOT3XMYTIj2opv8vq8AO5Yh7Qac/nSeP/3zjTK0w==", + "license": "MIT" + }, + "node_modules/@types/d3-transition": { + "version": "3.0.9", + "resolved": "https://registry.npmjs.org/@types/d3-transition/-/d3-transition-3.0.9.tgz", + "integrity": "sha512-uZS5shfxzO3rGlu0cC3bjmMFKsXv+SmZZcgp0KD22ts4uGXp5EVYGzu/0YdwZeKmddhcAccYtREJKkPfXkZuCg==", + "license": "MIT", + "dependencies": { + "@types/d3-selection": "*" + } + }, + "node_modules/@types/d3-zoom": { + "version": "3.0.8", + "resolved": "https://registry.npmjs.org/@types/d3-zoom/-/d3-zoom-3.0.8.tgz", + "integrity": "sha512-iqMC4/YlFCSlO8+2Ii1GGGliCAY4XdeG748w5vQUbevlbDu0zSjH/+jojorQVBK/se0j6DUFNPBGSqD3YWYnDw==", + "license": "MIT", + "dependencies": { + "@types/d3-interpolate": "*", + "@types/d3-selection": "*" + } + }, "node_modules/@types/deep-eql": { "version": "4.0.2", "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz", @@ -3996,6 +4046,48 @@ "url": "https://opencollective.com/vitest" } }, + "node_modules/@xyflow/react": { + "version": "12.11.1", + "resolved": "https://registry.npmjs.org/@xyflow/react/-/react-12.11.1.tgz", + "integrity": "sha512-L+zBoLGSXham0MnlY8QqjfR7/C5JNw0zxkaey5aZ5XmCgJBAdH4+WRIu8CR40d3l/BdU635V6YbhBK1jMo8/6Q==", + "license": "MIT", + "dependencies": { + "@xyflow/system": "0.0.78", + "classcat": "^5.0.3", + "zustand": "^4.4.0" + }, + "peerDependencies": { + "@types/react": ">=17", + "@types/react-dom": ">=17", + "react": ">=17", + "react-dom": ">=17" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@xyflow/system": { + "version": "0.0.78", + "resolved": "https://registry.npmjs.org/@xyflow/system/-/system-0.0.78.tgz", + "integrity": "sha512-lY0z2qP33fUhTva9Vaxrk0lqZta2pkbxB1trHAx1omnJqRtPvDlAQYV2r5fhS6AdpkulYmbNW0svy+A4/t4B/g==", + "license": "MIT", + "dependencies": { + "@types/d3-drag": "^3.0.7", + "@types/d3-interpolate": "^3.0.4", + "@types/d3-selection": "^3.0.10", + "@types/d3-transition": "^3.0.8", + "@types/d3-zoom": "^3.0.8", + "d3-drag": "^3.0.0", + "d3-interpolate": "^3.0.1", + "d3-selection": "^3.0.0", + "d3-zoom": "^3.0.0" + } + }, "node_modules/acorn": { "version": "8.15.0", "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz", @@ -4435,6 +4527,12 @@ "node": ">= 6" } }, + "node_modules/classcat": { + "version": "5.0.5", + "resolved": "https://registry.npmjs.org/classcat/-/classcat-5.0.5.tgz", + "integrity": "sha512-JhZUT7JFcQy/EzW605k/ktHtncoo9vnyW/2GspNYwFlN1C/WmjuV/xtS04e9SOkL2sTdw0VAZ2UGCcQ9lR6p6w==", + "license": "MIT" + }, "node_modules/cli-cursor": { "version": "5.0.0", "resolved": "https://registry.npmjs.org/cli-cursor/-/cli-cursor-5.0.0.tgz", @@ -4634,6 +4732,111 @@ "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==", "license": "MIT" }, + "node_modules/d3-color": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-color/-/d3-color-3.1.0.tgz", + "integrity": "sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==", + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-dispatch": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-dispatch/-/d3-dispatch-3.0.1.tgz", + "integrity": "sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==", + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-drag": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-drag/-/d3-drag-3.0.0.tgz", + "integrity": "sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==", + "license": "ISC", + "dependencies": { + "d3-dispatch": "1 - 3", + "d3-selection": "3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-ease": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-ease/-/d3-ease-3.0.1.tgz", + "integrity": "sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==", + "license": "BSD-3-Clause", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-interpolate": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-interpolate/-/d3-interpolate-3.0.1.tgz", + "integrity": "sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==", + "license": "ISC", + "dependencies": { + "d3-color": "1 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-selection": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz", + "integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==", + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-timer": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-timer/-/d3-timer-3.0.1.tgz", + "integrity": "sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==", + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-transition": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-transition/-/d3-transition-3.0.1.tgz", + "integrity": "sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w==", + "license": "ISC", + "dependencies": { + "d3-color": "1 - 3", + "d3-dispatch": "1 - 3", + "d3-ease": "1 - 3", + "d3-interpolate": "1 - 3", + "d3-timer": "1 - 3" + }, + "engines": { + "node": ">=12" + }, + "peerDependencies": { + "d3-selection": "2 - 3" + } + }, + "node_modules/d3-zoom": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-zoom/-/d3-zoom-3.0.0.tgz", + "integrity": "sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==", + "license": "ISC", + "dependencies": { + "d3-dispatch": "1 - 3", + "d3-drag": "2 - 3", + "d3-interpolate": "1 - 3", + "d3-selection": "2 - 3", + "d3-transition": "2 - 3" + }, + "engines": { + "node": ">=12" + } + }, "node_modules/data-urls": { "version": "5.0.0", "resolved": "https://registry.npmjs.org/data-urls/-/data-urls-5.0.0.tgz", @@ -9297,6 +9500,34 @@ "funding": { "url": "https://github.com/sponsors/sindresorhus" } + }, + "node_modules/zustand": { + "version": "4.5.7", + "resolved": "https://registry.npmjs.org/zustand/-/zustand-4.5.7.tgz", + "integrity": "sha512-CHOUy7mu3lbD6o6LJLfllpjkzhHXSBlX8B9+qPddUsIfeF5S/UZ5q0kmCsnRqT1UHFQZchNFDDzMbQsuesHWlw==", + "license": "MIT", + "dependencies": { + "use-sync-external-store": "^1.2.2" + }, + "engines": { + "node": ">=12.7.0" + }, + "peerDependencies": { + "@types/react": ">=16.8", + "immer": ">=9.0.6", + "react": ">=16.8" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "immer": { + "optional": true + }, + "react": { + "optional": true + } + } } } } diff --git a/frontend/package.json b/frontend/package.json index 2a6b6033..da03cbb7 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -32,6 +32,7 @@ "@types/dompurify": "^3.0.5", "@types/lodash": "^4.17.20", "@types/react-google-recaptcha": "^2.1.9", + "@xyflow/react": "^12.11.1", "axios": "1.15.2", "clsx": "^2.0.0", "date-fns": "4.1.0", diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index 169a0297..959628d3 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -46,6 +46,9 @@ import { QuoteResponsePage } from './pages/public/QuoteResponsePage'; import { ContractResponsePage } from './pages/public/ContractResponsePage'; import { ProjectsListPage } from './pages/admin/projects/ProjectsListPage'; import { ProjectCockpitPage } from './pages/admin/projects/ProjectCockpitPage'; +import { WorkflowsListPage } from './pages/admin/workflows/WorkflowsListPage'; +import { WorkflowApprovalsPage } from './pages/admin/workflows/WorkflowApprovalsPage'; +import { WorkflowEditorPage } from './pages/admin/workflows/WorkflowEditorPage'; import { ContractsListPage } from './pages/admin/contracts/ContractsListPage'; import { ContractEditorPage } from './pages/admin/contracts/ContractEditorPage'; import { ContractDetailPage } from './pages/admin/contracts/ContractDetailPage'; @@ -314,6 +317,14 @@ function App() {{t('workflows.approvals.subtitle', 'Workflow runs waiting on your confirmation.')}
+