docs(delmia-notifier): README + publish/AOT instructions

docs/plans/2026-06-26-delmia-recipe-notifier.md.tasks.json

@@ -1,14 +1,14 @@
 {
   "planPath": "docs/plans/2026-06-26-delmia-recipe-notifier.md",
   "tasks": [
-    {"id": 11, "subject": "Task 1: Scaffold src + test projects", "status": "pending"},
+    {"id": 11, "subject": "Task 1: Scaffold src + test projects", "status": "completed"},
-    {"id": 12, "subject": "Task 2: DTOs + JSON source-gen context", "status": "pending", "blockedBy": [11]},
+    {"id": 12, "subject": "Task 2: DTOs + JSON source-gen context", "status": "completed", "blockedBy": [11]},
-    {"id": 13, "subject": "Task 3: CLI arg parser", "status": "pending", "blockedBy": [11]},
+    {"id": 13, "subject": "Task 3: CLI arg parser", "status": "completed", "blockedBy": [11]},
-    {"id": 14, "subject": "Task 4: Config loader + API key", "status": "pending", "blockedBy": [11]},
+    {"id": 14, "subject": "Task 4: Config loader + API key", "status": "completed", "blockedBy": [11]},
-    {"id": 15, "subject": "Task 5: Failover loop (IRecipeSender seam)", "status": "pending", "blockedBy": [12]},
+    {"id": 15, "subject": "Task 5: Failover loop (IRecipeSender seam)", "status": "completed", "blockedBy": [12]},
-    {"id": 16, "subject": "Task 6: HttpClient recipe sender", "status": "pending", "blockedBy": [12, 15]},
+    {"id": 16, "subject": "Task 6: HttpClient recipe sender", "status": "completed", "blockedBy": [12, 15]},
-    {"id": 17, "subject": "Task 7: Program wiring + reporter + logger", "status": "pending", "blockedBy": [13, 14, 15, 16]},
+    {"id": 17, "subject": "Task 7: Program wiring + reporter + logger", "status": "completed", "blockedBy": [13, 14, 15, 16]},
-    {"id": 18, "subject": "Task 8: README + publish/AOT + final verify", "status": "pending", "blockedBy": [17]}
+    {"id": 18, "subject": "Task 8: README + publish/AOT + final verify", "status": "completed", "blockedBy": [17]}
   ],
   "lastUpdated": "2026-06-26"
 }

src/ZB.MOM.WW.ScadaBridge.DelmiaNotifier/README.md

@@ -0,0 +1,114 @@
+# DelmiaNotifier (`WWNotifier.exe`)
+
+A compact, self-contained Windows console app that **DELMIA Apriso shells out to** on each
+recipe / NC-program download to notify the plant that a recipe was placed at a path for a machine.
+
+It is the modern, drop-in replacement for the legacy `WWNotifier` (see
+[`../../docs/former-api-specs/dnc/Delmia-Integration-API.md`](../../docs/former-api-specs/dnc/Delmia-Integration-API.md),
+*Surface B*), repointed from the old Wonderware `/notify` receiver to the **ScadaBridge Inbound API**
+method `DelmiaRecipeDownload`. The command-line flags, the `YES`/`NO` stdout contract, and the
+exit-code semantics are **unchanged**, so Delmia's call site and output parsing need no changes — only
+the executable on disk and its `appsettings.json` are swapped.
+
+> The published assembly name is **`WWNotifier`** precisely so it is a literal file-for-file drop-in
+> for Delmia's existing call path.
+
+## What it does
+
+Per invocation it POSTs the recipe-download notification to the configured ScadaBridge node(s) and
+maps the result back to the legacy contract:
+
+```
+DELMIA → WWNotifier.exe → POST {baseUrl}/api/DelmiaRecipeDownload  (X-API-Key: <key>)
+                        ← { "Result": true/false, "ResultText": "..." }
+        ← stdout: YES | NO\n<reason>   ·   exit: 0 | -1
+```
+
+## Command-line flags
+
+| Short | Long | Required | → payload field |
+|---|---|---|---|
+| `-d` | `--downloadpath` | yes | `DownloadPath` |
+| `-m` | `--machine` | yes | `MachineCode` |
+| `-w` | `--workorder` | yes | `WorkOrderNumber` |
+| `-p` | `--partnumber` | yes | `PartNumber` |
+| `-s` | `--seqop` | no | `JobStepNumber` |
+| `-u` | `--username` | no | `Username` |
+
+Each flag takes one value (`-m Z28061`). A missing required flag → `NO` + reason, exit `-1`, **no**
+HTTP attempt.
+
+```
+WWNotifier.exe -m Z28061 -d "C:\recipes\job.nc" -w WO12345 -p PN-7788 -s 0100 -u operator1
+```
+
+## Output contract (drop-in parity)
+
+- **stdout** is reserved for the contract Delmia parses:
+  - success → `YES` (exit `0`)
+  - failure → `NO` on the first line, then a human-readable reason on the next line (exit `-1`)
+- **exit code**: `0` on success, `-1` on failure. (On POSIX shells `-1` surfaces as `255`; on Windows
+  `%ERRORLEVEL%` is `-1`.)
+- All diagnostics (per-URL attempt, status code, which URL answered, exceptions) go to **stderr** and,
+  if `LogPath` is set, an appended log file — never to stdout.
+
+## Configuration — `appsettings.json`
+
+Placed next to the exe (copied to the output on build/publish):
+
+```json
+{
+  "ScadaBridge": {
+    "BaseUrls": "http://host-a:8085,http://host-b:8085",
+    "TimeoutSeconds": 30,
+    "LogPath": "logs/delmia-notifier.log"
+  }
+}
+```
+
+- **`BaseUrls`** — comma-separated failover list of **base URLs only**; the app appends
+  `/api/DelmiaRecipeDownload`. URLs are tried in order with **connect-failure-only failover**: a node
+  that responds at all (even `4xx`/`5xx`) is authoritative and its answer is final; only a node that
+  fails to connect (refused/reset, DNS, TLS, timeout) rolls over to the next. If every URL fails to
+  connect → `NO` + last connection error.
+- **`TimeoutSeconds`** — per-attempt HTTP timeout (default `30`).
+- **`LogPath`** — optional diagnostic log file, relative to the exe. Omit to log to stderr only.
+
+## Secret — `SCADABRIDGE_API_KEY`
+
+The inbound API key is read **only** from the environment variable `SCADABRIDGE_API_KEY` and is sent
+as the `X-API-Key` header. It is never read from or written to a file. If unset/empty → `NO` +
+`API key not configured (SCADABRIDGE_API_KEY)`, exit `-1`, no HTTP attempt.
+
+Set it on the machine/account that DELMIA runs under (e.g. a system/user environment variable, or the
+service account's environment).
+
+## Building & publishing (Native AOT, `win-x64`)
+
+The runtime artifact is a self-contained, single-file native exe. **Native AOT does not cross-compile
+from macOS/Linux** — publish on Windows with the MSVC build tools (Desktop C++ workload) installed:
+
+```powershell
+# On Windows:
+dotnet publish src/ZB.MOM.WW.ScadaBridge.DelmiaNotifier -c Release -r win-x64
+# → bin/Release/net10.0/win-x64/publish/WWNotifier.exe  (+ appsettings.json)
+```
+
+Copy `WWNotifier.exe` **and** `appsettings.json` to the Delmia host, set `SCADABRIDGE_API_KEY`, and
+point `BaseUrls` at the central node(s).
+
+> Managed `dotnet build` / `dotnet test` run cross-platform and are the development/CI gate; only the
+> final native publish requires Windows.
+
+## Manual smoke test
+
+After deploying (or against a reachable test cluster such as `wonder-app-vd03`):
+
+```powershell
+$env:SCADABRIDGE_API_KEY = "sbk_..."
+.\WWNotifier.exe -m Z28061Sim -d "C:\recipes\test.nc" -w WO-TEST -p PN-TEST -s 0100 -u smoketest
+# expect: YES  (exit 0)   — or NO + reason (exit -1) with details on stderr / in the log file
+```
+
+This mirrors the earlier `curl` verification of `POST /api/DelmiaRecipeDownload` with the
+`X-API-Key` header.