docs: sister-repo index update + working notes
CLAUDE.md: the historian SDK is now owned inside HistorianGateway at histsdk/ (the separate ~/Desktop/histsdk repo was folded in with history), so the sister-project list no longer points at a standalone repo. Also checks in working notes that were sitting untracked in the tree: deferred.md (remaining deferred work snapshot), ScadaBridge-docs-fixed.md and ScadaBridge-docs-issues.md (documentation-analysis report output).
This commit was merged in pull request #19.
This commit is contained in:
Joseph Doherty
@@ -41,7 +41,7 @@ Repos cloned as sibling directories under `~/Desktop/` — referenced for contex
|
||||
- `~/Desktop/MxAccessGateway` — MxAccess Gateway (`https://gitea.dohertylan.com/dohertj2/mxaccessgw`).
|
||||
- `~/Desktop/OtOpcUa` — OtOpcUa (`https://gitea.dohertylan.com/dohertj2/lmxopcua`).
|
||||
|
||||
Other peers in the `scadaproj` family (see `scadaproj/CLAUDE.md` for details): `~/Desktop/HistorianGateway` (`historiangw`) — AVEVA Historian gRPC sidecar, OtOpcUa's sole historian backend; its SDK source `~/Desktop/histsdk` (`histsdk`); and `~/Desktop/scadaproj` (`scadaproj`) itself — shared `ZB.MOM.WW.*` libs + the dev/test GLAuth on `10.100.0.35:3893`.
|
||||
Other peers in the `scadaproj` family (see `scadaproj/CLAUDE.md` for details): `~/Desktop/HistorianGateway` (`historiangw`) — AVEVA Historian gRPC sidecar, OtOpcUa's sole historian backend; its historian SDK (`AVEVA.Historian.Client`) is now owned inside that repo at `HistorianGateway/histsdk/` (the separate `~/Desktop/histsdk` repo was folded in with history); and `~/Desktop/scadaproj` (`scadaproj`) itself — shared `ZB.MOM.WW.*` libs + the dev/test GLAuth on `10.100.0.35:3893`.
|
||||
|
||||
## Document Conventions
|
||||
|
||||
|
||||
@@ -0,0 +1,116 @@
|
||||
# Documentation Analysis Report
|
||||
|
||||
Files Scanned: 793
|
||||
Files With Issues: 10
|
||||
Total Issues: 11
|
||||
|
||||
## Issues
|
||||
|
||||
FILE: /Users/dohertj2/Desktop/ScadaBridge/src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/BrowserTime.cs
|
||||
LINE: 26
|
||||
CATEGORY: TaskReferenceInComment
|
||||
SEVERITY: Warning
|
||||
MEMBER: Comment
|
||||
SIGNATURE: UTC-5
|
||||
MESSAGE: Comment contains 'UTC-5', which looks like a task/issue tracking identifier; tracking IDs should not appear in code documentation.
|
||||
|
||||
---
|
||||
|
||||
FILE: /Users/dohertj2/Desktop/ScadaBridge/src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Pages/Design/TransportImport.razor.cs
|
||||
LINE: 225
|
||||
CATEGORY: TaskReferenceInComment
|
||||
SEVERITY: Warning
|
||||
MEMBER: Comment
|
||||
SIGNATURE: Step-2
|
||||
MESSAGE: Comment contains 'Step-2', which looks like a task/issue tracking identifier; tracking IDs should not appear in code documentation.
|
||||
|
||||
---
|
||||
|
||||
FILE: /Users/dohertj2/Desktop/ScadaBridge/src/ZB.MOM.WW.ScadaBridge.CentralUI/Services/ConnectionHealthQueryService.cs
|
||||
LINE: 18
|
||||
CATEGORY: TaskReferenceInComment
|
||||
SEVERITY: Warning
|
||||
MEMBER: Comment
|
||||
SIGNATURE: PLC-1
|
||||
MESSAGE: Comment contains 'PLC-1', which looks like a task/issue tracking identifier; tracking IDs should not appear in code documentation.
|
||||
|
||||
---
|
||||
|
||||
FILE: /Users/dohertj2/Desktop/ScadaBridge/src/ZB.MOM.WW.ScadaBridge.CLI/Commands/AuditExportHelpers.cs
|
||||
LINE: 156
|
||||
CATEGORY: TaskReferenceInComment
|
||||
SEVERITY: Warning
|
||||
MEMBER: Comment
|
||||
SIGNATURE: non-403
|
||||
MESSAGE: Comment contains 'non-403', which looks like a task/issue tracking identifier; tracking IDs should not appear in code documentation.
|
||||
|
||||
---
|
||||
|
||||
FILE: /Users/dohertj2/Desktop/ScadaBridge/src/ZB.MOM.WW.ScadaBridge.CLI/Commands/BundleCommands.cs
|
||||
LINE: 407
|
||||
CATEGORY: TaskReferenceInComment
|
||||
SEVERITY: Warning
|
||||
MEMBER: Comment
|
||||
SIGNATURE: non-403
|
||||
MESSAGE: Comment contains 'non-403', which looks like a task/issue tracking identifier; tracking IDs should not appear in code documentation.
|
||||
|
||||
---
|
||||
|
||||
FILE: /Users/dohertj2/Desktop/ScadaBridge/src/ZB.MOM.WW.ScadaBridge.Communication/Grpc/SiteStreamGrpcServer.cs
|
||||
LINE: 43
|
||||
CATEGORY: TaskReferenceInComment
|
||||
SEVERITY: Warning
|
||||
MEMBER: Comment
|
||||
SIGNATURE: sub-100
|
||||
MESSAGE: Comment contains 'sub-100', which looks like a task/issue tracking identifier; tracking IDs should not appear in code documentation.
|
||||
|
||||
---
|
||||
|
||||
FILE: /Users/dohertj2/Desktop/ScadaBridge/src/ZB.MOM.WW.ScadaBridge.HealthMonitoring/SiteHealthState.cs
|
||||
LINE: 29
|
||||
CATEGORY: TaskReferenceInComment
|
||||
SEVERITY: Warning
|
||||
MEMBER: Comment
|
||||
SIGNATURE: year-0001
|
||||
MESSAGE: Comment contains 'year-0001', which looks like a task/issue tracking identifier; tracking IDs should not appear in code documentation.
|
||||
|
||||
---
|
||||
|
||||
FILE: /Users/dohertj2/Desktop/ScadaBridge/src/ZB.MOM.WW.ScadaBridge.ManagementService/ManagementActor.cs
|
||||
LINE: 2034
|
||||
CATEGORY: TrackingReferenceInComment
|
||||
SEVERITY: Warning
|
||||
MEMBER: Comment
|
||||
SIGNATURE: M365
|
||||
MESSAGE: Comment contains 'M365', which looks like a project tracking reference; bookkeeping references should not appear in code documentation.
|
||||
|
||||
---
|
||||
|
||||
FILE: /Users/dohertj2/Desktop/ScadaBridge/src/ZB.MOM.WW.ScadaBridge.NotificationOutbox/Delivery/EmailNotificationDeliveryAdapter.cs
|
||||
LINE: 206
|
||||
CATEGORY: TrackingReferenceInComment
|
||||
SEVERITY: Warning
|
||||
MEMBER: Comment
|
||||
SIGNATURE: M365
|
||||
MESSAGE: Comment contains 'M365', which looks like a project tracking reference; bookkeeping references should not appear in code documentation.
|
||||
|
||||
---
|
||||
|
||||
FILE: /Users/dohertj2/Desktop/ScadaBridge/src/ZB.MOM.WW.ScadaBridge.NotificationService/MailKitSmtpClientWrapper.cs
|
||||
LINE: 9
|
||||
CATEGORY: TrackingReferenceInComment
|
||||
SEVERITY: Warning
|
||||
MEMBER: Comment
|
||||
SIGNATURE: M365
|
||||
MESSAGE: Comment contains 'M365', which looks like a project tracking reference; bookkeeping references should not appear in code documentation.
|
||||
|
||||
---
|
||||
|
||||
FILE: /Users/dohertj2/Desktop/ScadaBridge/src/ZB.MOM.WW.ScadaBridge.NotificationService/MailKitSmtpClientWrapper.cs
|
||||
LINE: 113
|
||||
CATEGORY: TrackingReferenceInComment
|
||||
SEVERITY: Warning
|
||||
MEMBER: Comment
|
||||
SIGNATURE: M365
|
||||
MESSAGE: Comment contains 'M365', which looks like a project tracking reference; bookkeeping references should not appear in code documentation.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
+44
@@ -0,0 +1,44 @@
|
||||
# Remaining Deferred Work
|
||||
|
||||
Source: `docs/plans/2026-07-08-deferred-work-register.md` (snapshot 2026-07-10).
|
||||
Everything in the register's "Fix-now" table is already landed via the archreview
|
||||
plans; what's left are the intentional deferrals below.
|
||||
|
||||
## Product / roadmap-locked (revisit needs a decision or a trigger event)
|
||||
|
||||
| # | Item | Why deferred | Revisit trigger |
|
||||
|---|------|--------------|-----------------|
|
||||
| 8 | Hash-chain tamper evidence (CLI `verify-chain` is a no-op stub) | v1.x by locked decision — append-only DB roles are the current control | A compliance requirement for cryptographic tamper evidence |
|
||||
| 9 | Parquet audit archival (endpoint returns `501`) | v1.x — the `501` + CLI messaging are honest, not broken | AuditLog partition volume nears the retention ceiling |
|
||||
| 11 | Central-persisted OPC UA cert-trust audit | Broadcast-to-both-nodes already covers HA | A governance/audit requirement for trust decisions |
|
||||
| 19 | Bundle signing / cluster-to-cluster pull / differential bundles | v1 manifest hash + AES-GCM held sufficient | A non-repudiation requirement across orgs |
|
||||
| 17 | Unified notifications + site-calls outbox page | Explicit M9 decision to keep two pages | Operator confusion reports |
|
||||
| 18 | Folder drag-drop | Permanently closed — menu reorder shipped instead | — (closed) |
|
||||
|
||||
## Scale / YAGNI (deferred until load justifies it)
|
||||
|
||||
| # | Item | Why deferred | Revisit trigger | Status |
|
||||
|---|------|--------------|-----------------|--------|
|
||||
| 10 | Aggregated live alarm stream for Alarm Summary | Snapshot fan-out is acceptable at current instance counts | Latency complaints or >~50 instances/site | ✅ **SHIPPED + MERGED to main 2026-07-10** (`8c888f13`, plan `docs/plans/2026-07-10-aggregated-live-alarm-stream-plan.md`, T1–T8). Transient per-site in-memory live cache (`ISiteAlarmLiveCache`/`SiteAlarmAggregatorActor`) seeded by snapshot fan-out + additive `SubscribeSite` alarm-only gRPC stream; live-cache-driven Alarm Summary with 15s poll fallback; `[PERM]` no-central-store honored (code-reviewer-confirmed); validated options + telemetry; end-to-end trace. Register row moved to Resolved. |
|
||||
| 22 | KPI history hourly rollups | 90-day retention already bounds the table | `KpiSample` query latency on dashboards | ✅ **SHIPPED + MERGED to main 2026-07-10** (`8c888f13`, plan `docs/plans/2026-07-10-kpi-history-hourly-rollups-plan.md`, T1–T8). Separate `KpiRollupHourly` table (migration `20260710153953`), recorder hourly fold w/ failover-safe lookback re-fold + idempotent upsert, per-metric gauge-vs-rate aggregation, range-threshold query routing (`RollupThresholdHours` 168h), longer rollup retention (365 ≥ 90) + dual purge, one-shot backfill, and 30 d/90 d window buttons. Register row moved to Resolved. |
|
||||
|
||||
## Low-priority polish (near-complete, small remainder)
|
||||
|
||||
| # | Item | Why deferred | Revisit trigger |
|
||||
|---|------|--------------|-----------------|
|
||||
| 12 | Native-alarm-source-override CSV import — Central UI upload button only | CLI + Management API + parser shipped 2026-07-10; the Blazor upload affordance is the only piece left, and it's pure polish (needs a live Blazor smoke) | First request to bulk-import native sources from the UI instead of the CLI |
|
||||
|
||||
## New deferrals from review 08 (engineering debt, no defect)
|
||||
|
||||
| Item | Why deferred | Revisit trigger |
|
||||
|------|--------------|-----------------|
|
||||
| Communication → HealthMonitoring layering inversion | Moving the interface + `SiteHealthState` to Commons ripples across 5 projects for a cosmetic inversion | Next breaking change to `ICentralHealthAggregator` |
|
||||
| Reference docs for ScriptAnalysis, KpiHistory, DelmiaNotifier | Full StyleGuide-conformant docs are substantial; README claim was scoped instead (PLAN-08 T10) | Next doc-writing session touching those components |
|
||||
| Test-coverage backfill: SiteCallAudit.Tests, DeploymentManager.Tests | No defect identified; coverage partly lives in ManagementService/Host/Integration suites | First regression escaping either component |
|
||||
| Failover-timing + broader perf envelope (S&F drain rate, per-subscriber backpressure) | Needs the PLAN-01 two-node rig; placeholder harness already shipped (PLAN-08 T8) | PLAN-01 rig landing |
|
||||
|
||||
---
|
||||
|
||||
Summary: 12 open deferrals (13th, folder drag-drop #18, is permanently closed).
|
||||
None are currently actionable without a triggering event or product decision —
|
||||
except row #12's UI upload button, whose CLI/API/parser core already shipped.
|
||||
Reference in New Issue
Block a user