feat(onboarding): [AB#71] add analytics event tracking endpoint

JobFlow.API/Controllers/OnboardingController.cs

@@ -88,6 +88,16 @@ public async Task<IResult> CompleteOnboarding()
             : orgResult.ToProblemDetails();
     }
 
+    [HttpPost("events")]
+    public async Task<IResult> RecordEvent([FromBody] OnboardingAnalyticsEventRequestDto request)
+    {
+        var organizationId = HttpContext.GetOrganizationId();
+        var result = await onboarding.RecordAnalyticsEventAsync(organizationId, request.StepName, request.EventType);
+        return result.IsSuccess
+            ? Results.Ok()
+            : result.ToProblemDetails();
+    }
+
     private static bool HasMinPlan(string? planName, string required)
     {
         static int Rank(string? plan)

JobFlow.Business/Models/DTOs/OnboardingAnalyticsEventRequestDto.cs

@@ -0,0 +1,7 @@
+namespace JobFlow.Business.Models.DTOs;
+
+public class OnboardingAnalyticsEventRequestDto
+{
+    public string StepName { get; set; } = string.Empty;
+    public string EventType { get; set; } = string.Empty;
+}

JobFlow.Business/Services/OnboardingService.cs

@@ -247,4 +247,31 @@ await priceBookItems.AddAsync(new PriceBookItem
 
         await uow.SaveChangesAsync();
     }
+
+    public async Task<Result> RecordAnalyticsEventAsync(Guid organizationId, string stepName, string eventType)
+    {
+        if (string.IsNullOrWhiteSpace(stepName) || string.IsNullOrWhiteSpace(eventType))
+            return Result.Failure(Error.Validation("Onboarding.Analytics.Invalid", "StepName and EventType are required."));
+
+        var allowedEventTypes = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
+        {
+            "onboarding_step_started",
+            "onboarding_step_completed",
+            "onboarding_step_skipped"
+        };
+
+        if (!allowedEventTypes.Contains(eventType))
+            return Result.Failure(Error.Validation("Onboarding.Analytics.UnknownEventType", $"Unknown event type: {eventType}."));
+
+        var eventsRepo = uow.RepositoryOf<OrganizationOnboardingEvent>();
+        await eventsRepo.AddAsync(new OrganizationOnboardingEvent
+        {
+            OrganizationId = organizationId,
+            StepName = stepName.Trim().ToLowerInvariant(),
+            EventType = eventType.Trim().ToLowerInvariant()
+        });
+
+        await uow.SaveChangesAsync();
+        return Result.Success();
+    }
 }

JobFlow.Business/Services/ServiceInterfaces/IOnboardingService.cs

@@ -11,4 +11,5 @@ public interface IOnboardingService
     Task<Result<OnboardingQuickStartStateDto>> ApplyQuickStartAsync(
         Guid organizationId,
         OnboardingQuickStartApplyRequestDto request);
+    Task<Result> RecordAnalyticsEventAsync(Guid organizationId, string stepName, string eventType);
 }

JobFlow.Domain/Models/OrganizationOnboardingEvent.cs

@@ -0,0 +1,11 @@
+namespace JobFlow.Domain.Models;
+
+public class OrganizationOnboardingEvent : Entity
+{
+    public Guid OrganizationId { get; set; }
+    public string StepName { get; set; } = string.Empty;
+    public string EventType { get; set; } = string.Empty;
+
+    // Navigation
+    public Organization Organization { get; set; } = null!;
+}

JobFlow.Infrastructure.Persistence/Configurations/OrganizationOnboardingEventConfiguration.cs

@@ -0,0 +1,25 @@
+using JobFlow.Domain.Models;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Metadata.Builders;
+
+namespace JobFlow.Infrastructure.Persistence.Configurations;
+
+public class OrganizationOnboardingEventConfiguration : IEntityTypeConfiguration<OrganizationOnboardingEvent>
+{
+    public void Configure(EntityTypeBuilder<OrganizationOnboardingEvent> builder)
+    {
+        builder.ToTable("OrganizationOnboardingEvents");
+        builder.Property(x => x.StepName)
+            .IsRequired()
+            .HasMaxLength(100);
+        builder.Property(x => x.EventType)
+            .IsRequired()
+            .HasMaxLength(100);
+        builder.HasIndex(x => new { x.OrganizationId, x.StepName, x.EventType });
+
+        builder.HasOne(x => x.Organization)
+            .WithMany()
+            .HasForeignKey(x => x.OrganizationId)
+            .OnDelete(DeleteBehavior.Cascade);
+    }
+}

JobFlow.Infrastructure.Persistence/JobFlowDbContext.cs

@@ -45,6 +45,7 @@ public JobFlowDbContext(DbContextOptions options) : base(options)
     public DbSet<ChangelogEntry> ChangelogEntries { get; set; }
     public DbSet<SupportChatSession> SupportChatSessions { get; set; }
     public DbSet<SupportChatMessage> SupportChatMessages { get; set; }
+    public DbSet<OrganizationOnboardingEvent> OrganizationOnboardingEvents { get; set; }
 
     protected override void OnModelCreating(ModelBuilder modelBuilder)
     {