Joseph Doherty
9cff87fe85
Remove project bookkeeping citations from shipped code comments across the solution: hyphenated task IDs (WP-14, StoreAndForward-025), milestone/task/ issue refs (M3, Task 4, Audit Log #23, #21), Bundle X task-bundle labels, and C/D/K/S/T phase labels. Comment text only — no code logic, string/log literals, or XML-doc structure changed. Genuine descriptions are preserved (only the citation is stripped), and technical lookalikes are retained (UTF-8, SHA-256, T00:00:00, M365, UTC-5, pre-C4/pre-C5 schema versions). Flagged by the new CommentChecker TaskReferenceInComment / TrackingReferenceInComment checks plus targeted grep passes; full solution builds clean, append-only guard tests pass.
83 lines
4.1 KiB
C#
83 lines
4.1 KiB
C#
using ZB.MOM.WW.ScadaBridge.Commons.Entities.SecuredWrites;
|
|
|
|
namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
|
|
|
|
/// <summary>
|
|
/// Operational-state data access for the central <c>PendingSecuredWrites</c> table.
|
|
/// One row per pending two-person secured
|
|
/// write; rows are inserted at submission and mutated as the request is decided and
|
|
/// executed. Mirrors the <c>SiteCalls</c> repository shape.
|
|
/// </summary>
|
|
public interface ISecuredWriteRepository
|
|
{
|
|
/// <summary>
|
|
/// Inserts <paramref name="securedWrite"/> and returns the store-generated
|
|
/// <see cref="PendingSecuredWrite.Id"/>.
|
|
/// </summary>
|
|
/// <param name="securedWrite">The pending secured write to persist.</param>
|
|
/// <param name="ct">Cancellation token.</param>
|
|
/// <returns>A task that resolves to the generated identity of the inserted row.</returns>
|
|
Task<long> AddAsync(PendingSecuredWrite securedWrite, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Returns the row for the given id, or <c>null</c> if none exists.
|
|
/// </summary>
|
|
/// <param name="id">The identity to look up.</param>
|
|
/// <param name="ct">Cancellation token.</param>
|
|
/// <returns>A task that resolves to the matching <see cref="PendingSecuredWrite"/>, or <c>null</c> if no row exists.</returns>
|
|
Task<PendingSecuredWrite?> GetAsync(long id, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Persists the current state of <paramref name="securedWrite"/> (matched by
|
|
/// <see cref="PendingSecuredWrite.Id"/>).
|
|
/// </summary>
|
|
/// <param name="securedWrite">The tracked entity whose changes to persist.</param>
|
|
/// <param name="ct">Cancellation token.</param>
|
|
/// <returns>A task that represents the asynchronous operation.</returns>
|
|
Task UpdateAsync(PendingSecuredWrite securedWrite, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Returns up to <paramref name="take"/> rows (skipping <paramref name="skip"/>)
|
|
/// optionally filtered by <paramref name="status"/> and <paramref name="siteId"/>,
|
|
/// ordered by <c>SubmittedAtUtc DESC, Id DESC</c>. A <c>null</c> filter argument
|
|
/// matches every row.
|
|
/// </summary>
|
|
/// <param name="status">Status filter; <c>null</c> matches every status.</param>
|
|
/// <param name="siteId">Site id filter; <c>null</c> matches every site.</param>
|
|
/// <param name="skip">Number of rows to skip (offset paging).</param>
|
|
/// <param name="take">Maximum number of rows to return.</param>
|
|
/// <param name="ct">Cancellation token.</param>
|
|
/// <returns>A task that resolves to a page of matching rows, newest submission first.</returns>
|
|
Task<IReadOnlyList<PendingSecuredWrite>> QueryAsync(
|
|
string? status,
|
|
string? siteId,
|
|
int skip,
|
|
int take,
|
|
CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Atomically flips a row from <c>Pending</c> to <c>Approved</c>, stamping the
|
|
/// verifier identity, comment, and decision time, but ONLY if the row is still
|
|
/// <c>Pending</c>. This is the compare-and-swap guard for the two-verifier race:
|
|
/// two verifiers may approve the same write concurrently, but the
|
|
/// conditional <c>WHERE Status='Pending'</c> guarantees exactly one wins. The
|
|
/// loser observes <c>false</c> and must not relay the write.
|
|
/// </summary>
|
|
/// <param name="id">Identity of the pending secured write.</param>
|
|
/// <param name="verifierUser">The approving verifier's username.</param>
|
|
/// <param name="verifierComment">Optional free-text comment from the verifier.</param>
|
|
/// <param name="decidedAtUtc">UTC instant the approval decision was made.</param>
|
|
/// <param name="ct">Cancellation token.</param>
|
|
/// <returns>
|
|
/// A task resolving to <c>true</c> if this caller won the approval (exactly one
|
|
/// row transitioned), or <c>false</c> if the row was no longer <c>Pending</c>
|
|
/// (already decided by another verifier).
|
|
/// </returns>
|
|
Task<bool> TryMarkApprovedAsync(
|
|
long id,
|
|
string verifierUser,
|
|
string? verifierComment,
|
|
DateTime decidedAtUtc,
|
|
CancellationToken ct = default);
|
|
}
|