CRM Leads

// Inside SubmitContactSalesLeadCommandHandler.cs:
// Check 1: Workspace Collision
var slug = SubdomainHelper.Normalize(request.CompanyName);
if (await _tenantRepository.ExistsBySlugAsync(slug, ct))
    return Result.Fail("workspace_exists");

// Check 2: Deduplication & ABM Parent Linking
var activeLead = await _leadRepository.GetActiveByCompanyAsync(request.CompanyName, ct);
if (activeLead != null)
{
    if (activeLead.Email == request.Email)
        return Result.Fail("duplicate_lead");
        
    // Enterprise ABM: link colleague submission
    parentLeadId = activeLead.Id;
}

// Check 3: Daily Cap
var todayCount = await _leadRepository.CountTodayAsync(ct);
if (todayCount >= 1000) // DailyLeadCap
    return Result.Fail("daily_cap_exceeded");

Entitlements.Domain/
├── Entities/
│   └── PlatformLead.cs              # Lead entity (inherits AuditableEntity)
├── Enums/
│   ├── LeadStatus.cs                # New, Contacted, Qualified, Won, Converted, Lost
│   └── LeadSource.cs                # Website, Admin
└── Interfaces/
    └── IPlatformLeadRepository.cs   # Repository contract

Entitlements.Application/
├── Commands/
│   └── Leads/
│       ├── SubmitContactSalesLead/   # Public signup wizard form submission
│       ├── CreateLead/               # Admin-created lead
│       ├── UpdateLeadStatus/         # Status transition (New → Contacted → …)
│       ├── AssignLead/               # Assign/unassign to admin
│       ├── ConvertLeadToTenant/      # Atomic lead → tenant conversion
│       └── DeleteLead/               # Soft delete
├── Queries/
│   └── Leads/
│       ├── GetLeads/                 # Paginated list with filters
│       ├── GetLeadById/              # Full detail
│       └── GetLeadActivity/          # Timeline of status changes + notes
└── DTOs/
    └── Leads/
        └── PlatformLeadResponse.cs   # Full detail DTO
        └── PlatformLeadListResponse.cs

Entitlements.Infrastructure/
└── Persistence/
    └── PlatformLeadRepository.cs     # EF Core implementation

public class PlatformLead : AuditableEntity
{
    // ── Contact info ──────────────────────────────────────────────
    public string CompanyName { get; set; } = string.Empty;
    public string ContactName { get; set; } = string.Empty;
    public string Email       { get; set; } = string.Empty;
    public string? Phone      { get; set; }

    // ── Interest ──────────────────────────────────────────────────
    public string?     EditionKey      { get; set; }  // Plan selected in wizard
    public string?     Message         { get; set; }  // Free-text message
    public LeadSource  Source          { get; set; } = LeadSource.Website;

    // ── Discovery Intelligence (from signup wizard) ───────────────
    public string? BusinessType     { get; set; }   // Q1: erp / healthcare / general
    public string? TeamSize         { get; set; }   // Q2: solo / 2-10 / 11-50 / …
    public string? Priority         { get; set; }   // Q3: comma-separated, max 3
    public string? RecommendedTier  { get; set; }   // Computed: free / pro / business / enterprise

    // ── CRM Lifecycle ─────────────────────────────────────────────
    public LeadStatus Status             { get; set; } = LeadStatus.New;
    public Guid?      AssignedToAdminId  { get; set; }
    public string?    Notes              { get; set; }

    // ── Conversion ────────────────────────────────────────────────
    public DateTime? ConvertedAt           { get; set; }
    public string?   ConvertedToTenantId  { get; set; }  // Encrypted
}

public record ConvertLeadToTenantCommand(
    string  EncryptedLeadId,
    string  TenantName,
    string  TenantCode,
    string  AdminEmail,
    string? AdminUsername,
    string? EditionId,          // null = use lead's EditionKey
    string? SubscriptionType,   // null = handler decides
    string  Currency,           // default: USD
    bool    SkipPayment = true  // always true for contact-sales
) : ICommand<ConvertLeadToTenantResult>;

// Inside ConvertLeadToTenantCommandHandler.cs:
// 1. Check if lead is already Converted/Closed.
// 2. Resolve EditionId from lead.EditionKey if not provided.
// 3. Call ITenantProvisioner.ProvisionAsync() inside transaction:
//    - Phase 1: Create tenant, seed default roles, and create tenant admin user.
//    - Phase 2: Call _subscriptionManager.AssignEditionAsync() to create subscription.
// 4. Save custom feature overrides.
// 5. Update lead entity status = Converted, set ConvertedAt and ConvertedToTenantId.
// 6. Log Converted activity.
// 7. SaveChangesAsync() to commit the transaction.
// 8. Saga Compensation: If updating the lead fails after tenant provisioning,
//    throw a critical exception to trigger database transaction rollback or manual reconciliation.

{
  "Leads": {
    "SalesNotificationEmail": "sales@yourcompany.com"
  },
  "SmtpSettings": {
    "Host": "smtp-relay.gmail.com",
    "Port": 587,
    "Username": "noreply@yourcompany.com",
    "Password": "<app-password>",
    "FromName": "SCRIPE",
    "FromEmail": "noreply@yourcompany.com",
    "EnableSsl": true
  }
}

src/modules/entitlements/leads/
├── locales/
│   ├── leads.en.ts                    # EN translations (drawer, stats, dialogs)
│   ├── leads.ar.ts                    # AR translations (native UTF-8)
│   └── index.ts
└── src/
    ├── domain/
    │   ├── entities/
    │   │   └── PlatformLead.ts         # Rich entity with computed getters
    │   └── interfaces/
    │       └── ILeadsRepository.ts     # Repository contract
    ├── data/
    │   ├── models/
    │   │   └── leads.models.ts         # PlatformLeadDto + request models
    │   ├── mappers/
    │   │   └── LeadsMapper.ts          # DTO ↔ PlatformLead entity
    │   ├── services/
    │   │   └── LeadsService.ts         # HTTP calls via IApiService
    │   └── repositories/
    │       └── LeadsRepository.ts      # Service → entity via mapper
    └── presentation/
        ├── viewmodels/
        │   └── useLeadsViewModel.ts    # TanStack Query + mutations + drawer state
        ├── views/
        │   └── LeadsView.tsx           # Stats bar + table + all dialogs mounted
        └── components/
            ├── LeadDetailDrawer.tsx    # 480px slide-in drawer (8 sections)
            ├── AssignLeadDialog.tsx    # Assign/unassign with admin selector
            ├── ConvertToTenantDialog.tsx # Pre-filled conversion form
            └── CreateLeadDialog.tsx    # 2-column admin lead creation form

export class PlatformLead {
  constructor(private readonly data: PlatformLeadData) {}

  // ── Identity ──────────────────────────────────────────────────
  get id()          { return this.data.id; }
  get companyName() { return this.data.companyName; }
  get contactName() { return this.data.contactName; }
  get email()       { return this.data.email; }
  get phone()       { return this.data.phone ?? ""; }

  // ── CRM state ────────────────────────────────────────────────
  get status()           { return this.data.status; }          // "New" | "Contacted" | …
  get source()           { return this.data.source; }          // "Website" | "Admin"
  get assignedToAdminId(){ return this.data.assignedToAdminId; }
  get editionKey()       { return this.data.editionKey ?? ""; }

  // ── Discovery Intelligence ────────────────────────────────────
  get businessType()    { return this.data.businessType ?? ""; }
  get teamSize()        { return this.data.teamSize ?? ""; }
  get priority()        { return this.data.priority ?? ""; }
  get recommendedTier() { return this.data.recommendedTier ?? ""; }

  // ── Computed ─────────────────────────────────────────────────
  get discoveryTags(): string[] {
    return [this.businessType, this.teamSize, this.priority]
      .filter(Boolean);
  }
  get isConverted() { return this.status === "Converted"; }
  get relativeTime() {
    // Uses Intl.RelativeTimeFormat for "2h ago" / "3 days ago"
    const diff = Date.now() - new Date(this.data.createdAt).getTime();
    const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
    if (diff < 3_600_000) return rtf.format(-Math.floor(diff / 60_000), "minute");
    if (diff < 86_400_000) return rtf.format(-Math.floor(diff / 3_600_000), "hour");
    return rtf.format(-Math.floor(diff / 86_400_000), "day");
  }
}

Step 1: Prospect completes Contact Sales form in signup wizard
  → POST /api/v1/leads/contact-sales (no auth)
  → Lead created (Status: New, Source: Website)
  → Sales team receives alert email
  → Prospect receives confirmation email

Step 2: Sales admin reviews lead
  → GET /api/v1/leads → list with Discovery tags visible
  → Click row → LeadDetailDrawer opens with full context

Step 3: Admin assigns lead to team member
  → PUT /api/v1/leads/{id}/assign  { adminId: "..." }
  → Lead status transitions to Contacted

Step 4: Qualify + advance status
  → PUT /api/v1/leads/{id}/status  { status: "Qualified" }
  → PUT /api/v1/leads/{id}/status  { status: "Won" }

Step 5: Convert to tenant (one-click)
  → POST /api/v1/leads/{id}/convert-to-tenant
  → Tenant created, edition assigned, setup email sent
  → Lead status: Converted, ConvertedToTenantId set