task-f.3
This commit is contained in:
phaichayon
504
plans/task-f.3.md
Normal file
504
plans/task-f.3.md
Normal file
@@ -0,0 +1,504 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user