Extract historian into a runtime-loaded plugin so hosts without the Wonderware SDK can run with Historian.Enabled=false

The aahClientManaged SDK is now isolated in ZB.MOM.WW.LmxOpcUa.Historian.Aveva and loaded via HistorianPluginLoader from a Historian/ subfolder only when enabled, removing the SDK from Host's compile-time and deploy-time surface. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-12 15:16:07 -04:00
parent 9e1a180ce3
commit 9b42b61eb6
40 changed files with 739 additions and 15855 deletions
--- a/StyleGuide.md
+++ b/StyleGuide.md
@@ -0,0 +1,282 @@
+# Documentation Style Guide
+
+This guide defines writing conventions and formatting rules for all ScadaBridge documentation.
+
+## Tone and Voice
+
+### Be Technical and Direct
+
+Write for developers who are familiar with .NET. Don't explain basic concepts like dependency injection or async/await unless they're used in an unusual way.
+
+**Good:**
+> The `ScadaGatewayActor` routes messages to the appropriate `ScadaClientActor` based on the client ID in the message.
+
+**Avoid:**
+> The ScadaGatewayActor is a really powerful component that helps manage all your SCADA connections efficiently!
+
+### Explain "Why" Not Just "What"
+
+Document the reasoning behind patterns and decisions, not just the mechanics.
+
+**Good:**
+> Health checks use a 5-second timeout because actors under heavy load may take several seconds to respond, but longer delays indicate a real problem.
+
+**Avoid:**
+> Health checks use a 5-second timeout.
+
+### Use Present Tense
+
+Describe what the code does, not what it will do.
+
+**Good:**
+> The actor validates the message before processing.
+
+**Avoid:**
+> The actor will validate the message before processing.
+
+### No Marketing Language
+
+This is internal technical documentation. Avoid superlatives and promotional language.
+
+**Avoid:** "powerful", "robust", "cutting-edge", "seamless", "blazing fast"
+
+## Formatting Rules
+
+### File Names
+
+Use `PascalCase.md` for all documentation files:
+- `Overview.md`
+- `HealthChecks.md`
+- `StateMachines.md`
+- `SignalR.md`
+
+### Headings
+
+- **H1 (`#`):** Document title only, Title Case
+- **H2 (`##`):** Major sections, Title Case
+- **H3 (`###`):** Subsections, Sentence case
+- **H4+ (`####`):** Rarely needed, Sentence case
+
+```markdown
+# Actor Health Checks
+
+## Configuration Options
+
+### Setting the timeout
+
+#### Default values
+```
+
+### Code Blocks
+
+Always specify the language:
+
+````markdown
+```csharp
+public class MyActor : ReceiveActor { }
+```
+
+```json
+{
+  "Setting": "value"
+}
+```
+
+```bash
+dotnet build
+```
+````
+
+Supported languages: `csharp`, `json`, `bash`, `xml`, `sql`, `yaml`, `html`, `css`, `javascript`
+
+### Code Snippets
+
+**Length:** 5-25 lines is typical. Shorter for simple concepts, longer for complete examples.
+
+**Context:** Include enough to understand where the code lives:
+
+```csharp
+// Good - shows class context
+public class TemplateInstanceActor : ReceiveActor
+{
+    public TemplateInstanceActor(TemplateInstanceConfig config)
+    {
+        Receive<StartProcessing>(Handle);
+    }
+}
+
+// Avoid - orphaned snippet
+Receive<StartProcessing>(Handle);
+```
+
+**Accuracy:** Only use code that exists in the codebase. Never invent examples.
+
+### Lists
+
+Use bullet points for unordered items:
+```markdown
+- First item
+- Second item
+- Third item
+```
+
+Use numbers for sequential steps:
+```markdown
+1. Do this first
+2. Then do this
+3. Finally do this
+```
+
+### Tables
+
+Use tables for structured reference information:
+
+```markdown
+| Option | Default | Description |
+|--------|---------|-------------|
+| `Timeout` | `5000` | Milliseconds to wait |
+| `RetryCount` | `3` | Number of retry attempts |
+```
+
+### Inline Code
+
+Use backticks for:
+- Class names: `ScadaGatewayActor`
+- Method names: `HandleMessage()`
+- File names: `appsettings.json`
+- Configuration keys: `ScadaBridge:Timeout`
+- Command-line commands: `dotnet build`
+
+### Links
+
+Use relative paths for internal documentation:
+```markdown
+[See the Actors guide](../Akka/Actors.md)
+[Configuration options](./Configuration.md)
+```
+
+Use descriptive link text:
+```markdown
+<!-- Good -->
+See the [Actor Health Checks](../Akka/HealthChecks.md) documentation.
+
+<!-- Avoid -->
+See [here](../Akka/HealthChecks.md) for more.
+```
+
+## Structure Conventions
+
+### Document Opening
+
+Every document starts with:
+1. H1 title
+2. 1-2 sentence description of purpose
+
+```markdown
+# Actor Health Checks
+
+Health checks monitor actor responsiveness and report status to the ASP.NET Core health check system.
+```
+
+### Section Organization
+
+Organize content from general to specific:
+1. Overview/introduction
+2. Key concepts (if needed)
+3. Basic usage
+4. Advanced usage
+5. Configuration
+6. Troubleshooting
+7. Related documentation
+
+### Code Example Placement
+
+Place code examples immediately after the concept they illustrate:
+
+```markdown
+## Message Handling
+
+Actors process messages using `Receive<T>` handlers:
+
+```csharp
+Receive<MyMessage>(msg => HandleMyMessage(msg));
+```
+
+Each handler processes one message type...
+```
+
+### Related Documentation Section
+
+End each document with links to related topics:
+
+```markdown
+## Related Documentation
+
+- [Actor Patterns](./Patterns.md)
+- [Health Checks](../Operations/HealthChecks.md)
+- [Configuration](../Configuration/Akka.md)
+```
+
+## Naming Conventions
+
+### Match Code Exactly
+
+Use the exact names from source code:
+- `TemplateInstanceActor` not "Template Instance Actor"
+- `ScadaGatewayActor` not "SCADA Gateway Actor"
+- `IRequiredActor<T>` not "required actor interface"
+
+### Acronyms
+
+Spell out on first use, then use acronym:
+> OPC Unified Architecture (OPC UA) provides industrial communication standards. OPC UA servers expose...
+
+Common acronyms that don't need expansion:
+- API
+- JSON
+- SQL
+- HTTP/HTTPS
+- REST
+- JWT
+- UI
+
+### File Paths
+
+Use forward slashes and backticks:
+- `src/Infrastructure/Akka/Actors/`
+- `appsettings.json`
+- `Documentation/Akka/Overview.md`
+
+## What to Avoid
+
+### Don't Document the Obvious
+
+```markdown
+<!-- Avoid -->
+## Constructor
+
+The constructor creates a new instance of the class.
+
+<!-- Better - only document if there's something notable -->
+## Constructor
+
+The constructor accepts an `IActorRef` for the gateway actor, which must be resolved before actor creation.
+```
+
+### Don't Duplicate Source Code Comments
+
+If code has good comments, reference the file rather than copying:
+> See `ScadaGatewayActor.cs` lines 45-60 for the message routing logic.
+
+### Don't Include Temporary Information
+
+Avoid dates, version numbers, or "coming soon" notes that will become stale.
+
+### Don't Over-Explain .NET Basics
+
+Assume readers know:
+- Dependency injection
+- async/await
+- LINQ
+- Entity Framework basics
+- ASP.NET Core middleware pipeline