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