< Summary

Information
Class: RoleRadar.Application.Tracking.Commands.TransitionPostingCommandHandler
Assembly: RoleRadar.Application
File(s): /home/runner/work/roleradar/roleradar/src/RoleRadar.Application/Tracking/Commands/TransitionPostingCommand.cs
Line coverage
95%
Covered lines: 164
Uncovered lines: 8
Coverable lines: 172
Total lines: 442
Line coverage: 95.3%
Branch coverage
89%
Covered branches: 68
Total branches: 76
Branch coverage: 89.4%
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Metrics

MethodBranch coverage Crap Score Cyclomatic complexity Line coverage
.cctor()100%11100%
.ctor(...)50%44100%
HandleAsync()86.36%454493.2%
.ctor(...)100%11100%
get_Application()100%11100%
get_Event()100%11100%
get_Warnings()100%11100%
.cctor()100%11100%
PlanApplicationSyncAsync()92.3%272689.47%
AppendAuditAsync(...)100%44100%

File(s)

/home/runner/work/roleradar/roleradar/src/RoleRadar.Application/Tracking/Commands/TransitionPostingCommand.cs

#LineLine coverage
 1using System.Globalization;
 2using RoleRadar.Application.Abstractions;
 3using RoleRadar.Domain.Audit;
 4using RoleRadar.Domain.Common;
 5using RoleRadar.Domain.Tracking;
 6
 7namespace RoleRadar.Application.Tracking.Commands;
 8
 9public sealed record PostingTransitionResultDto(
 10    Guid PostingId,
 11    string PreviousDisposition,
 12    string CurrentDisposition,
 13    string? DispositionReason,
 14    Guid? CriterionId,
 15    string ResurfacePolicy,
 16    DateTimeOffset? DecidedAtUtc,
 17    Guid VersionToken,
 18    DateTimeOffset UpdatedAtUtc)
 19{
 20    /// <summary>Non-fatal notices about the application linked to the posting. Empty when there are none.</summary>
 21    public IReadOnlyList<TransitionWarningDto> Warnings { get; init; } = [];
 22}
 23
 24/// <summary>A fixed, host-displayable notice. Hosts show <see cref="Message"/> and never branch on <see cref="Code"/>.<
 25public sealed record TransitionWarningDto(string Code, string Message);
 26
 27/// <summary>The closed set of transition warnings (ADR 0033). Messages are fixed strings, never posting text.</summary>
 28public static class TransitionWarnings
 29{
 30    public const string ApplicationStillRejected = "application_still_rejected";
 31    public const string ApplicationClosed = "application_closed";
 32
 33    public static IReadOnlyList<string> Codes { get; } = [ApplicationStillRejected, ApplicationClosed];
 34
 35    public static TransitionWarningDto Create(string code) => code switch
 36    {
 37        ApplicationStillRejected => new TransitionWarningDto(code, "The application is still rejected."),
 38        ApplicationClosed => new TransitionWarningDto(code, "The application is closed and was not changed."),
 39        _ => throw new ArgumentOutOfRangeException(nameof(code), code, "Unknown transition warning code."),
 40    };
 41}
 42
 43public sealed record TransitionPostingCommand(
 44    Guid PostingId,
 45    string TargetDisposition,
 46    Guid VersionToken,
 47    string Actor,
 48    string? Reason = null,
 49    Guid? CriterionId = null,
 50    string? ResurfacePolicy = null,
 51    string? OverrideReason = null,
 52    string? EventDate = null,
 53    string? OwnerId = null) : ICommand<PostingTransitionResultDto>;
 54
 55public sealed class TransitionPostingCommandValidator : ICommandValidator<TransitionPostingCommand>
 56{
 57    public ResultError? Validate(TransitionPostingCommand command)
 58    {
 59        ArgumentNullException.ThrowIfNull(command);
 60
 61        var actorError = CommandActor.Validate(command.Actor);
 62        if (actorError is not null)
 63        {
 64            return actorError;
 65        }
 66
 67        if (command.PostingId == Guid.Empty)
 68        {
 69            return new ResultError(ErrorCode.ValidationError, "PostingId is required.");
 70        }
 71
 72        if (string.IsNullOrWhiteSpace(command.TargetDisposition))
 73        {
 74            return new ResultError(ErrorCode.ValidationError, "TargetDisposition is required.");
 75        }
 76
 77        if (command.VersionToken == Guid.Empty)
 78        {
 79            return new ResultError(ErrorCode.StaleVersionToken, "VersionToken is required.");
 80        }
 81
 82        if (!TrackingEnumExtensions.TryParseDisposition(command.TargetDisposition, out var targetDisp))
 83        {
 84            return new ResultError(ErrorCode.ValidationError, $"Unknown disposition '{command.TargetDisposition}'.");
 85        }
 86
 87        // Checked on the parsed value, not the raw string, so every spelling the parser accepts (case,
 88        // surrounding whitespace, hyphens) is rejected here, in one place.
 89        if (targetDisp == PostingDisposition.Applied)
 90        {
 91            return new ResultError(ErrorCode.InvalidTransition, "Target 'applied' is disallowed via posting_transition; 
 92        }
 93
 94        // EventDate only matters when the transition records a rejection on the application. Rejected is
 95        // reachable only from applied, so validating it for the rejected target is exact, and it is ignored
 96        // (never validated) for every other target.
 97        if (targetDisp == PostingDisposition.Rejected
 98            && !string.IsNullOrWhiteSpace(command.EventDate)
 99            && !DateOnly.TryParseExact(command.EventDate.Trim(), "yyyy-MM-dd", CultureInfo.InvariantCulture, DateTimeSty
 100        {
 101            return new ResultError(
 102                ErrorCode.ValidationError,
 103                $"Event date must be in YYYY-MM-DD format: '{command.EventDate}'.",
 104                new Dictionary<string, object?> { ["field"] = "eventDate" });
 105        }
 106
 107        if (targetDisp is PostingDisposition.ScreenedOut or PostingDisposition.Closed or PostingDisposition.Rejected)
 108        {
 109            if (string.IsNullOrWhiteSpace(command.Reason))
 110            {
 111                return new ResultError(ErrorCode.ValidationError, $"Reason is required when transitioning to '{command.T
 112            }
 113
 114            if (command.Reason.Trim().Length > Posting.MaxDispositionReasonLength)
 115            {
 116                return new ResultError(ErrorCode.ValidationError, $"Reason cannot exceed {Posting.MaxDispositionReasonLe
 117            }
 118        }
 119
 120        return null;
 121    }
 122}
 123
 124public sealed class TransitionPostingCommandHandler : ICommandHandler<TransitionPostingCommand, PostingTransitionResultD
 125{
 126    /// <summary>Event source recorded on the application event created by a posting transition (ADR 0033).</summary>
 127    public const string PostingTransitionEventSource = "posting_transition";
 128
 129    // The decorator runs the registered validator on the normal path. The handler keeps this call so a caller
 130    // that constructs it directly (the contract tests do) cannot skip validation.
 10131    private static readonly TransitionPostingCommandValidator Validator = new();
 132    private readonly ITrackingTransactionContext _context;
 133    private readonly IUtcClock _clock;
 134
 416135    public TransitionPostingCommandHandler(ITrackingTransactionContext context, IUtcClock clock)
 136    {
 416137        _context = context ?? throw new ArgumentNullException(nameof(context));
 416138        _clock = clock ?? throw new ArgumentNullException(nameof(clock));
 416139    }
 140
 141    public async Task<Result<PostingTransitionResultDto>> HandleAsync(
 142        TransitionPostingCommand command,
 143        CancellationToken cancellationToken = default)
 144    {
 130145        ArgumentNullException.ThrowIfNull(command);
 146
 130147        var valError = Validator.Validate(command);
 130148        if (valError is not null)
 149        {
 8150            return Result<PostingTransitionResultDto>.Failure(valError.Value);
 151        }
 152
 122153        var ownerId = string.IsNullOrWhiteSpace(command.OwnerId)
 122154            ? OwnerId.Default.Value
 122155            : new OwnerId(command.OwnerId).Value;
 122156        var now = _clock.UtcNow;
 157
 122158        var postingResult = await _context.Postings.GetByIdAsync(ownerId, command.PostingId, cancellationToken);
 122159        if (!postingResult.IsSuccess || postingResult.Value is null)
 160        {
 4161            return Result<PostingTransitionResultDto>.Failure(ErrorCode.NotFound, "Posting not found.");
 162        }
 163
 118164        var posting = postingResult.Value;
 118165        if (posting.VersionToken != command.VersionToken)
 166        {
 8167            return Result<PostingTransitionResultDto>.Failure(ErrorCode.StaleVersionToken, "Posting version token mismat
 168        }
 169
 110170        if (!TrackingEnumExtensions.TryParseDisposition(command.TargetDisposition, out var targetDisposition))
 171        {
 0172            return Result<PostingTransitionResultDto>.Failure(ErrorCode.ValidationError, $"Unknown disposition '{command
 173        }
 174
 175        // Target 'applied' is rejected by the validator above, so it never reaches the matrix.
 176
 177        // Validate via DispositionMatrix
 110178        if (!DispositionMatrix.CanTransition(posting.Disposition, targetDisposition, posting.ResurfacePolicy))
 179        {
 12180            return Result<PostingTransitionResultDto>.Failure(
 12181                ErrorCode.InvalidTransition,
 12182                $"Invalid state transition from '{posting.Disposition.ToSnakeCase()}' to '{targetDisposition.ToSnakeCase
 183        }
 184
 185        // Reopening rejected requires explicit override reason
 98186        if (posting.Disposition == PostingDisposition.Rejected && targetDisposition == PostingDisposition.Lead)
 187        {
 14188            if (string.IsNullOrWhiteSpace(command.OverrideReason))
 189            {
 2190                return Result<PostingTransitionResultDto>.Failure(
 2191                    ErrorCode.ValidationError,
 2192                    "Reopening a rejected posting requires an explicit non-empty overrideReason.");
 193            }
 194        }
 195
 96196        var resurfacePolicy = posting.ResurfacePolicy;
 96197        if (!string.IsNullOrWhiteSpace(command.ResurfacePolicy) &&
 96198            TrackingEnumExtensions.TryParseResurfacePolicy(command.ResurfacePolicy, out var parsedRp))
 199        {
 2200            resurfacePolicy = parsedRp;
 201        }
 202
 96203        var prevDisposition = posting.Disposition;
 96204        var reason = command.Reason ?? command.OverrideReason;
 205
 206        // Read everything the application side needs before any write, so a failure here changes nothing.
 207        // Structural no-loop guarantee: this handler depends only on the transaction context and the clock. It
 208        // writes the application through the repository pair below and has no path to the application-event
 209        // handler that syncs an application event back onto the posting.
 96210        var planResult = await PlanApplicationSyncAsync(ownerId, posting, prevDisposition, targetDisposition, command, r
 96211        if (!planResult.IsSuccess)
 212        {
 0213            return Result<PostingTransitionResultDto>.Failure(planResult.Error!.Value);
 214        }
 215
 96216        var plan = planResult.Value!;
 217
 96218        posting.Transition(targetDisposition, reason, command.CriterionId, resurfacePolicy, now);
 96219        var postingWrite = await _context.Postings.UpsertPostingAsync(posting, cancellationToken);
 96220        if (!postingWrite.IsSuccess)
 221        {
 0222            return Result<PostingTransitionResultDto>.Failure(postingWrite.Error!.Value);
 223        }
 224
 96225        string? priorApplicationOutcome = null;
 96226        if (plan.Event is not null && plan.Application is not null)
 227        {
 46228            priorApplicationOutcome = plan.Application.Outcome.ToSnakeCase();
 46229            plan.Application.ApplyEvent(ApplicationEventType.Rejected, plan.Event.Notes, now);
 230
 231            // The existing repository pair: AppendEventAsync is the single place milestones and derived
 232            // read-model fields are recomputed.
 46233            var appWrite = await _context.Applications.UpsertApplicationAsync(plan.Application, cancellationToken);
 46234            if (!appWrite.IsSuccess)
 235            {
 0236                return Result<PostingTransitionResultDto>.Failure(appWrite.Error!.Value);
 237            }
 238
 46239            var eventWrite = await _context.Applications.AppendEventAsync(plan.Event, cancellationToken);
 44240            if (!eventWrite.IsSuccess)
 241            {
 4242                return Result<PostingTransitionResultDto>.Failure(eventWrite.Error!.Value);
 243            }
 244        }
 245
 90246        var correlationId = plan.Event is not null ? Guid.CreateVersion7().ToString() : null;
 247
 90248        var auditSummary = new PostingAuditSummary(
 90249            PostingId: posting.Id,
 90250            ChangedFieldNames: ["disposition", "disposition_reason", "resurface_policy", "decided_at"],
 90251            PriorDisposition: prevDisposition.ToSnakeCase(),
 90252            NewDisposition: targetDisposition.ToSnakeCase(),
 90253            Reason: reason,
 90254            Timestamp: now);
 255
 90256        await AppendAuditAsync(
 90257            ownerId,
 90258            command.Actor,
 90259            AuditOperation.PostingTransition,
 90260            posting.Id,
 90261            posting.VersionToken,
 90262            auditSummary,
 90263            correlationId,
 10264            plan.Warnings.Select(w => w.Code).ToArray(),
 90265            cancellationToken);
 266
 90267        if (plan.Event is not null && plan.Application is not null)
 268        {
 40269            var appDetails = AuditDetails.ForEntity(
 40270                changedFields: ["outcome"],
 40271                before: new Dictionary<string, object?> { ["outcome"] = priorApplicationOutcome },
 40272                after: new Dictionary<string, object?>
 40273                {
 40274                    ["outcome"] = plan.Application.Outcome.ToSnakeCase(),
 40275                    ["event_type"] = plan.Event.EventType.ToSnakeCase(),
 40276                    ["event_date"] = plan.Event.EventDate,
 40277                    ["event_source"] = plan.Event.EventSource,
 40278                    ["correlation_id"] = correlationId,
 40279                });
 280
 40281            await _context.AppendAuditEntryAsync(
 40282                AuditLogEntry.CreateForTracking(
 40283                    ownerId: ownerId,
 40284                    actor: command.Actor,
 40285                    operation: AuditOperation.ApplicationEventAppend,
 40286                    entityType: "application",
 40287                    entityId: plan.Application.Id,
 40288                    resultingVersionToken: plan.Application.VersionToken,
 40289                    occurredAtUtc: now,
 40290                    details: appDetails),
 40291                cancellationToken);
 292        }
 293
 90294        return Result<PostingTransitionResultDto>.Success(new PostingTransitionResultDto(
 90295            PostingId: posting.Id,
 90296            PreviousDisposition: prevDisposition.ToSnakeCase(),
 90297            CurrentDisposition: targetDisposition.ToSnakeCase(),
 90298            DispositionReason: posting.DispositionReason,
 90299            CriterionId: posting.DispositionCriterionId,
 90300            ResurfacePolicy: posting.ResurfacePolicy.ToSnakeCase(),
 90301            DecidedAtUtc: posting.DecidedAt,
 90302            VersionToken: posting.VersionToken,
 90303            UpdatedAtUtc: posting.UpdatedAt)
 90304        {
 90305            Warnings = plan.Warnings,
 90306        });
 128307    }
 308
 64309    private sealed record ApplicationSyncPlan(
 344310        Domain.Tracking.Application? Application,
 488311        ApplicationEvent? Event,
 244312        IReadOnlyList<TransitionWarningDto> Warnings)
 313    {
 8314        public static readonly ApplicationSyncPlan None = new(null, null, []);
 315    }
 316
 317    /// <summary>
 318    /// Decides, from reads only, whether the transition must record a rejected event on the posting's
 319    /// application and which warnings apply. Rows of the table in research R3.
 320    /// </summary>
 321    private async Task<Result<ApplicationSyncPlan>> PlanApplicationSyncAsync(
 322        string ownerId,
 323        Posting posting,
 324        PostingDisposition previous,
 325        PostingDisposition target,
 326        TransitionPostingCommand command,
 327        string? reason,
 328        DateTimeOffset now,
 329        CancellationToken cancellationToken)
 330    {
 96331        var isReject = previous == PostingDisposition.Applied && target == PostingDisposition.Rejected;
 96332        var isReopen = previous == PostingDisposition.Rejected && target == PostingDisposition.Lead;
 96333        if (!isReject && !isReopen)
 334        {
 24335            return Result<ApplicationSyncPlan>.Success(ApplicationSyncPlan.None);
 336        }
 337
 72338        var appRes = await _context.Applications.GetByPostingIdAsync(ownerId, posting.Id, cancellationToken);
 72339        if (!appRes.IsSuccess)
 340        {
 0341            return Result<ApplicationSyncPlan>.Failure(appRes.Error!.Value);
 342        }
 343
 72344        var application = appRes.Value;
 72345        if (application is null)
 346        {
 347            // A posting with no application behaves exactly as before.
 4348            return Result<ApplicationSyncPlan>.Success(ApplicationSyncPlan.None);
 349        }
 350
 68351        if (isReopen)
 352        {
 10353            return Result<ApplicationSyncPlan>.Success(application.Outcome == ApplicationOutcome.Rejected
 10354                ? new ApplicationSyncPlan(null, null, [TransitionWarnings.Create(TransitionWarnings.ApplicationStillReje
 10355                : ApplicationSyncPlan.None);
 356        }
 357
 58358        switch (application.Outcome)
 359        {
 360            case ApplicationOutcome.Rejected:
 6361                return Result<ApplicationSyncPlan>.Success(ApplicationSyncPlan.None);
 362
 363            case ApplicationOutcome.Closed:
 4364                return Result<ApplicationSyncPlan>.Success(
 4365                    new ApplicationSyncPlan(null, null, [TransitionWarnings.Create(TransitionWarnings.ApplicationClosed)
 366        }
 367
 48368        var eventsRes = await _context.Applications.GetEventsAsync(ownerId, application.Id, cancellationToken);
 48369        if (!eventsRes.IsSuccess)
 370        {
 0371            return Result<ApplicationSyncPlan>.Failure(eventsRes.Error!.Value);
 372        }
 373
 74374        if (eventsRes.Value!.Any(e => e.EventType == ApplicationEventType.Rejected))
 375        {
 2376            return Result<ApplicationSyncPlan>.Success(ApplicationSyncPlan.None);
 377        }
 378
 46379        var eventDate = string.IsNullOrWhiteSpace(command.EventDate)
 46380            ? DateOnly.FromDateTime(now.UtcDateTime).ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)
 46381            : command.EventDate.Trim();
 382
 383        ApplicationEvent appEvent;
 384        try
 385        {
 46386            appEvent = ApplicationEvent.Create(
 46387                ownerId: ownerId,
 46388                applicationId: application.Id,
 46389                eventDate: eventDate,
 46390                eventType: ApplicationEventType.Rejected,
 46391                eventSource: PostingTransitionEventSource,
 46392                notes: reason,
 46393                now: now);
 46394        }
 0395        catch (ArgumentException ex)
 396        {
 0397            return Result<ApplicationSyncPlan>.Failure(ErrorCode.ValidationError, ex.Message);
 398        }
 399
 46400        return Result<ApplicationSyncPlan>.Success(new ApplicationSyncPlan(application, appEvent, []));
 96401    }
 402
 403    private Task AppendAuditAsync(
 404        string ownerId,
 405        string actor,
 406        string operation,
 407        Guid postingId,
 408        Guid versionToken,
 409        PostingAuditSummary summary,
 410        string? correlationId,
 411        string[] warningCodes,
 412        CancellationToken cancellationToken)
 413    {
 90414        var after = new Dictionary<string, object?> { ["disposition"] = summary.NewDisposition, ["reason"] = summary.Rea
 90415        if (correlationId is not null)
 416        {
 40417            after["correlation_id"] = correlationId;
 418        }
 419
 90420        if (warningCodes.Length > 0)
 421        {
 10422            after["warnings"] = warningCodes;
 423        }
 424
 90425        var details = AuditDetails.ForEntity(
 90426            changedFields: summary.ChangedFieldNames,
 90427            before: new Dictionary<string, object?> { ["disposition"] = summary.PriorDisposition },
 90428            after: after);
 429
 90430        var entry = AuditLogEntry.CreateForTracking(
 90431            ownerId: ownerId,
 90432            actor: actor,
 90433            operation: operation,
 90434            entityType: "posting",
 90435            entityId: postingId,
 90436            resultingVersionToken: versionToken,
 90437            occurredAtUtc: summary.Timestamp.UtcDateTime,
 90438            details: details);
 439
 90440        return _context.AppendAuditEntryAsync(entry, cancellationToken);
 441    }
 442}