< Summary

Information
Class: RoleRadar.Application.Tracking.Commands.TransitionPostingCommandValidator
Assembly: RoleRadar.Application
File(s): /home/runner/work/roleradar/roleradar/src/RoleRadar.Application/Tracking/Commands/TransitionPostingCommand.cs
Line coverage
96%
Covered lines: 26
Uncovered lines: 1
Coverable lines: 27
Total lines: 442
Line coverage: 96.2%
Branch coverage
96%
Covered branches: 25
Total branches: 26
Branch coverage: 96.1%
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Metrics

MethodBranch coverage Crap Score Cyclomatic complexity Line coverage
Validate(...)96.15%262696.29%

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    {
 21459        ArgumentNullException.ThrowIfNull(command);
 60
 21261        var actorError = CommandActor.Validate(command.Actor);
 21262        if (actorError is not null)
 63        {
 064            return actorError;
 65        }
 66
 21267        if (command.PostingId == Guid.Empty)
 68        {
 269            return new ResultError(ErrorCode.ValidationError, "PostingId is required.");
 70        }
 71
 21072        if (string.IsNullOrWhiteSpace(command.TargetDisposition))
 73        {
 274            return new ResultError(ErrorCode.ValidationError, "TargetDisposition is required.");
 75        }
 76
 20877        if (command.VersionToken == Guid.Empty)
 78        {
 279            return new ResultError(ErrorCode.StaleVersionToken, "VersionToken is required.");
 80        }
 81
 20682        if (!TrackingEnumExtensions.TryParseDisposition(command.TargetDisposition, out var targetDisp))
 83        {
 284            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.
 20489        if (targetDisp == PostingDisposition.Applied)
 90        {
 1091            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.
 19497        if (targetDisp == PostingDisposition.Rejected
 19498            && !string.IsNullOrWhiteSpace(command.EventDate)
 19499            && !DateOnly.TryParseExact(command.EventDate.Trim(), "yyyy-MM-dd", CultureInfo.InvariantCulture, DateTimeSty
 100        {
 8101            return new ResultError(
 8102                ErrorCode.ValidationError,
 8103                $"Event date must be in YYYY-MM-DD format: '{command.EventDate}'.",
 8104                new Dictionary<string, object?> { ["field"] = "eventDate" });
 105        }
 106
 186107        if (targetDisp is PostingDisposition.ScreenedOut or PostingDisposition.Closed or PostingDisposition.Rejected)
 108        {
 166109            if (string.IsNullOrWhiteSpace(command.Reason))
 110            {
 2111                return new ResultError(ErrorCode.ValidationError, $"Reason is required when transitioning to '{command.T
 112            }
 113
 164114            if (command.Reason.Trim().Length > Posting.MaxDispositionReasonLength)
 115            {
 2116                return new ResultError(ErrorCode.ValidationError, $"Reason cannot exceed {Posting.MaxDispositionReasonLe
 117            }
 118        }
 119
 182120        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.
 131    private static readonly TransitionPostingCommandValidator Validator = new();
 132    private readonly ITrackingTransactionContext _context;
 133    private readonly IUtcClock _clock;
 134
 135    public TransitionPostingCommandHandler(ITrackingTransactionContext context, IUtcClock clock)
 136    {
 137        _context = context ?? throw new ArgumentNullException(nameof(context));
 138        _clock = clock ?? throw new ArgumentNullException(nameof(clock));
 139    }
 140
 141    public async Task<Result<PostingTransitionResultDto>> HandleAsync(
 142        TransitionPostingCommand command,
 143        CancellationToken cancellationToken = default)
 144    {
 145        ArgumentNullException.ThrowIfNull(command);
 146
 147        var valError = Validator.Validate(command);
 148        if (valError is not null)
 149        {
 150            return Result<PostingTransitionResultDto>.Failure(valError.Value);
 151        }
 152
 153        var ownerId = string.IsNullOrWhiteSpace(command.OwnerId)
 154            ? OwnerId.Default.Value
 155            : new OwnerId(command.OwnerId).Value;
 156        var now = _clock.UtcNow;
 157
 158        var postingResult = await _context.Postings.GetByIdAsync(ownerId, command.PostingId, cancellationToken);
 159        if (!postingResult.IsSuccess || postingResult.Value is null)
 160        {
 161            return Result<PostingTransitionResultDto>.Failure(ErrorCode.NotFound, "Posting not found.");
 162        }
 163
 164        var posting = postingResult.Value;
 165        if (posting.VersionToken != command.VersionToken)
 166        {
 167            return Result<PostingTransitionResultDto>.Failure(ErrorCode.StaleVersionToken, "Posting version token mismat
 168        }
 169
 170        if (!TrackingEnumExtensions.TryParseDisposition(command.TargetDisposition, out var targetDisposition))
 171        {
 172            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
 178        if (!DispositionMatrix.CanTransition(posting.Disposition, targetDisposition, posting.ResurfacePolicy))
 179        {
 180            return Result<PostingTransitionResultDto>.Failure(
 181                ErrorCode.InvalidTransition,
 182                $"Invalid state transition from '{posting.Disposition.ToSnakeCase()}' to '{targetDisposition.ToSnakeCase
 183        }
 184
 185        // Reopening rejected requires explicit override reason
 186        if (posting.Disposition == PostingDisposition.Rejected && targetDisposition == PostingDisposition.Lead)
 187        {
 188            if (string.IsNullOrWhiteSpace(command.OverrideReason))
 189            {
 190                return Result<PostingTransitionResultDto>.Failure(
 191                    ErrorCode.ValidationError,
 192                    "Reopening a rejected posting requires an explicit non-empty overrideReason.");
 193            }
 194        }
 195
 196        var resurfacePolicy = posting.ResurfacePolicy;
 197        if (!string.IsNullOrWhiteSpace(command.ResurfacePolicy) &&
 198            TrackingEnumExtensions.TryParseResurfacePolicy(command.ResurfacePolicy, out var parsedRp))
 199        {
 200            resurfacePolicy = parsedRp;
 201        }
 202
 203        var prevDisposition = posting.Disposition;
 204        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.
 210        var planResult = await PlanApplicationSyncAsync(ownerId, posting, prevDisposition, targetDisposition, command, r
 211        if (!planResult.IsSuccess)
 212        {
 213            return Result<PostingTransitionResultDto>.Failure(planResult.Error!.Value);
 214        }
 215
 216        var plan = planResult.Value!;
 217
 218        posting.Transition(targetDisposition, reason, command.CriterionId, resurfacePolicy, now);
 219        var postingWrite = await _context.Postings.UpsertPostingAsync(posting, cancellationToken);
 220        if (!postingWrite.IsSuccess)
 221        {
 222            return Result<PostingTransitionResultDto>.Failure(postingWrite.Error!.Value);
 223        }
 224
 225        string? priorApplicationOutcome = null;
 226        if (plan.Event is not null && plan.Application is not null)
 227        {
 228            priorApplicationOutcome = plan.Application.Outcome.ToSnakeCase();
 229            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.
 233            var appWrite = await _context.Applications.UpsertApplicationAsync(plan.Application, cancellationToken);
 234            if (!appWrite.IsSuccess)
 235            {
 236                return Result<PostingTransitionResultDto>.Failure(appWrite.Error!.Value);
 237            }
 238
 239            var eventWrite = await _context.Applications.AppendEventAsync(plan.Event, cancellationToken);
 240            if (!eventWrite.IsSuccess)
 241            {
 242                return Result<PostingTransitionResultDto>.Failure(eventWrite.Error!.Value);
 243            }
 244        }
 245
 246        var correlationId = plan.Event is not null ? Guid.CreateVersion7().ToString() : null;
 247
 248        var auditSummary = new PostingAuditSummary(
 249            PostingId: posting.Id,
 250            ChangedFieldNames: ["disposition", "disposition_reason", "resurface_policy", "decided_at"],
 251            PriorDisposition: prevDisposition.ToSnakeCase(),
 252            NewDisposition: targetDisposition.ToSnakeCase(),
 253            Reason: reason,
 254            Timestamp: now);
 255
 256        await AppendAuditAsync(
 257            ownerId,
 258            command.Actor,
 259            AuditOperation.PostingTransition,
 260            posting.Id,
 261            posting.VersionToken,
 262            auditSummary,
 263            correlationId,
 264            plan.Warnings.Select(w => w.Code).ToArray(),
 265            cancellationToken);
 266
 267        if (plan.Event is not null && plan.Application is not null)
 268        {
 269            var appDetails = AuditDetails.ForEntity(
 270                changedFields: ["outcome"],
 271                before: new Dictionary<string, object?> { ["outcome"] = priorApplicationOutcome },
 272                after: new Dictionary<string, object?>
 273                {
 274                    ["outcome"] = plan.Application.Outcome.ToSnakeCase(),
 275                    ["event_type"] = plan.Event.EventType.ToSnakeCase(),
 276                    ["event_date"] = plan.Event.EventDate,
 277                    ["event_source"] = plan.Event.EventSource,
 278                    ["correlation_id"] = correlationId,
 279                });
 280
 281            await _context.AppendAuditEntryAsync(
 282                AuditLogEntry.CreateForTracking(
 283                    ownerId: ownerId,
 284                    actor: command.Actor,
 285                    operation: AuditOperation.ApplicationEventAppend,
 286                    entityType: "application",
 287                    entityId: plan.Application.Id,
 288                    resultingVersionToken: plan.Application.VersionToken,
 289                    occurredAtUtc: now,
 290                    details: appDetails),
 291                cancellationToken);
 292        }
 293
 294        return Result<PostingTransitionResultDto>.Success(new PostingTransitionResultDto(
 295            PostingId: posting.Id,
 296            PreviousDisposition: prevDisposition.ToSnakeCase(),
 297            CurrentDisposition: targetDisposition.ToSnakeCase(),
 298            DispositionReason: posting.DispositionReason,
 299            CriterionId: posting.DispositionCriterionId,
 300            ResurfacePolicy: posting.ResurfacePolicy.ToSnakeCase(),
 301            DecidedAtUtc: posting.DecidedAt,
 302            VersionToken: posting.VersionToken,
 303            UpdatedAtUtc: posting.UpdatedAt)
 304        {
 305            Warnings = plan.Warnings,
 306        });
 307    }
 308
 309    private sealed record ApplicationSyncPlan(
 310        Domain.Tracking.Application? Application,
 311        ApplicationEvent? Event,
 312        IReadOnlyList<TransitionWarningDto> Warnings)
 313    {
 314        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    {
 331        var isReject = previous == PostingDisposition.Applied && target == PostingDisposition.Rejected;
 332        var isReopen = previous == PostingDisposition.Rejected && target == PostingDisposition.Lead;
 333        if (!isReject && !isReopen)
 334        {
 335            return Result<ApplicationSyncPlan>.Success(ApplicationSyncPlan.None);
 336        }
 337
 338        var appRes = await _context.Applications.GetByPostingIdAsync(ownerId, posting.Id, cancellationToken);
 339        if (!appRes.IsSuccess)
 340        {
 341            return Result<ApplicationSyncPlan>.Failure(appRes.Error!.Value);
 342        }
 343
 344        var application = appRes.Value;
 345        if (application is null)
 346        {
 347            // A posting with no application behaves exactly as before.
 348            return Result<ApplicationSyncPlan>.Success(ApplicationSyncPlan.None);
 349        }
 350
 351        if (isReopen)
 352        {
 353            return Result<ApplicationSyncPlan>.Success(application.Outcome == ApplicationOutcome.Rejected
 354                ? new ApplicationSyncPlan(null, null, [TransitionWarnings.Create(TransitionWarnings.ApplicationStillReje
 355                : ApplicationSyncPlan.None);
 356        }
 357
 358        switch (application.Outcome)
 359        {
 360            case ApplicationOutcome.Rejected:
 361                return Result<ApplicationSyncPlan>.Success(ApplicationSyncPlan.None);
 362
 363            case ApplicationOutcome.Closed:
 364                return Result<ApplicationSyncPlan>.Success(
 365                    new ApplicationSyncPlan(null, null, [TransitionWarnings.Create(TransitionWarnings.ApplicationClosed)
 366        }
 367
 368        var eventsRes = await _context.Applications.GetEventsAsync(ownerId, application.Id, cancellationToken);
 369        if (!eventsRes.IsSuccess)
 370        {
 371            return Result<ApplicationSyncPlan>.Failure(eventsRes.Error!.Value);
 372        }
 373
 374        if (eventsRes.Value!.Any(e => e.EventType == ApplicationEventType.Rejected))
 375        {
 376            return Result<ApplicationSyncPlan>.Success(ApplicationSyncPlan.None);
 377        }
 378
 379        var eventDate = string.IsNullOrWhiteSpace(command.EventDate)
 380            ? DateOnly.FromDateTime(now.UtcDateTime).ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)
 381            : command.EventDate.Trim();
 382
 383        ApplicationEvent appEvent;
 384        try
 385        {
 386            appEvent = ApplicationEvent.Create(
 387                ownerId: ownerId,
 388                applicationId: application.Id,
 389                eventDate: eventDate,
 390                eventType: ApplicationEventType.Rejected,
 391                eventSource: PostingTransitionEventSource,
 392                notes: reason,
 393                now: now);
 394        }
 395        catch (ArgumentException ex)
 396        {
 397            return Result<ApplicationSyncPlan>.Failure(ErrorCode.ValidationError, ex.Message);
 398        }
 399
 400        return Result<ApplicationSyncPlan>.Success(new ApplicationSyncPlan(application, appEvent, []));
 401    }
 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    {
 414        var after = new Dictionary<string, object?> { ["disposition"] = summary.NewDisposition, ["reason"] = summary.Rea
 415        if (correlationId is not null)
 416        {
 417            after["correlation_id"] = correlationId;
 418        }
 419
 420        if (warningCodes.Length > 0)
 421        {
 422            after["warnings"] = warningCodes;
 423        }
 424
 425        var details = AuditDetails.ForEntity(
 426            changedFields: summary.ChangedFieldNames,
 427            before: new Dictionary<string, object?> { ["disposition"] = summary.PriorDisposition },
 428            after: after);
 429
 430        var entry = AuditLogEntry.CreateForTracking(
 431            ownerId: ownerId,
 432            actor: actor,
 433            operation: operation,
 434            entityType: "posting",
 435            entityId: postingId,
 436            resultingVersionToken: versionToken,
 437            occurredAtUtc: summary.Timestamp.UtcDateTime,
 438            details: details);
 439
 440        return _context.AppendAuditEntryAsync(entry, cancellationToken);
 441    }
 442}