# 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](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/db/schema.ts):
  - workflow: `description`, `isSystem`, `createdBy`, `updatedBy`
  - step: `approvalMode`
- Added migration [drizzle/0003_workflow_builder_foundation.sql](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/drizzle/0003_workflow_builder_foundation.sql)
- Added builder validation schemas:
  - [src/features/crm/approval/schemas/approval-workflow.schema.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/approval/schemas/approval-workflow.schema.ts)
  - [src/features/crm/approval/schemas/approval-step.schema.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/approval/schemas/approval-step.schema.ts)
- Added builder server rules in [src/features/crm/approval/server/workflow-builder.service.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/approval/server/workflow-builder.service.ts)
- Replaced the settings APIs with builder-aware behavior under:
  - [src/app/api/crm/settings/approval-workflows/route.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/approval-workflows/route.ts)
  - [src/app/api/crm/settings/approval-workflows/[id]/route.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/approval-workflows/[id]/route.ts)
  - [src/app/api/crm/settings/approval-workflows/[id]/clone/route.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/approval-workflows/[id]/clone/route.ts)
  - [src/app/api/crm/settings/approval-workflows/[id]/activate/route.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/approval-workflows/[id]/activate/route.ts)
  - [src/app/api/crm/settings/approval-workflows/[id]/deactivate/route.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/approval-workflows/[id]/deactivate/route.ts)
  - [src/app/api/crm/settings/approval-workflows/[id]/steps/route.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/approval-workflows/[id]/steps/route.ts)
  - [src/app/api/crm/settings/approval-workflows/[id]/steps/[stepId]/route.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/approval-workflows/[id]/steps/[stepId]/route.ts)
  - [src/app/api/crm/settings/approval-workflows/[id]/steps/reorder/route.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/approval-workflows/[id]/steps/reorder/route.ts)
- Rebuilt workflow builder client contracts and UI in:
  - [src/features/foundation/approval/types.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/approval/types.ts)
  - [src/features/foundation/approval/service.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/approval/service.ts)
  - [src/features/foundation/approval/queries.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/approval/queries.ts)
  - [src/features/foundation/approval/mutations.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/approval/mutations.ts)
  - [src/features/foundation/approval/components/approval-workflow-settings.tsx](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/approval/components/approval-workflow-settings.tsx)

## 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](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/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