git.stella-ops.org/src/Policy/StellaOps.Policy.Registry/Services/IReviewWorkflowService.cs

using StellaOps.Policy.Registry.Contracts;

namespace StellaOps.Policy.Registry.Services;

/// <summary>
/// Service for managing policy pack review workflows with audit trails.
/// Implements REGISTRY-API-27-006: Review workflow with audit trails.
/// </summary>
public interface IReviewWorkflowService
{
    /// <summary>
    /// Submits a policy pack for review.
    /// </summary>
    Task<ReviewRequest> SubmitForReviewAsync(
        Guid tenantId,
        Guid packId,
        SubmitReviewRequest request,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Approves a review request.
    /// </summary>
    Task<ReviewDecision> ApproveAsync(
        Guid tenantId,
        string reviewId,
        ApproveReviewRequest request,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Rejects a review request.
    /// </summary>
    Task<ReviewDecision> RejectAsync(
        Guid tenantId,
        string reviewId,
        RejectReviewRequest request,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Requests changes to a policy pack under review.
    /// </summary>
    Task<ReviewDecision> RequestChangesAsync(
        Guid tenantId,
        string reviewId,
        RequestChangesRequest request,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets a review request by ID.
    /// </summary>
    Task<ReviewRequest?> GetReviewAsync(
        Guid tenantId,
        string reviewId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Lists review requests for a tenant.
    /// </summary>
    Task<ReviewRequestList> ListReviewsAsync(
        Guid tenantId,
        ReviewStatus? status = null,
        Guid? packId = null,
        int pageSize = 20,
        string? pageToken = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the audit trail for a review.
    /// </summary>
    Task<IReadOnlyList<ReviewAuditEntry>> GetAuditTrailAsync(
        Guid tenantId,
        string reviewId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the audit trail for a policy pack across all reviews.
    /// </summary>
    Task<IReadOnlyList<ReviewAuditEntry>> GetPackAuditTrailAsync(
        Guid tenantId,
        Guid packId,
        int limit = 100,
        CancellationToken cancellationToken = default);
}

/// <summary>
/// Request to submit a policy pack for review.
/// </summary>
public sealed record SubmitReviewRequest
{
    public string? Description { get; init; }
    public IReadOnlyList<string>? Reviewers { get; init; }
    public ReviewUrgency Urgency { get; init; } = ReviewUrgency.Normal;
    public IReadOnlyDictionary<string, string>? Metadata { get; init; }
}

/// <summary>
/// Request to approve a review.
/// </summary>
public sealed record ApproveReviewRequest
{
    public string? Comment { get; init; }
    public string? ApprovedBy { get; init; }
}

/// <summary>
/// Request to reject a review.
/// </summary>
public sealed record RejectReviewRequest
{
    public required string Reason { get; init; }
    public string? RejectedBy { get; init; }
}

/// <summary>
/// Request to request changes.
/// </summary>
public sealed record RequestChangesRequest
{
    public required IReadOnlyList<ReviewComment> Comments { get; init; }
    public string? RequestedBy { get; init; }
}

/// <summary>
/// Review comment.
/// </summary>
public sealed record ReviewComment
{
    public string? RuleId { get; init; }
    public required string Comment { get; init; }
    public ReviewCommentSeverity Severity { get; init; } = ReviewCommentSeverity.Suggestion;
}

/// <summary>
/// Review comment severity.
/// </summary>
public enum ReviewCommentSeverity
{
    Suggestion,
    Warning,
    Blocking
}

/// <summary>
/// Review urgency level.
/// </summary>
public enum ReviewUrgency
{
    Low,
    Normal,
    High,
    Critical
}

/// <summary>
/// Review request status.
/// </summary>
public enum ReviewStatus
{
    Pending,
    InReview,
    ChangesRequested,
    Approved,
    Rejected,
    Cancelled
}

/// <summary>
/// Review request.
/// </summary>
public sealed record ReviewRequest
{
    public required string ReviewId { get; init; }
    public required Guid TenantId { get; init; }
    public required Guid PackId { get; init; }
    public required string PackVersion { get; init; }
    public required ReviewStatus Status { get; init; }
    public string? Description { get; init; }
    public IReadOnlyList<string>? Reviewers { get; init; }
    public ReviewUrgency Urgency { get; init; }
    public string? SubmittedBy { get; init; }
    public required DateTimeOffset SubmittedAt { get; init; }
    public DateTimeOffset? ResolvedAt { get; init; }
    public string? ResolvedBy { get; init; }
    public IReadOnlyList<ReviewComment>? PendingComments { get; init; }
    public IReadOnlyDictionary<string, string>? Metadata { get; init; }
}

/// <summary>
/// Review decision result.
/// </summary>
public sealed record ReviewDecision
{
    public required string ReviewId { get; init; }
    public required ReviewStatus NewStatus { get; init; }
    public required DateTimeOffset DecidedAt { get; init; }
    public string? DecidedBy { get; init; }
    public string? Comment { get; init; }
    public IReadOnlyList<ReviewComment>? Comments { get; init; }
}

/// <summary>
/// List of review requests.
/// </summary>
public sealed record ReviewRequestList
{
    public required IReadOnlyList<ReviewRequest> Items { get; init; }
    public string? NextPageToken { get; init; }
    public int TotalCount { get; init; }
}

/// <summary>
/// Audit entry for review actions.
/// </summary>
public sealed record ReviewAuditEntry
{
    public required string AuditId { get; init; }
    public required string ReviewId { get; init; }
    public required Guid PackId { get; init; }
    public required ReviewAuditAction Action { get; init; }
    public required DateTimeOffset Timestamp { get; init; }
    public string? PerformedBy { get; init; }
    public ReviewStatus? PreviousStatus { get; init; }
    public ReviewStatus? NewStatus { get; init; }
    public string? Comment { get; init; }
    public IReadOnlyDictionary<string, object>? Details { get; init; }
}

/// <summary>
/// Review audit action types.
/// </summary>
public enum ReviewAuditAction
{
    Submitted,
    AssignedReviewer,
    RemovedReviewer,
    CommentAdded,
    ChangesRequested,
    Approved,
    Rejected,
    Cancelled,
    Reopened,
    StatusChanged
}