task-f.3
This commit is contained in:
phaichayon
@@ -0,0 +1,112 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user