82 lines
4.5 KiB
Markdown
82 lines
4.5 KiB
Markdown
# Task F.2: Approval Matrix Foundation
|
|
|
|
## Summary
|
|
|
|
This task adds approval-matrix based workflow resolution for quotation submission so the system no longer relies on a single static workflow code.
|
|
|
|
## Delivered
|
|
|
|
- Added `crm_approval_matrices` persistence in [src/db/schema.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/db/schema.ts).
|
|
- Added SQL migration in [drizzle/0002_calm_approval_matrix.sql](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/drizzle/0002_calm_approval_matrix.sql).
|
|
- Seeded a default quotation matrix in [src/db/seeds/foundation.seed.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/db/seeds/foundation.seed.ts) to preserve current behavior.
|
|
- Added matrix validation in [src/features/crm/approval/schemas/approval-matrix.schema.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/approval/schemas/approval-matrix.schema.ts).
|
|
- Added matrix CRUD and resolver services in [src/features/crm/approval/server/service.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/approval/server/service.ts).
|
|
- Added settings APIs:
|
|
- [src/app/api/crm/settings/approval-matrices/route.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/approval-matrices/route.ts)
|
|
- [src/app/api/crm/settings/approval-matrices/[id]/route.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/approval-matrices/[id]/route.ts)
|
|
- Updated quotation submit approval flow in [src/app/api/crm/quotations/[id]/submit-approval/route.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/quotations/[id]/submit-approval/route.ts) to resolve workflow by matrix before creating the approval request.
|
|
- Extended foundation approval submit input 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/server/service.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/approval/server/service.ts)
|
|
- Added permissions in [src/lib/auth/rbac.ts](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/lib/auth/rbac.ts):
|
|
- `crm.approval.matrix.read`
|
|
- `crm.approval.matrix.create`
|
|
- `crm.approval.matrix.update`
|
|
- `crm.approval.matrix.delete`
|
|
|
|
## Matching Rules
|
|
|
|
- Scope filters consider organization, entity type, active state, and soft delete.
|
|
- `productType`, `branchId`, and `currency` match exact values or `null` wildcard.
|
|
- `amount` respects `minAmount` and `maxAmount` when those bounds exist.
|
|
- Specific rules outrank default rules.
|
|
- Specificity scoring prefers:
|
|
- product type match
|
|
- branch match
|
|
- currency match
|
|
- amount-range match
|
|
- Lower `priority` value wins after specificity.
|
|
- If specificity and priority tie, the newest active rule wins.
|
|
- If candidates still tie on the same creation timestamp, the resolver throws a deterministic configuration conflict.
|
|
- If no specific rule matches, the resolver falls back to an active default rule.
|
|
|
|
## Submit Approval Integration
|
|
|
|
- Quotation submit approval now:
|
|
1. loads the quotation
|
|
2. enforces CRM scoped access
|
|
3. resolves the approval matrix
|
|
4. submits approval using the resolved `workflowId`
|
|
5. writes audit data for the resolution
|
|
- Existing approve, reject, return, and cancel flows remain unchanged.
|
|
|
|
## Audit
|
|
|
|
- Matrix CRUD uses `entityType = crm_approval_matrix`.
|
|
- Matrix maintenance actions:
|
|
- `create_approval_matrix`
|
|
- `update_approval_matrix`
|
|
- `delete_approval_matrix`
|
|
- Quotation submission writes `resolve_approval_matrix` with:
|
|
- `quotationId`
|
|
- `approvalRequestId`
|
|
- `matrixId`
|
|
- `workflowId`
|
|
- `matchReason`
|
|
- `productType`
|
|
- `branchId`
|
|
- `amount`
|
|
- `currency`
|
|
|
|
## Seed Behavior
|
|
|
|
- Foundation seed creates or refreshes one active default quotation matrix pointing to `quotation_standard_approval`.
|
|
- This preserves legacy quotation approval behavior until organization-specific rules are added.
|
|
- Sample non-default matrices were intentionally not seeded because additional workflows such as executive approval are not yet guaranteed in every environment.
|
|
|
|
## Known Limitations
|
|
|
|
- F.2 adds API and service foundations only. No matrix admin UI is included.
|
|
- Overlapping active rules are allowed. Resolver handles them deterministically, but configuration hygiene still matters.
|
|
- Matrix branch, product, and currency values currently assume the same ids already stored on quotation records.
|