Add optional network.json node IDs across supported integrations

docs/v2.0/configuration-advanced.md

@@ -131,6 +131,26 @@ How overrides apply:
 
 Network.json allows ISP operators to define a Hierarchical Network Topology, or Flat Network Topology.
 
+Each topology node may optionally include an `"id"` field. This is intended to carry a stable node identifier from the source CRM/NMS when one exists. LibreQoS currently still matches hierarchy and overrides by node name, not by this ID, so `"id"` is metadata for now.
+
+Recommended format:
+
+```json
+{
+  "Tower_A": {
+    "id": "uisp:site:abc123",
+    "downloadBandwidthMbps": 1000,
+    "uploadBandwidthMbps": 1000,
+    "type": "site"
+  }
+}
+```
+
+Notes:
+- Use namespaced string IDs such as `uisp:site:<id>`, `splynx:network_site:<id>`, or `sonar:ap:<id>`.
+- Generated LibreQoS-only nodes may use stable generated IDs such as `libreqos:generated:uisp:site:orphans`.
+- Existing integration-specific metadata fields such as `uisp_site` and `uisp_device` may also appear alongside the generic `id` field.
+
 If you plan to use the built-in UISP, Splynx, or Netzur integrations, you do not need to create a network.json file quite yet.
 If you plan to use the built-in UISP integration, it will create this automatically on its first run (assuming network.json is not already present).
 

docs/v2.0/integrations.md

@@ -51,6 +51,20 @@ When integrations are enabled:
 - `network.json` may also be overwritten depending on integration settings (for example `always_overwrite_network_json`).
 - Manual edits may be overwritten on the next refresh cycle.
 
+## Topology Node ID Support
+
+LibreQoS supports an optional generic `"id"` field on `network.json` nodes. This field is intended to carry stable node identifiers from the integration source where possible. In the current release, the field is informational and is not yet the authoritative match key for shaping or overrides.
+
+| Integration | `network.json` node ID support | Notes |
+|---|---|---|
+| UISP | Yes | Real UISP sites/devices export generic `id` plus existing `uisp_site` / `uisp_device` metadata. Synthetic LibreQoS nodes use stable generated IDs. |
+| Splynx | Yes | Network sites and AP/site topology nodes export generic `id`. |
+| Sonar | Yes | Site and AP topology nodes export generic `id`. |
+| Netzur | Partial | Exported only when the upstream zone payload includes a stable zone ID. |
+| VISP | No | Current importer shapes services/devices but does not build topology nodes in `network.json`. |
+| Powercode | No | Current importer does not build topology nodes in `network.json`. |
+| WISPGate | No | Current importer does not build topology nodes from stable upstream topology identifiers. |
+
 ## Common Client Rate Handling
 
 For built-in integrations that import raw subscriber plan speeds, LibreQoS applies the same shared client-rate rule before writing `ShapedDevices.csv`: