alla-allaos-fullstack/plans/task-f.3.md

Task F.3: Approval Workflow Builder Foundation

Status

Planned

Objective

Build the Approval Workflow Builder foundation so admins can manage approval workflows and workflow steps without changing code or seed data.

This task extends the F.2 Approval Matrix Foundation by making workflow definitions editable and maintainable through service/API/UI foundations.

The goal is to support:

• workflow list
• workflow create/edit
• workflow clone
• workflow activate/deactivate
• step add/update/delete
• step reorder
• matrix-ready workflow selection
• safe compatibility with existing approval requests

This task does not implement Notification, Reminder, Escalation, or full parallel approval behavior yet.

---

Mandatory Review

Review before implementation:

• AGENTS.md
• docs/standards/project-foundations.md
• docs/standards/task-catalog.md
• docs/implementation/task-f2-approval-matrix-foundation.md
• existing Approval implementation
• existing Approval Matrix implementation
• src/db/schema.ts
• src/features/crm/approval/**
• src/features/foundation/approval/**
• src/features/foundation/audit-log/**
• src/lib/auth/rbac.ts
• docs/security/crm-authorization-boundaries.md

---

Current Foundation

Already available:

crm_approval_workflows
crm_approval_steps
crm_approval_requests
crm_approval_actions
crm_approval_matrices

Approval matrix resolver
Quotation submit approval flow
Default quotation matrix
Approval audit foundation

Current limitation:

Approval workflows and steps are mostly seed/config driven.

This task makes them manageable through Builder APIs and UI foundation.

---

Business Requirement

Admin must be able to configure approval workflows such as:

Quotation Standard Approval
  1. Sales Manager
  2. Department Manager
  3. CEO

Quotation Crane Executive Approval
  1. Sales Manager
  2. Product Head
  3. Finance
  4. CEO

Approval Matrix from F.2 can then point to any active workflow.

---

Scope F.3.1 Workflow Builder Domain Rules

Workflow has:

code
name
entityType
description
isActive
steps

Step has:

stepNumber
roleCode
roleName
approvalMode
isRequired

Recommended approvalMode values:

sequential
any_one
all_required

For F.3 behavior:

• sequential remains the only fully executed runtime mode if current approval engine supports only sequential
• any_one and all_required can be stored for future use if schema supports it
• if runtime does not support non-sequential modes, UI/API must clearly mark them as future/disabled

---

Scope F.3.2 Schema Review / Extension

Review existing tables:

crm_approval_workflows
crm_approval_steps

Add missing fields only if needed:

Recommended workflow fields:

description text null
is_system boolean default false
created_by text
updated_by text

Recommended step fields:

approval_mode text default 'sequential'
approver_type text default 'role'
approver_ref text null
sort_order integer

Definitions:

approver_type = role | user | permission | manager
approver_ref = role code, user id, permission code, or manager rule key

If current phase should stay simple, use only:

roleCode
roleName
stepNumber
isRequired

and defer advanced approver resolution to later tasks.

---

Scope F.3.3 Workflow CRUD API

Create or extend settings APIs:

GET    /api/crm/settings/approval-workflows
POST   /api/crm/settings/approval-workflows
GET    /api/crm/settings/approval-workflows/[id]
PATCH  /api/crm/settings/approval-workflows/[id]
DELETE /api/crm/settings/approval-workflows/[id]
POST   /api/crm/settings/approval-workflows/[id]/clone
POST   /api/crm/settings/approval-workflows/[id]/activate
POST   /api/crm/settings/approval-workflows/[id]/deactivate

Rules:

• delete should be soft delete
• do not allow hard delete
• do not allow deleting workflow used by an active approval request
• deactivation allowed only if not used by active matrix or active approval request unless forced by admin policy
• clone creates a new workflow and copies steps
• code must be unique within organization

---

Scope F.3.4 Step Management API

Create:

GET    /api/crm/settings/approval-workflows/[id]/steps
POST   /api/crm/settings/approval-workflows/[id]/steps
PATCH  /api/crm/settings/approval-workflows/[id]/steps/[stepId]
DELETE /api/crm/settings/approval-workflows/[id]/steps/[stepId]
POST   /api/crm/settings/approval-workflows/[id]/steps/reorder

Rules:

• step numbers must be continuous: 1, 2, 3...

• deleting a step reorders remaining steps

• reorder must be transactional

• at least one required step must remain for active workflow

• cannot modify steps of workflow with active approval requests unless versioning is implemented

• F.3 may choose strict lock behavior:

  • if workflow is already used by any approval request, require clone before edit

Recommended:

Existing used workflow = locked
Edit by clone only

This prevents historical approval requests from changing meaning retroactively.

---

Scope F.3.5 Workflow Version Safety

Implement one of these strategies:

Option A: Lock Used Workflows

If workflow has ever been used in approval request:

workflow cannot be edited
steps cannot be edited
admin must clone workflow

This is recommended for F.3.

Option B: Versioned Workflows

Create workflow versions.

This is more powerful but larger scope.

Recommendation:

Use Option A in F.3.
Defer versioned workflows to future task if needed.

---

Scope F.3.6 Workflow Builder UI

Create settings page:

/dashboard/crm/settings/approval-workflows

Required UI:

• workflow list
• create workflow
• edit workflow metadata
• clone workflow
• activate/deactivate workflow
• view steps
• add step
• edit step
• delete step
• reorder steps
• usage warning if workflow is locked

Use existing UI conventions:

shadcn/ui
card layout
dialog/sheet forms
table
bento/card section where useful
design tokens only

No drag-and-drop is required in F.3. Simple up/down reorder is enough.

---

Scope F.3.7 Matrix Integration UI Hook

Approval Matrix settings must be able to select an active workflow.

If F.2 has no matrix UI yet, expose workflow list API so future matrix UI can consume it.

Workflow list API should support:

entityType filter
active only filter

---

Scope F.3.8 Validation Rules

Create schemas:

src/features/crm/approval/schemas/approval-workflow.schema.ts
src/features/crm/approval/schemas/approval-step.schema.ts

Workflow validation:

• code required
• code normalized lowercase / snake_case
• name required
• entityType required
• code unique per organization
• cannot update code if workflow is used

Step validation:

• roleCode required
• roleName required
• stepNumber positive integer
• approvalMode required
• isRequired boolean
• cannot create duplicate stepNumber
• cannot leave active workflow with no required step

---

Scope F.3.9 Audit Logging

Audit actions:

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

Audit must capture:

workflowId
stepId
before
after
actor
timestamp

---

Scope F.3.10 Permissions

Add or verify permissions:

crm.approval.workflow.read
crm.approval.workflow.create
crm.approval.workflow.update
crm.approval.workflow.delete
crm.approval.workflow.clone
crm.approval.workflow.activate
crm.approval.workflow.deactivate
crm.approval.workflow.step.manage

Rules:

• Admin/settings-only feature
• route handlers must not check role strings directly
• use existing CRM authorization foundation
• do not expose builder to normal sales users

---

Scope F.3.11 Documentation

Create:

docs/implementation/task-f3-approval-workflow-builder-foundation.md

Document:

workflow schema
step schema
lock strategy
clone behavior
API routes
permission map
known limitations

---

Explicit Non-Scope

Do not implement:

• Notification Center
• Email sending
• LINE sending
• approval reminder
• approval escalation
• delegation
• vacation substitute approval
• manager hierarchy approver lookup
• full workflow versioning
• drag-and-drop builder
• advanced parallel approval runtime
• approval dashboard

These belong to later F tasks.

---

Verification

Run:

npm exec tsc --noEmit
npm run build

Manual verification:

Create workflow
Edit unused workflow
Add steps
Edit steps
Delete step and verify reorder
Reorder steps
Clone workflow
Deactivate workflow
Activate workflow
Cannot edit used workflow if lock strategy is applied
Cannot delete workflow used by active approval request
Approval Matrix can resolve to newly created active workflow
Submit quotation approval still works
Approve/reject existing flow still works
Audit logs are created

---

Definition of Done

Task is complete when:

• Approval Workflow Builder APIs exist
• Approval Workflow settings UI exists
• Admin can create/clone/activate/deactivate workflow
• Admin can add/edit/delete/reorder steps
• Used workflow edit safety is enforced
• Approval Matrix can select active workflows
• Existing quotation approval submit/approve/reject flow remains operational
• Audit logs capture workflow and step maintenance

Result:

Approval Workflow Builder Foundation = Established
Approval Matrix Configuration = Maintainable
Ready for F.4 Notification Framework