feat(history): add aligned online simulation action

Reuse the existing simulation endpoint and align backfill to the hydraulic timestep. Block backfill when event metadata fails so the fallback query window cannot be calculated as event history.

docs/scene-resource-cache.md

@@ -0,0 +1,19 @@
+# 三维场景静态资源下载与缓存
+
+`public/three-dimensional/zjb/v29/resourceCache.mjs` 统一加载模型和管网静态元数据，不缓存实时仿真或 SCADA 数据。
+
+- 每次请求最多下载 1 MiB，通过单区间 `Range` 请求获取资源。服务器返回 `206` 时，校验 `Content-Range` 的起止位置、总长度以及实际收到的字节数；不支持 Range 的服务器可在首次请求返回完整的 `200` 响应。
+- 网络中断、连续 30 秒无数据以及临时 HTTP 错误可重试，每个分段最多尝试 3 次，等待间隔为 300、600 毫秒。永久 HTTP 错误和不合法的分段响应直接显示失败提示。
+- 每个完整分段保存至 IndexedDB。刷新页面或重新载入后，从已保存的分段末尾继续；未完成的当前分段会重新下载。浏览器禁止存储或配额不足时，仍能在本次加载中下载和重试，但无法保证刷新后保留断点。
+- 完整资源和部分下载均按 URL、manifest revision 匹配，版本改变后重新下载。完整资源经过解析验证后才进入正式缓存，后续打开场景直接复用。
+- 进度界面显示下载、解析和断点重试状态。加载模块版本参数需要与 `preview.html`、`preview.mjs` 和 `ThreeDimensionalScene.tsx` 同步，防止浏览器沿用旧加载器。
+
+反向代理应透传 `Range` 请求及 `206`、`Content-Range` 响应。若内网完整下载正常，而公网完整下载中断，应同时排查代理的大文件传输；客户端分段恢复不代表代理链路问题已修复。
+
+聚焦回归：
+
+```bash
+E2E_BASE_URL=http://127.0.0.1:3000 npx playwright test e2e/three-dimensional-loading.spec.ts --workers=1
+```
+
+该命令需要已运行的前端。测试覆盖完整缓存复用、分段重试、跨刷新续传、错误分段拒绝及浏览器存储不可用的降级行为。

e2e/page-navigation.spec.ts

@@ -0,0 +1,96 @@
+import { expect, test, type Page } from "@playwright/test";
+
+import { mockBackend } from "./support/mockBackend";
+
+test.setTimeout(90_000);
+
+async function prepare(page: Page) {
+  await mockBackend(page);
+  await page.route("**/api/v1/admin/**", (route) => route.fulfill({
+    json: route.request().url().endsWith("/users/me")
+      ? { id: "playwright-user", is_system_admin: true, system_role: "system_admin" }
+      : [],
+  }));
+}
+
+test("菜单点击后立即反馈，等待页面响应时显示路由骨架", async ({ page }) => {
+  await prepare(page);
+  await page.goto("/system-admin");
+  await expect(page.getByRole("link", { name: "审计日志", exact: true })).toBeVisible();
+  await page.locator("[data-page-scroll-content]").evaluate((element) => { element.scrollTop = element.scrollHeight; });
+  let release: () => void = () => {};
+  const gate = new Promise<void>((resolve) => { release = resolve; });
+  let waiting = false;
+  await page.route("**/audit-logs?*", async (route) => {
+    if (route.request().headers().rsc !== "1") return route.fallback();
+    waiting = true;
+    await gate;
+    await route.continue();
+  });
+  try {
+    await page.getByRole("link", { name: "审计日志", exact: true }).click();
+    await expect.poll(() => waiting).toBe(true);
+    await expect(page.getByRole("progressbar", { name: "正在切换页面", exact: true })).toBeVisible({ timeout: 1500 });
+    await expect(page.getByRole("status", { name: "正在加载审计日志", exact: true })).toBeVisible();
+  } finally { release(); }
+  await expect(page.getByRole("heading", { name: "审计日志", exact: true })).toBeVisible();
+  await expect(page.getByRole("progressbar", { name: "正在切换页面", exact: true })).toHaveCount(0);
+});
+
+test("地图页面切换复用原地图，并显示目标面板的既有骨架", async ({ page }) => {
+  await prepare(page);
+  await page.route("**/ows?**", (route) => route.fulfill({ json: { type: "FeatureCollection", features: [] } }));
+  await page.route("**/api/v1/scada-devices", (route) => route.fulfill({ json: [] }));
+  await page.goto("/network-simulation");
+  const map = page.locator(".ol-viewport").first();
+  await expect(map).toBeVisible({ timeout: 60_000 });
+  await map.evaluate((element) => element.setAttribute("data-navigation-map", "original"));
+  let release: () => void = () => {};
+  const gate = new Promise<void>((resolve) => { release = resolve; });
+  await page.route("**/scada-data-cleaning?*", async (route) => {
+    if (route.request().headers().rsc !== "1") return route.fallback();
+    await gate;
+    await route.continue();
+  });
+  try {
+    await page.getByRole("link", { name: "SCADA 数据清洗", exact: true }).click();
+    await expect(page.getByRole("status", { name: "正在加载数据清洗", exact: true })).toBeVisible();
+    await expect(page.locator('[data-navigation-map="original"]')).toBeVisible();
+    await expect(page.locator("[data-map-page-content]")).toHaveCSS("display", "none");
+    await page.screenshot({ path: "test-results/navigation-map-skeleton.png" });
+  } finally { release(); }
+  await expect(page).toHaveURL(/\/scada-data-cleaning$/);
+  await expect(page.locator("[data-map-page-content]")).toHaveCSS("display", "contents");
+  await expect(page.locator('[data-navigation-map="original"]')).toBeVisible();
+  await expect(page.getByRole("progressbar", { name: "正在切换页面", exact: true })).toHaveCount(0);
+  await page.goBack();
+  await expect(page).toHaveURL(/\/network-simulation$/);
+  await expect(page.locator('[data-navigation-map="original"]')).toBeVisible();
+  await expect(page.getByRole("progressbar", { name: "正在切换页面", exact: true })).toHaveCount(0);
+});
+
+test("移动端收起菜单后仍显示页面切换反馈，窄屏无溢出", async ({ page }) => {
+  await prepare(page);
+  await page.setViewportSize({ width: 375, height: 812 });
+  await page.goto("/system-admin");
+  await page.getByRole("button", { name: "open drawer", exact: true }).click();
+  let release: () => void = () => {};
+  const gate = new Promise<void>((resolve) => { release = resolve; });
+  await page.route("**/audit-logs?*", async (route) => {
+    if (route.request().headers().rsc !== "1") return route.fallback();
+    await gate;
+    await route.continue();
+  });
+  try {
+    await page.getByRole("link", { name: "审计日志", exact: true }).click();
+    for (const width of [375, 320]) {
+      await page.setViewportSize({ width, height: 812 });
+      await expect(page.getByRole("progressbar", { name: "正在切换页面", exact: true })).toBeVisible();
+      await expect(page.getByRole("status", { name: "正在加载审计日志", exact: true })).toBeVisible();
+      expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true);
+      await page.screenshot({ path: `test-results/navigation-mobile-${width}.png` });
+    }
+  } finally { release(); }
+  await expect(page.getByRole("heading", { name: "审计日志", exact: true })).toBeVisible();
+  await expect(page.getByRole("progressbar", { name: "正在切换页面", exact: true })).toHaveCount(0);
+});

e2e/scada-history-zoom.spec.ts

@@ -0,0 +1,63 @@
+import { expect, test } from "@playwright/test";
+
+import { mockBackend } from "./support/mockBackend";
+
+test("地图缩放不会重新请求已打开的 SCADA 历史数据", async ({ page }) => {
+  await mockBackend(page);
+
+  await page.route("**/ows?**", (route) =>
+    route.fulfill({
+      contentType: "application/json",
+      body: JSON.stringify({
+        type: "FeatureCollection",
+        features: [
+          {
+            type: "Feature",
+            id: "S-1",
+            properties: {
+              id: "S-1",
+              device_type: "pressure",
+              reliability: 0.95,
+              transmission_frequency: "00:15:00",
+            },
+            geometry: { type: "Point", coordinates: [13530000, 3620000] },
+          },
+        ],
+      }),
+    }),
+  );
+  await page.route("**/api/v1/scada-devices", (route) =>
+    route.fulfill({
+      contentType: "application/json",
+      body: JSON.stringify([
+        { device_id: "S-1", device_type: "pressure", node_id: "J-1", link_id: null },
+      ]),
+    }),
+  );
+
+  let historyRequests = 0;
+  await page.route("**/api/v1/timeseries/views/element-history/query", (route) => {
+    historyRequests += 1;
+    return route.fulfill({
+      contentType: "application/json",
+      body: JSON.stringify({ series: [] }),
+    });
+  });
+
+  await page.goto("/network-simulation");
+  await page.getByText("S-1", { exact: true }).click();
+  await expect(page.getByText("SCADA 历史数据")).toBeVisible();
+  await expect.poll(() => historyRequests).toBe(1);
+
+  const zoomLabel = page.getByText(/缩放: \d+\.\d/);
+  const initialZoom = await zoomLabel.textContent();
+  // The history drawer covers the map controls. Invoke their real handlers
+  // without targeting a covered screen coordinate.
+  await page.getByRole("button", { name: "放大" }).evaluate((button: HTMLButtonElement) => button.click());
+  await expect(zoomLabel).not.toHaveText(initialZoom!);
+  expect(historyRequests).toBe(1);
+
+  await page.getByRole("button", { name: "缩小" }).evaluate((button: HTMLButtonElement) => button.click());
+  await expect(zoomLabel).toHaveText(initialZoom!);
+  expect(historyRequests).toBe(1);
+});

e2e/three-dimensional-camera.spec.ts

@@ -4,6 +4,41 @@ import { mockBackend } from "./support/mockBackend";
 
 test.setTimeout(180_000);
 
+test("首次加载和失败提示位于工具面板上方，窄屏可直接重试", async ({ page }) => {
+  await mockBackend(page);
+  await page.addInitScript(() => {
+    localStorage.setItem("active_project", "playwright-project");
+    localStorage.setItem("MAP_WORKSPACE", "zjb");
+    localStorage.setItem("NETWORK_NAME", "zjb");
+  });
+  let release: () => void = () => {};
+  const pending = new Promise<void>((resolve) => { release = resolve; });
+  const failedModel = "**/models/detail_roof.glb*";
+  await page.route(failedModel, async (route) => { await pending; await route.abort("failed"); });
+  await page.goto("/three-dimensional-scene");
+  const scene = page.frameLocator('iframe[title="高铁湛江北站供水系统三维场景"]');
+  await expect(scene.locator("#boot-title")).toHaveText("正在载入场景资源 9 / 10", { timeout: 60_000 });
+  const loadingMaterial = await scene.locator(".boot-panel").evaluate((element) => ({
+    background: getComputedStyle(element).backgroundImage,
+    blur: getComputedStyle(element).backdropFilter,
+  }));
+  for (const width of [1280, 375, 320]) {
+    await page.setViewportSize({ width, height: 800 });
+    expect(await page.evaluate(() => document.elementFromPoint(innerWidth / 2, innerHeight / 2)?.tagName)).toBe("IFRAME");
+    await page.screenshot({ path: `test-results/scene-host-loading-${width}.png` });
+  }
+  release();
+  await expect(scene.locator("#boot-title")).toHaveText("场景资源加载失败");
+  await page.unroute(failedModel);
+  await scene.getByRole("button", { name: "重新载入场景" }).click();
+  await expect(scene.locator("#boot")).toBeHidden({ timeout: 60_000 });
+  await expect(page.getByRole("slider", { name: /建筑背景透明度/ })).toBeEnabled();
+  expect(await page.getByLabel("三维场景控制面板").evaluate((element) => ({
+    background: getComputedStyle(element).backgroundImage,
+    blur: getComputedStyle(element).backdropFilter,
+  }))).toEqual(loadingMaterial);
+});
+
 type CameraProbe = {
   active: string | null;
   position: number[];

e2e/three-dimensional-loading.spec.ts

@@ -0,0 +1,304 @@
+import { expect, test } from "@playwright/test";
+
+const root = "/three-dimensional/zjb/v29/";
+const preview = root + "preview.html?host=platform2&v=36-resumable-cache";
+const isAsset = (url: string) => /\.glb(?:\?|$)|water-network-v28\.json/.test(url);
+
+test.setTimeout(120_000);
+
+test("HTTP 200 的错误元数据不会进入缓存，服务器恢复后重试成功", async ({ page }) => {
+  let requests = 0;
+  await page.route("**/water-network-v28.json*", async (route) => {
+    requests++;
+    if (requests === 1) return route.fulfill({ json: { error: "temporary proxy failure" } });
+    return route.continue();
+  });
+  await page.goto(preview);
+  await expect(page.locator("#boot")).toHaveAttribute("data-state", "error", { timeout: 60_000 });
+  const cached = await page.evaluate((base) => new Promise((resolve, reject) => {
+    const request = indexedDB.open("tjwater-scene-assets-v1", 1);
+    request.onerror = () => reject(request.error);
+    request.onsuccess = () => {
+      const database = request.result;
+      const read = database.transaction("resources").objectStore("resources").get(new URL(base + "water-network-v28.json", location.origin).href);
+      read.onsuccess = () => { resolve(Boolean(read.result)); database.close(); };
+      read.onerror = () => { reject(read.error); database.close(); };
+    };
+  }), root);
+  expect(cached).toBe(false);
+  await page.getByRole("button", { name: "重新载入场景" }).click();
+  await expect(page.locator("#boot")).toBeHidden({ timeout: 60_000 });
+  expect(requests).toBe(5);
+});
+
+test("模型和元数据跨页面复用持久缓存，即使服务器资源不可用也能重开场景", async ({ page, context }) => {
+  const requests: string[] = [];
+  let block = false;
+  // Routing disables HTTP cache, so this checks IndexedDB rather than browser HTTP caching.
+  await context.route("**/three-dimensional/**", (route) => {
+    if (isAsset(route.request().url())) {
+      requests.push(route.request().url());
+      if (block) return route.abort("failed");
+    }
+    return route.continue();
+  });
+  const coldStart = Date.now();
+  await page.goto(preview);
+  await expect(page.locator("#boot")).toBeHidden({ timeout: 60_000 });
+  const coldMs = Date.now() - coldStart;
+  expect(new Set(requests).size).toBe(10);
+  requests.length = 0;
+  block = true;
+  await page.close();
+  const reopened = await context.newPage();
+  const warmStart = Date.now();
+  await reopened.goto(preview);
+  await expect(reopened.locator("#boot")).toBeHidden({ timeout: 60_000 });
+  expect(await reopened.evaluate(() =>
+    (window as typeof window & { webQA: { camera: { active: string } } }).webQA.camera.active,
+  )).toBe("overview");
+  expect(requests).toEqual([]);
+  console.log(JSON.stringify({ coldMs, warmMs: Date.now() - warmStart, warmAssetRequests: requests.length }));
+});
+
+test("首次载入显示真实进度，失败保留提示，重试可以恢复", async ({ page }) => {
+  let release: () => void = () => {};
+  const pending = new Promise<void>((resolve) => { release = resolve; });
+  const failedModel = "**/models/detail_roof.glb*";
+  await page.route(failedModel, async (route) => { await pending; await route.abort("failed"); });
+  await page.goto(preview);
+  await expect(page.locator("#boot-title")).toHaveText("正在载入场景资源 9 / 10", { timeout: 60_000 });
+  await expect(page.getByRole("progressbar")).toHaveAttribute("value", "9");
+  await expect(page.locator("#boot-detail")).toContainText(/已读取 \d+\.\d MB/);
+  await page.screenshot({ path: "test-results/scene-loading-desktop.png" });
+  await page.setViewportSize({ width: 320, height: 640 });
+  await page.screenshot({ path: "test-results/scene-loading-mobile.png" });
+  expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true);
+  release();
+  await expect(page.locator("#boot-title")).toHaveText("场景资源加载失败");
+  await expect(page.locator("#boot-detail")).toContainText("detail_roof.glb");
+  await expect(page.locator("#boot")).toHaveAttribute("aria-busy", "false");
+  await expect(page.getByRole("button", { name: "重新载入场景" })).toBeVisible();
+  await page.screenshot({ path: "test-results/scene-loading-error.png" });
+  await page.unroute(failedModel);
+  await page.getByRole("button", { name: "重新载入场景" }).click();
+  await expect(page.locator("#boot")).toBeHidden({ timeout: 60_000 });
+});
+
+test("同一资源合并并发请求，摘要改变后重新下载并覆盖旧缓存", async ({ page }) => {
+  let requests = 0;
+  await page.route("**/cache-probe.json*", (route) => {
+    requests++;
+    return route.fulfill({ json: { revision: new URL(route.request().url()).searchParams.get("v") } });
+  });
+  await page.goto(root + "manifest.json");
+  const result = await page.evaluate(async (base) => {
+    const moduleUrl = base + "resourceCache.mjs";
+    const { createSceneResourceCache } = await import(moduleUrl);
+    const cache = createSceneResourceCache(location.origin + base);
+    const decode = (data: ArrayBuffer) => JSON.parse(new TextDecoder().decode(data));
+    const first = await Promise.all([
+      cache.load("cache-probe.json", "first", decode),
+      cache.load("cache-probe.json", "first", decode),
+    ]);
+    const updated = await cache.load("cache-probe.json", "second", decode);
+    const freshClient = createSceneResourceCache(location.origin + base);
+    const cached = await freshClient.load("cache-probe.json", "second", decode);
+    return { first, updated, cached };
+  }, root);
+  expect(requests).toBe(2);
+  expect(result.first).toEqual([{ revision: "first" }, { revision: "first" }]);
+  expect(result.updated).toEqual({ revision: "second" });
+  expect(result.cached).toEqual({ revision: "second" });
+});
+
+for (const failure of ["denied", "quota"] as const) {
+  test(`浏览器缓存${failure === "denied" ? "被禁用" : "空间不足"}时仍可下载并解析资源`, async ({ page }) => {
+    await page.goto(root + "manifest.json");
+    await page.route("**/cache-probe.json*", (route) => route.fulfill({ json: { ok: true } }));
+    const result = await page.evaluate(async ({ base, failure }) => {
+      if (failure === "denied") {
+        Object.defineProperty(window, "indexedDB", { get() { throw new Error("denied"); } });
+      } else {
+        const transaction = IDBDatabase.prototype.transaction;
+        IDBDatabase.prototype.transaction = function (...args: Parameters<typeof transaction>) {
+          if (args[1] === "readwrite") throw new DOMException("Full", "QuotaExceededError");
+          return transaction.apply(this, args);
+        };
+      }
+      const moduleUrl = base + "resourceCache.mjs";
+      const { createSceneResourceCache } = await import(moduleUrl);
+      const cache = createSceneResourceCache(location.origin + base);
+      return cache.load("cache-probe.json", "first", (data: ArrayBuffer) => JSON.parse(new TextDecoder().decode(data)));
+    }, { base: root, failure });
+    expect(result).toEqual({ ok: true });
+  });
+}
+
+test("HTTP 错误和解析失败不会写入缓存，下一次请求可恢复", async ({ page }) => {
+  let requests = 0;
+  await page.route("**/cache-probe.json*", (route) => {
+    requests++;
+    return requests === 1
+      ? route.fulfill({ status: 404, body: "not found" })
+      : requests === 2
+        ? route.fulfill({ body: "invalid json" })
+        : route.fulfill({ json: { ok: true } });
+  });
+  await page.goto(root + "manifest.json");
+  const result = await page.evaluate(async (base) => {
+    const moduleUrl = base + "resourceCache.mjs";
+    const { createSceneResourceCache } = await import(moduleUrl);
+    const cache = createSceneResourceCache(location.origin + base);
+    const decode = (data: ArrayBuffer) => JSON.parse(new TextDecoder().decode(data));
+    const errors: string[] = [];
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try { await cache.load("cache-probe.json", "first", decode); }
+      catch (error) { errors.push(String(error)); }
+    }
+    return { errors, recovered: await cache.load("cache-probe.json", "first", decode) };
+  }, root);
+  expect(requests).toBe(3);
+  expect(result.errors).toHaveLength(2);
+  expect(result.errors[0]).toContain("HTTP 404");
+  expect(result.recovered).toEqual({ ok: true });
+});
+
+test("公网整文件中断时分段下载，重试失败分段并缓存完整模型", async ({ page }) => {
+  const { readFile } = await import("node:fs/promises");
+  const { createHash } = await import("node:crypto");
+  const bytes = await readFile("public/three-dimensional/zjb/v29/models/detail_interior.glb");
+  const ranges: string[] = [];
+  let interrupted = false;
+  await page.route("**/models/detail_interior.glb*", async (route) => {
+    const range = route.request().headers().range;
+    ranges.push(range ?? "whole-file");
+    // The public proxy drops whole-file responses, and one partial request drops too.
+    if (!range) return route.abort("failed");
+    if (range.startsWith("bytes=1048576-") && !interrupted) {
+      interrupted = true;
+      return route.abort("failed");
+    }
+    const match = /^bytes=(\d+)-(\d+)$/.exec(range)!;
+    const start = Number(match[1]);
+    const end = Math.min(Number(match[2]), bytes.length - 1);
+    return route.fulfill({ status: 206, headers: {
+      "content-type": "model/gltf-binary",
+      "content-range": `bytes ${start}-${end}/${bytes.length}`,
+    }, body: bytes.subarray(start, end + 1) });
+  });
+  await page.goto(root + "manifest.json");
+  const result = await page.evaluate(async (base) => {
+    const { createSceneResourceCache } = await import(base + "resourceCache.mjs");
+    const load = () => createSceneResourceCache(location.origin + base).load("models/detail_interior.glb", "range-recovery");
+    const data = await load();
+    const cached = await load();
+    return { length: data.byteLength, cachedLength: cached.byteLength,
+      sha256: Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", data)), n => n.toString(16).padStart(2, "0")).join("") };
+  }, root);
+  expect(result).toEqual({ length: bytes.length, cachedLength: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") });
+  expect(ranges).toHaveLength(7);
+  expect(ranges[0]).toBe("bytes=0-1048575");
+  expect(ranges[1]).toBe(ranges[2]);
+  expect(interrupted).toBe(true);
+});
+
+for (const fault of ["offset", "total", "truncated", "whole-response"] as const) {
+  test(`无效分段响应 ${fault} 不会进入缓存，恢复后可重新下载`, async ({ page }) => {
+    const bytes = Buffer.alloc(1048576 + 16, 7);
+    let broken = true;
+    let requests = 0;
+    await page.route("**/range-probe.bin*", (route) => {
+      requests++;
+      const range = route.request().headers().range;
+      if (!range) return route.abort("failed");
+      const match = /^bytes=(\d+)-(\d+)$/.exec(range)!;
+      const start = Number(match[1]);
+      const end = Math.min(Number(match[2]), bytes.length - 1);
+      if (broken && start > 0 && fault === "whole-response") return route.fulfill({ body: bytes });
+      return route.fulfill({ status: 206, headers: {
+        "content-range": `bytes ${broken && start > 0 && fault === "offset" ? 0 : start}-${end}/${bytes.length + (broken && start > 0 && fault === "total" ? 1 : 0)}`,
+      }, body: bytes.subarray(start, end + (broken && start > 0 && fault === "truncated" ? 0 : 1)) });
+    });
+    await page.goto(root + "manifest.json");
+    const failed = await page.evaluate(async (base) => {
+      const { createSceneResourceCache } = await import(base + "resourceCache.mjs");
+      try { await createSceneResourceCache(location.origin + base).load("range-probe.bin", "first"); return false; }
+      catch { return true; }
+    }, root);
+    expect(failed).toBe(true);
+    const before = requests;
+    broken = false;
+    const length = await page.evaluate(async (base) => {
+      const { createSceneResourceCache } = await import(base + "resourceCache.mjs");
+      return (await createSceneResourceCache(location.origin + base).load("range-probe.bin", "first")).byteLength;
+    }, root);
+    expect(length).toBe(bytes.length);
+    // The valid first segment survives; only the rejected final segment is fetched again.
+    expect(requests - before).toBe(1);
+  });
+}
+
+test("下载中断后刷新页面，从已保存的分段继续下载", async ({ page }) => {
+  const bytes = Buffer.alloc(2 * 1048576 + 16, 9);
+  let disconnected = true;
+  const ranges: string[] = [];
+  await page.route("**/resume-probe.bin*", (route) => {
+    const range = route.request().headers().range;
+    ranges.push(range ?? "whole-file");
+    if (!range) return route.abort("failed");
+    const match = /^bytes=(\d+)-(\d+)$/.exec(range)!;
+    const start = Number(match[1]);
+    const end = Math.min(Number(match[2]), bytes.length - 1);
+    if (disconnected && start > 0) return route.abort("failed");
+    return route.fulfill({ status: 206, headers: { "content-range": `bytes ${start}-${end}/${bytes.length}` }, body: bytes.subarray(start, end + 1) });
+  });
+  await page.goto(root + "manifest.json");
+  const load = (base: string) => page.evaluate(async (base) => {
+    const { createSceneResourceCache } = await import(base + "resourceCache.mjs");
+    try {
+      const data = await createSceneResourceCache(location.origin + base).load("resume-probe.bin", "first");
+      return { length: data.byteLength, failed: false };
+    } catch { return { failed: true }; }
+  }, base);
+  expect(await load(root)).toEqual({ failed: true });
+  expect(ranges.filter(range => range === "bytes=1048576-2097151")).toHaveLength(3);
+  disconnected = false;
+  ranges.length = 0;
+  await page.reload();
+  expect(await load(root)).toEqual({ length: bytes.length, failed: false });
+  expect(ranges).toEqual(["bytes=1048576-2097151", "bytes=2097152-2097167"]);
+});
+
+test("临时 HTTP 503 自动重试，成功后才写入缓存", async ({ page }) => {
+  let requests = 0;
+  await page.route("**/retry-probe.json*", (route) => {
+    requests++;
+    return requests < 3 ? route.fulfill({ status: 503, body: "unavailable" }) : route.fulfill({ json: { ok: true } });
+  });
+  await page.goto(root + "manifest.json");
+  const result = await page.evaluate(async (base) => {
+    const { createSceneResourceCache } = await import(base + "resourceCache.mjs");
+    const stages: string[] = [];
+    const cache = createSceneResourceCache(location.origin + base, ({ stage }: { stage: string }) => stages.push(stage));
+    const data = await cache.load("retry-probe.json", "first", (data: ArrayBuffer) => JSON.parse(new TextDecoder().decode(data)));
+    return { data, retries: stages.filter(stage => stage === "retry").length };
+  }, root);
+  expect(result).toEqual({ data: { ok: true }, retries: 2 });
+  expect(requests).toBe(3);
+});
+
+test("服务器返回空的完整响应时只解析一次，不循环下载", async ({ page }) => {
+  let requests = 0;
+  await page.route("**/empty-probe.json*", (route) => { requests++; return route.fulfill({ body: "" }); });
+  await page.goto(root + "manifest.json");
+  const failed = await page.evaluate(async (base) => {
+    const { createSceneResourceCache } = await import(base + "resourceCache.mjs");
+    try {
+      await createSceneResourceCache(location.origin + base).load("empty-probe.json", "first", (data: ArrayBuffer) => JSON.parse(new TextDecoder().decode(data)));
+      return false;
+    } catch { return true; }
+  }, root);
+  expect(failed).toBe(true);
+  expect(requests).toBe(1);
+});

public/three-dimensional/zjb/v29/camera-navigation.mjs

@@ -76,7 +76,7 @@ export function createCameraNavigation({camera,controls,model,networkRoot,root,s
    flight={start:performance.now(),from:camera.position.clone(),targetFrom:controls.target.clone(),to:new THREE.Vector3(...pose.position),targetTo:new THREE.Vector3(...pose.target)};
    if(matchMedia('(prefers-reduced-motion: reduce)').matches){camera.position.copy(flight.to);controls.target.copy(flight.targetTo);flight=null;controls.update();}
    emit(p.note??'已保存的相机位置');
-  }catch(e){if(token===request)emit('视角加载失败：'+e.message);}
+  }catch(e){if(token===request)emit('视角加载失败：'+e.message);throw e;}
  }
  function tick(now){if(!flight)return;const t=Math.min(1,(now-flight.start)/500),v=t*t*(3-2*t);camera.position.lerpVectors(flight.from,flight.to,v);controls.target.lerpVectors(flight.targetFrom,flight.targetTo,v);if(t===1)flight=null;}
  function save(label){label=label.trim();if(!label||label.length>24)throw Error('请输入 1–24 字的视角名称。');if(saved.length>=8)throw Error('最多保存 8 个视角，请先移除不用的视角。');const p={id:'saved-'+Date.now(),label,mode:getMode(),displayMode:getDisplayMode(),position:camera.position.toArray(),target:controls.target.toArray(),up:camera.up.toArray(),context:root.visible,roof:root.children.filter(o=>/roof|ceiling/.test(o.userData.resourceId)).every(o=>o.visible)};p.layers=Object.fromEntries(root.children.map(o=>[o.userData.resourceId,o.visible]));const next=[...saved,p];localStorage.setItem(key,JSON.stringify(next));saved=next;active=p.id;emit('视角已保存在本机浏览器');}

public/three-dimensional/zjb/v29/integration.mjs

@@ -1,5 +1,14 @@
 // Framework-independent data adapter. Does not parse or modify the project's INP.
 export const CAD_ORIGIN=Object.freeze([513800,2344450]);
+// This decoder runs before IDB writes, including when checking an existing entry.
+// A parseable HTTP 200 error response must not become a permanent model cache.
+export function parseNetworkMetadata(data,modelId){
+ const model=JSON.parse(new TextDecoder().decode(data));
+ const arrays=['nodes','links','pipeInstances','nodeInstances','bendInstances','cadEquipmentBindings','pumpEntityBindings','cadAttachments'];
+ const objects=['layouts','connectivity','coordination','coordinatedLayouts','verticalCoordination'];
+ if(!model||model.modelId!==modelId||!arrays.every(key=>Array.isArray(model[key]))||!objects.every(key=>model[key]&&typeof model[key]==='object'&&!Array.isArray(model[key]))||!model.nodes.length||!model.links.length)throw Error('管网元数据格式无效，请重新载入场景。');
+ return model;
+}
 export function cadToGltf(point,displayZ=0){
  if(!Array.isArray(point)||point.length<2||!point.slice(0,2).every(Number.isFinite)||!Number.isFinite(displayZ))throw Error('Expected finite CAD XY and an explicit display height.');
  return [point[0]-CAD_ORIGIN[0],displayZ,-(point[1]-CAD_ORIGIN[1])];

public/three-dimensional/zjb/v29/loadingProgress.mjs

@@ -0,0 +1,61 @@
+const boot = document.getElementById('boot');
+const title = document.getElementById('boot-title');
+const detail = document.getElementById('boot-detail');
+const progress = document.getElementById('boot-progress');
+const retry = document.getElementById('boot-retry');
+const formatBytes = bytes => (bytes / 1024 / 1024).toFixed(1) + ' MB';
+let entries = new Map();
+let failed = false;
+let lastPaint = 0;
+
+export function beginLoading(files, message = '正在载入三维场景') {
+ entries = new Map(files.map(file => [file, {stage:'waiting', loaded:0, total:0}]));
+ failed = false;
+ boot.hidden = false;
+ boot.dataset.state = 'loading';
+ boot.setAttribute('aria-busy', 'true');
+ title.textContent = message;
+ detail.textContent = '正在检查本地资源缓存';
+ progress.hidden = false;
+ progress.removeAttribute('value');
+ retry.hidden = true;
+ lastPaint = 0;
+}
+
+export function reportProgress(update) {
+ if (failed || !entries.has(update.file)) return;
+ entries.set(update.file, update);
+ // Large streamed files can emit hundreds of chunks in a frame.
+ if (update.stage === 'download' && performance.now() - lastPaint < 100) return;
+ lastPaint = performance.now();
+ const values = [...entries.values()];
+ const done = values.filter(item => item.stage === 'ready').length;
+ const loaded = values.reduce((sum, item) => sum + item.loaded, 0);
+ const cached = values.filter(item => item.stage === 'cache').length;
+ const retrying = values.some(item => item.stage === 'retry');
+ const parsing = values.some(item => item.stage === 'parse');
+ const downloading = values.some(item => item.stage === 'download');
+ progress.max = Math.max(1, values.length);
+ progress.value = done;
+ title.textContent = `正在载入场景资源 ${done} / ${values.length}`;
+ detail.textContent = `${retrying ? '连接中断，正在从断点重试' : parsing ? '正在解析模型' : downloading ? '正在下载资源' : cached ? '正在读取本地缓存' : '正在准备场景'} · 已读取 ${formatBytes(loaded)}`;
+}
+
+export function finishLoading() {
+ if (failed) return;
+ boot.setAttribute('aria-busy', 'false');
+ boot.hidden = true;
+}
+
+export function failLoading(error) {
+ failed = true;
+ boot.hidden = false;
+ boot.dataset.state = 'error';
+ boot.setAttribute('aria-busy', 'false');
+ title.textContent = '场景资源加载失败';
+ detail.textContent = '部分资源未能载入，请检查网络后重试。' + (error?.message ? '（' + error.message + '）' : '');
+ progress.hidden = true;
+ retry.hidden = false;
+}
+
+retry.addEventListener('click', () => window.location.reload());

public/three-dimensional/zjb/v29/manifest.json

@@ -17094,6 +17094,7 @@
     "id": "zjb-water-network-v23",
     "file": "models/water_network_v28.glb",
     "metadata": "water-network-v28.json",
+    "metadataSha256": "b9af91296f7f9269a51141b732ffb9fcd82906133eca75b96273a85f776c75f5",
     "sha256": "c3d16fd287a2e057649e3f25a939ff7edcc5f6b152c9dc09860bee7675912768",
     "runtimeInpRequired": false,
     "representationRevision": 28

public/three-dimensional/zjb/v29/preview.html

@@ -8,18 +8,36 @@
       html,body{width:100%;height:100%;margin:0;overflow:hidden;background:#e2e8e9}
       body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif}
       canvas{display:block;width:100%;height:100%;touch-action:none}
-      #boot{position:absolute;inset:0;z-index:2;display:grid;place-items:center;color:#526777;background:#e2e8e9;transition:opacity 180ms cubic-bezier(.16,1,.3,1)}
+      #boot{position:absolute;inset:0;z-index:2;display:grid;place-items:center;padding:16px;box-sizing:border-box;color:#334155;background:rgba(241,245,249,.38)}
       #boot[hidden]{display:none}
-      #boot span{display:flex;align-items:center;gap:10px;font-size:13px}
-      #boot i{width:18px;height:18px;border:2px solid rgba(37,125,212,.22);border-top-color:#257dd4;border-radius:50%;animation:spin .8s linear infinite}
+      .boot-panel{box-sizing:border-box;width:min(100%,360px);padding:24px;border-radius:16px;background:linear-gradient(135deg,rgba(255,255,255,.50),rgba(224,239,250,.28));backdrop-filter:blur(24px) saturate(170%) contrast(94%);-webkit-backdrop-filter:blur(24px) saturate(170%) contrast(94%);box-shadow:inset 0 1px 0 rgba(255,255,255,.88),inset 0 -1px 0 rgba(112,145,168,.18),0 18px 50px rgba(15,43,69,.20),0 0 0 1px rgba(255,255,255,.55)}
+      .boot-heading{display:flex;align-items:center;gap:10px;font-size:14px;font-weight:600;color:#0f172a}
+      #boot i{flex:none;width:18px;height:18px;border:2px solid rgba(37,125,212,.22);border-top-color:#257dd4;border-radius:50%;animation:spin .8s linear infinite}
+      #boot-detail{margin:12px 0 0;font-size:12px;line-height:1.75;overflow-wrap:anywhere}
+      #boot-progress{display:block;width:100%;height:6px;margin-top:20px;accent-color:#2563eb}
+      #boot-progress[hidden],#boot-retry[hidden]{display:none}
+      #boot-retry{min-height:40px;margin-top:16px;padding:0 16px;border:0;border-radius:8px;background:#2563eb;color:white;font:inherit;font-size:13px;cursor:pointer;transition:transform 150ms ease,background-color 150ms ease}
+      #boot-retry:hover{background:#1d4ed8}#boot-retry:active{transform:scale(.96)}#boot-retry:focus-visible{outline:2px solid #2563eb;outline-offset:3px}
+      #boot[data-state=error] i{animation:none;border-color:#dc2626;background:#fee2e2}
+      #boot[data-state=error] #boot-title{color:#991b1b}
       @keyframes spin{to{transform:rotate(360deg)}}
-      @media(prefers-reduced-motion:reduce){#boot i{animation:none;border-top-color:rgba(37,125,212,.22)}}
+      @media(prefers-reduced-motion:reduce){#boot i{animation:none;border-top-color:rgba(37,125,212,.22)}#boot-retry{transition:none}}
     </style>
     <script type="importmap">{"imports":{"three":"./vendor/three/three.module.js","three/addons/":"./vendor/three/addons/"}}</script>
   </head>
   <body>
-    <div id="boot" role="status"><span><i aria-hidden="true"></i>正在载入三维模型</span></div>
+    <div id="boot" role="status" aria-live="polite" aria-busy="true" data-state="loading">
+      <div class="boot-panel">
+        <div class="boot-heading"><i aria-hidden="true"></i><span id="boot-title">正在准备三维场景</span></div>
+        <p id="boot-detail">首次载入需要下载模型，后续将优先使用本地缓存。</p>
+        <progress id="boot-progress" aria-label="场景资源加载进度"></progress>
+        <button id="boot-retry" type="button" hidden>重新载入场景</button>
+      </div>
+    </div>
     <output id="qa" hidden></output>
-    <script type="module" src="./preview.mjs?v=34-detailed-network-context"></script>
+    <script type="module">
+      import {failLoading} from './loadingProgress.mjs?v=36-resumable-cache';
+      import('./preview.mjs?v=36-resumable-cache').catch(failLoading);
+    </script>
   </body>
 </html>

public/three-dimensional/zjb/v29/preview.mjs

@@ -1,18 +1,21 @@
 import {createRenderEffects} from './render-effects.mjs';
-import {createCameraNavigation,framePose} from './camera-navigation.mjs?v=31-camera-presets';
+import {createCameraNavigation,framePose} from './camera-navigation.mjs?v=36-resumable-cache';
+import {createSceneResourceCache} from './resourceCache.mjs?v=36-resumable-cache';
+import {beginLoading,reportProgress,finishLoading,failLoading} from './loadingProgress.mjs?v=36-resumable-cache';
 import {createAssetInspector} from './asset-inspector.mjs?v=29-platform2';
 import * as THREE from 'three';
 import {GLTFLoader} from 'three/addons/loaders/GLTFLoader.js';
 import {OrbitControls} from 'three/addons/controls/OrbitControls.js';
 import {MeshoptDecoder} from './vendor/meshopt_decoder.module.js';
 import {attachNetworkStyle,DEFAULT_STYLE} from './network-style.mjs?v=33-scada-markers';
-import {cadToGltf} from './integration.mjs';
+import {cadToGltf,parseNetworkMetadata} from './integration.mjs';
 import {createAppearance,enhanceMaterials,grain,applyBuildingContext} from './appearance.mjs?v=30-context-opacity';
 
 const HOST_CHANNEL='tjwater:zjb-scene',HOST_VERSION=2,PROJECT_CODE='zjb',MODEL_ID='zjb-water-network-v23';
 let net,networkRoot,networkStyle,navigation,inspector;
 let mode='network',generation=0,contextVisible=true,roofVisible=true;
 let sceneStatus='正在载入三维模型';
+let sceneReady=false;
 let cameraState={active:null,note:'正在准备观察位置',views:[]};
 let appearanceState={preset:'day',exposure:.95,contextOpacity:.4,shadows:true,effects:true,quality:'standard'};
 
@@ -41,7 +44,12 @@ window.webQA={errors:[],loaded:[],mode:'network',contextVisible};
 window.addEventListener('error',event=>{const message=String(event.message||'三维场景运行错误');window.webQA.errors.push(message);postHost('error',{message});});
 window.addEventListener('unhandledrejection',event=>{const message=String(event.reason||'三维场景异步任务失败');window.webQA.errors.push(message);postHost('error',{message});});
 
-const manifest=await (await fetch('./manifest.json',{cache:'no-store'})).json();
+const manifestResponse=await fetch('./manifest.json',{cache:'no-cache',signal:AbortSignal.timeout(30000)});
+if(!manifestResponse.ok)throw Error('场景清单加载失败：HTTP '+manifestResponse.status);
+const manifest=await manifestResponse.json();
+const resourceCache=createSceneResourceCache(import.meta.url,reportProgress);
+function startLoading(files){beginLoading(files);postHost('loading',{active:true});}
+function completeLoading(){finishLoading();postHost('loading',{active:false});}
 const viewport=()=>({width:Math.max(240,innerWidth),height:Math.max(240,innerHeight)});
 const initialViewport=viewport();
 const renderer=new THREE.WebGLRenderer({antialias:true,logarithmicDepthBuffer:false});
@@ -52,6 +60,7 @@ const controls=new OrbitControls(camera,renderer.domElement);
 const appearance=createAppearance(renderer,scene);
 const effects=createRenderEffects(renderer,scene,camera,initialViewport.width,initialViewport.height);
 const loader=new GLTFLoader().setMeshoptDecoder(MeshoptDecoder);
+const loadModel=asset=>resourceCache.load(asset.file,asset.sha256,data=>loader.parseAsync(data,new URL('./',new URL(asset.file,import.meta.url)).href));
 const cache=new Map(),root=new THREE.Group();scene.add(root);
 
 function isBuildingResource(resourceId=''){
@@ -86,11 +95,11 @@ async function load(id){
  if(!cache.has(id)){
   const asset=manifest.assets.find(item=>item.id===id);
   if(!asset)throw Error('场景清单中不存在资源：'+id);
-  cache.set(id,loader.loadAsync(asset.file).then(gltf=>{
+  cache.set(id,loadModel(asset).then(gltf=>{
    enhanceMaterials(gltf.scene);gltf.scene.userData.assetId=asset.logicalId??asset.assetId;gltf.scene.userData.resourceId=id;
    gltf.scene.traverse(object=>{if(object.isMesh)for(const material of Array.isArray(object.material)?object.material:[object.material])material.userData.original={opacity:material.opacity,transparent:material.transparent,depthWrite:material.depthWrite};});
    return gltf.scene;
-  }));
+  }).catch(error=>{cache.delete(id);throw error;}));
  }
  return cache.get(id);
 }
@@ -100,8 +109,14 @@ async function show(next,{frame=true}={}){
  if(next==='detail')ids=[...manifest.mapDefault.filter(id=>!['map_roof','map_facade'].includes(id)),'detail_roof','detail_facade','detail_interior','detail_ceiling'];
  if(next==='pump')ids=['detail_pump_walls','detail_pump_access','detail_pump_auxiliary','detail_pump_piping_reference',...manifest.assets.filter(asset=>asset.id.startsWith('physical_')).map(asset=>asset.id)];
  if(next==='meters')ids=['meter_dn150','valve_dn250','pump_symbol'];
+ if(sceneReady)startLoading(ids.map(id=>manifest.assets.find(asset=>asset.id===id).file));
  setStatus('正在载入 '+ids.length+' 组场景资源');
- const objects=await Promise.all(ids.map(load));if(token!==generation)return;
+ let objects;
+ try{objects=await Promise.all(ids.map(async id=>{
+  const object=await load(id);const asset=manifest.assets.find(item=>item.id===id);
+  reportProgress({file:asset.file,stage:'ready',loaded:asset.bytes,total:asset.bytes});return object;
+ }));}catch(error){if(token===generation){setStatus('场景资源加载失败，请重试');failLoading(error);postHost('loading',{active:false,failed:true});}throw error;}
+ if(token!==generation)return;
  root.clear();objects.forEach((object,index)=>{
   object.position.set(next==='meters'?index*1.5:0,0,0);object.visible=true;root.add(object);
   object.traverse(mesh=>{if(mesh.isMesh)for(const material of Array.isArray(mesh.material)?mesh.material:[mesh.material])applyBuildingContext(material,['network','hydraulic'].includes(next),appearanceState.contextOpacity);});
@@ -110,6 +125,7 @@ async function show(next,{frame=true}={}){
  networkStyle?.setFocusScope(next==='hydraulic');applyVisibility();inspector?.highlight();if(frame)fit();
  window.webQA.loaded=ids;window.webQA.mode=next;
  setStatus(next==='pump'?'六泵实体与 CAD 管路参考，接口配准待核':next==='meters'?'设备样件，主管不包含在样件内':['network','hydraulic'].includes(next)?'管网实体模型，建筑为透明背景':'已载入 '+ids.length+' 组场景资源');
+ completeLoading();
 }
 function updateStyle(){appearance.refresh();inspector?.refresh();window.webQA.networkStyle={...networkStyle.summary,style:networkStyle.style};postState();}
 function setDisplayMode(value){networkStyle.setDisplayMode(value);navigation?.stop();updateStyle();}
@@ -161,8 +177,9 @@ renderer.setAnimationLoop(()=>{
  effects.render(mode);window.webQA.drawCalls=renderer.info.render.calls;window.webQA.triangles=renderer.info.render.triangles;window.webQA.camera={active:cameraState.active,position:camera.position.toArray(),target:controls.target.toArray(),up:camera.up.toArray()};document.getElementById('qa').textContent=JSON.stringify(window.webQA);
 });
 
-net=await (await fetch(manifest.networkModel.metadata,{cache:'no-store'})).json();
-const built=await loader.loadAsync(manifest.networkModel.file+'?v='+manifest.networkModel.sha256);networkRoot=built.scene;enhanceMaterials(networkRoot);scene.add(networkRoot);
+startLoading([manifest.networkModel.metadata,manifest.networkModel.file,...manifest.networkContext.map(id=>manifest.assets.find(asset=>asset.id===id).file)]);
+net=await resourceCache.load(manifest.networkModel.metadata,manifest.networkModel.metadataSha256,data=>parseNetworkMetadata(data,manifest.networkModel.id));
+const built=await loadModel(manifest.networkModel);networkRoot=built.scene;enhanceMaterials(networkRoot);scene.add(networkRoot);
 networkStyle=attachNetworkStyle(networkRoot,net);grain(networkStyle.pipes.material,{frequency:140,amplitude:.00004,variation:.08});
 try{const saved=localStorage.getItem('zjb-network-style-v24');if(saved)networkStyle.setStyle(JSON.parse(saved));}catch{}
 try{const quality=localStorage.getItem('zjb-render-quality-v27')??'standard';effects.setQuality(quality);appearanceState.quality=quality;}catch{effects.setQuality('standard');}
@@ -204,5 +221,6 @@ window.addEventListener('message',async event=>{
 });
 
 await navigation.visit('overview');
-document.getElementById('boot').hidden=true;
+sceneReady=true;
+completeLoading();
 postHost('ready',{nodeIds:net.nodes.map(node=>String(node.id)),linkIds:net.links.map(link=>String(link.id)),state:runtimeState()});

public/three-dimensional/zjb/v29/resourceCache.mjs

@@ -0,0 +1,188 @@
+// Only static scene assets enter this database. Live simulation/SCADA data do not.
+const DATABASE = 'tjwater-scene-assets-v1';
+const STORE = 'resources';
+const REQUEST_TIMEOUT_MS = 30_000;
+const CHUNK_BYTES = 1024 * 1024;
+const MAX_ATTEMPTS = 3;
+
+function openDatabase() {
+ return new Promise(resolve => {
+  let settled = false;
+  const finish = value => { if (!settled) { settled = true; resolve(value); } };
+  try {
+   const request = globalThis.indexedDB.open(DATABASE, 1);
+   request.onupgradeneeded = () => request.result.createObjectStore(STORE, {keyPath:'url'});
+   request.onerror = request.onblocked = () => finish(null);
+   request.onsuccess = () => {
+    const database = request.result;
+    if (settled) { database.close(); return; }
+    database.onversionchange = () => database.close();
+    finish(database);
+   };
+  } catch { finish(null); }
+ });
+}
+
+function transact(database, mode, operation) {
+ return new Promise((resolve, reject) => {
+  const transaction = database.transaction(STORE, mode);
+  const request = operation(transaction.objectStore(STORE));
+  transaction.oncomplete = () => resolve(request.result);
+  transaction.onerror = transaction.onabort = () => reject(transaction.error ?? request.error);
+ });
+}
+
+export function createSceneResourceCache(baseUrl, onProgress = () => {}) {
+ // Open lazily, after synchronous WebGL setup, so database callbacks can run promptly.
+ let database;
+ const pending = new Map();
+
+ async function read(file, revision, decode) {
+  const url = new URL(file, baseUrl);
+  const key = url.href;
+  const report = (stage, loaded = 0, total = 0) => onProgress({file, stage, loaded, total});
+  const storage = await (database ??= openDatabase());
+  if (storage && revision) {
+   try {
+    const entry = await transact(storage, 'readonly', store => store.get(key));
+    if (entry?.revision === revision && entry.data instanceof ArrayBuffer) {
+     report('cache', entry.data.byteLength, entry.data.byteLength);
+     const result = await decode(entry.data);
+     report('ready', entry.data.byteLength, entry.data.byteLength);
+     return result;
+    }
+   } catch { /* Unavailable or invalid cache: fetch a fresh copy below. */ }
+  }
+
+  // Revisioned URLs also keep the browser's HTTP cache in sync with the manifest.
+  if (revision) url.searchParams.set('v', revision);
+  const partialKey = key + '#partial';
+  let chunks = [], loaded = 0, total = 0;
+  if (storage && revision) {
+   try {
+    const partial = await transact(storage, 'readonly', store => store.get(partialKey));
+    if (partial?.revision === revision && Number.isSafeInteger(partial.total) && partial.total > 0 &&
+        Array.isArray(partial.chunks) && partial.chunks.length &&
+        partial.chunks.every(chunk => chunk instanceof ArrayBuffer && chunk.byteLength > 0 && chunk.byteLength <= CHUNK_BYTES)) {
+     const size = partial.chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+     if (size <= partial.total) { chunks = partial.chunks; loaded = size; total = partial.total; }
+    }
+   } catch { /* A denied partial cache does not prevent downloading. */ }
+  }
+
+  async function downloadPart() {
+   const controller = new AbortController();
+   let timer;
+   const resetTimeout = () => {
+    clearTimeout(timer);
+    timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+   };
+   resetTimeout();
+   try {
+    const end = total ? Math.min(loaded + CHUNK_BYTES, total) - 1 : loaded + CHUNK_BYTES - 1;
+    const response = await fetch(url, {signal:controller.signal, cache:'no-cache', headers:{Range:`bytes=${loaded}-${end}`}});
+    if (!response.ok) {
+     const error = Error('HTTP ' + response.status);
+     error.retryable = [408, 429, 500, 502, 503, 504].includes(response.status);
+     throw error;
+    }
+    let partTotal = 0, expected = 0;
+    if (response.status === 206) {
+     const range = /^bytes (\d+)-(\d+)\/(\d+)$/.exec(response.headers.get('content-range') ?? '');
+     const start = Number(range?.[1]), last = Number(range?.[2]);
+     partTotal = Number(range?.[3]);
+     if (!range || start !== loaded || last < start || last > end || last >= partTotal ||
+         !Number.isSafeInteger(partTotal) || (total && total !== partTotal)) {
+      throw Error('资源分段响应无效');
+     }
+     expected = last - start + 1;
+    } else {
+     if (loaded) throw Error('服务器未按断点返回资源');
+     // Servers without Range support can still return an ordinary complete response.
+     partTotal = Number(response.headers.get('content-length')) || 0;
+    }
+    const buffers = [];
+    let size = 0;
+    if (response.body) {
+     const reader = response.body.getReader();
+     try {
+      while (true) {
+       const {done, value} = await reader.read();
+       if (done) break;
+       buffers.push(value); size += value.byteLength;
+       if (expected && size > expected) throw Error('资源分段长度无效');
+       report('download', loaded + size, partTotal); resetTimeout();
+      }
+     } finally { await reader.cancel().catch(() => {}); }
+    } else {
+     const buffer = new Uint8Array(await response.arrayBuffer());
+     buffers.push(buffer); size = buffer.byteLength;
+    }
+    if (expected && size !== expected) throw Error('资源分段不完整');
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const buffer of buffers) { bytes.set(buffer, offset); offset += buffer.byteLength; }
+    return {data:bytes.buffer, total:response.status === 206 ? partTotal : size, ranged:response.status === 206};
+   } catch (error) {
+    controller.abort();
+    throw error;
+   } finally { clearTimeout(timer); }
+  }
+
+  report('download', loaded, total);
+  try {
+   while (!total || loaded < total) {
+    let part;
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+     try { part = await downloadPart(); break; }
+     catch (error) {
+      // Permanent HTTP/contract errors stop; temporary transport/server errors can recover.
+      if (!error.retryable && !(error instanceof TypeError) && error.name !== 'AbortError' && error.message !== '资源分段不完整') throw error;
+      if (attempt + 1 === MAX_ATTEMPTS) throw error;
+      report('retry', loaded, total);
+      await new Promise(resolve => setTimeout(resolve, 300 * (attempt + 1)));
+     }
+    }
+    chunks.push(part.data); loaded += part.data.byteLength; total = part.total;
+    if (storage && revision && part.ranged) {
+     try { await transact(storage, 'readwrite', store => store.put({url:partialKey, revision, total, chunks})); }
+     catch { /* Storage denied/full: retain the in-memory download. */ }
+    }
+    if (!part.ranged) break;
+   }
+  } catch (error) {
+   throw Error(file + '：' + (error.name === 'AbortError' ? '下载超时，请重试' : error.message));
+  }
+  const bytes = new Uint8Array(loaded);
+  let offset = 0;
+  for (const chunk of chunks) { bytes.set(new Uint8Array(chunk), offset); offset += chunk.byteLength; }
+  const data = bytes.buffer;
+  if (storage) {
+   try { await transact(storage, 'readwrite', store => store.delete(partialKey)); }
+   catch { /* Completed bytes can still be parsed when storage is unavailable. */ }
+  }
+
+  report('parse', data.byteLength, data.byteLength);
+  // Validate/parse before persisting so an HTML error page or bad GLB cannot poison the cache.
+  const result = await decode(data);
+  if (storage && revision) {
+   try {
+    // One entry per URL: a successful new revision replaces the old bytes.
+    await transact(storage, 'readwrite', store => store.put({url:key, revision, data}));
+   } catch { /* Storage denied/full must not prevent scene rendering. */ }
+  }
+  report('ready', data.byteLength, data.byteLength);
+  return result;
+ }
+
+ return {
+  load(file, revision, decode = data => data) {
+   const key = file + ':' + revision;
+   if (!pending.has(key)) {
+    const task = read(file, revision, decode).finally(() => pending.delete(key));
+    pending.set(key, task);
+   }
+   return pending.get(key);
+  },
+ };
+}

src/app/(main)/(map)/layout.tsx

@@ -3,7 +3,12 @@
 import type { ReactNode } from "react";
 
 import MapComponent from "@components/olmap/core/MapComponent";
+import { MapNavigationContent } from "@components/loading/NavigationFeedback";
 
 export default function MapLayout({ children }: { children: ReactNode }) {
-  return <MapComponent>{children}</MapComponent>;
+  return (
+    <MapComponent>
+      <MapNavigationContent>{children}</MapNavigationContent>
+    </MapComponent>
+  );
 }

src/app/(main)/(map)/loading.tsx

@@ -0,0 +1,11 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+import { MapRouteSkeleton } from "@components/loading/PageLoadingSkeleton";
+import { useNavigationFeedback } from "@components/loading/NavigationFeedback";
+
+export default function Loading() {
+  const pathname = usePathname();
+  const { pendingPath } = useNavigationFeedback();
+  return <MapRouteSkeleton pathname={pendingPath ?? pathname} />;
+}

src/app/(main)/layout.tsx

@@ -6,6 +6,10 @@ import authOptions from "@app/api/auth/[...nextauth]/options";
 import { Header } from "@components/header";
 import { Title } from "@components/title";
 import { AppSider } from "@components/sider/AppSider";
+import {
+  NavigationFeedbackProvider,
+  PageNavigationContent,
+} from "@components/loading/NavigationFeedback";
 import { ThemedLayout } from "@refinedev/mui";
 import { getServerSession } from "next-auth/next";
 import { redirect } from "next/navigation";
@@ -32,24 +36,26 @@ export default async function MainLayout({
   }
 
   return (
-    <ThemedLayout
-      Header={Header}
-      Title={Title}
-      Sider={AppSider}
-      childrenBoxProps={{
-        sx: {
-          flex: 1,
-          minHeight: 0,
-          overflow: "auto",
-          p: 0,
-        },
-      }}
-      containerBoxProps={{
-        sx: { height: "100vh", overflow: "hidden" },
-      }}
-    >
-      {children}
-    </ThemedLayout>
+    <NavigationFeedbackProvider>
+      <ThemedLayout
+        Header={Header}
+        Title={Title}
+        Sider={AppSider}
+        childrenBoxProps={{
+          sx: {
+            flex: 1,
+            minHeight: 0,
+            overflow: "hidden",
+            p: 0,
+          },
+        }}
+        containerBoxProps={{
+          sx: { height: "100vh", overflow: "hidden" },
+        }}
+      >
+        <PageNavigationContent>{children}</PageNavigationContent>
+      </ThemedLayout>
+    </NavigationFeedbackProvider>
   );
 }
 

src/app/(main)/loading.tsx

@@ -0,0 +1,5 @@
+import { PageLoadingSkeleton } from "@components/loading/PageLoadingSkeleton";
+
+export default function Loading() {
+  return <PageLoadingSkeleton />;
+}

src/app/(main)/three-dimensional-scene/page.tsx

@@ -1,17 +1,13 @@
 "use client";
 
 import dynamic from "next/dynamic";
-import { Box, CircularProgress } from "@mui/material";
+import { PageLoadingSkeleton } from "@components/loading/PageLoadingSkeleton";
 
 const ThreeDimensionalScene = dynamic(
   () => import("@components/threeDimensional/ThreeDimensionalScene"),
   {
     ssr: false,
-    loading: () => (
-      <Box sx={{ height: "100%", display: "grid", placeItems: "center" }}>
-        <CircularProgress size={32} />
-      </Box>
-    ),
+    loading: () => <PageLoadingSkeleton pathname="/three-dimensional-scene" />,
   },
 );
 

src/app/RefineContext.tsx

@@ -12,6 +12,7 @@ import { usePathname } from "next/navigation";
 import React, { useEffect } from "react";
 
 import routerProvider from "@refinedev/nextjs-router";
+import { NavigationLink } from "@components/loading/NavigationLink";
 
 import { ColorModeContextProvider } from "@contexts/color-mode";
 import { dataProvider } from "@providers/data-provider";
@@ -46,6 +47,8 @@ type RefineContextProps = {
   defaultMode?: string;
 };
 
+const appRouterProvider = { ...routerProvider, Link: NavigationLink };
+
 export const RefineContext = (
   props: React.PropsWithChildren<RefineContextProps>,
 ) => (
@@ -377,7 +380,7 @@ export const App = (props: React.PropsWithChildren<AppProps>) => {
         <ColorModeContextProvider defaultMode={props.defaultMode}>
           <RefineSnackbarProvider>
             <Refine
-              routerProvider={routerProvider}
+              routerProvider={appRouterProvider}
               dataProvider={dataProvider}
               notificationProvider={useAppNotificationProvider}
               authProvider={authProvider}

src/components/loading/NavigationFeedback.test.tsx

@@ -0,0 +1,78 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+
+import {
+  MapNavigationContent,
+  NavigationFeedbackProvider,
+  PageNavigationContent,
+  useNavigationFeedback,
+} from "./NavigationFeedback";
+import { mapSkeletonForPath } from "./PageLoadingSkeleton";
+import { MAP_SKELETON_VARIANTS } from "./mapComponentSkeletonConfig";
+
+let mockPathname = "/network-simulation";
+jest.mock("next/navigation", () => ({ usePathname: () => mockPathname }));
+
+function Harness() {
+  const { reportPending } = useNavigationFeedback();
+  return (
+    <>
+      <button onClick={() => reportPending("first", "/scada-data-cleaning", true)}>清洗</button>
+      <button onClick={() => reportPending("second", "/audit-logs", true)}>审计</button>
+      <button onClick={() => reportPending("first", "/scada-data-cleaning", false)}>取消旧导航</button>
+      <button onClick={() => reportPending("second", "/audit-logs", false)}>结束导航</button>
+      <PageNavigationContent>
+        <div data-testid="map">原有地图</div>
+        <MapNavigationContent><input aria-label="页面草稿" defaultValue="保留输入" /></MapNavigationContent>
+      </PageNavigationContent>
+    </>
+  );
+}
+
+describe("page navigation feedback", () => {
+  beforeEach(() => { mockPathname = "/network-simulation"; });
+
+  it("shows the destination skeleton while preserving the map and a cancelled page's draft", () => {
+    render(<NavigationFeedbackProvider><Harness /></NavigationFeedbackProvider>);
+    const map = screen.getByTestId("map");
+    const draft = screen.getByRole("textbox", { name: "页面草稿" });
+    fireEvent.click(screen.getByText("清洗"));
+    expect(screen.getByRole("status", { name: "正在加载数据清洗" })).toBeVisible();
+    expect(screen.getByTestId("map")).toBe(map);
+    expect(map).toBeVisible();
+    expect(draft).not.toBeVisible();
+    fireEvent.click(screen.getByText("取消旧导航"));
+    expect(draft).toBeVisible();
+    expect(draft).toHaveValue("保留输入");
+    expect(screen.queryByRole("progressbar", { name: "正在切换页面" })).not.toBeInTheDocument();
+  });
+
+  it("does not dismiss a newer destination when the previous link settles", () => {
+    render(<NavigationFeedbackProvider><Harness /></NavigationFeedbackProvider>);
+    fireEvent.click(screen.getByText("清洗"));
+    fireEvent.click(screen.getByText("审计"));
+    fireEvent.click(screen.getByText("取消旧导航"));
+    expect(screen.getByRole("status", { name: "正在加载审计日志" })).toBeVisible();
+    expect(screen.getByRole("progressbar", { name: "正在切换页面" })).toBeVisible();
+    fireEvent.click(screen.getByText("结束导航"));
+    expect(screen.queryByRole("status", { name: "正在加载审计日志" })).not.toBeInTheDocument();
+  });
+
+  it("hands off to route/component loading boundaries as soon as history commits", () => {
+    const { rerender } = render(<NavigationFeedbackProvider><Harness /></NavigationFeedbackProvider>);
+    fireEvent.click(screen.getByText("清洗"));
+    expect(screen.getByRole("progressbar", { name: "正在切换页面" })).toBeVisible();
+    mockPathname = "/scada-data-cleaning";
+    rerender(<NavigationFeedbackProvider><Harness /></NavigationFeedbackProvider>);
+    expect(screen.queryByRole("progressbar", { name: "正在切换页面" })).not.toBeInTheDocument();
+    expect(screen.getByRole("textbox", { name: "页面草稿" })).toBeVisible();
+  });
+
+  it("connects every existing map skeleton to its exact public route", () => {
+    const paths = [
+      "/network-simulation", "/scada-data-cleaning", "/health-risk-analysis", "/monitoring-place-optimization",
+      ...["burst-detection", "burst-location", "burst-simulation", "contaminant-simulation", "dma-leak-detection", "flushing-analysis"].map((name) => "/hydraulic-simulation/" + name),
+    ];
+    expect(paths.map(mapSkeletonForPath).sort()).toEqual([...MAP_SKELETON_VARIANTS].sort());
+    expect(mapSkeletonForPath("/system-admin")).toBeUndefined();
+  });
+});

src/components/loading/NavigationFeedback.tsx

@@ -0,0 +1,98 @@
+"use client";
+
+import { Box, LinearProgress } from "@mui/material";
+import { usePathname } from "next/navigation";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+
+import {
+  mapSkeletonForPath,
+  MapRouteSkeleton,
+  PageLoadingSkeleton,
+} from "./PageLoadingSkeleton";
+
+type PendingNavigation = { id: string; pathname: string };
+type NavigationFeedback = {
+  pendingPath: string | null;
+  reportPending: (id: string, pathname: string, pending: boolean) => void;
+};
+
+const NavigationContext = createContext<NavigationFeedback>({
+  pendingPath: null,
+  reportPending: () => {},
+});
+
+export const useNavigationFeedback = () => useContext(NavigationContext);
+
+export function NavigationFeedbackProvider({ children }: { children: ReactNode }) {
+  const pathname = usePathname();
+  const [navigation, setNavigation] = useState<PendingNavigation | null>(null);
+  const reportPending = useCallback((id: string, target: string, pending: boolean) => {
+    setNavigation((current) => {
+      if (!pending) return current?.id === id ? null : current;
+      return current?.id === id && current.pathname === target ? current : { id, pathname: target };
+    });
+  }, []);
+  // History commits can precede a page's lazy component. Its loading.tsx and
+  // dynamic fallback take over at that point, without an artificial delay.
+  const pendingPath = navigation && navigation.pathname !== pathname ? navigation.pathname : null;
+  const value = useMemo(() => ({ pendingPath, reportPending }), [pendingPath, reportPending]);
+  return (
+    <NavigationContext.Provider value={value}>
+      {children}
+    </NavigationContext.Provider>
+  );
+}
+
+export function PageNavigationContent({ children }: { children: ReactNode }) {
+  const pathname = usePathname();
+  const { pendingPath } = useNavigationFeedback();
+  const withinMap = Boolean(mapSkeletonForPath(pathname) && pendingPath && mapSkeletonForPath(pendingPath));
+  return (
+    <Box
+      data-page-navigation-content
+      aria-busy={Boolean(pendingPath)}
+      sx={{ position: "relative", height: "100%", minHeight: 0, overflow: "hidden" }}
+    >
+      <Box
+        data-page-scroll-content
+        inert={Boolean(pendingPath) && !withinMap}
+        aria-hidden={Boolean(pendingPath) && !withinMap}
+        sx={{ height: "100%", overflow: "auto" }}
+      >
+        {children}
+      </Box>
+      {pendingPath && (
+        <>
+          <LinearProgress
+            aria-label="正在切换页面"
+            sx={{ position: "absolute", top: 0, left: 0, right: 0, zIndex: 1401, height: 3 }}
+          />
+          {!withinMap && (
+            <Box sx={{ position: "absolute", inset: 0, zIndex: 1400, overflow: "hidden" }}>
+              <PageLoadingSkeleton pathname={pendingPath} />
+            </Box>
+          )}
+        </>
+      )}
+    </Box>
+  );
+}
+
+export function MapNavigationContent({ children }: { children: ReactNode }) {
+  const { pendingPath } = useNavigationFeedback();
+  return (
+    <>
+      <Box data-map-page-content sx={{ display: pendingPath ? "none" : "contents" }}>
+        {children}
+      </Box>
+      {pendingPath && <MapRouteSkeleton pathname={pendingPath} />}
+    </>
+  );
+}

src/components/loading/NavigationLink.tsx

@@ -0,0 +1,33 @@
+"use client";
+
+import type { RouterProvider } from "@refinedev/core";
+import Link, { useLinkStatus } from "next/link";
+import { forwardRef, useEffect, useId, type ComponentProps } from "react";
+
+import { useNavigationFeedback } from "./NavigationFeedback";
+
+function NavigationLinkStatus({ to }: { to: string }) {
+  const { pending } = useLinkStatus();
+  const { reportPending } = useNavigationFeedback();
+  const id = useId();
+  const pathname = to.split(/[?#]/)[0];
+  useEffect(() => {
+    reportPending(id, pathname, pending);
+    return () => reportPending(id, pathname, false);
+  }, [id, pathname, pending, reportPending]);
+  return null;
+}
+
+export const NavigationLink = forwardRef<
+  HTMLAnchorElement,
+  ComponentProps<NonNullable<RouterProvider["Link"]>>
+>(
+  function NavigationLink({ to, children, ...props }, ref) {
+    return (
+      <Link href={to} {...props} ref={ref}>
+        {children}
+        <NavigationLinkStatus to={to} />
+      </Link>
+    );
+  },
+);

src/components/loading/PageLoadingSkeleton.tsx

@@ -0,0 +1,110 @@
+"use client";
+
+import { Box, CircularProgress, Skeleton, Typography } from "@mui/material";
+import { usePathname } from "next/navigation";
+
+import { MapPanelSkeleton, MapTimelineSkeleton } from "./MapComponentSkeletons";
+import {
+  MAP_SKELETON_CONFIGS,
+  type MapSkeletonVariant,
+} from "./mapComponentSkeletonConfig";
+
+const sceneLoadingSurface = {
+  width: "min(100%, 360px)",
+  p: 3,
+  boxSizing: "border-box",
+  borderRadius: "16px",
+  background: "linear-gradient(135deg,rgba(255,255,255,.50),rgba(224,239,250,.28))",
+  backdropFilter: "blur(24px) saturate(170%) contrast(94%)",
+  WebkitBackdropFilter: "blur(24px) saturate(170%) contrast(94%)",
+  boxShadow: "inset 0 1px 0 rgba(255,255,255,.88),inset 0 -1px 0 rgba(112,145,168,.18),0 18px 50px rgba(15,43,69,.20),0 0 0 1px rgba(255,255,255,.55)",
+};
+
+const mapPaths: Record<string, MapSkeletonVariant> = {
+  "/network-simulation": "network-simulation",
+  "/scada-data-cleaning": "scada-data-cleaning",
+  "/health-risk-analysis": "health-risk-analysis",
+  "/monitoring-place-optimization": "monitoring-place-optimization",
+  "/hydraulic-simulation/burst-detection": "burst-detection",
+  "/hydraulic-simulation/burst-location": "burst-location",
+  "/hydraulic-simulation/burst-simulation": "burst-simulation",
+  "/hydraulic-simulation/contaminant-simulation": "contaminant-simulation",
+  "/hydraulic-simulation/dma-leak-detection": "dma-leak-detection",
+  "/hydraulic-simulation/flushing-analysis": "flushing-analysis",
+};
+
+export const mapSkeletonForPath = (
+  pathname: string,
+): MapSkeletonVariant | undefined => mapPaths[pathname];
+
+export const pageTitleForPath = (pathname: string) => {
+  const variant = mapSkeletonForPath(pathname);
+  if (variant) return MAP_SKELETON_CONFIGS[variant].title;
+  return ({
+    "/system-admin": "系统管理",
+    "/audit-logs": "审计日志",
+    "/three-dimensional-scene": "三维场景",
+  } as Record<string, string>)[pathname] ?? "页面";
+};
+
+export function MapRouteSkeleton({ pathname }: { pathname: string }) {
+  const variant = mapSkeletonForPath(pathname);
+  if (!variant) return null;
+  return (
+    <>
+      <MapPanelSkeleton variant={variant} />
+      {(variant === "network-simulation" || variant === "health-risk-analysis") && (
+        <MapTimelineSkeleton />
+      )}
+    </>
+  );
+}
+
+export function PageLoadingSkeleton({ pathname }: { pathname?: string }) {
+  const currentPath = usePathname();
+  const path = pathname ?? currentPath;
+  if (path === "/three-dimensional-scene") {
+    return (
+      <Box
+        role="status"
+        aria-live="polite"
+        aria-label="正在加载三维场景"
+        sx={{ height: "100%", minHeight: 0, display: "grid", placeItems: "center", p: 2, boxSizing: "border-box", bgcolor: "#e2e8e9" }}
+      >
+        <Box sx={sceneLoadingSurface}>
+          <Box sx={{ display: "flex", alignItems: "center", gap: 1.25 }}>
+            <CircularProgress size={20} />
+            <Typography sx={{ fontSize: 14, fontWeight: 600, color: "#0f172a" }}>
+              正在准备三维场景
+            </Typography>
+          </Box>
+          <Typography sx={{ mt: 1.5, fontSize: 12, lineHeight: 1.75, color: "#334155" }}>
+            正在载入页面，随后将检查本地模型缓存。
+          </Typography>
+        </Box>
+      </Box>
+    );
+  }
+  if (mapSkeletonForPath(path)) {
+    return (
+      <Box sx={{ position: "relative", height: "100%", minHeight: 320, overflow: "hidden", bgcolor: "#f1f5f9" }}>
+        <MapRouteSkeleton pathname={path} />
+      </Box>
+    );
+  }
+  const title = pageTitleForPath(path);
+  return (
+    <Box
+      role="status"
+      aria-live="polite"
+      aria-label={`正在加载${title}`}
+      sx={{ p: { xs: 2, md: 3 }, height: "100%", boxSizing: "border-box", bgcolor: "background.default" }}
+    >
+      <Typography sx={{ fontSize: 16, fontWeight: 600, mb: 3 }}>正在加载{title}</Typography>
+      <Skeleton variant="rounded" height={40} sx={{ maxWidth: 480, mb: 3 }} />
+      {[0, 1, 2, 3].map((row) => (
+        <Skeleton key={row} variant="rounded" height={56} sx={{ mb: 1.5 }} />
+      ))}
+    </Box>
+  );
+}

src/components/olmap/SCADA/SCADADataPanel.test.tsx

@@ -0,0 +1,50 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+
+import { apiFetch } from "@/lib/apiFetch";
+import SCADADataPanel from "./SCADADataPanel";
+
+jest.mock("@/lib/apiFetch", () => ({ apiFetch: jest.fn() }));
+jest.mock("@refinedev/core", () => ({
+  useGetIdentity: () => ({ data: { id: "test-user" } }),
+  useNotification: () => ({ open: jest.fn() }),
+}));
+jest.mock("@mui/x-date-pickers", () => ({
+  DateTimePicker: () => null,
+  LocalizationProvider: ({ children }: { children: React.ReactNode }) => children,
+}));
+jest.mock("echarts-for-react", () => () => null);
+
+const response = (payload: unknown) =>
+  ({ ok: true, json: async () => payload }) as Response;
+
+describe("SCADADataPanel requests", () => {
+  beforeEach(() => {
+    jest.mocked(apiFetch).mockImplementation(async (url) =>
+      response(
+        String(url).includes("/scada-devices")
+          ? [
+              { device_id: "S-1", device_type: "pressure", node_id: "J-1", link_id: null },
+              { device_id: "S-2", device_type: "pressure", node_id: "J-2", link_id: null },
+            ]
+          : { series: [] },
+      ),
+    );
+  });
+
+  afterEach(() => jest.clearAllMocks());
+
+  it("does not request history again when the same device IDs arrive in a new array", async () => {
+    const { rerender } = render(<SCADADataPanel deviceIds={["S-1"]} />);
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(2));
+
+    rerender(<SCADADataPanel deviceIds={["S-1"]} />);
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(2));
+
+    rerender(<SCADADataPanel deviceIds={["S-1", "S-2"]} />);
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(4));
+    expect(jest.mocked(apiFetch).mock.calls[3][1]?.body).toContain('"device_ids":["S-2"]');
+
+    fireEvent.click(screen.getByRole("button", { name: "刷新" }));
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(6));
+  });
+});

src/components/olmap/SCADA/SCADADataPanel.tsx

@@ -307,9 +307,15 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
 
   const normalizedRange = useMemo(() => ensureValidRange(from, to), [from, to]);
 
-  const hasDevices = deviceIds.length > 0;
+  // Parent map updates can pass a new array with identical IDs. Keep the
+  // request dependency tied to the IDs themselves, not the array identity.
+  const deviceIdsKey = JSON.stringify(deviceIds);
+  const requestedDeviceIds = useMemo(
+    () => JSON.parse(deviceIdsKey) as string[],
+    [deviceIdsKey],
+  );
+  const hasDevices = requestedDeviceIds.length > 0;
   const hasData = timeSeries.length > 0;
-  const deviceIdsKey = useMemo(() => deviceIds.join(","), [deviceIds]);
 
   const dataset = useMemo(
     () => buildDataset(timeSeries, deviceIds, fractionDigits, showCleaning),
@@ -348,7 +354,7 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
       setError(null);
       try {
         const { from: rangeFrom, to: rangeTo } = normalizedRange;
-        const result = await customFetcher(deviceIds, {
+        const result = await customFetcher(requestedDeviceIds, {
           from: rangeFrom.toDate(),
           to: rangeTo.toDate(),
         });
@@ -360,7 +366,7 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
         setLoadingState("error");
       }
     },
-    [deviceIds, customFetcher, hasDevices, normalizedRange],
+    [requestedDeviceIds, customFetcher, hasDevices, normalizedRange],
   );
 
   // 处理数据清洗
@@ -447,7 +453,7 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
       setTimeSeries([]);
       setHistorySeries([]);
     }
-  }, [deviceIdsKey, handleFetch, hasDevices]);
+  }, [handleFetch, hasDevices]);
 
   // 当设备数量变化时，调整数据源选择
   useEffect(() => {

src/components/olmap/core/Controls/HistoryDataPanel.test.ts

@@ -1,14 +1,42 @@
+import React from "react";
+import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import dayjs from "dayjs";
+import ReactECharts from "echarts-for-react";
 import { apiFetch } from "@/lib/apiFetch";
-import { fetchHistoryData } from "./HistoryDataPanel";
+import { getAnalysisScheme, toAnalysisSchemeRecord } from "@/lib/analysisRuns";
+import { useAccessStore } from "@/store/accessStore";
+import { useProjectStore } from "@/store/projectStore";
+import HistoryDataPanel, { fetchHistoryData } from "./HistoryDataPanel";
 
 jest.mock("@/lib/apiFetch", () => ({
   apiFetch: jest.fn(),
 }));
+jest.mock("@/lib/analysisRuns", () => ({
+  ...jest.requireActual("@/lib/analysisRuns"),
+  getAnalysisScheme: jest.fn(),
+}));
 
 jest.mock("@components/olmap/core/MapComponent", () => ({
   useData: () => null,
 }));
 
+jest.mock("@mui/x-date-pickers", () => ({
+  DateTimePicker: ({ label, value, onChange }: {
+    label: string; value: dayjs.Dayjs; onChange: (value: dayjs.Dayjs) => void;
+  }) => React.createElement("input", {
+    "aria-label": label,
+    value: value.toISOString(),
+    onChange: (event: React.ChangeEvent<HTMLInputElement>) => onChange(dayjs(event.target.value)),
+  }),
+  LocalizationProvider: ({ children }: { children: React.ReactNode }) => children,
+}));
+jest.mock("echarts-for-react", () => jest.fn(() => null));
+jest.mock("./useTimelineTimeConfig", () => ({
+  useTimelineTimeConfig: () => ({
+    durationMinutes: 1440, stepMinutes: 15, properties: { "HYDRAULIC TIMESTEP": "0:15" },
+  }),
+}));
+
 const jsonResponse = (payload: unknown, status = 200) =>
   ({
     ok: status >= 200 && status < 300,
@@ -58,14 +86,63 @@ describe("fetchHistoryData", () => {
       "99dd4142-368b-54cb-bfca-d59ee48f6298",
     );
 
-    expect(apiFetch).toHaveBeenCalledTimes(1);
-    const [, init] = jest.mocked(apiFetch).mock.calls[0];
-    expect(JSON.parse(String(init?.body))).toMatchObject({
+    expect(apiFetch).toHaveBeenCalledTimes(2);
+    const bodies = jest.mocked(apiFetch).mock.calls.map(([, init]) => JSON.parse(String(init?.body)));
+    expect(bodies[0]).toMatchObject({ mode: "realtime_comparison" });
+    expect(bodies[0]).not.toHaveProperty("run_id");
+    expect(bodies[1]).toMatchObject({
       mode: "analysis_comparison",
       run_id: "99dd4142-368b-54cb-bfca-d59ee48f6298",
     });
   });
 
+  it("combines element simulations without SCADA and deduplicates monitoring", async () => {
+    const base = {
+      element_id: "P-1", element_type: "pipe", device_id: null,
+      metric: "flow", source_unit: "L/s", display_unit: "m³/h", unit_inferred: false,
+    };
+    const observed = {
+      ...base, device_id: "F-1", source: "scada_raw",
+      points: [{ time: "2026-08-17T09:30:00Z", value: 5 }],
+    };
+    const targets: [string, string][] = [["P-1", "pipe"], ["J-1", "junction"]];
+    jest.mocked(apiFetch).mockImplementation(async (_url, init) => {
+      const { mode } = JSON.parse(String(init?.body));
+      return jsonResponse({ series: mode === "analysis_comparison" ? [
+        observed,
+        { ...base, source: "analysis_simulation", points: [
+          { time: "2026-08-17T09:30:00Z", value: 20 },
+        ] },
+      ] : [
+        observed,
+        { ...base, source: "realtime_simulation", points: [
+          { time: "2026-08-17T09:00:00Z", value: 10 },
+          { time: "2026-08-17T10:00:00Z", value: 12 },
+        ] },
+        { ...base, element_id: "J-1", element_type: "junction", metric: "pressure",
+          source_unit: "m", source: "realtime_simulation", points: [
+            { time: "2026-08-17T09:00:00Z", value: 30 },
+          ] },
+      ] });
+    });
+    const result = await fetchHistoryData(targets, range, "scheme", "run-1");
+    expect(result.series).toHaveLength(4);
+    expect(result.points[0].values).toEqual({ '["pipe","P-1","realtime_simulation"]': 36, '["junction","J-1","realtime_simulation"]': 30 });
+    expect(result.points[1].values['["pipe","P-1","analysis_simulation"]']).toBe(72);
+    expect(result.points[2].values['["pipe","P-1","realtime_simulation"]']).toBeCloseTo(43.2);
+    expect(apiFetch).toHaveBeenCalledTimes(2);
+    for (const [, init] of jest.mocked(apiFetch).mock.calls) {
+      expect(JSON.parse(String(init?.body)).elements).toHaveLength(2);
+    }
+  });
+
+  it("reports an aggregate request failure instead of showing an incomplete comparison", async () => {
+    jest.mocked(apiFetch).mockResolvedValueOnce(jsonResponse({ series: [] }))
+      .mockResolvedValueOnce(jsonResponse({ detail: "analysis unavailable" }, 503));
+    await expect(fetchHistoryData([["P-1", "pipe"]], range, "scheme", "run-1"))
+      .rejects.toThrow("analysis unavailable");
+  });
+
   it("rejects oversized element selections before issuing requests", async () => {
     jest.mocked(apiFetch).mockResolvedValue(jsonResponse({}));
     const featureInfos = Array.from(
@@ -94,3 +171,238 @@ describe("fetchHistoryData", () => {
     expect(apiFetch).toHaveBeenCalledTimes(1);
   });
 });
+
+const eventRun = (runId = "run-1", startedAt = "2026-08-17T09:00:00Z") =>
+  toAnalysisSchemeRecord({
+    run_id: runId, name: "event", run_type: "burst_analysis", created_by: "alice",
+    created_at: "2026-11-03T00:00:00Z", started_at: startedAt,
+    status: "completed", parameters: { modify_total_duration: 3600 },
+  });
+
+describe("HistoryDataPanel requests", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.mocked(apiFetch).mockResolvedValue(jsonResponse({ series: [] }));
+    jest.mocked(getAnalysisScheme).mockReset().mockResolvedValue(eventRun());
+    useAccessStore.setState({ permissions: ["simulation.run"], loading: false });
+    useProjectStore.getState().setCurrentProject("project-1", "network-1");
+  });
+
+  afterEach(() => jest.clearAllMocks());
+
+  it("does not reload unchanged elements when its parent rerenders", async () => {
+    const props = { type: "none" as const, onClose: jest.fn() };
+    const { rerender } = render(
+      React.createElement(HistoryDataPanel, {
+        ...props,
+        featureInfos: [["J-1", "junction"]],
+      }),
+    );
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(1));
+
+    rerender(
+      React.createElement(HistoryDataPanel, {
+        ...props,
+        featureInfos: [["J-1", "junction"]],
+      }),
+    );
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(1));
+
+    rerender(
+      React.createElement(HistoryDataPanel, {
+        ...props,
+        featureInfos: [["J-2", "junction"]],
+      }),
+    );
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(2));
+  });
+
+  const props = {
+    featureInfos: [["P-1", "pipe"]] as [string, string][],
+    type: "scheme" as const, runId: "run-1", onClose: jest.fn(),
+  };
+
+  it("initializes a historical event with one hour of context on both sides", async () => {
+    render(React.createElement(HistoryDataPanel, props));
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(2));
+    for (const [, init] of jest.mocked(apiFetch).mock.calls) {
+      expect(JSON.parse(String(init?.body))).toMatchObject({
+        start_time: "2026-08-17T08:00:00.000Z", end_time: "2026-08-17T11:00:00.000Z",
+      });
+    }
+    expect(screen.getByText(/事件方案时段：2026-08-17 17:00/)).toBeInTheDocument();
+    expect(screen.getByLabelText("开始时间")).toHaveValue("2026-08-17T08:00:00.000Z");
+  });
+
+  it("keeps explicit query dates and issues one pair of requests per date change", async () => {
+    render(React.createElement(HistoryDataPanel, {
+      ...props, start_time: "2026-08-17T07:00:00Z", end_time: "2026-08-17T12:00:00Z",
+    }));
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(2));
+    fireEvent.change(screen.getByLabelText("开始时间"), { target: { value: "2026-08-17T06:00:00Z" } });
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(4));
+    expect(JSON.parse(String(jest.mocked(apiFetch).mock.calls[2][1]?.body))).toMatchObject({
+      start_time: "2026-08-17T06:00:00.000Z", end_time: "2026-08-17T12:00:00.000Z",
+    });
+    expect(jest.mocked(apiFetch).mock.calls[0][1]?.signal?.aborted).toBe(true);
+    expect(getAnalysisScheme).toHaveBeenCalledTimes(1);
+  });
+
+  it("ignores a stale scheme response after switching events", async () => {
+    let resolveOld!: (value: ReturnType<typeof eventRun>) => void;
+    jest.mocked(getAnalysisScheme).mockReturnValueOnce(new Promise((resolve) => { resolveOld = resolve; }))
+      .mockResolvedValueOnce(eventRun("run-2", "2026-08-18T09:00:00Z"));
+    const { rerender } = render(React.createElement(HistoryDataPanel, props));
+    expect(apiFetch).not.toHaveBeenCalled();
+    rerender(React.createElement(HistoryDataPanel, { ...props, runId: "run-2" }));
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(2));
+    await act(async () => { resolveOld(eventRun()); });
+    expect(apiFetch).toHaveBeenCalledTimes(2);
+    expect(JSON.parse(String(jest.mocked(apiFetch).mock.calls[1][1]?.body))).toMatchObject({
+      run_id: "run-2", start_time: "2026-08-18T08:00:00.000Z",
+    });
+  });
+
+  it("preserves the manually chosen end date when only the start date prop changes", async () => {
+    const partialProps = { ...props, type: "none" as const, start_time: "2026-08-17T07:00:00Z" };
+    const { rerender } = render(React.createElement(HistoryDataPanel, partialProps));
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(1));
+    fireEvent.change(screen.getByLabelText("结束时间"), { target: { value: "2026-08-17T12:00:00Z" } });
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(2));
+    rerender(React.createElement(HistoryDataPanel, { ...partialProps, start_time: "2026-08-17T06:00:00Z" }));
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(3));
+    expect(screen.getByLabelText("结束时间")).toHaveValue("2026-08-17T12:00:00.000Z");
+    expect(JSON.parse(String(jest.mocked(apiFetch).mock.calls[2][1]?.body))).toMatchObject({
+      start_time: "2026-08-17T06:00:00.000Z", end_time: "2026-08-17T12:00:00.000Z",
+    });
+  });
+
+  it("queries online element readings for an analysis without hydraulic results", async () => {
+    jest.mocked(getAnalysisScheme).mockResolvedValue({ ...eventRun(), run_type: "burst_detection" });
+    render(React.createElement(HistoryDataPanel, props));
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(1));
+    const body = JSON.parse(String(jest.mocked(apiFetch).mock.calls[0][1]?.body));
+    expect(body.mode).toBe("realtime_comparison");
+    expect(body).not.toHaveProperty("run_id");
+  });
+
+  it("does not restore stale curves after the selected elements are cleared", async () => {
+    const pending: Array<(value: Response) => void> = [];
+    jest.mocked(apiFetch).mockImplementation(() => new Promise((resolve) => { pending.push(resolve); }));
+    const { rerender } = render(React.createElement(HistoryDataPanel, props));
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(2));
+    rerender(React.createElement(HistoryDataPanel, { ...props, featureInfos: [] }));
+    expect(jest.mocked(apiFetch).mock.calls[0][1]?.signal?.aborted).toBe(true);
+    expect(jest.mocked(apiFetch).mock.calls[1][1]?.signal?.aborted).toBe(true);
+    await act(async () => {
+      pending[0](jsonResponse({ series: [{
+        element_id: "P-1", element_type: "pipe", device_id: null, metric: "flow",
+        source: "realtime_simulation", source_unit: "m3/h", display_unit: "m³/h",
+        unit_inferred: false, points: [{ time: "2026-08-17T09:00:00Z", value: 10 }],
+      }] }));
+      pending[1](jsonResponse({ series: [] }));
+    });
+    expect(ReactECharts).not.toHaveBeenCalled();
+    expect(screen.getByText("尚未选择地图要素")).toBeInTheDocument();
+  });
+
+  it("allows a failed event metadata query to be retried", async () => {
+    jest.mocked(getAnalysisScheme).mockRejectedValueOnce(new Error("unavailable"));
+    render(React.createElement(HistoryDataPanel, props));
+    await screen.findByText(/无法读取事件方案/);
+    expect(apiFetch).not.toHaveBeenCalled();
+    expect(screen.getByRole("button", { name: "在线模拟" })).toBeDisabled();
+    fireEvent.click(screen.getByRole("button", { name: "刷新" }));
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(2));
+    expect(getAnalysisScheme).toHaveBeenCalledTimes(2);
+  });
+
+  it("plots native timestamps and explicit gaps with the event interval marked", async () => {
+    const series = {
+      element_id: "P-1", element_type: "pipe", device_id: null, metric: "flow",
+      source_unit: "m3/h", display_unit: "m³/h", unit_inferred: false,
+    };
+    jest.mocked(apiFetch).mockImplementation(async (_url, init) => {
+      const { mode } = JSON.parse(String(init?.body));
+      return jsonResponse({ series: [{ ...series,
+        source: mode === "analysis_comparison" ? "analysis_simulation" : "realtime_simulation",
+        points: mode === "analysis_comparison" ? [
+          { time: "2026-08-17T09:15:00Z", value: 8 },
+        ] : [
+          { time: "2026-08-17T08:00:00Z", value: 10 },
+          { time: "2026-08-17T09:00:00Z", value: null },
+          { time: "2026-08-17T11:00:00Z", value: 12 },
+        ],
+      }] });
+    });
+    render(React.createElement(HistoryDataPanel, props));
+    await waitFor(() => expect(ReactECharts).toHaveBeenCalled());
+    const option = jest.mocked(ReactECharts).mock.calls.at(-1)![0].option as any;
+    expect(option.xAxis).toMatchObject({ type: "time", min: Date.parse("2026-08-17T08:00:00Z"), max: Date.parse("2026-08-17T11:00:00Z") });
+    expect(option.series[0].connectNulls).toBe(false);
+    expect(option.series[0].data).toEqual([
+      [Date.parse("2026-08-17T08:00:00Z"), 10],
+      [Date.parse("2026-08-17T09:00:00Z"), null],
+      [Date.parse("2026-08-17T11:00:00Z"), 12],
+    ]);
+    expect(option.series[0].markArea.data[0]).toEqual([
+      { name: "事件方案时段", xAxis: Date.parse("2026-08-17T09:00:00Z") },
+      { xAxis: Date.parse("2026-08-17T10:00:00Z") },
+    ]);
+    expect(option.series[1].data).toEqual([[Date.parse("2026-08-17T09:15:00Z"), 8]]);
+  });
+
+  it("snaps off-step event context without changing the actual event marker", async () => {
+    jest.mocked(getAnalysisScheme).mockResolvedValue(eventRun("run-1", "2026-07-30T05:38:00Z"));
+    render(React.createElement(HistoryDataPanel, props));
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(2));
+    expect(JSON.parse(String(jest.mocked(apiFetch).mock.calls[0][1]?.body))).toMatchObject({
+      start_time: "2026-07-30T04:30:00.000Z", end_time: "2026-07-30T07:45:00.000Z",
+    });
+    expect(screen.getByText(/事件方案时段：2026-07-30 13:38/)).toBeInTheDocument();
+  });
+
+  it("runs online simulation once, shows progress, then refreshes both history sources", async () => {
+    let finishSimulation!: (value: Response) => void;
+    jest.mocked(apiFetch).mockImplementation(async (url) => {
+      if (String(url).endsWith("/network-options/time")) return jsonResponse({ "HYDRAULIC TIMESTEP": "0:15" });
+      if (String(url).endsWith("/simulation-runs")) return new Promise((resolve) => { finishSimulation = resolve; });
+      return jsonResponse({ series: [] });
+    });
+    render(React.createElement(HistoryDataPanel, props));
+    const button = screen.getByRole("button", { name: "在线模拟" });
+    await waitFor(() => expect(button).toBeEnabled());
+    fireEvent.click(button);
+    await screen.findByText("正在计算在线模拟数据，完成后将自动刷新图表。");
+    expect(screen.getByRole("button", { name: "模拟中…" })).toBeDisabled();
+    await waitFor(() => expect(finishSimulation).toBeDefined());
+    fireEvent.click(button);
+    expect(jest.mocked(apiFetch).mock.calls.filter(([url]) => String(url).endsWith("/simulation-runs"))).toHaveLength(1);
+    await act(async () => { finishSimulation(jsonResponse({ status: "success" })); });
+    await waitFor(() => expect(jest.mocked(apiFetch).mock.calls.filter(([url]) => String(url).endsWith("/element-history/query"))).toHaveLength(4));
+    expect(screen.getByRole("button", { name: "在线模拟" })).toBeEnabled();
+  });
+
+  it("disables the write action for a viewer while allowing history reads", async () => {
+    useAccessStore.setState({ permissions: ["simulation.view"] });
+    render(React.createElement(HistoryDataPanel, props));
+    await waitFor(() => expect(apiFetch).toHaveBeenCalledTimes(2));
+    expect(screen.getByRole("button", { name: "在线模拟" })).toBeDisabled();
+    expect(screen.getByRole("button", { name: "刷新" })).toBeEnabled();
+  });
+
+  it("shows a simulation failure without retrying or claiming data was refreshed", async () => {
+    jest.mocked(apiFetch).mockImplementation(async (url) => {
+      if (String(url).endsWith("/network-options/time")) return jsonResponse({ "HYDRAULIC TIMESTEP": "0:15" });
+      if (String(url).endsWith("/simulation-runs")) return jsonResponse({ detail: "计算服务不可用" }, 503);
+      return jsonResponse({ series: [] });
+    });
+    render(React.createElement(HistoryDataPanel, props));
+    const button = screen.getByRole("button", { name: "在线模拟" });
+    await waitFor(() => expect(button).toBeEnabled());
+    fireEvent.click(button);
+    expect(await screen.findByRole("alert")).toHaveTextContent("计算服务不可用");
+    expect(jest.mocked(apiFetch).mock.calls.filter(([url]) => String(url).endsWith("/simulation-runs"))).toHaveLength(1);
+    expect(jest.mocked(apiFetch).mock.calls.filter(([url]) => String(url).endsWith("/element-history/query"))).toHaveLength(2);
+  });
+});

src/components/olmap/core/Controls/HistoryDataPanel.tsx

@@ -22,7 +22,7 @@ import {
   Tooltip,
   Typography,
 } from "@mui/material";
-import { Close, Refresh, ShowChart, TableChart } from "@mui/icons-material";
+import { Close, PlayArrow, Refresh, ShowChart, TableChart } from "@mui/icons-material";
 import { DataGrid, GridColDef } from "@mui/x-data-grid";
 import { zhCN } from "@mui/x-data-grid/locales";
 import ReactECharts from "echarts-for-react";
@@ -41,8 +41,23 @@ import {
   fetchElementHistory,
   historySeriesKey,
   historySeriesLabel,
+  toTimeSeriesPoints,
   TimeSeriesPoint,
 } from "@/lib/elementHistory";
+import {
+  type AnalysisHistoryContext,
+  getAnalysisHistoryContext,
+  getAnalysisScheme,
+} from "@/lib/analysisRuns";
+import {
+  alignSimulationRange,
+  parseHydraulicStepSeconds,
+  runOnlineSimulation,
+} from "@/lib/onlineSimulation";
+import { permissionCodes } from "@/lib/permissions";
+import { useAccessStore } from "@/store/accessStore";
+import { useProjectStore } from "@/store/projectStore";
+import { useTimelineTimeConfig } from "./useTimelineTimeConfig";
 import {
   FLOW_DISPLAY_UNIT,
   PRESSURE_DISPLAY_UNIT,
@@ -54,7 +69,7 @@ dayjs.extend(timezone);
 export interface SCADADataPanelProps {
   /** 选中的要素信息列表，格式为 [[id, type], [id, type]] */
   featureInfos: [string, string][];
-  /** 数据类型: realtime-查询模拟值和监测值, none-仅查询监测值, scheme-查询策略模拟值和监测值 */
+  /** 数据类型: realtime-在线模拟与监测, none-仅监测, scheme-方案、在线模拟与监测 */
   type?: "realtime" | "scheme" | "none";
   /** 默认展示的选项卡 */
   defaultTab?: "chart" | "table";
@@ -107,6 +122,13 @@ export const fetchHistoryData = async (
   ) {
     throw new Error("历史数据包含无效的管网元素 ID");
   }
+  if (
+    featureInfos.some(
+      ([, elementType]) => !["pipe", "junction"].includes(elementType.toLowerCase()),
+    )
+  ) {
+    throw new Error("历史数据仅支持管道和节点");
+  }
 
   const uniqueFeatureInfos = Array.from(
     new Map(
@@ -118,25 +140,33 @@ export const fetchHistoryData = async (
     throw new Error("历史方案缺少分析运行 ID，无法读取方案时序数据");
   }
 
-  try {
-    return await fetchElementHistory(
-      uniqueFeatureInfos.map(([id, elementType]) => ({
-        element_id: id.trim(),
-        element_type: elementType.toLowerCase() as "pipe" | "junction",
-      })),
-      range,
-      type === "none"
-        ? "observed"
-        : type === "scheme"
-          ? "analysis_comparison"
-          : "realtime_comparison",
-      schemeRunId,
-      signal,
-    );
-  } catch (error) {
-    console.error("[HistoryDataPanel] 从后端获取数据失败:", error);
-    throw error;
+  const elements = uniqueFeatureInfos.map(([id, elementType]) => ({
+    element_id: id.trim(),
+    element_type: elementType.toLowerCase() as "pipe" | "junction",
+  }));
+  if (type === "scheme") {
+    const [online, analysis] = await Promise.all([
+      fetchElementHistory(
+        elements, range, "realtime_comparison", undefined, signal,
+      ),
+      fetchElementHistory(
+        elements, range, "analysis_comparison", schemeRunId, signal,
+      ),
+    ]);
+    // 两次聚合查询均返回监测序列，只保留在线查询中的一份。
+    const series = [
+      ...online.series,
+      ...analysis.series.filter((item) => item.source === "analysis_simulation"),
+    ];
+    return { series, points: toTimeSeriesPoints(series) };
   }
+  return fetchElementHistory(
+    elements,
+    range,
+    type === "none" ? "observed" : "realtime_comparison",
+    undefined,
+    signal,
+  );
 };
 
 const formatTimestamp = (timestamp: string) =>
@@ -186,11 +216,11 @@ const emptyStateMessages: Record<
 > = {
   chart: {
     title: "暂无时序数据",
-    subtitle: "请调整时间范围，或确认所选设备在该时段已有数据。",
+    subtitle: "请调整时间范围，或确认所选元素在该时段已有数据。",
   },
   table: {
     title: "暂无表格数据",
-    subtitle: "请调整时间范围，或确认所选设备在该时段已有数据。",
+    subtitle: "请调整时间范围，或确认所选元素在该时段已有数据。",
   },
 };
 
@@ -204,35 +234,86 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
   runId,
   onClose,
 }) => {
-  // 从 featureInfos 中提取设备 ID 列表
-  const deviceIds = useMemo(
-    () => featureInfos.map(([id]) => id),
-    [featureInfos]
+  const timeConfig = useTimelineTimeConfig();
+  const stepSeconds = parseHydraulicStepSeconds(timeConfig.properties["HYDRAULIC TIMESTEP"])
+    ?? timeConfig.stepMinutes * 60;
+  const canRunSimulation = useAccessStore((state) =>
+    state.permissions.includes(permissionCodes.simulationRun),
   );
+  const projectId = useProjectStore((state) => state.currentProjectId);
+  const [schemeState, setSchemeState] = useState<{
+    runId: string;
+    context?: AnalysisHistoryContext;
+    error?: string;
+  } | null>(null);
+  const [schemeReload, setSchemeReload] = useState(0);
+  const schemeReady = type !== "scheme" || !runId || schemeState?.runId === runId;
+  const schemeContext =
+    type === "scheme" && schemeState?.runId === runId
+      ? schemeState?.context
+      : undefined;
+  const schemeError =
+    type === "scheme" && schemeState?.runId === runId
+      ? schemeState?.error
+      : undefined;
+  const eventRange = schemeContext?.eventRange;
+  const rangeKey = JSON.stringify([type, runId]);
+  const defaultRange = useMemo(() => {
+    const now = dayjs();
+    const start = start_time ? dayjs(start_time) : null;
+    const end = end_time ? dayjs(end_time) : null;
+    const range = {
+      from: start?.isValid()
+        ? start
+        : eventRange
+          ? dayjs(eventRange.start).subtract(1, "hour")
+          : now.subtract(1, "day"),
+      to: end?.isValid()
+        ? end
+        : eventRange
+          ? dayjs(eventRange.end).add(1, "hour")
+          : now,
+    };
+    const aligned = alignSimulationRange({ from: range.from.toDate(), to: range.to.toDate() }, stepSeconds);
+    return { from: dayjs(aligned.from), to: dayjs(aligned.to) };
+  }, [start_time, end_time, eventRange, stepSeconds]);
+  const [selectedRange, setSelectedRange] = useState<{
+    key: string;
+    from: Dayjs;
+    to: Dayjs;
+    startTime?: string;
+    endTime?: string;
+  } | null>(null);
+  const rangeForContext = selectedRange?.key === rangeKey ? selectedRange : null;
+  const from = rangeForContext && (
+    rangeForContext.startTime === start_time || !start_time || !dayjs(start_time).isValid()
+  ) ? rangeForContext.from : defaultRange.from;
+  const to = rangeForContext && (
+    rangeForContext.endTime === end_time || !end_time || !dayjs(end_time).isValid()
+  ) ? rangeForContext.to : defaultRange.to;
+  const setFrom = (value: Dayjs) => {
+    const range = alignSimulationRange({ from: value.toDate(), to: to.toDate() }, stepSeconds);
+    setSelectedRange({ key: rangeKey, from: dayjs(range.from), to: dayjs(range.to), startTime: start_time, endTime: end_time });
+  };
+  const setTo = (value: Dayjs) => {
+    const range = alignSimulationRange({ from: from.toDate(), to: value.toDate() }, stepSeconds);
+    setSelectedRange({ key: rangeKey, from: dayjs(range.from), to: dayjs(range.to), startTime: start_time, endTime: end_time });
+  };
 
-  const [from, setFrom] = useState<Dayjs>(() => {
-    if (start_time) {
-      const parsedStart = dayjs(start_time);
-      if (parsedStart.isValid()) {
-        return parsedStart;
-      }
-    }
-    return dayjs().subtract(1, "day");
-  });
-  const [to, setTo] = useState<Dayjs>(() => {
-    if (end_time) {
-      const parsedEnd = dayjs(end_time);
-      if (parsedEnd.isValid()) {
-        return parsedEnd;
-      }
-    }
-    return dayjs();
-  });
+  useEffect(() => {
+    if (!rangeForContext || (
+      rangeForContext.startTime === start_time && rangeForContext.endTime === end_time
+    )) return;
+    setSelectedRange({ key: rangeKey, from, to, startTime: start_time, endTime: end_time });
+  }, [rangeForContext, rangeKey, from, to, start_time, end_time]);
   const [activeTab, setActiveTab] = useState<PanelTab>(defaultTab);
   const [timeSeries, setTimeSeries] = useState<TimeSeriesPoint[]>([]);
   const [historySeries, setHistorySeries] = useState<ElementHistorySeries[]>([]);
   const [loadingState, setLoadingState] = useState<LoadingState>("idle");
   const [error, setError] = useState<string | null>(null);
+  const [isSimulating, setIsSimulating] = useState(false);
+  const [simulationError, setSimulationError] = useState<string | null>(null);
+  const simulationControllerRef = useRef<AbortController | null>(null);
   const draggableRef = useRef<HTMLDivElement>(null);
   const requestControllerRef = useRef<AbortController | null>(null);
 
@@ -241,29 +322,74 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
   }, [defaultTab]);
 
   useEffect(() => {
-    if (!start_time && !end_time) return;
-    if (start_time) {
-      const parsedStart = dayjs(start_time);
-      if (parsedStart.isValid()) {
-        setFrom((prev) => (parsedStart.isSame(prev) ? prev : parsedStart));
-      }
-    }
-    if (end_time) {
-      const parsedEnd = dayjs(end_time);
-      if (parsedEnd.isValid()) {
-        setTo((prev) => (parsedEnd.isSame(prev) ? prev : parsedEnd));
-      }
-    }
-  }, [start_time, end_time]);
+    if (type !== "scheme" || !runId) return;
+    let cancelled = false;
+    getAnalysisScheme(runId).then(
+      (run) => {
+        if (!cancelled) {
+          setSchemeState({ runId, context: getAnalysisHistoryContext(run) });
+        }
+      },
+      () => {
+        if (!cancelled) {
+          setSchemeState({ runId, error: "无法读取事件方案，请刷新重试" });
+        }
+      },
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [type, runId, schemeReload]);
 
-  const normalizedRange = useMemo(() => ensureValidRange(from, to), [from, to]);
+  const normalizedRange = useMemo(() => {
+    const ordered = ensureValidRange(from, to);
+    const aligned = alignSimulationRange({ from: ordered.from.toDate(), to: ordered.to.toDate() }, stepSeconds);
+    return { from: dayjs(aligned.from), to: dayjs(aligned.to) };
+  }, [from, to, stepSeconds]);
 
-  const hasDevices = deviceIds.length > 0;
-  const hasData = timeSeries.length > 0;
-  const featureInfosKey = useMemo(
-    () => JSON.stringify(featureInfos),
-    [featureInfos]
+  const featureInfosKey = JSON.stringify(featureInfos);
+  const requestedFeatureInfos = useMemo(
+    () => JSON.parse(featureInfosKey) as [string, string][],
+    [featureInfosKey],
   );
+  const hasDevices = requestedFeatureInfos.length > 0;
+  const hasData = timeSeries.length > 0;
+  const simulationContext = JSON.stringify([
+    projectId, type, runId, featureInfosKey, start_time, end_time,
+  ]);
+  const simulationContextRef = useRef(simulationContext);
+  useEffect(() => {
+    simulationContextRef.current = simulationContext;
+    setSimulationError(null);
+  }, [simulationContext]);
+
+  const handleOnlineSimulation = async () => {
+    if (simulationControllerRef.current || !canRunSimulation || !projectId || !hasDevices || !schemeReady || schemeError) return;
+    const controller = new AbortController();
+    simulationControllerRef.current = controller;
+    setIsSimulating(true);
+    setSimulationError(null);
+    try {
+      const result = await runOnlineSimulation({
+        from: normalizedRange.from.toDate(), to: normalizedRange.to.toDate(),
+      }, controller.signal);
+      if (controller.signal.aborted || simulationContextRef.current !== simulationContext) return;
+      // 更新查询范围会触发历史数据重查，读取刚保存的在线结果。
+      setSelectedRange({
+        key: rangeKey, from: dayjs(result.range.from), to: dayjs(result.range.to),
+        startTime: start_time, endTime: end_time,
+      });
+    } catch (err) {
+      if (!controller.signal.aborted && simulationContextRef.current === simulationContext) {
+        setSimulationError(err instanceof Error ? err.message : "在线模拟失败，请刷新确认已生成的数据");
+      }
+    } finally {
+      if (simulationControllerRef.current === controller) {
+        simulationControllerRef.current = null;
+        setIsSimulating(false);
+      }
+    }
+  };
 
   const dataset = useMemo(
     () => buildDataset(timeSeries, historySeries, fractionDigits),
@@ -271,9 +397,10 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
   );
 
   const handleFetch = useCallback(
-    async (reason: string) => {
-      if (!hasDevices) {
+    async () => {
+      if (!hasDevices || !schemeReady || schemeError) {
         requestControllerRef.current?.abort();
+        requestControllerRef.current = null;
         setTimeSeries([]);
         setHistorySeries([]);
         setLoadingState("idle");
@@ -289,49 +416,57 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
       try {
         const { from: rangeFrom, to: rangeTo } = normalizedRange;
         const result = await fetchHistoryData(
-          featureInfos,
+          requestedFeatureInfos,
           {
             from: rangeFrom.toDate(),
             to: rangeTo.toDate(),
           },
-          type,
-          runId,
+          type === "scheme" && schemeContext && !schemeContext.simulationRunId
+            ? "realtime"
+            : type,
+          schemeContext?.simulationRunId,
           requestController.signal,
         );
-        if (requestControllerRef.current !== requestController) return;
+        if (
+          requestController.signal.aborted ||
+          requestControllerRef.current !== requestController
+        ) return;
         setTimeSeries(result.points);
         setHistorySeries(result.series);
         setLoadingState("success");
       } catch (err) {
         if (
           requestControllerRef.current !== requestController ||
+          requestController.signal.aborted ||
           (err instanceof Error && err.name === "AbortError")
         ) {
           return;
         }
+        setTimeSeries([]);
+        setHistorySeries([]);
         setError(err instanceof Error ? err.message : "未知错误");
         setLoadingState("error");
       }
     },
-    [featureInfos, hasDevices, normalizedRange, runId, type],
+    [
+      requestedFeatureInfos, hasDevices, normalizedRange,
+      schemeReady, schemeError, schemeContext, type,
+    ],
   );
 
   useEffect(
     () => () => {
       requestControllerRef.current?.abort();
+      simulationControllerRef.current?.abort();
+      simulationControllerRef.current = null;
     },
     [],
   );
 
-  // 设备变化时自动查询
+  // 元素、方案或查询范围变化时自动查询。
   useEffect(() => {
-    if (hasDevices) {
-      handleFetch("device-change");
-    } else {
-      setTimeSeries([]);
-      setHistorySeries([]);
-    }
-  }, [featureInfosKey, handleFetch, hasDevices]);
+    void handleFetch();
+  }, [handleFetch]);
 
   const columns: GridColDef[] = useMemo(() => {
     const base: GridColDef[] = [
@@ -386,6 +521,11 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
   );
 
   const renderEmpty = () => {
+    if (isSimulating) {
+      return <Box sx={{ display: "grid", placeItems: "center", height: "100%" }}>
+        <CircularProgress size={32} />
+      </Box>;
+    }
     if (!hasDevices) {
       return (
         <PanelEmptyState
@@ -423,7 +563,6 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
       "#3f51b5", // 靛蓝色
     ];
 
-    const xData = dataset.map((item) => item.label);
     const hasFlowSeries = historySeries.some((item) => item.metric === "flow");
     const hasPressureSeries = historySeries.some(
       (item) => item.metric === "pressure",
@@ -452,11 +591,17 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
             symbolSize: isObserved ? 7 : 0,
             showSymbol: isObserved,
             sampling: "lttb",
-            connectNulls: !isObserved,
+            connectNulls: false,
             itemStyle: {
               color: colors[index % colors.length],
             },
-            data: dataset.map((item) => item[key]),
+            data: timeSeries
+              .filter((point) =>
+                Object.prototype.hasOwnProperty.call(point.values, key),
+              )
+              .map((point) => [
+                new Date(point.timestamp).getTime(), point.values[key] ?? null,
+              ]),
             lineStyle: isObserved ? { width: 0 } : undefined,
             areaStyle: isObserved
               ? undefined
@@ -506,9 +651,15 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
         },
       },
       xAxis: {
-        type: "category",
+        type: "time",
         boundaryGap: false,
-        data: xData,
+        min: normalizedRange.from.valueOf(),
+        max: normalizedRange.to.valueOf(),
+        minInterval: stepSeconds * 1000,
+        axisLabel: {
+          formatter: (value: number) => dayjs(value).tz("Asia/Shanghai").format("MM-DD\nHH:mm"),
+          hideOverlap: true,
+        },
       },
       yAxis: [
         ...(hasFlowSeries
@@ -541,7 +692,21 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
           end: 100,
         },
       ],
-      series: getSeries(),
+      series: getSeries().map((series, index) => ({
+        ...series,
+        ...(index === 0 && eventRange
+          ? {
+              markArea: {
+                silent: true,
+                itemStyle: { color: "rgba(255, 152, 0, 0.10)" },
+                data: [[
+                  { name: "事件方案时段", xAxis: Date.parse(eventRange.start) },
+                  { xAxis: Date.parse(eventRange.end) },
+                ]],
+              },
+            }
+          : {}),
+      })),
     };
 
     return (
@@ -710,21 +875,12 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
                     <DateTimePicker
                       label="开始时间"
                       value={from}
+                      disabled={isSimulating}
                       onChange={(value) => {
                         if (value && dayjs.isDayjs(value) && value.isValid()) {
                           setFrom(value);
                         }
                       }}
-                      onAccept={(value) => {
-                        if (
-                          value &&
-                          dayjs.isDayjs(value) &&
-                          value.isValid() &&
-                          hasDevices
-                        ) {
-                          handleFetch("date-change");
-                        }
-                      }}
                       maxDateTime={to}
                       slotProps={{
                         textField: { fullWidth: true, size: "small" },
@@ -733,21 +889,12 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
                     <DateTimePicker
                       label="结束时间"
                       value={to}
+                      disabled={isSimulating}
                       onChange={(value) => {
                         if (value && dayjs.isDayjs(value) && value.isValid()) {
                           setTo(value);
                         }
                       }}
-                      onAccept={(value) => {
-                        if (
-                          value &&
-                          dayjs.isDayjs(value) &&
-                          value.isValid() &&
-                          hasDevices
-                        ) {
-                          handleFetch("date-change");
-                        }
-                      }}
                       minDateTime={from}
                       slotProps={{
                         textField: { fullWidth: true, size: "small" },
@@ -755,7 +902,7 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
                     />
                   </Stack>
                   <Stack
-                    direction="row"
+                    direction={{ xs: "column", sm: "row" }}
                     spacing={1}
                     alignItems="center"
                     justifyContent="space-between"
@@ -779,6 +926,23 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
                       />
                     </Tabs>
                     <Stack direction="row" spacing={1}>
+                      {type !== "none" && (
+                        <Tooltip title={canRunSimulation
+                          ? "按管网水力步长计算当前查询时段的在线模拟数据"
+                          : "需要在线模拟运行权限"}>
+                          <span>
+                            <Button
+                              variant="contained"
+                              size="small"
+                              startIcon={isSimulating ? <CircularProgress size={16} color="inherit" /> : <PlayArrow fontSize="small" />}
+                              disabled={!canRunSimulation || !projectId || !hasDevices || !schemeReady || Boolean(schemeError) || isSimulating || loadingState === "loading"}
+                              onClick={() => { void handleOnlineSimulation(); }}
+                            >
+                              {isSimulating ? "模拟中…" : "在线模拟"}
+                            </Button>
+                          </span>
+                        </Tooltip>
+                      )}
                       <Tooltip title="刷新数据">
                         <span>
                           <Button
@@ -786,8 +950,17 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
                             size="small"
                             color="primary"
                             startIcon={<Refresh fontSize="small" />}
-                            disabled={!hasDevices || loadingState === "loading"}
-                            onClick={() => handleFetch("manual")}
+                            disabled={
+                              !hasDevices || !schemeReady || isSimulating || loadingState === "loading"
+                            }
+                            onClick={() => {
+                              if (schemeError) {
+                                setSchemeState(null);
+                                setSchemeReload((value) => value + 1);
+                              } else {
+                                void handleFetch();
+                              }
+                            }}
                           >
                             刷新
                           </Button>
@@ -798,13 +971,34 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
                 </Stack>
               </LocalizationProvider>
 
-              {error && (
+              {eventRange && (
+                <Typography variant="caption" sx={{ mt: 1, display: "block" }}>
+                  事件方案时段：{formatTimestamp(eventRange.start)} ～ {formatTimestamp(eventRange.end)}
+                </Typography>
+              )}
+              {isSimulating && (
+                <Typography role="status" variant="caption" sx={{ mt: 1, display: "block" }}>
+                  正在计算在线模拟数据，完成后将自动刷新图表。
+                </Typography>
+              )}
+              {!isSimulating && type !== "none" && hasDevices && loadingState === "success" &&
+                !historySeries.some((series) => series.source === "realtime_simulation" && series.points.some((point) => point.value !== null)) && (
+                <Typography variant="caption" sx={{ mt: 1, display: "block" }}>
+                  当前时段暂无在线模拟数据。{canRunSimulation ? "可点击“在线模拟”计算。" : ""}
+                </Typography>
+              )}
+              {simulationError && (
+                <Typography role="alert" variant="caption" color="error" sx={{ mt: 1, display: "block" }}>
+                  在线模拟失败：{simulationError}
+                </Typography>
+              )}
+              {(schemeError || error) && (
                 <Typography
                   variant="caption"
                   color="error"
                   sx={{ mt: 1, display: "block" }}
                 >
-                  获取数据失败：{error}
+                  获取数据失败：{schemeError || error}
                 </Typography>
               )}
             </Box>
@@ -813,7 +1007,7 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
 
             {/* Content */}
             <Box sx={{ flex: 1, position: "relative", p: 2, overflow: "auto" }}>
-              {loadingState === "loading" && (
+              {(!schemeReady || loadingState === "loading") && (
                 <Box
                   sx={{
                     position: "absolute",

src/components/threeDimensional/ThreeDimensionalScene.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import Link from "next/link";
+import { NavigationLink } from "@components/loading/NavigationLink";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   FiAlertCircle,
@@ -38,8 +38,8 @@ import {
   type SceneRuntimeState,
 } from "./sceneProtocol";
 
-const SCENE_URL = "/three-dimensional/zjb/v29/preview.html?host=platform2&v=34-detailed-network-context";
-const SCENE_LOAD_TIMEOUT_MS = 30_000;
+const SCENE_URL = "/three-dimensional/zjb/v29/preview.html?host=platform2&v=36-resumable-cache";
+const SCENE_LOAD_TIMEOUT_MS = 120_000;
 
 const initialRuntimeState: SceneRuntimeState = {
   mode: "network",
@@ -138,6 +138,9 @@ export default function ThreeDimensionalScene() {
   const [loading, setLoading] = useState(false);
   const [loadError, setLoadError] = useState<string | null>(null);
   const [sceneError, setSceneError] = useState<string | null>(null);
+  const [sceneLoading, setSceneLoading] = useState(true);
+  const [sceneResourceError, setSceneResourceError] = useState(false);
+  const [sceneStarted, setSceneStarted] = useState(false);
   const [refreshVersion, setRefreshVersion] = useState(0);
   const [sceneKey, setSceneKey] = useState(0);
 
@@ -169,6 +172,9 @@ export default function ThreeDimensionalScene() {
     setSelection(null);
     setRuntimeState(initialRuntimeState);
     setSceneError(null);
+    setSceneLoading(true);
+    setSceneResourceError(false);
+    setSceneStarted(false);
     setSceneKey((value) => value + 1);
   }, []);
 
@@ -198,6 +204,17 @@ export default function ThreeDimensionalScene() {
         });
         setRuntimeState(message.state);
         setSceneError(null);
+        setSceneLoading(false);
+        setSceneResourceError(false);
+        return;
+      }
+      if (message.type === "loading") {
+        if (typeof message.active === "boolean") {
+          setSceneLoading(message.active);
+          setSceneStarted(true);
+          setSceneResourceError(message.failed === true);
+          if (message.active) setSceneError(null);
+        }
         return;
       }
       if (message.type === "scene-state") {
@@ -222,12 +239,14 @@ export default function ThreeDimensionalScene() {
   }, [isZjbProject, sceneKey]);
 
   useEffect(() => {
-    if (!isZjbProject || model) return;
+    // Once the viewer starts, its per-request inactivity timeout owns recovery.
+    // A long but progressing first download should not hit a total-load deadline.
+    if (!isZjbProject || model || !sceneLoading || sceneStarted) return;
     const timerId = window.setTimeout(() => {
       setSceneError("三维模型载入超时，请检查静态资源后重试。");
     }, SCENE_LOAD_TIMEOUT_MS);
     return () => window.clearTimeout(timerId);
-  }, [isZjbProject, model, sceneKey]);
+  }, [isZjbProject, model, sceneKey, sceneLoading, sceneStarted]);
 
   useEffect(() => {
     if (!isZjbProject) return;
@@ -301,9 +320,9 @@ export default function ThreeDimensionalScene() {
             <p className="mt-1 text-sm leading-6 text-slate-600">
               目前仅高铁湛江北站项目提供三维模型。请切换到 ZJB 项目后再打开此页面。
             </p>
-            <Link href="/network-simulation" className="mt-2 inline-flex min-h-10 items-center text-sm font-medium text-blue-700 hover:text-blue-800 hover:underline">
+            <NavigationLink to="/network-simulation" className="mt-2 inline-flex min-h-10 items-center text-sm font-medium text-blue-700 hover:text-blue-800 hover:underline">
               返回管网在线模拟
-            </Link>
+            </NavigationLink>
           </div>
         </section>
       </main>
@@ -324,14 +343,7 @@ export default function ThreeDimensionalScene() {
 
   return (
     <main lang="zh-CN" className="relative h-full min-h-0 overflow-hidden bg-slate-200">
-        <iframe key={sceneKey} ref={iframeRef} src={SCENE_URL} title="高铁湛江北站供水系统三维场景" referrerPolicy="same-origin" className="block h-full w-full border-0" />
-
-        {!model && !sceneError && (
-          <div className="pointer-events-none absolute inset-0 flex flex-col items-center justify-center gap-3 bg-slate-100/55 text-sm text-slate-600 backdrop-blur-sm">
-            <span className="h-8 w-8 animate-spin rounded-full border-[3px] border-blue-200 border-t-blue-600" />
-            正在载入三维模型
-          </div>
-        )}
+        <iframe key={sceneKey} ref={iframeRef} src={SCENE_URL} title="高铁湛江北站供水系统三维场景" referrerPolicy="same-origin" className={`block h-full w-full border-0 ${!model || sceneLoading || sceneResourceError ? "relative z-40" : ""}`} />
 
         {(loadError || sceneError) && (
           <div role="alert" className="absolute left-1/2 top-28 z-40 flex w-[min(560px,calc(100%-24px))] -translate-x-1/2 items-center gap-3 rounded-xl border border-red-200/70 bg-red-50/80 px-4 py-3 text-sm text-red-800 shadow-xl shadow-red-950/10 backdrop-blur-xl md:top-4">
@@ -387,7 +399,7 @@ export default function ThreeDimensionalScene() {
         <ThreeDimensionalControls
           open={controlsOpen}
           activeTab={controlTab}
-          ready={Boolean(model)}
+          ready={Boolean(model) && !sceneLoading && !sceneResourceError}
           state={runtimeState}
           selection={selection}
           timelineOpen={timelineOpen}

src/components/threeDimensional/sceneAssets.test.ts

@@ -21,7 +21,7 @@ describe("ZJB three-dimensional runtime assets", () => {
       renderRevision: number;
       assets: Array<{ file: string; sha256: string }>;
       networkContext: string[];
-      networkModel: { file: string; metadata: string; sha256: string };
+      networkModel: { file: string; metadata: string; sha256: string; metadataSha256: string };
       sourceCatalogFile?: string;
       bindingsFile?: string;
     };
@@ -48,6 +48,9 @@ describe("ZJB three-dimensional runtime assets", () => {
     });
     expect(existsSync(join(sceneRoot, manifest.networkModel.file))).toBe(true);
     expect(existsSync(join(sceneRoot, manifest.networkModel.metadata))).toBe(true);
+    expect(createHash("sha256").update(
+      readFileSync(join(sceneRoot, manifest.networkModel.metadata)),
+    ).digest("hex")).toBe(manifest.networkModel.metadataSha256);
     expect(manifest.sourceCatalogFile).toBeUndefined();
     expect(manifest.bindingsFile).toBeUndefined();
 
@@ -67,6 +70,8 @@ describe("ZJB three-dimensional runtime assets", () => {
       "network-style.mjs",
       "integration.mjs",
       "render-effects.mjs",
+      "resourceCache.mjs",
+      "loadingProgress.mjs",
       "vendor/meshopt_decoder.module.js",
       "vendor/meshoptimizer-LICENSE.md",
       "vendor/three/LICENSE",

src/components/threeDimensional/sceneProtocol.ts

@@ -145,6 +145,7 @@ export type SceneRuntimeMessage = HostMessageBase &
         state: SceneRuntimeState;
       }
     | { type: "scene-state"; state: SceneRuntimeState }
+    | { type: "loading"; active: boolean; failed?: boolean }
     | { type: "selection-changed"; selection: SceneAssetSelection | null }
     | { type: "results-applied"; summary: SceneStyleSummary }
     | { type: "results-cleared" }

src/lib/analysisRuns.test.ts

@@ -2,6 +2,7 @@ import { api } from "@/lib/api";
 import {
   getAnalysisResults,
   getAnalysisScheme,
+  getAnalysisHistoryContext,
   listAnalysisSchemes,
 } from "./analysisRuns";
 
@@ -94,3 +95,49 @@ describe("analysis runs API adapter", () => {
     );
   });
 });
+
+describe("analysis history context", () => {
+  const run = {
+    run_id: "run-1", name: "event", run_type: "burst_analysis",
+    created_by: "alice", created_at: "2026-11-03T05:00:00Z",
+    started_at: "2026-08-25T09:00:00+08:00", status: "completed", parameters: {},
+  };
+
+  it.each([
+    ["burst_analysis", { modify_total_duration: 3600 }],
+    ["flushing_analysis", { duration: 3600 }],
+    ["contaminant_analysis", { duration: 3600 }],
+  ])("uses the simulated interval of %s rather than its creation time", (run_type, parameters) => {
+    expect(getAnalysisHistoryContext({ ...run, run_type, parameters })).toEqual({
+      simulationRunId: "run-1",
+      eventRange: { start: "2026-08-25T01:00:00.000Z", end: "2026-08-25T02:00:00.000Z" },
+    });
+  });
+
+  it("does not treat a detection run as a hydraulic simulation", () => {
+    expect(getAnalysisHistoryContext({
+      ...run, run_type: "burst_detection", parameters: {
+        scada_window: { start: "2026-08-25T01:00:00Z", end: "2026-08-25T02:00:00Z" },
+      },
+    })).toEqual({
+      eventRange: { start: "2026-08-25T01:00:00Z", end: "2026-08-25T02:00:00Z" },
+    });
+  });
+
+  it("uses the linked hydraulic run for a localization analysis", () => {
+    expect(getAnalysisHistoryContext({
+      ...run, run_type: "burst_location", parameters: {
+        result_payload: {
+          simulation_run: { run_id: "simulation-1" },
+          scada_window: { burst_start: "2026-08-25T01:00:00Z", burst_end: "2026-08-25T02:00:00Z" },
+        },
+      },
+    }).simulationRunId).toBe("simulation-1");
+  });
+
+  it("rejects invalid or missing event durations without inventing an interval", () => {
+    expect(getAnalysisHistoryContext(run).eventRange).toBeNull();
+    expect(getAnalysisHistoryContext({ ...run, parameters: { duration: -1 } }).eventRange).toBeNull();
+    expect(getAnalysisHistoryContext({ ...run, started_at: "invalid", parameters: { duration: 3600 } }).eventRange).toBeNull();
+  });
+});

src/lib/analysisRuns.ts

@@ -11,6 +11,66 @@ export type AnalysisRun = {
   parameters: Record<string, unknown>;
 };
 
+export type AnalysisHistoryContext = {
+  simulationRunId?: string;
+  eventRange: { start: string; end: string } | null;
+};
+
+const SIMULATION_RUN_TYPES = new Set([
+  "burst_analysis",
+  "flushing_analysis",
+  "contaminant_analysis",
+  "valve_close_analysis",
+  "pressure_regulation",
+]);
+
+export const getAnalysisHistoryContext = (
+  run: AnalysisRun,
+): AnalysisHistoryContext => {
+  const parameters = normalizeParameters(run.parameters);
+  if (SIMULATION_RUN_TYPES.has(run.run_type)) {
+    const start = Date.parse(run.started_at);
+    const duration = parameters.modify_total_duration ?? parameters.duration;
+    const end = new Date(
+      typeof duration === "number" ? start + duration * 1000 : NaN,
+    ).getTime();
+    return {
+      simulationRunId: run.run_id,
+      eventRange:
+        Number.isFinite(start) && Number.isFinite(end) && end > start
+          ? {
+              start: new Date(start).toISOString(),
+              end: new Date(end).toISOString(),
+            }
+          : null,
+    };
+  }
+
+  const payload = normalizeParameters(parameters.result_payload);
+  const window = normalizeParameters(
+    parameters.scada_window ?? payload.scada_window,
+  );
+  const start = window.burst_start ?? window.start ?? parameters.scada_start;
+  const end = window.burst_end ?? window.end ?? parameters.scada_end;
+  const simulation = normalizeParameters(
+    payload.simulation_run ?? payload.simulation_scheme,
+  );
+  const simulationRunId = parameters.simulation_run_id ?? simulation.run_id;
+  return {
+    simulationRunId:
+      typeof simulationRunId === "string" && simulationRunId.trim()
+        ? simulationRunId.trim()
+        : undefined,
+    eventRange:
+      typeof start === "string" &&
+      typeof end === "string" &&
+      Number.isFinite(Date.parse(start)) &&
+      Date.parse(end) > Date.parse(start)
+        ? { start, end }
+        : null,
+  };
+};
+
 export type AnalysisResult = {
   result_id: string;
   run_id: string;

src/lib/elementHistory.test.ts

@@ -28,8 +28,46 @@ describe("element history display conversion", () => {
     ];
 
     const points = toTimeSeriesPoints(series);
-    expect(points[0].timestamp).toBe("2026-09-01T00:00:00Z");
-    expect(points[0].values["P-1_sim"]).toBeCloseTo(83.3333333334);
+    expect(points[0].timestamp).toBe("2026-09-01T00:00:00.000Z");
+    expect(points[0].values['["pipe","P-1","realtime_simulation"]']).toBeCloseTo(83.3333333334);
     expect(points[0].values["pressure-1_clean"]).toBeCloseTo(1.019716213);
   });
+
+  it("aligns equivalent timestamps and keeps same-name pipes and junctions separate", () => {
+    const base: ElementHistorySeries = {
+      element_id: "shared-id", element_type: "pipe", device_id: null,
+      metric: "flow", source: "realtime_simulation", source_unit: "L/s",
+      display_unit: "m³/h", unit_inferred: false,
+      points: [{ time: "2026-09-01T08:00:00+08:00", value: 10 }],
+    };
+    const points = toTimeSeriesPoints([
+      base,
+      { ...base, element_type: "junction", metric: "pressure", source_unit: "m",
+        points: [{ time: "2026-09-01T00:00:00Z", value: 20 }] },
+      { ...base, source: "analysis_simulation", points: [
+        { time: "2026-09-01T00:00:00.000Z", value: null },
+      ] },
+    ]);
+    expect(points).toHaveLength(1);
+    expect(points[0].values).toEqual({
+      '["pipe","shared-id","realtime_simulation"]': 36,
+      '["junction","shared-id","realtime_simulation"]': 20,
+      '["pipe","shared-id","analysis_simulation"]': null,
+    });
+  });
+
+  it("keeps online IDs ending in _scheme distinct from another element's scheme series", () => {
+    const base: ElementHistorySeries = {
+      element_id: "P_scheme", element_type: "pipe", device_id: null,
+      metric: "flow", source: "realtime_simulation", source_unit: "m3/h",
+      display_unit: "m³/h", unit_inferred: false,
+      points: [{ time: "2026-09-01T00:00:00Z", value: 100 }],
+    };
+    const points = toTimeSeriesPoints([
+      base,
+      { ...base, element_id: "P", source: "analysis_simulation",
+        points: [{ time: "2026-09-01T00:00:00Z", value: 5 }] },
+    ]);
+    expect(Object.values(points[0].values).sort((a, b) => Number(a) - Number(b))).toEqual([5, 100]);
+  });
 });

src/lib/elementHistory.ts

@@ -49,8 +49,10 @@ const SOURCE_SUFFIX: Record<HistorySource, string> = {
   analysis_simulation: "scheme_sim",
 };
 
-export const historySeriesKey = (series: ElementHistorySeries) =>
-  `${series.device_id ?? series.element_id}_${SOURCE_SUFFIX[series.source]}`;
+export const historySeriesKey = (series: ElementHistorySeries) => {
+  if (series.device_id) return `${series.device_id}_${SOURCE_SUFFIX[series.source]}`;
+  return JSON.stringify([series.element_type, series.element_id, series.source]);
+};
 
 export const historySourceLabel = (source: HistorySource) => {
   switch (source) {
@@ -65,8 +67,11 @@ export const historySourceLabel = (source: HistorySource) => {
   }
 };
 
-export const historySeriesLabel = (series: ElementHistorySeries) =>
-  `${series.device_id ?? series.element_id} (${historySourceLabel(series.source)})`;
+export const historySeriesLabel = (series: ElementHistorySeries) => {
+  const target = series.device_id ??
+    `${series.element_type === "pipe" ? "管道" : "节点"} ${series.element_id}`;
+  return `${target} (${historySourceLabel(series.source)})`;
+};
 
 export const toTimeSeriesPoints = (
   seriesList: ElementHistorySeries[],
@@ -75,13 +80,14 @@ export const toTimeSeriesPoints = (
   seriesList.forEach((series) => {
     const key = historySeriesKey(series);
     series.points.forEach((point) => {
-      const values = timeMap.get(point.time) ?? {};
+      const timestamp = new Date(point.time).toISOString();
+      const values = timeMap.get(timestamp) ?? {};
       values[key] = toDisplayValue(
         point.value,
         series.metric,
         series.source_unit,
       );
-      timeMap.set(point.time, values);
+      timeMap.set(timestamp, values);
     });
   });
   return Array.from(timeMap, ([timestamp, values]) => ({ timestamp, values })).sort(

src/lib/onlineSimulation.test.ts

@@ -0,0 +1,86 @@
+import { apiFetch } from "@/lib/apiFetch";
+import { useProjectStore } from "@/store/projectStore";
+import { alignSimulationRange, parseHydraulicStepSeconds, runOnlineSimulation } from "./onlineSimulation";
+
+jest.mock("@/lib/apiFetch", () => ({ apiFetch: jest.fn() }));
+
+const response = (body: unknown, ok = true) => ({
+  ok, json: async () => body,
+}) as Response;
+
+describe("online simulation time alignment", () => {
+  it.each([["0:15", 900], ["00:05:00", 300], ["1:00", 3600], ["0:00:30", 30]])(
+    "reads the configured step %s", (clock, seconds) => {
+      expect(parseHydraulicStepSeconds(clock)).toBe(seconds);
+    },
+  );
+
+  it.each(["0:00", "0:60", "0:00:60", "15", "invalid", undefined])(
+    "does not invent a step from invalid config %s", (clock) => {
+      expect(parseHydraulicStepSeconds(clock)).toBeUndefined();
+    },
+  );
+
+  it("aligns the screenshot's range to 15-minute clock boundaries", () => {
+    const range = alignSimulationRange({
+      from: new Date("2026-07-30T12:38:42+08:00"),
+      to: new Date("2026-07-30T15:38:42+08:00"),
+    }, 900);
+    expect(range.from.toISOString()).toBe("2026-07-30T04:30:00.000Z");
+    expect(range.to.toISOString()).toBe("2026-07-30T07:45:00.000Z");
+  });
+
+  it("keeps aligned endpoints and handles ranges crossing midnight", () => {
+    const range = alignSimulationRange({
+      from: new Date("2026-07-30T23:50:00+08:00"),
+      to: new Date("2026-07-31T00:10:00+08:00"),
+    }, 900);
+    expect(range.from.toISOString()).toBe("2026-07-30T15:45:00.000Z");
+    expect(range.to.toISOString()).toBe("2026-07-30T16:15:00.000Z");
+    expect(alignSimulationRange(range, 900)).toEqual(range);
+  });
+});
+
+describe("online simulation request", () => {
+  const range = {
+    from: new Date("2026-07-30T12:38:00+08:00"),
+    to: new Date("2026-07-30T15:38:00+08:00"),
+  };
+  beforeEach(() => {
+    jest.mocked(apiFetch).mockReset();
+    useProjectStore.getState().setCurrentProject("project-1", "network-1");
+  });
+
+  it("runs the full snapped range including the right endpoint, without network fields", async () => {
+    jest.mocked(apiFetch).mockResolvedValueOnce(response({ times: { "HYDRAULIC TIMESTEP": "0:15" } }))
+      .mockResolvedValueOnce(response({ status: "success" }));
+    const result = await runOnlineSimulation(range);
+    expect(result.range.to.toISOString()).toBe("2026-07-30T07:45:00.000Z");
+    expect(JSON.parse(String(jest.mocked(apiFetch).mock.calls[1][1]?.body))).toEqual({
+      start_time: "2026-07-30T04:30:00.000Z", duration: 210,
+    });
+    expect(String(jest.mocked(apiFetch).mock.calls[1][0])).toContain("/api/v1/simulation-runs");
+  });
+
+  it("refuses to calculate with a missing hydraulic step", async () => {
+    jest.mocked(apiFetch).mockResolvedValue(response({}));
+    await expect(runOnlineSimulation(range)).rejects.toThrow("水力时间步长无效");
+    expect(apiFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not submit a write if the project changed during the config read", async () => {
+    jest.mocked(apiFetch).mockImplementationOnce(async () => {
+      useProjectStore.getState().setCurrentProject("project-2", "network-2");
+      return response({ "HYDRAULIC TIMESTEP": "0:15" });
+    });
+    await expect(runOnlineSimulation(range)).rejects.toThrow("项目已切换");
+    expect(apiFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not retry or treat a queued acknowledgment as completion", async () => {
+    jest.mocked(apiFetch).mockResolvedValueOnce(response({ "HYDRAULIC TIMESTEP": "0:15" }))
+      .mockResolvedValueOnce(response({ status: "queued" }));
+    await expect(runOnlineSimulation(range)).rejects.toThrow("未确认完成");
+    expect(apiFetch).toHaveBeenCalledTimes(2);
+  });
+});

src/lib/onlineSimulation.ts

@@ -0,0 +1,79 @@
+import dayjs from "dayjs";
+import utc from "dayjs/plugin/utc";
+import timezone from "dayjs/plugin/timezone";
+import config from "@/config/config";
+import { apiFetch } from "@/lib/apiFetch";
+import { useProjectStore } from "@/store/projectStore";
+
+dayjs.extend(utc);
+dayjs.extend(timezone);
+
+export type SimulationRange = { from: Date; to: Date };
+
+export const parseHydraulicStepSeconds = (value: unknown): number | undefined => {
+  if (typeof value !== "string" || !/^\d+:\d{1,2}(:\d{1,2})?$/.test(value.trim())) {
+    return undefined;
+  }
+  const [hours, minutes, seconds = 0] = value.trim().split(":").map(Number);
+  const step = hours * 3600 + minutes * 60 + seconds;
+  return minutes < 60 && seconds < 60 && step > 0 ? step : undefined;
+};
+
+/** 与地图时间轴一致，以北京时间零点为基准向外取整，跨日仍保持同一步长。 */
+export const alignSimulationRange = (
+  range: SimulationRange,
+  stepSeconds: number,
+): SimulationRange => {
+  if (!Number.isFinite(stepSeconds) || stepSeconds <= 0 ||
+    !Number.isFinite(range.from.getTime()) || !Number.isFinite(range.to.getTime())) {
+    throw new Error("查询时间或水力时间步长无效");
+  }
+  const start = Math.min(range.from.getTime(), range.to.getTime());
+  const end = Math.max(range.from.getTime(), range.to.getTime());
+  const origin = dayjs(start).tz("Asia/Shanghai").startOf("day").valueOf();
+  const step = stepSeconds * 1000;
+  const from = origin + Math.floor((start - origin) / step) * step;
+  const to = Math.max(from + step, origin + Math.ceil((end - origin) / step) * step);
+  return { from: new Date(from), to: new Date(to) };
+};
+
+/** 复用同步在线模拟接口，成功响应表示计算和保存已完成；不自动重试写请求。 */
+export const runOnlineSimulation = async (
+  range: SimulationRange,
+  signal?: AbortSignal,
+): Promise<{ range: SimulationRange; stepSeconds: number }> => {
+  const projectId = useProjectStore.getState().currentProjectId;
+  if (!projectId) throw new Error("请先选择项目，未启动在线模拟");
+  const projectHeaders = { "X-Project-Id": projectId };
+  const timeResponse = await apiFetch(
+    `${config.BACKEND_URL}/api/v1/network-options/time`, {
+      signal, headers: projectHeaders, projectHeaderMode: "omit",
+    },
+  );
+  if (!timeResponse.ok) throw new Error("无法读取管网时间步长，未启动在线模拟");
+  const payload = await timeResponse.json();
+  const stepSeconds = parseHydraulicStepSeconds(
+    (payload?.times ?? payload)?.["HYDRAULIC TIMESTEP"],
+  );
+  if (!stepSeconds) throw new Error("管网水力时间步长无效，未启动在线模拟");
+  if (signal?.aborted || useProjectStore.getState().currentProjectId !== projectId) {
+    throw new Error("项目已切换或面板已关闭，未启动在线模拟");
+  }
+  const alignedRange = alignSimulationRange(range, stepSeconds);
+  const response = await apiFetch(`${config.BACKEND_URL}/api/v1/simulation-runs`, {
+    method: "POST",
+    headers: { ...projectHeaders, "Content-Type": "application/json" },
+    projectHeaderMode: "omit",
+    // 后端循环的结束时间不包含在计算内，多算一个步长以覆盖图表右端点。
+    body: JSON.stringify({
+      start_time: alignedRange.from.toISOString(),
+      duration: Math.ceil((alignedRange.to.getTime() - alignedRange.from.getTime() + stepSeconds * 1000) / 60000),
+    }),
+    signal,
+  });
+  const result = await response.json().catch(() => null);
+  if (!response.ok || result?.status !== "success") {
+    throw new Error(typeof result?.detail === "string" ? result.detail : "在线模拟未确认完成，请刷新查看已生成的数据");
+  }
+  return { range: alignedRange, stepSeconds };
+};