实现应用健康监控（07-27-app-health-monitoring）

.trellis/spec/hyb-oa/deployment-trialrun.md

@@ -1097,3 +1097,99 @@ bash scripts/run-automatic-backup.sh run
 # The Docker CLI inherits the value without placing it in argv.
 PGPASSWORD="$POSTGRES_PASSWORD" docker exec -e PGPASSWORD db pg_dump ...
 ```
+
+## Scenario: Independent Public Application Health Monitor
+
+### 1. Scope / Trigger
+
+- Trigger: installing or changing the off-host public `/ready` probe, its ARM
+  timer, application-health alert states or the shared WeCom group-alert helper.
+- Purpose: detect an unavailable OA host, edge/TLS path, application or database
+  readiness signal without adding a time-series platform or relying on traffic.
+
+### 2. Signatures
+
+- Probe: `scripts/check-public-app-health.py --ready-url <https-/ready> --state-dir
+  <root-0700-dir> --webhook-file <root-0600-file> --alert-helper <installed-helper>
+  --failure-threshold 2 --timeout-seconds <1..30>`.
+- Installer: `deploy/trialrun/install-offhost-app-health-monitor.sh
+  install|enable|uninstall`.
+- Units: `hyb-oa-public-app-health.service` and
+  `hyb-oa-public-app-health.timer`; the timer uses `OnCalendar=*:0/5`.
+- Local contract: `bash scripts/qa/run-app-health-monitor-contract.sh`.
+
+### 3. Contracts
+
+- Run the probe from the existing ARM host against an exact HTTPS `/ready` URL.
+  Success requires trusted TLS, HTTP 2xx, bounded JSON and `data.ok === true`.
+- Count any stable failure category toward the same consecutive-failure
+  threshold. The first failure is pending; the second evaluates a failure
+  alert. Once alerting, a changed category may send a new alert, identical
+  failures are deduplicated, and one later success sends one recovery notice.
+- Persist only schema version, count, stable category and the alert state in a
+  root-owned `0700` directory with atomic `0600` files. Never persist or send
+  the URL, resolved address, response payload, credential or raw exception.
+- Application-health probe state and alert state are separate from backup and
+  dead-man state. The installer must deploy the helper revision that passed the
+  backup contract; an older installed helper may reject the new status tokens.
+- `install` writes only the exact managed probe/helper/state/unit targets and
+  leaves the timer disabled. `enable`, ARM writes, real robot messages and a
+  controlled failure/recovery drill remain separately approved operations.
+- `uninstall` removes only the exact application-health units and probe. It
+  retains the shared helper, webhook, state evidence and all backup components.
+
+### 4. Validation & Error Matrix
+
+- Non-HTTPS, userinfo, query, fragment or non-`/ready` URL -> reject before a
+  request with `ready_url_invalid`.
+- DNS/connect, TLS, timeout, HTTP, oversized response or invalid JSON/contract
+  -> stable redacted category and non-zero oneshot exit.
+- Invalid owner/mode/link/state or alert-helper failure -> fail closed with a
+  fixed local error; do not include the offending value.
+- A first isolated failure followed by health -> no failure or recovery message.
+- Any overridden managed target or service name -> installer stops before
+  `systemctl`, file replacement or removal.
+- ARM itself or its network/robot path unavailable -> the monitor can be silent;
+  do not report this design as having an independent third-party dead-man.
+
+### 5. Good/Base/Bad Cases
+
+- Good: ARM observes two consecutive unavailable checks, sends one redacted
+  category alert, suppresses repeats and sends one recovery after health returns.
+- Base: repository contracts pass while units remain disabled; report the code
+  as ready for an approved rollout, not as an active monitor.
+- Bad: run the timer only on the OA host, send raw `/ready` errors, install and
+  enable in one unapproved step, or deploy the probe without its helper revision.
+
+### 6. Tests Required
+
+- The local HTTPS stub must assert healthy baseline, pending first failure,
+  second-failure alert, identical deduplication, changed-category alert, one
+  recovery, transient suppression, TLS/connect/timeout/HTTP/size/JSON failures,
+  corrupt private state, URL rejection and absence of sensitive output.
+- Run Python compile and shell syntax checks, validate the five-minute calendar,
+  and assert disabled-by-default plus exact managed targets and retained state.
+- Re-run `bash scripts/qa/run-automatic-backup-contract.sh` whenever the shared
+  helper allowlist or behavior changes.
+- ARM install, enabled/active timer status and real failure/recovery messages are
+  external evidence and may not be inferred from the local contract.
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```bash
+# Local contract passed, so install and enable remotely and call it active.
+bash deploy/trialrun/install-offhost-app-health-monitor.sh enable
+```
+
+#### Correct
+
+```bash
+bash scripts/qa/run-app-health-monitor-contract.sh
+bash scripts/qa/run-automatic-backup-contract.sh
+# After separate ARM-write approval: install disabled, inspect, then seek
+# enable/real-message/drill approval before claiming the monitor is active.
+<explicit-controlled-paths> \
+  bash deploy/trialrun/install-offhost-app-health-monitor.sh install
+```