alla-allaos-fullstack/docs/implementation/task-f2-approval-matrix-foundation.md

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.
• Added SQL migration in drizzle/0002_calm_approval_matrix.sql.
• Seeded a default quotation matrix in src/db/seeds/foundation.seed.ts to preserve current behavior.
• Added matrix validation in src/features/crm/approval/schemas/approval-matrix.schema.ts.
• Added matrix CRUD and resolver services in src/features/crm/approval/server/service.ts.
• Added settings APIs:
  • src/app/api/crm/settings/approval-matrices/route.ts
  • 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 to resolve workflow by matrix before creating the approval request.
• Extended foundation approval submit input in:
  • src/features/foundation/approval/types.ts
  • src/features/foundation/approval/server/service.ts
• Added permissions in 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.