Acceptance Criteria

• Users with correct permissions can update lifecycle stage via UI and API

• Updated stage reflects in UI within 2 seconds after API call

• Only predefined tenant stages are allowed (no free-text stages)

• Every lifecycle change is logged in customer_lifecycle_history

• System gracefully handles simultaneous updates (concurrent modification)

• UI clearly shows the current stage and last change date

• Caching layer is refreshed automatically after lifecycle updates

• Reason field is required when moving to "At-Risk" or "Churned"

Testing Notes

Unit Tests

• Validate stage transitions: allowed vs. disallowed

• Ensure data validation (e.g., ENUM values, UUID formats)

• Test reason code enforcement logic

Integration Tests

• API permission tests for different roles

• Test full lifecycle from CRM event to UI update

• Verify audit trail is recorded correctly

Performance Tests

• Test 100,000 lifecycle transitions in under 5 minutes

• Ensure Redis cache invalidation happens on write

• Simulate burst update traffic to validate rate-limiting

Regression Scenarios

• Updates to lifecycle should not affect unrelated customer modules (CRM, Billing)

• Transition logic should remain consistent after tenant config changes