Task F.3: Approval Workflow Builder Foundation

Summary

This task upgrades the existing approval workflow settings surface into a safer workflow builder foundation. Admins can now manage workflow metadata and steps through dedicated APIs and a richer settings UI without editing seed data directly.

Delivered

Extended approval workflow schema in src/db/schema.ts:
- workflow: description, isSystem, createdBy, updatedBy
- step: approvalMode
Added migration drizzle/0003_workflow_builder_foundation.sql
Added builder validation schemas:
- src/features/crm/approval/schemas/approval-workflow.schema.ts
- src/features/crm/approval/schemas/approval-step.schema.ts
Added builder server rules in src/features/crm/approval/server/workflow-builder.service.ts
Replaced the settings APIs with builder-aware behavior under:
Rebuilt workflow builder client contracts and UI in:

Workflow Safety Strategy

F.3 uses the recommended lock strategy from the task:

if a workflow has ever been used by any approval request, the workflow becomes locked for metadata edits
locked workflows also block step create, update, delete, and reorder
admins must clone a used workflow before changing its behavior

This prevents historical approval requests from silently changing meaning after configuration edits.

Clone and Activation Rules

clone copies workflow metadata and all active steps
cloned workflows start inactive
deactivation is blocked when:
- active approval requests still use the workflow
- active approval matrices still point to the workflow
deletion is blocked when:
- any approval request has ever used the workflow
- active approval matrices still point to the workflow

Step Builder Rules

steps are managed individually instead of replacing the whole step list
create supports inserting at a target stepNumber
delete reorders remaining steps to continuous numbering
reorder uses explicit orderedStepIds
active workflows must retain at least one required step

Approval Mode Support

Stored step modes:

sequential
any_one
all_required

Current runtime still executes sequentially only. The builder UI marks non-sequential modes as stored for future use instead of pretending they already affect runtime behavior.

Permissions Added

Extended in src/lib/auth/rbac.ts:

crm.approval.workflow.clone
crm.approval.workflow.activate
crm.approval.workflow.deactivate
crm.approval.workflow.step.manage

Existing workflow read/create/update/delete permissions remain in use.

Audit Actions

Builder routes now emit:

create_approval_workflow
update_approval_workflow
delete_approval_workflow
clone_approval_workflow
activate_approval_workflow
deactivate_approval_workflow
create_approval_step
update_approval_step
delete_approval_step
reorder_approval_steps

Matrix Integration Hook

Workflow list API now accepts optional filters:

entityType
activeOnly

This keeps Approval Matrix integration future-ready without requiring F.3 to build the matrix UI itself.

Known Limitations

approval runtime still executes sequentially even if a step stores any_one or all_required
no drag-and-drop builder is included; reorder uses simple up/down actions
no workflow version table exists yet; lock-and-clone is the current compatibility strategy
matrix admin UI is still outside this task scope

6.3 KiB Raw Blame History