# 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:

```txt
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:

```txt
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:

```txt
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:

```txt
code
name
entityType
description
isActive
steps
```

Step has:

```txt
stepNumber
roleCode
roleName
approvalMode
isRequired
```

Recommended `approvalMode` values:

```txt
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:

```txt
crm_approval_workflows
crm_approval_steps
```

Add missing fields only if needed:

Recommended workflow fields:

```txt
description text null
is_system boolean default false
created_by text
updated_by text
```

Recommended step fields:

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

Definitions:

```txt
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:

```txt
roleCode
roleName
stepNumber
isRequired
```

and defer advanced approver resolution to later tasks.

---

## Scope F.3.3 Workflow CRUD API

Create or extend settings APIs:

```txt
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:

```txt
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:

```txt
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:

```txt
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:

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

---

## Scope F.3.6 Workflow Builder UI

Create settings page:

```txt
/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:

```txt
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:

```txt
entityType filter
active only filter
```

---

## Scope F.3.8 Validation Rules

Create schemas:

```txt
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:

```txt
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:

```txt
workflowId
stepId
before
after
actor
timestamp
```

---

## Scope F.3.10 Permissions

Add or verify permissions:

```txt
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:

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

Document:

```txt
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:

```txt
npm exec tsc --noEmit
npm run build
```

Manual verification:

```txt
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:

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