505 lines
9.5 KiB
Markdown
505 lines
9.5 KiB
Markdown
# 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
|
|
```
|