dohertj2/scadalink-design
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(requirements): clarify Site Call Audit lifecycle states and actionability

Browse Source
This commit is contained in:
Joseph Doherty
2026-05-19 11:34:44 -04:00
parent 627c48c458
commit e0026c6da7
1 changed files with 20 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/requirements/Component-SiteCallAudit.md
View File

@@ -37,7 +37,9 @@ Lives in the central MS SQL configuration database — a sibling of the
- **TrackedOperationId** — GUID, primary key. Generated site-side at call time. - **TrackedOperationId** — GUID, primary key. Generated site-side at call time.
- **SourceSite** — site that issued the call. - **SourceSite** — site that issued the call.
- **Kind** — `ExternalCall` or `DatabaseWrite`. - **Kind** — `ExternalCall` or `DatabaseWrite`.
- **TargetSummary** — external system + method name, or database connection name. - **TargetSummary** — external system + method name for an `ExternalCall`; for a
`DatabaseWrite`, just the database connection name — intentionally not the SQL
statement or table, a deliberate scoping choice.
- **Status** — `Pending`, `Retrying`, `Delivered`, `Parked`, `Failed`, `Discarded`. - **Status** — `Pending`, `Retrying`, `Delivered`, `Parked`, `Failed`, `Discarded`.
- **RetryCount** — attempts so far. - **RetryCount** — attempts so far.
- **LastError** — most recent error detail, if any. - **LastError** — most recent error detail, if any.
@@ -48,12 +50,18 @@ Lives in the central MS SQL configuration database — a sibling of the
`Pending → Retrying → Delivered / Parked / Failed / Discarded` `Pending → Retrying → Delivered / Parked / Failed / Discarded`
- **Delivered** — succeeded. A cached call that succeeds on its first immediate - **Pending** — non-terminal: buffered after a transient failure, awaiting its
attempt is recorded directly as `Delivered`. first retry.
- **Parked** — transient retries exhausted; awaiting manual action. - **Retrying** — non-terminal: undergoing retry attempts.
- **Failed** — permanent failure (e.g. HTTP 4xx). The error was also returned - **Delivered** — terminal, success. A cached call that succeeds on its first
synchronously to the calling script; the record captures it. immediate attempt is recorded directly as `Delivered`.
- **Discarded** — an operator discarded a parked operation. - **Parked** — non-terminal: transient retries exhausted; awaiting manual action.
- **Failed** — terminal: permanent failure (e.g. HTTP 4xx). The error was also
returned synchronously to the calling script; the record captures it. `Failed`
rows are **not operator-actionable** — see Retry / Discard Relay.
- **Discarded** — terminal, reached **only by operator action** on a `Parked`
row. The row is kept (not deleted) so the table remains a complete audit
record.
The site is the source of truth. The `SiteCalls` row is an eventually-consistent The site is the source of truth. The `SiteCalls` row is an eventually-consistent
mirror — never queried by scripts (`Tracking.Status()` is answered site-locally). mirror — never queried by scripts (`Tracking.Status()` is answered site-locally).
@@ -81,6 +89,11 @@ applies the change and emits telemetry reflecting the new state; central never
mutates the `SiteCalls` row directly. If the site is offline the command fails mutates the `SiteCalls` row directly. If the site is offline the command fails
fast and the UI surfaces a "site unreachable" message. fast and the UI surfaces a "site unreachable" message.
Only `Parked` rows are operator-actionable. `Failed` rows offer no Retry or
Discard: a permanent failure (e.g. HTTP 4xx) would simply fail again, and the
error was already returned synchronously to the calling script — there is
nothing for an operator to recover.
## KPIs ## KPIs
Point-in-time, computed from the `SiteCalls` table, global and per-source-site, Point-in-time, computed from the `SiteCalls` table, global and per-source-site,