fix(auth): preserve intentional logout across browser return

Keep a bounded per-tab logout intent and broadcast it to already open tabs so back navigation after a normal logout is not mistaken for renewal failure. Preserve real refresh and session expiry signals, and keep IdP navigation reachable when local cleanup fails.

contracts/manifest.json

@@ -7,7 +7,7 @@
     },
     "server": {
       "file": "server-v1.openapi.json",
-      "sha256": "b565d841061c9091f48ff3118bcc0cbb1b918b0cb8c2316d177570e8b2d8ba29"
+      "sha256": "1edfd78405cfe2a50022afe70a4c4f32caa4e98e3b5b54b40841d532058f2fd6"
     }
   }
 }

contracts/server-v1.openapi.json

@@ -1201,6 +1201,59 @@
         "type": "string"
       },
       "JsonValue": {},
+      "KeycloakUserSyncIssue": {
+        "properties": {
+          "reason": {
+            "title": "Reason",
+            "type": "string"
+          },
+          "username": {
+            "title": "Username",
+            "type": "string"
+          }
+        },
+        "required": [
+          "username",
+          "reason"
+        ],
+        "title": "KeycloakUserSyncIssue",
+        "type": "object"
+      },
+      "KeycloakUserSyncResponse": {
+        "properties": {
+          "created": {
+            "title": "Created",
+            "type": "integer"
+          },
+          "issues": {
+            "items": {
+              "$ref": "#/components/schemas/KeycloakUserSyncIssue"
+            },
+            "title": "Issues",
+            "type": "array"
+          },
+          "scanned": {
+            "title": "Scanned",
+            "type": "integer"
+          },
+          "skipped": {
+            "title": "Skipped",
+            "type": "integer"
+          },
+          "updated": {
+            "title": "Updated",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "scanned",
+          "created",
+          "updated",
+          "skipped"
+        ],
+        "title": "KeycloakUserSyncResponse",
+        "type": "object"
+      },
       "LeakageIdentifyRequestRest": {
         "properties": {
           "dma_count": {
@@ -3201,6 +3254,92 @@
         ]
       }
     },
+    "/api/v1/admin/keycloak-user-syncs": {
+      "post": {
+        "operationId": "post_admin_keycloak_user_syncs",
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/KeycloakUserSyncResponse"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            },
+            "description": "Authentication required"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            },
+            "description": "Insufficient permission"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            },
+            "description": "Resource not found"
+          },
+          "409": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            },
+            "description": "Resource conflict"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            },
+            "description": "Validation error"
+          },
+          "503": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            },
+            "description": "Dependency unavailable"
+          }
+        },
+        "security": [
+          {
+            "OAuth2PasswordBearer": []
+          }
+        ],
+        "summary": "Sync Keycloak User Directory",
+        "tags": [
+          "Metadata Admin"
+        ]
+      }
+    },
     "/api/v1/admin/project-provisions": {
       "post": {
         "operationId": "post_admin_project_provisions",
@@ -35969,6 +36108,23 @@
               "type": "array"
             }
           },
+          {
+            "description": "事故要素类型；auto优先管段再节点；分析同名节点须指定node，纯管段分析可指定link",
+            "in": "query",
+            "name": "accident_element_type",
+            "required": false,
+            "schema": {
+              "default": "auto",
+              "description": "事故要素类型；auto优先管段再节点；分析同名节点须指定node，纯管段分析可指定link",
+              "enum": [
+                "auto",
+                "link",
+                "node"
+              ],
+              "title": "Accident Element Type",
+              "type": "string"
+            }
+          },
           {
             "in": "header",
             "name": "X-Project-Id",

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/authenticated.spec.ts

@@ -15,3 +15,76 @@ test("已登录管理员可以打开审计日志页面", async ({ page }) => {
   await expect(page.getByText("系统管理员权限已验证")).toBeVisible();
   await expect(page.getByRole("heading", { name: "查询结果" })).toBeVisible();
 });
+
+test("已认证但未授权的账号会看到明确说明", async ({ page }) => {
+  await page.addInitScript(() => window.localStorage.clear());
+  await page.route("**/api/v1/access-context", (route) =>
+    route.fulfill({
+      status: 403,
+      contentType: "application/json",
+      body: JSON.stringify({ detail: "User authorization pending" }),
+    }),
+  );
+
+  await page.goto("/");
+
+  await expect(page.getByText("账号尚未获得访问权限")).toBeVisible();
+  await expect(
+    page.getByText("身份认证已成功，但当前账号尚未由系统管理员启用"),
+  ).toBeVisible();
+  const accountMenu = page.getByRole("button", {
+    name: "E2E 测试用户 账号菜单",
+  });
+  await expect(accountMenu).toBeVisible();
+  await accountMenu.click();
+  await expect(page.getByRole("menuitem", { name: "登出" })).toBeVisible();
+  await expect(page.getByRole("menuitem", { name: "切换项目" })).toHaveCount(0);
+  await page.keyboard.press("Escape");
+
+  await page.setViewportSize({ width: 390, height: 844 });
+  await expect(page.getByText("账号尚未获得访问权限")).toBeVisible();
+  await expect(accountMenu).toBeVisible();
+});
+
+test("无权访问项目时可以在窄屏切换项目", async ({ page }) => {
+  await page.route("**/api/v1/access-context", (route) =>
+    route.fulfill({
+      status: 403,
+      contentType: "application/json",
+      body: JSON.stringify({ detail: "No access to project" }),
+    }),
+  );
+
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.goto("/");
+
+  await expect(page.getByText("无权访问当前项目")).toBeVisible();
+  await page
+    .getByRole("button", { name: "E2E 测试用户 账号菜单" })
+    .click();
+  await page.getByRole("menuitem", { name: "切换项目" }).click();
+
+  const projectDialog = page.getByRole("dialog");
+  await expect(projectDialog).toBeVisible();
+  const bounds = await projectDialog.boundingBox();
+  expect(bounds).not.toBeNull();
+  expect(bounds!.x).toBeGreaterThanOrEqual(0);
+  expect(bounds!.x + bounds!.width).toBeLessThanOrEqual(390);
+});
+
+test("系统管理员可以手动同步 Keycloak 用户目录", async ({ page }) => {
+  await page.goto("/system-admin");
+  await page.getByRole("tab", { name: "系统用户" }).click();
+
+  await page.getByRole("button", { name: "同步 Keycloak 用户" }).click();
+  await expect(page.getByRole("button", { name: "正在同步" })).toBeDisabled();
+
+  await expect(
+    page.getByText("已扫描 3 个 Keycloak 身份，新增 1 个，更新 1 个，跳过 1 个。"),
+  ).toBeVisible();
+  await expect(page.getByText("跳过项包括服务账号、缺少邮箱或身份冲突")).toBeVisible();
+
+  await page.setViewportSize({ width: 390, height: 844 });
+  await expect(page.getByRole("button", { name: "同步 Keycloak 用户" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "刷新", exact: true })).toBeVisible();
+});

e2e/support/mockBackend.ts

@@ -50,10 +50,27 @@ export const mockBackend = async (page: Page) => {
       return json(route, { count: 0 });
     }
 
+    if (
+      url.pathname === "/api/v1/admin/keycloak-user-syncs" &&
+      route.request().method() === "POST"
+    ) {
+      await new Promise((resolve) => setTimeout(resolve, 150));
+      return json(route, {
+        scanned: 3,
+        created: 1,
+        updated: 1,
+        skipped: 1,
+        issues: [{ username: "no-email", reason: "missing_email" }],
+      });
+    }
+
     if (
       url.pathname === "/api/v1/audit-logs" ||
       url.pathname === "/api/v1/admin/users" ||
-      url.pathname === "/api/v1/admin/projects"
+      url.pathname === "/api/v1/admin/projects" ||
+      /^\/api\/v1\/admin\/projects\/[^/]+\/(members|databases)$/.test(
+        url.pathname,
+      )
     ) {
       return json(route, []);
     }

e2e/three-dimensional-loading.spec.ts

@@ -1,7 +1,7 @@
 import { expect, test } from "@playwright/test";
 
 const root = "/three-dimensional/zjb/v29/";
-const preview = root + "preview.html?host=platform2&v=35-resource-cache";
+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);
@@ -28,7 +28,7 @@ test("HTTP 200 的错误元数据不会进入缓存，服务器恢复后重试
   expect(cached).toBe(false);
   await page.getByRole("button", { name: "重新载入场景" }).click();
   await expect(page.locator("#boot")).toBeHidden({ timeout: 60_000 });
-  expect(requests).toBe(2);
+  expect(requests).toBe(5);
 });
 
 test("模型和元数据跨页面复用持久缓存，即使服务器资源不可用也能重开场景", async ({ page, context }) => {
@@ -46,7 +46,7 @@ test("模型和元数据跨页面复用持久缓存，即使服务器资源不
   await page.goto(preview);
   await expect(page.locator("#boot")).toBeHidden({ timeout: 60_000 });
   const coldMs = Date.now() - coldStart;
-  expect(requests).toHaveLength(10);
+  expect(new Set(requests).size).toBe(10);
   requests.length = 0;
   block = true;
   await page.close();
@@ -140,7 +140,7 @@ test("HTTP 错误和解析失败不会写入缓存，下一次请求可恢复",
   await page.route("**/cache-probe.json*", (route) => {
     requests++;
     return requests === 1
-      ? route.fulfill({ status: 503, body: "unavailable" })
+      ? route.fulfill({ status: 404, body: "not found" })
       : requests === 2
         ? route.fulfill({ body: "invalid json" })
         : route.fulfill({ json: { ok: true } });
@@ -160,6 +160,145 @@ test("HTTP 错误和解析失败不会写入缓存，下一次请求可恢复",
   }, root);
   expect(requests).toBe(3);
   expect(result.errors).toHaveLength(2);
-  expect(result.errors[0]).toContain("HTTP 503");
+  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/loadingProgress.mjs

@@ -32,12 +32,13 @@ export function reportProgress(update) {
  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 = `${parsing ? '正在解析模型' : downloading ? '正在下载资源' : cached ? '正在读取本地缓存' : '正在准备场景'} · 已读取 ${formatBytes(loaded)}`;
+ detail.textContent = `${retrying ? '连接中断，正在从断点重试' : parsing ? '正在解析模型' : downloading ? '正在下载资源' : cached ? '正在读取本地缓存' : '正在准备场景'} · 已读取 ${formatBytes(loaded)}`;
 }
 
 export function finishLoading() {

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

@@ -36,8 +36,8 @@
     </div>
     <output id="qa" hidden></output>
     <script type="module">
-      import {failLoading} from './loadingProgress.mjs?v=35-resource-cache';
-      import('./preview.mjs?v=35-resource-cache').catch(failLoading);
+      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,7 +1,7 @@
 import {createRenderEffects} from './render-effects.mjs';
-import {createCameraNavigation,framePose} from './camera-navigation.mjs?v=35-resource-cache';
-import {createSceneResourceCache} from './resourceCache.mjs?v=35-resource-cache';
-import {beginLoading,reportProgress,finishLoading,failLoading} from './loadingProgress.mjs?v=35-resource-cache';
+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';

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

@@ -2,6 +2,8 @@
 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 => {
@@ -54,39 +56,111 @@ export function createSceneResourceCache(baseUrl, onProgress = () => {}) {
 
   // 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);
    };
-  report('download');
    resetTimeout();
-  let data;
    try {
-   const response = await fetch(url, {signal:controller.signal, cache:'no-cache'});
-   if (!response.ok) throw Error('HTTP ' + response.status);
-   const total = Number(response.headers.get('content-length')) || 0;
+    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();
-    const chunks = [];
-    let loaded = 0;
+     try {
       while (true) {
        const {done, value} = await reader.read();
        if (done) break;
-     chunks.push(value); loaded += value.byteLength;
-     report('download', loaded, total); resetTimeout();
+       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(chunk, offset); offset += chunk.byteLength; }
-    data = bytes.buffer;
-   } else {
-    data = await response.arrayBuffer();
+  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. */ }
   }
-  } catch (error) {
-   throw Error(file + '：' + (controller.signal.aborted ? '下载超时，请重试' : error.message));
-  } finally { clearTimeout(timer); }
 
   report('parse', data.byteLength, data.byteLength);
   // Validate/parse before persisting so an HTML error page or bad GLB cannot poison the cache.

src/app/RefineContext.test.tsx

@@ -3,12 +3,17 @@ import type { ReactNode } from "react";
 
 import { useAccessStore } from "@/store/accessStore";
 import { useAuthStore } from "@/store/authStore";
+import {
+  clearIntentionalLogout,
+  markIntentionalLogout,
+} from "@/lib/logoutIntent";
 import { App } from "./RefineContext";
 
 let mockSessionState: {
   data: {
     accessToken: string;
     user: { id: string; name: string };
+    error?: "RefreshAccessTokenError" | "SessionExpired";
   } | null;
   status: "authenticated" | "unauthenticated";
 } = {
@@ -18,6 +23,8 @@ let mockSessionState: {
   },
   status: "authenticated",
 };
+let mockPathname = "/network-simulation";
+let mockProjectProviderBlocks = false;
 
 jest.mock("next-auth/react", () => ({
   SessionProvider: ({ children }: { children: ReactNode }) => children,
@@ -26,7 +33,7 @@ jest.mock("next-auth/react", () => ({
 }));
 
 jest.mock("next/navigation", () => ({
-  usePathname: () => "/network-simulation",
+  usePathname: () => mockPathname,
 }));
 
 jest.mock("@refinedev/core", () => ({
@@ -43,6 +50,11 @@ jest.mock("@refinedev/mui", () => ({
 }));
 
 jest.mock("@refinedev/nextjs-router", () => ({}));
+jest.mock("@/components/header", () => ({
+  Header: ({ accessMode }: { accessMode: string }) => (
+    <div data-testid="access-header">{accessMode}</div>
+  ),
+}));
 jest.mock("@providers/data-provider", () => ({ dataProvider: {} }));
 jest.mock("@/providers/notification-provider/useAppNotificationProvider", () => ({
   useAppNotificationProvider: {},
@@ -51,7 +63,8 @@ jest.mock("@contexts/color-mode", () => ({
   ColorModeContextProvider: ({ children }: { children: ReactNode }) => children,
 }));
 jest.mock("@/contexts/ProjectContext", () => ({
-  ProjectProvider: ({ children }: { children: ReactNode }) => children,
+  ProjectProvider: ({ children }: { children: ReactNode }) =>
+    mockProjectProviderBlocks ? <div>请选择项目环境</div> : children,
 }));
 jest.mock("@/lib/authToken", () => ({
   getAccessToken: jest.fn().mockResolvedValue("expired-access-token"),
@@ -62,6 +75,9 @@ describe("RefineContext access authentication", () => {
   const originalRequest = global.Request;
 
   beforeEach(() => {
+    clearIntentionalLogout();
+    mockPathname = "/network-simulation";
+    mockProjectProviderBlocks = false;
     mockSessionState = {
       data: {
         accessToken: "expired-access-token",
@@ -115,6 +131,54 @@ describe("RefineContext access authentication", () => {
     });
   });
 
+  it("shows an authorization message when access-context rejects the account", async () => {
+    mockProjectProviderBlocks = true;
+    global.fetch = jest.fn().mockResolvedValue({
+      ok: false,
+      status: 403,
+      headers: new Headers(),
+      json: async () => ({ detail: "User authorization pending" }),
+    } as Response);
+
+    render(
+      <App>
+        <div>应用内容</div>
+      </App>,
+    );
+
+    expect(
+      await screen.findByText("账号尚未获得访问权限"),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("access-header")).toHaveTextContent("account");
+    expect(screen.queryByText("应用内容")).not.toBeInTheDocument();
+    expect(useAuthStore.getState()).toMatchObject({
+      sessionExpired: false,
+      sessionExpiryReason: null,
+    });
+  });
+
+  it("keeps project recovery available when the selected project is denied", async () => {
+    global.fetch = jest.fn().mockResolvedValue({
+      ok: false,
+      status: 403,
+      headers: new Headers(),
+      json: async () => ({ detail: "No access to project" }),
+    } as Response);
+
+    render(
+      <App>
+        <div>应用内容</div>
+      </App>,
+    );
+
+    expect(await screen.findByText("无权访问当前项目")).toBeInTheDocument();
+    expect(
+      screen.queryByRole("button", { name: "切换项目" }),
+    ).not.toBeInTheDocument();
+    expect(screen.getByTestId("access-header")).toHaveTextContent("project");
+    expect(screen.queryByText("应用内容")).not.toBeInTheDocument();
+  });
+
   it("prioritizes an unauthenticated session over route permissions", async () => {
     mockSessionState = { data: null, status: "unauthenticated" };
 
@@ -134,4 +198,81 @@ describe("RefineContext access authentication", () => {
       });
     });
   });
+
+  it("does not treat an intentional logout landing on login as session expiry", async () => {
+    mockPathname = "/login";
+    mockSessionState = { data: null, status: "unauthenticated" };
+
+    render(
+      <App>
+        <div>登录页面</div>
+      </App>,
+    );
+
+    await waitFor(() => {
+      expect(useAuthStore.getState()).toMatchObject({
+        sessionExpired: false,
+        sessionExpiryReason: null,
+      });
+    });
+  });
+
+  it("does not treat returning to a protected route after logout as session expiry", async () => {
+    markIntentionalLogout();
+    mockSessionState = { data: null, status: "unauthenticated" };
+    useAuthStore.setState({
+      accessToken: null,
+      sessionExpired: true,
+      sessionExpiryReason: "refresh_failed",
+    });
+
+    render(
+      <App>
+        <div>应用内容</div>
+      </App>,
+    );
+
+    await waitFor(() => {
+      expect(useAuthStore.getState()).toMatchObject({
+        sessionExpired: false,
+        sessionExpiryReason: null,
+      });
+    });
+  });
+
+  it("does not hide a real refresh failure after an intentional logout", async () => {
+    markIntentionalLogout();
+    mockSessionState = {
+      data: {
+        accessToken: "expired-access-token",
+        user: { id: "user-1", name: "Test User" },
+        error: "RefreshAccessTokenError",
+      },
+      status: "authenticated",
+    };
+
+    const { rerender } = render(
+      <App>
+        <div>应用内容</div>
+      </App>,
+    );
+
+    await waitFor(() => {
+      expect(useAuthStore.getState()).toMatchObject({
+        sessionExpired: true,
+        sessionExpiryReason: "refresh_failed",
+      });
+    });
+
+    mockSessionState = { data: null, status: "unauthenticated" };
+    rerender(
+      <App>
+        <div>应用内容</div>
+      </App>,
+    );
+
+    await waitFor(() => {
+      expect(useAuthStore.getState().sessionExpired).toBe(true);
+    });
+  });
 });

src/app/RefineContext.tsx

@@ -9,7 +9,7 @@ import { RefineKbar, RefineKbarProvider } from "@refinedev/kbar";
 import { RefineSnackbarProvider } from "@refinedev/mui";
 import { SessionProvider, signIn, useSession } from "next-auth/react";
 import { usePathname } from "next/navigation";
-import React, { useEffect } from "react";
+import React, { useEffect, useState } from "react";
 
 import routerProvider from "@refinedev/nextjs-router";
 import { NavigationLink } from "@components/loading/NavigationLink";
@@ -24,6 +24,10 @@ import { useAccessStore } from "@/store/accessStore";
 import { useProjectStore } from "@/store/projectStore";
 import { apiFetch } from "@/lib/apiFetch";
 import { completeLogout, reportLogoutAudit } from "@/lib/logoutFlow";
+import {
+  clearIntentionalLogout,
+  isIntentionalLogout,
+} from "@/lib/logoutIntent";
 import { clearSessionRecoveryDrafts } from "@/lib/sessionRecoveryDraft";
 import { permissionCodes, resourcePermissions } from "@/lib/permissions";
 import { config } from "@config/config";
@@ -75,6 +79,9 @@ export const App = (props: React.PropsWithChildren<AppProps>) => {
   const setAccessContext = useAccessStore((state) => state.setContext);
   const setAccessLoading = useAccessStore((state) => state.setLoading);
   const resetAccess = useAccessStore((state) => state.reset);
+  const [accessDeniedReason, setAccessDeniedReason] = useState<
+    "account" | "project" | null
+  >(null);
   const can = (permission: string) => permissions.includes(permission);
 
   useEffect(() => {
@@ -85,39 +92,64 @@ export const App = (props: React.PropsWithChildren<AppProps>) => {
 
   useEffect(() => {
     if (data?.error === "SessionExpired") {
+      clearIntentionalLogout();
       markSessionExpired("session_max_age");
       return;
     }
     if (data?.error === "RefreshAccessTokenError") {
+      clearIntentionalLogout();
       markSessionExpired("refresh_failed");
       return;
     }
     if (status === "unauthenticated") {
+      if (to === "/login" || isIntentionalLogout()) {
+        clearSessionExpired();
+        return;
+      }
       markSessionExpired("unauthorized");
       return;
     }
     if (status === "authenticated") {
+      clearIntentionalLogout();
       clearSessionExpired();
     }
-  }, [clearSessionExpired, data?.error, markSessionExpired, status]);
+  }, [clearSessionExpired, data?.error, markSessionExpired, status, to]);
 
   useEffect(() => {
     if (status !== "authenticated") {
+      setAccessDeniedReason(null);
       resetAccess();
       return;
     }
 
     let cancelled = false;
+    setAccessDeniedReason(null);
     setAccessLoading(true);
     apiFetch(`${config.BACKEND_URL}/api/v1/access-context`, {
       projectHeaderMode: currentProjectId ? "include" : "omit",
     })
       .then(async (response) => {
         if (cancelled) return;
+        if (response.status === 403) {
+          let detail = "";
+          try {
+            const payload = await response.json();
+            detail = typeof payload?.detail === "string" ? payload.detail : "";
+          } catch {
+            // Treat an unparseable 403 as a project access failure so the user
+            // keeps a recovery path instead of being trapped in the account shell.
+          }
+          setAccessDeniedReason(
+            detail === "User authorization pending" ? "account" : "project",
+          );
+          resetAccess();
+          return;
+        }
         if (!response.ok) {
           resetAccess();
           return;
         }
+        setAccessDeniedReason(null);
         setAccessContext(await response.json());
       })
       .catch(() => {
@@ -157,15 +189,7 @@ export const App = (props: React.PropsWithChildren<AppProps>) => {
     return <span>loading...</span>;
   }
 
-  const authProvider: AuthProvider = {
-    login: async () => {
-      signIn("keycloak", {
-        callbackUrl: to ? to.toString() : "/",
-        redirect: true,
-      });
-      return { success: true };
-    },
-    logout: () =>
+  const handleLogout = () =>
     completeLogout({
       reportAudit: () =>
         reportLogoutAudit({
@@ -176,13 +200,26 @@ export const App = (props: React.PropsWithChildren<AppProps>) => {
               : useAuthStore.getState().accessToken,
         }),
       clearLocalState: () => {
+        const authStore = useAuthStore.getState();
+        authStore.setAccessToken(null);
+        authStore.clearSessionExpired();
         if (data?.user?.id) {
           sessionStorage.removeItem(`tjwater-login-audit:${data.user.id}`);
         }
         clearSessionRecoveryDrafts();
       },
       navigate: (path) => window.location.assign(path),
-      }),
+    });
+
+  const authProvider: AuthProvider = {
+    login: async () => {
+      signIn("keycloak", {
+        callbackUrl: to ? to.toString() : "/",
+        redirect: true,
+      });
+      return { success: true };
+    },
+    logout: handleLogout,
     onError: async (error) => {
       return { error };
     },
@@ -375,7 +412,6 @@ export const App = (props: React.PropsWithChildren<AppProps>) => {
   ];
 
   return (
-    <ProjectProvider>
     <RefineKbarProvider>
       <ColorModeContextProvider defaultMode={props.defaultMode}>
         <RefineSnackbarProvider>
@@ -392,14 +428,18 @@ export const App = (props: React.PropsWithChildren<AppProps>) => {
             }}
           >
             <SessionExpiryDialog expiresAt={data?.sessionExpiresAt} />
-              <RoutePermissionGuard authenticated={status === "authenticated"}>
+            <RoutePermissionGuard
+              authenticated={status === "authenticated"}
+              accessDeniedReason={accessDeniedReason}
+            >
+              <ProjectProvider>
                 {props.children}
+              </ProjectProvider>
             </RoutePermissionGuard>
             <RefineKbar />
           </Refine>
         </RefineSnackbarProvider>
       </ColorModeContextProvider>
     </RefineKbarProvider>
-    </ProjectProvider>
   );
 };

src/app/api/auth/[...nextauth]/options.test.ts

@@ -1,5 +1,36 @@
 import authOptions from "./options";
 
+describe("Keycloak profile mapping", () => {
+  const mapProfile = authOptions.providers[0].profile as (profile: {
+    sub: string;
+    preferred_username: string;
+    name?: string;
+    email?: string;
+    picture?: string;
+  }) => { image?: string | null };
+
+  it("uses the Keycloak picture instead of a shared local avatar", () => {
+    expect(
+      mapProfile({
+        sub: "user-1",
+        preferred_username: "zjb",
+        picture: "https://keycloak.example/avatar/zjb.png",
+      }),
+    ).toMatchObject({
+      image: "https://keycloak.example/avatar/zjb.png",
+    });
+  });
+
+  it("leaves the image empty when Keycloak has no picture", () => {
+    const profile = mapProfile({
+      sub: "user-1",
+      preferred_username: "zjb",
+    });
+
+    expect(profile.image).toBeUndefined();
+  });
+});
+
 describe("NextAuth access token refresh", () => {
   it("forces a Keycloak refresh for an agent credential request", async () => {
     const previousEnv = {

src/app/api/auth/[...nextauth]/options.ts

@@ -1,7 +1,6 @@
 import { NextAuthOptions } from "next-auth";
 import { JWT } from "next-auth/jwt";
 import KeycloakProvider from "next-auth/providers/keycloak";
-import Avatar from "@assets/avatar/avatar-small.jpeg";
 
 const SESSION_MAX_AGE_SECONDS = 12 * 60 * 60;
 const ACCESS_TOKEN_REFRESH_SKEW_MS = 30_000;
@@ -86,12 +85,16 @@ const authOptions: NextAuthOptions = {
       clientSecret: process.env.KEYCLOAK_CLIENT_SECRET ?? "",
       issuer: process.env.KEYCLOAK_ISSUER ?? "",
       profile(profile) {
+        const picture =
+          typeof (profile as { picture?: unknown }).picture === "string"
+            ? String((profile as { picture: string }).picture).trim()
+            : "";
         return {
           id: profile.sub,
           username: profile.preferred_username,
           name: profile.name ?? profile.preferred_username,
           email: profile.email,
-          image: Avatar.src,
+          image: picture || null,
         };
       },
     }),

src/components/admin/SystemAdminPanel.test.tsx

@@ -0,0 +1,87 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+
+import { apiFetch } from "@/lib/apiFetch";
+import { SystemAdminPanel } from "./SystemAdminPanel";
+
+const openNotification = jest.fn();
+
+jest.mock("@refinedev/core", () => ({
+  useNotification: () => ({ open: openNotification }),
+}));
+
+jest.mock("@config/config", () => ({
+  config: { BACKEND_URL: "https://server.example.com" },
+}));
+
+jest.mock("@/lib/apiFetch", () => ({
+  apiFetch: jest.fn(),
+}));
+
+jest.mock("@/lib/sessionRecoveryDraft", () => ({
+  useSessionRecoveryDraft: jest.fn(),
+}));
+
+jest.mock("@/store/projectStore", () => ({
+  useProjectStore: (selector: (state: { currentProjectId: null }) => unknown) =>
+    selector({ currentProjectId: null }),
+}));
+
+const jsonResponse = (body: unknown) =>
+  ({
+    ok: true,
+    status: 200,
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  }) as Response;
+
+describe("SystemAdminPanel Keycloak synchronization", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    (apiFetch as jest.Mock).mockImplementation((input: string) => {
+      if (input.endsWith("/api/v1/admin/users/me")) {
+        return Promise.resolve(
+          jsonResponse({
+            id: "admin-id",
+            keycloak_id: "admin-keycloak-id",
+            username: "admin",
+            email: "admin@example.com",
+            role: "admin",
+            is_active: true,
+            is_superuser: true,
+          }),
+        );
+      }
+      if (input.endsWith("/api/v1/admin/keycloak-user-syncs")) {
+        return Promise.resolve(
+          jsonResponse({
+            scanned: 3,
+            created: 1,
+            updated: 1,
+            skipped: 1,
+            issues: [{ username: "no-email", reason: "missing_email" }],
+          }),
+        );
+      }
+      return Promise.resolve(jsonResponse([]));
+    });
+  });
+
+  it("syncs the Keycloak directory and shows the result", async () => {
+    render(<SystemAdminPanel />);
+
+    fireEvent.click(await screen.findByRole("tab", { name: "系统用户" }));
+    fireEvent.click(
+      screen.getByRole("button", { name: "同步 Keycloak 用户" }),
+    );
+
+    await waitFor(() => {
+      expect(apiFetch).toHaveBeenCalledWith(
+        "https://server.example.com/api/v1/admin/keycloak-user-syncs",
+        expect.objectContaining({ method: "POST" }),
+      );
+    });
+    expect(await screen.findByRole("alert")).toHaveTextContent(
+      "已扫描 3 个 Keycloak 身份，新增 1 个，更新 1 个，跳过 1 个。",
+    );
+  });
+});

src/components/admin/SystemAdminPanel.tsx

@@ -53,6 +53,7 @@ import {
   Save as SaveIcon,
   Security as SecurityIcon,
   Storage as StorageIcon,
+  Sync as SyncIcon,
 } from "@mui/icons-material";
 import { useNotification } from "@refinedev/core";
 import { config } from "@config/config";
@@ -70,6 +71,17 @@ type MetadataUser = {
   is_superuser: boolean;
 };
 
+type KeycloakUserSyncResult = {
+  scanned: number;
+  created: number;
+  updated: number;
+  skipped: number;
+  issues: Array<{
+    username: string;
+    reason: "missing_email" | "service_account" | "identity_conflict" | string;
+  }>;
+};
+
 type ProjectMember = {
   id: string;
   user_id: string;
@@ -469,6 +481,9 @@ export const SystemAdminPanel = () => {
   const [adminChecked, setAdminChecked] = useState(false);
   const [isAuthorized, setIsAuthorized] = useState(false);
   const [metadataConfigAvailable, setMetadataConfigAvailable] = useState(true);
+  const [syncingKeycloakUsers, setSyncingKeycloakUsers] = useState(false);
+  const [keycloakSyncResult, setKeycloakSyncResult] =
+    useState<KeycloakUserSyncResult | null>(null);
   const [projectId, setProjectId] = useState(currentProjectId ?? "");
   const [memberForm, setMemberForm] = useState({
     user_id: "",
@@ -564,6 +579,33 @@ export const SystemAdminPanel = () => {
     setUsers(await response.json());
   }, []);
 
+  const syncKeycloakUsers = useCallback(async () => {
+    if (syncingKeycloakUsers) return;
+    setSyncingKeycloakUsers(true);
+    try {
+      const response = await apiFetch(
+        `${config.BACKEND_URL}/api/v1/admin/keycloak-user-syncs`,
+        {
+          method: "POST",
+          projectHeaderMode: "omit",
+        },
+      );
+      if (!response.ok) {
+        throw new Error(await readErrorText(response));
+      }
+      const result = (await response.json()) as KeycloakUserSyncResult;
+      setKeycloakSyncResult(result);
+      await loadUsers();
+      notifySuccess(
+        `Keycloak 用户同步完成：新增 ${result.created}，更新 ${result.updated}，跳过 ${result.skipped}`,
+      );
+    } catch (error) {
+      notifyError(error instanceof Error ? error.message : String(error));
+    } finally {
+      setSyncingKeycloakUsers(false);
+    }
+  }, [loadUsers, notifyError, notifySuccess, syncingKeycloakUsers]);
+
   const applyProjectForm = useCallback((project: AdminProject | null) => {
     if (!project) {
       setProjectForm(defaultProjectForm);
@@ -1238,13 +1280,44 @@ export const SystemAdminPanel = () => {
                   <Stack spacing={2}>
                     <SectionHeader
                       title="系统用户"
-                      description="Keycloak 信息只读展示；这里维护系统角色和启用状态。超级管理员由后台初始化或受控脚本设置，不在页面修改。"
+                      description="从 Keycloak 同步身份后，在这里维护系统角色和启用状态。新用户默认停用，项目权限仍需单独配置。"
                       action={
-                        <Button startIcon={<RefreshIcon />} variant="outlined" onClick={loadUsers}>
+                        <Stack direction="row" spacing={1} useFlexGap flexWrap="wrap">
+                          <Button
+                            startIcon={
+                              syncingKeycloakUsers ? (
+                                <CircularProgress color="inherit" size={16} />
+                              ) : (
+                                <SyncIcon />
+                              )
+                            }
+                            variant="contained"
+                            disabled={syncingKeycloakUsers}
+                            onClick={() => void syncKeycloakUsers()}
+                          >
+                            {syncingKeycloakUsers ? "正在同步" : "同步 Keycloak 用户"}
+                          </Button>
+                          <Button
+                            startIcon={<RefreshIcon />}
+                            variant="outlined"
+                            disabled={syncingKeycloakUsers}
+                            onClick={() => void loadUsers()}
+                          >
                             刷新
                           </Button>
+                        </Stack>
                       }
                     />
+                    {keycloakSyncResult && (
+                      <Alert
+                        severity={keycloakSyncResult.skipped > 0 ? "warning" : "success"}
+                        sx={{ borderRadius: 2 }}
+                      >
+                        {`已扫描 ${keycloakSyncResult.scanned} 个 Keycloak 身份，新增 ${keycloakSyncResult.created} 个，更新 ${keycloakSyncResult.updated} 个，跳过 ${keycloakSyncResult.skipped} 个。`}
+                        {keycloakSyncResult.skipped > 0 &&
+                          " 跳过项包括服务账号、缺少邮箱或身份冲突，请检查 Keycloak 用户资料。"}
+                      </Alert>
+                    )}
                     <TableContainer component={Paper} variant="outlined" sx={{ borderRadius: 2 }}>
                       <Table size="small" sx={tableSx}>
                         <TableHead>

src/components/auth/RoutePermissionGuard.test.tsx

@@ -8,6 +8,12 @@ jest.mock("next/navigation", () => ({
   usePathname: () => "/network-simulation",
 }));
 
+jest.mock("@/components/header", () => ({
+  Header: ({ accessMode }: { accessMode: string }) => (
+    <div data-testid="access-header">{accessMode}</div>
+  ),
+}));
+
 describe("RoutePermissionGuard", () => {
   beforeEach(() => {
     useAccessStore.setState({
@@ -52,6 +58,34 @@ describe("RoutePermissionGuard", () => {
     expect(screen.getByText(/simulation\.view/)).toBeInTheDocument();
   });
 
+  it("keeps a minimal identity header and logout action for pending accounts", () => {
+    render(
+      <RoutePermissionGuard
+        authenticated
+        accessDeniedReason="account"
+      >
+        <div>受保护内容</div>
+      </RoutePermissionGuard>,
+    );
+
+    expect(screen.getByTestId("access-header")).toHaveTextContent("account");
+    expect(screen.queryByText("受保护内容")).not.toBeInTheDocument();
+  });
+
+  it("keeps project recovery available when only the selected project is denied", () => {
+    render(
+      <RoutePermissionGuard
+        authenticated
+        accessDeniedReason="project"
+      >
+        <div>受保护内容</div>
+      </RoutePermissionGuard>,
+    );
+
+    expect(screen.getByText("无权访问当前项目")).toBeInTheDocument();
+    expect(screen.getByTestId("access-header")).toHaveTextContent("project");
+  });
+
   it("checks authentication before the expired state effect runs", () => {
     render(
       <RoutePermissionGuard authenticated={false}>

src/components/auth/RoutePermissionGuard.tsx

@@ -1,10 +1,17 @@
 "use client";
 
 import LockOutlinedIcon from "@mui/icons-material/LockOutlined";
-import { Alert, Box, CircularProgress, Stack, Typography } from "@mui/material";
+import {
+  Alert,
+  Box,
+  CircularProgress,
+  Stack,
+  Typography,
+} from "@mui/material";
 import { usePathname } from "next/navigation";
 import type { ReactNode } from "react";
 
+import { Header } from "@/components/header";
 import { permissionForPath } from "@/lib/permissions";
 import { useAccessStore } from "@/store/accessStore";
 import { useAuthStore } from "@/store/authStore";
@@ -12,9 +19,11 @@ import { useAuthStore } from "@/store/authStore";
 export const RoutePermissionGuard = ({
   children,
   authenticated,
+  accessDeniedReason = null,
 }: {
   children: ReactNode;
   authenticated: boolean;
+  accessDeniedReason?: "account" | "project" | null;
 }) => {
   const pathname = usePathname();
   const permissions = useAccessStore((state) => state.permissions);
@@ -37,6 +46,39 @@ export const RoutePermissionGuard = ({
     );
   }
 
+  if (accessDeniedReason) {
+    const accountPending = accessDeniedReason === "account";
+
+    return (
+      <Box sx={{ minHeight: "100vh", bgcolor: "background.default" }}>
+        <Header accessMode={accessDeniedReason} />
+        <Box
+          component="main"
+          sx={{
+            width: "100%",
+            maxWidth: 840,
+            mx: "auto",
+            px: { xs: 2, sm: 3 },
+            py: { xs: 4, md: 8 },
+          }}
+        >
+          <Alert severity="warning" icon={<LockOutlinedIcon />}>
+            <Stack spacing={0.5}>
+              <Typography fontWeight={700}>
+                {accountPending ? "账号尚未获得访问权限" : "无权访问当前项目"}
+              </Typography>
+              <Typography variant="body2">
+                {accountPending
+                  ? "身份认证已成功，但当前账号尚未由系统管理员启用。请联系系统管理员完成授权后重试。"
+                  : "当前账号无法访问所选项目。请选择其他已授权项目，或联系系统管理员调整项目权限。"}
+              </Typography>
+            </Stack>
+          </Alert>
+        </Box>
+      </Box>
+    );
+  }
+
   if (requiredPermission && loading) {
     return (
       <Box sx={{ minHeight: 320, display: "grid", placeItems: "center" }}>

src/components/header/index.tsx

@@ -3,6 +3,7 @@
 import { ColorModeContext } from "@contexts/color-mode";
 import DarkModeOutlined from "@mui/icons-material/DarkModeOutlined";
 import LightModeOutlined from "@mui/icons-material/LightModeOutlined";
+import { FiUser } from "react-icons/fi";
 import { IoChatbubbleEllipsesOutline } from "react-icons/io5";
 import Logout from "@mui/icons-material/Logout";
 import SwapHoriz from "@mui/icons-material/SwapHoriz";
@@ -37,8 +38,13 @@ type IUser = {
   avatar?: string;
 };
 
-export const Header: React.FC<RefineThemedLayoutHeaderProps> = ({
+type HeaderProps = RefineThemedLayoutHeaderProps & {
+  accessMode?: "default" | "account" | "project";
+};
+
+export const Header: React.FC<HeaderProps> = ({
   sticky = true,
+  accessMode = "default",
 }) => {
   const { mode, setMode } = useContext(ColorModeContext);
   const { mutate: logout } = useLogout();
@@ -51,6 +57,7 @@ export const Header: React.FC<RefineThemedLayoutHeaderProps> = ({
   );
 
   const { data: user } = useGetIdentity<IUser>();
+  const restricted = accessMode !== "default";
 
   const handleMenuOpen = (event: React.MouseEvent<HTMLElement>) => {
     setAnchorEl(event.currentTarget);
@@ -92,7 +99,7 @@ export const Header: React.FC<RefineThemedLayoutHeaderProps> = ({
           justifyContent="flex-end"
           alignItems="center"
         >
-          <HamburgerMenu />
+          {!restricted && <HamburgerMenu />}
           <Stack
             direction="row"
             width="100%"
@@ -110,6 +117,7 @@ export const Header: React.FC<RefineThemedLayoutHeaderProps> = ({
 
             {(user?.avatar || user?.name) && (
               <>
+                {!restricted && (
                   <IconButton
                     color="inherit"
                     onClick={() => setShowChatbox(true)}
@@ -117,20 +125,24 @@ export const Header: React.FC<RefineThemedLayoutHeaderProps> = ({
                   >
                     <IoChatbubbleEllipsesOutline />
                   </IconButton>
+                )}
                 <ButtonBase
+                  aria-label={
+                    user?.name ? `${user.name} 账号菜单` : "账号菜单"
+                  }
                   onClick={handleMenuOpen}
                   sx={{
                     borderRadius: "30px",
                     padding: "6px 12px",
                     marginLeft: "8px",
-                    transition: "all 0.3s ease",
+                    transition:
+                      "background-color 0.3s ease, border-color 0.3s ease, box-shadow 0.3s ease",
                     border: "1px solid transparent",
                     "&:hover": {
                       backgroundColor:
                         mode === "dark"
                           ? "rgba(255, 255, 255, 0.05)"
                           : "rgba(0, 0, 0, 0.04)",
-                      transform: "translateY(-1px)",
                       border: `1px solid ${mode === "dark"
                           ? "rgba(255, 255, 255, 0.2)"
                           : "rgba(0, 0, 0, 0.1)"
@@ -141,7 +153,6 @@ export const Header: React.FC<RefineThemedLayoutHeaderProps> = ({
                           : "0 4px 12px rgba(0,0,0,0.08)",
                     },
                     "&:active": {
-                      transform: "translateY(0px)",
                       boxShadow: "none",
                     },
                   }}
@@ -176,13 +187,13 @@ export const Header: React.FC<RefineThemedLayoutHeaderProps> = ({
                             ? "rgba(255,255,255,0.2)"
                             : "rgba(0,0,0,0.1)"
                           }`,
-                        transition: "transform 0.3s ease",
                         ".MuiButtonBase-root:hover &": {
-                          transform: "rotate(5deg) scale(1.05)",
                           borderColor: "primary.main",
                         },
                       }}
-                    />
+                    >
+                      {!user?.avatar && <FiUser aria-hidden="true" />}
+                    </Avatar>
                   </Stack>
                 </ButtonBase>
                 <Menu
@@ -208,13 +219,15 @@ export const Header: React.FC<RefineThemedLayoutHeaderProps> = ({
                     },
                   }}
                 >
+                  {accessMode !== "account" && (
                     <MenuItem onClick={handleSwitchProjectClick}>
                       <ListItemIcon>
                         <SwapHoriz fontSize="small" />
                       </ListItemIcon>
                       <ListItemText>切换项目</ListItemText>
                     </MenuItem>
-                  <Divider />
+                  )}
+                  {accessMode !== "account" && <Divider />}
                   <MenuItem onClick={() => logout()}>
                     <ListItemIcon>
                       <Logout fontSize="small" />
@@ -222,17 +235,21 @@ export const Header: React.FC<RefineThemedLayoutHeaderProps> = ({
                     <ListItemText>登出</ListItemText>
                   </MenuItem>
                 </Menu>
+                {accessMode !== "account" && (
                   <ProjectSelector
                     open={showProjectSelector}
                     onSelect={handleProjectSelect}
                     onClose={() => setShowProjectSelector(false)}
                   />
+                )}
               </>
             )}
+            {!restricted && (
               <GlobalChatbox
                 open={showChatbox}
                 onClose={() => setShowChatbox(false)}
               />
+            )}
           </Stack>
         </Stack>
       </Toolbar>

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

@@ -1,21 +1,41 @@
 import React from "react";
-import { render, waitFor } from "@testing-library/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 { 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: () => null,
+  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", () => () => null);
+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) =>
   ({
@@ -66,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(
@@ -103,10 +172,20 @@ describe("fetchHistoryData", () => {
   });
 });
 
+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());
@@ -137,4 +216,193 @@ describe("HistoryDataPanel requests", () => {
     );
     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,11 +22,10 @@ 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";
-import * as echarts from "echarts";
 import "dayjs/locale/zh-cn"; // 引入中文包
 import dayjs, { Dayjs } from "dayjs";
 import utc from "dayjs/plugin/utc";
@@ -41,8 +40,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 +68,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 +121,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 +139,33 @@ export const fetchHistoryData = async (
     throw new Error("历史方案缺少分析运行 ID，无法读取方案时序数据");
   }
 
-  try {
-    return await fetchElementHistory(
-      uniqueFeatureInfos.map(([id, elementType]) => ({
+  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"
-        : type === "scheme"
-          ? "analysis_comparison"
-          : "realtime_comparison",
-      schemeRunId,
+    type === "none" ? "observed" : "realtime_comparison",
+    undefined,
     signal,
   );
-  } catch (error) {
-    console.error("[HistoryDataPanel] 从后端获取数据失败:", error);
-    throw error;
-  }
 };
 
 const formatTimestamp = (timestamp: string) =>
@@ -186,11 +215,11 @@ const emptyStateMessages: Record<
 > = {
   chart: {
     title: "暂无时序数据",
-    subtitle: "请调整时间范围，或确认所选设备在该时段已有数据。",
+    subtitle: "请调整时间范围，或确认所选元素在该时段已有数据。",
   },
   table: {
     title: "暂无表格数据",
-    subtitle: "请调整时间范围，或确认所选设备在该时段已有数据。",
+    subtitle: "请调整时间范围，或确认所选元素在该时段已有数据。",
   },
 };
 
@@ -204,35 +233,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,22 +321,30 @@ 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 (type !== "scheme" || !runId) return;
+    let cancelled = false;
+    getAnalysisScheme(runId).then(
+      (run) => {
+        if (!cancelled) {
+          setSchemeState({ runId, context: getAnalysisHistoryContext(run) });
         }
+      },
+      () => {
+        if (!cancelled) {
+          setSchemeState({ runId, error: "无法读取事件方案，请刷新重试" });
         }
-    if (end_time) {
-      const parsedEnd = dayjs(end_time);
-      if (parsedEnd.isValid()) {
-        setTo((prev) => (parsedEnd.isSame(prev) ? prev : parsedEnd));
-      }
-    }
-  }, [start_time, end_time]);
+      },
+    );
+    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 featureInfosKey = JSON.stringify(featureInfos);
   const requestedFeatureInfos = useMemo(
@@ -265,6 +353,42 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
   );
   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),
@@ -272,9 +396,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");
@@ -295,44 +420,52 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
             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");
       }
     },
-    [requestedFeatureInfos, 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([]);
-    }
-  }, [handleFetch, hasDevices]);
+    void handleFetch();
+  }, [handleFetch]);
 
   const columns: GridColDef[] = useMemo(() => {
     const base: GridColDef[] = [
@@ -387,6 +520,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
@@ -424,7 +562,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",
@@ -449,30 +586,24 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
                 ? "circle"
                 : metadata.source === "scada_raw"
                   ? "diamond"
-                  : "none",
-            symbolSize: isObserved ? 7 : 0,
+                  : "circle",
+            symbolSize: isObserved ? 7 : 5,
             showSymbol: isObserved,
             sampling: "lttb",
-            connectNulls: !isObserved,
+            connectNulls: false,
             itemStyle: {
               color: colors[index % colors.length],
             },
-            data: dataset.map((item) => item[key]),
-            lineStyle: isObserved ? { width: 0 } : undefined,
-            areaStyle: isObserved
-              ? undefined
-              : {
-                  color: new echarts.graphic.LinearGradient(0, 0, 0, 1, [
-                    {
-                      offset: 0,
-                      color: colors[index % colors.length],
-                    },
-                    {
-                      offset: 1,
-                      color: "rgba(255, 255, 255, 0)",
-                    },
+            data: timeSeries
+              .filter((point) =>
+                Object.prototype.hasOwnProperty.call(point.values, key),
+              )
+              .map((point) => [
+                new Date(point.timestamp).getTime(), point.values[key] ?? null,
               ]),
-                  opacity: 0.3,
+            lineStyle: {
+              width: isObserved ? 0 : 2,
+              type: metadata.source === "analysis_simulation" ? "dashed" : "solid",
             },
           },
         ];
@@ -484,20 +615,34 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
       tooltip: {
         trigger: "axis",
         confine: true,
-        position: function (pt: any[]) {
-          return [pt[0], "10%"];
-        },
+        axisPointer: { type: "line", lineStyle: { color: "#94a3b8", type: "dashed" } },
+        valueFormatter: (value: number | string) => typeof value === "number"
+          ? value.toLocaleString("zh-CN", { maximumSignificantDigits: 6, useGrouping: false })
+          : String(value ?? "--"),
       },
       legend: {
-        top: "top",
+        type: "scroll",
+        top: 8,
+        left: 20,
+        width: "90%",
+        itemWidth: 20,
+        itemHeight: 8,
+        itemGap: 20,
+        textStyle: { color: "#475569", fontSize: 12 },
       },
       grid: {
-        left: "5%",
-        right: "5%",
-        bottom: "11%",
+        top: 120,
+        left: 20,
+        right: 24,
+        bottom: 76,
         containLabel: true,
       },
       toolbox: {
+        top: 36,
+        right: 16,
+        itemSize: 15,
+        itemGap: 16,
+        iconStyle: { borderColor: "#64748b" },
         feature: {
           dataZoom: {
             yAxisIndex: "none",
@@ -507,9 +652,22 @@ 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,
+          color: "#64748b",
+          fontSize: 12,
+          lineHeight: 16,
+          margin: 12,
+        },
+        splitNumber: 6,
+        axisLine: { lineStyle: { color: "#cbd5e1" } },
+        axisTick: { show: false },
       },
       yAxis: [
         ...(hasFlowSeries
@@ -518,6 +676,9 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
                 type: "value",
                 scale: true,
                 name: `流量 (${FLOW_DISPLAY_UNIT})`,
+                nameTextStyle: { color: "#64748b", fontSize: 12 },
+                axisLabel: { color: "#64748b", fontSize: 12 },
+                splitLine: { lineStyle: { color: "#e2e8f0", type: "dashed" } },
               },
             ]
           : []),
@@ -527,6 +688,9 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
                 type: "value",
                 scale: true,
                 name: `压力 (${PRESSURE_DISPLAY_UNIT})`,
+                nameTextStyle: { color: "#64748b", fontSize: 12 },
+                axisLabel: { color: "#64748b", fontSize: 12 },
+                splitLine: { show: !hasFlowSeries, lineStyle: { color: "#e2e8f0", type: "dashed" } },
               },
             ]
           : []),
@@ -538,11 +702,46 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
           end: 100,
         },
         {
+          type: "slider",
           start: 0,
           end: 100,
+          bottom: 12,
+          height: 24,
+          showDetail: false,
+          borderColor: "transparent",
+          backgroundColor: "#f5f7fa",
+          fillerColor: "rgba(25, 118, 210, 0.08)",
+          dataBackground: {
+            lineStyle: { color: "#94a3b8" },
+            areaStyle: { opacity: 0 },
+          },
+          selectedDataBackground: {
+            lineStyle: { color: "#1976d2" },
+            areaStyle: { opacity: 0 },
+          },
         },
       ],
-      series: getSeries(),
+      series: getSeries().map((series, index) => ({
+        ...series,
+        ...(index === 0 && eventRange
+          ? {
+              markArea: {
+                silent: true,
+                itemStyle: { color: "rgba(255, 152, 0, 0.06)" },
+                label: {
+                  position: "insideTop",
+                  distance: 10,
+                  color: "#996515",
+                  fontSize: 11,
+                },
+                data: [[
+                  { name: "事件方案时段", xAxis: Date.parse(eventRange.start) },
+                  { xAxis: Date.parse(eventRange.end) },
+                ]],
+              },
+            }
+          : {}),
+      })),
     };
 
     return (
@@ -711,21 +910,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" },
@@ -734,21 +924,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" },
@@ -756,7 +937,7 @@ const SCADADataPanel: React.FC<SCADADataPanelProps> = ({
                     />
                   </Stack>
                   <Stack
-                    direction="row"
+                    direction={{ xs: "column", sm: "row" }}
                     spacing={1}
                     alignItems="center"
                     justifyContent="space-between"
@@ -780,6 +961,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
@@ -787,8 +985,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>
@@ -799,13 +1006,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>
@@ -814,7 +1042,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/project/ProjectSelector.tsx

@@ -132,8 +132,11 @@ export const ProjectSelector: React.FC<ProjectSelectorProps> = ({
         paper: {
           sx: {
             borderRadius: 2,
-            padding: 2,
-            minWidth: 400,
+            boxSizing: "border-box",
+            margin: { xs: 2, sm: 4 },
+            padding: { xs: 1.5, sm: 2 },
+            width: { xs: "calc(100vw - 32px)", sm: 400 },
+            maxWidth: "calc(100vw - 32px)",
             background: "rgba(255, 255, 255, 0.95)",
             backdropFilter: "blur(10px)",
             position: "relative",

src/components/threeDimensional/ThreeDimensionalControls.test.tsx

@@ -110,7 +110,7 @@ describe("ThreeDimensionalControls", () => {
       />,
     );
 
-    fireEvent.click(screen.getByRole("button", { name: "站房精细版" }));
+    fireEvent.click(screen.getByRole("button", { name: "站区精细版" }));
     expect(onCommand).toHaveBeenCalledWith({ name: "set-mode", mode: "detail" });
     fireEvent.change(screen.getByRole("slider", { name: "建筑背景透明度 60%" }), {
       target: { value: "0.35" },

src/components/threeDimensional/ThreeDimensionalControls.tsx

@@ -35,7 +35,7 @@ const sceneModes: Array<{ mode: SceneMode; label: string }> = [
   { mode: "network", label: "供水管网" },
   { mode: "hydraulic", label: "泵组与管网" },
   { mode: "map", label: "站区轻量版" },
-  { mode: "detail", label: "站房精细版" },
+  { mode: "detail", label: "站区精细版" },
   { mode: "pump", label: "CAD 泵房参考" },
   { mode: "meters", label: "设备样件" },
 ];

src/components/threeDimensional/ThreeDimensionalScene.tsx

@@ -38,7 +38,7 @@ import {
   type SceneRuntimeState,
 } from "./sceneProtocol";
 
-const SCENE_URL = "/three-dimensional/zjb/v29/preview.html?host=platform2&v=35-resource-cache";
+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 = {

src/generated/serverApi.ts

@@ -21,6 +21,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/admin/keycloak-user-syncs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Sync Keycloak User Directory */
+        post: operations["post_admin_keycloak_user_syncs"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/admin/project-provisions": {
         parameters: {
             query?: never;
@@ -5149,6 +5166,26 @@ export interface components {
          */
         HistorySource: "scada_raw" | "scada_cleaned" | "realtime_simulation" | "analysis_simulation";
         JsonValue: unknown;
+        /** KeycloakUserSyncIssue */
+        KeycloakUserSyncIssue: {
+            /** Reason */
+            reason: string;
+            /** Username */
+            username: string;
+        };
+        /** KeycloakUserSyncResponse */
+        KeycloakUserSyncResponse: {
+            /** Created */
+            created: number;
+            /** Issues */
+            issues?: components["schemas"]["KeycloakUserSyncIssue"][];
+            /** Scanned */
+            scanned: number;
+            /** Skipped */
+            skipped: number;
+            /** Updated */
+            updated: number;
+        };
         /** LeakageIdentifyRequestRest */
         LeakageIdentifyRequestRest: {
             /**
@@ -5995,6 +6032,80 @@ export interface operations {
             };
         };
     };
+    post_admin_keycloak_user_syncs: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["KeycloakUserSyncResponse"];
+                };
+            };
+            /** @description Authentication required */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Insufficient permission */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Resource not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Resource conflict */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Validation error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description Dependency unavailable */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProblemDetails"];
+                };
+            };
+        };
+    };
     post_admin_project_provisions: {
         parameters: {
             query?: never;
@@ -28768,6 +28879,8 @@ export interface operations {
                 accident_element: string[];
                 /** @description 已故障的阀门ID列表（可选） */
                 disabled_valves?: string[];
+                /** @description 事故要素类型；auto优先管段再节点；分析同名节点须指定node，纯管段分析可指定link */
+                accident_element_type?: "auto" | "link" | "node";
             };
             header: {
                 "X-Project-Id": string;

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/logoutFlow.test.ts

@@ -1,4 +1,8 @@
 import { completeLogout, reportLogoutAudit } from "./logoutFlow";
+import {
+  clearIntentionalLogout,
+  isIntentionalLogout,
+} from "./logoutIntent";
 
 describe("reportLogoutAudit", () => {
   it("starts an authenticated keepalive request", async () => {
@@ -28,6 +32,10 @@ describe("reportLogoutAudit", () => {
 });
 
 describe("completeLogout", () => {
+  beforeEach(() => {
+    clearIntentionalLogout();
+  });
+
   it("navigates immediately without waiting for audit reporting", async () => {
     const reportAudit = jest.fn(
       () => new Promise<unknown>(() => undefined),
@@ -44,6 +52,7 @@ describe("completeLogout", () => {
     await Promise.resolve();
 
     expect(reportAudit).toHaveBeenCalledTimes(1);
+    expect(isIntentionalLogout()).toBe(true);
     expect(clearLocalState).toHaveBeenCalledTimes(1);
     expect(navigate).toHaveBeenCalledWith("/api/auth/keycloak-logout");
     await expect(result).resolves.toEqual({ success: true });
@@ -79,4 +88,20 @@ describe("completeLogout", () => {
     expect(clearLocalState).toHaveBeenCalledTimes(1);
     expect(navigate).toHaveBeenCalledWith("/api/auth/keycloak-logout");
   });
+
+  it("still navigates when local cleanup throws", async () => {
+    const navigate = jest.fn();
+
+    await expect(
+      completeLogout({
+        reportAudit: jest.fn().mockResolvedValue(undefined),
+        clearLocalState: () => {
+          throw new DOMException("Storage unavailable", "SecurityError");
+        },
+        navigate,
+      }),
+    ).resolves.toEqual({ success: true });
+
+    expect(navigate).toHaveBeenCalledWith("/api/auth/keycloak-logout");
+  });
 });

src/lib/logoutFlow.ts

@@ -1,3 +1,5 @@
+import { markIntentionalLogout } from "@/lib/logoutIntent";
+
 const KEYCLOAK_LOGOUT_PATH = "/api/auth/keycloak-logout";
 
 type CompleteLogoutOptions = {
@@ -41,7 +43,12 @@ export const completeLogout = async ({
     // Synchronous reporting errors must not block logout either.
   }
 
+  markIntentionalLogout();
+  try {
     clearLocalState();
+  } catch {
+    // Browser storage cleanup failures must not prevent the IdP logout.
+  }
   navigate(KEYCLOAK_LOGOUT_PATH);
   return { success: true as const };
 };

src/lib/logoutIntent.test.ts

@@ -0,0 +1,57 @@
+import {
+  clearIntentionalLogout,
+  isIntentionalLogout,
+  markIntentionalLogout,
+} from "./logoutIntent";
+
+describe("intentional logout marker", () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+    clearIntentionalLogout();
+  });
+
+  it("stores a timestamp only for the current tab", () => {
+    jest.spyOn(Date, "now").mockReturnValue(1_700_000_000_000);
+
+    markIntentionalLogout();
+
+    expect(sessionStorage.getItem("tjwater:intentional-logout")).toBe(
+      "1700000000000",
+    );
+    expect(localStorage.getItem("tjwater:intentional-logout")).toBeNull();
+    expect(isIntentionalLogout()).toBe(true);
+  });
+
+  it("accepts an intentional logout event from another open tab", () => {
+    window.dispatchEvent(
+      new StorageEvent("storage", {
+        key: "tjwater:intentional-logout-event",
+        newValue: JSON.stringify({
+          type: "mark",
+          markedAt: Date.now(),
+        }),
+      }),
+    );
+
+    expect(isIntentionalLogout()).toBe(true);
+  });
+
+  it("does not broadcast a clear event when the current tab has no marker", () => {
+    clearIntentionalLogout();
+    const setItem = jest.spyOn(Storage.prototype, "setItem");
+
+    expect(isIntentionalLogout()).toBe(false);
+    expect(setItem).not.toHaveBeenCalled();
+  });
+
+  it("expires a stale marker", () => {
+    const now = 1_700_000_000_000;
+    const nowSpy = jest.spyOn(Date, "now").mockReturnValue(now);
+    markIntentionalLogout();
+
+    nowSpy.mockReturnValue(now + 30 * 60 * 1000 + 1);
+
+    expect(isIntentionalLogout()).toBe(false);
+    expect(sessionStorage.getItem("tjwater:intentional-logout")).toBeNull();
+  });
+});

src/lib/logoutIntent.ts

@@ -0,0 +1,81 @@
+const INTENTIONAL_LOGOUT_STORAGE_KEY = "tjwater:intentional-logout";
+const INTENTIONAL_LOGOUT_EVENT_KEY = "tjwater:intentional-logout-event";
+const INTENTIONAL_LOGOUT_TTL_MS = 30 * 60 * 1000;
+let memoryMarkedAt: number | null = null;
+
+const withStorage = (
+  storageName: "localStorage" | "sessionStorage",
+  callback: (storage: Storage) => void,
+) => {
+  if (typeof window === "undefined") return;
+  try {
+    callback(window[storageName]);
+  } catch {
+    // Logout must still proceed when browser storage is unavailable.
+  }
+};
+
+const setLocalMarker = (markedAt: number | null) => {
+  memoryMarkedAt = markedAt;
+  withStorage("sessionStorage", (storage) => {
+    if (markedAt === null) {
+      storage.removeItem(INTENTIONAL_LOGOUT_STORAGE_KEY);
+    } else {
+      storage.setItem(INTENTIONAL_LOGOUT_STORAGE_KEY, String(markedAt));
+    }
+  });
+};
+
+const broadcastIntent = (
+  payload: { type: "mark"; markedAt: number } | { type: "clear" },
+) => {
+  withStorage("localStorage", (storage) => {
+    storage.setItem(INTENTIONAL_LOGOUT_EVENT_KEY, JSON.stringify(payload));
+    storage.removeItem(INTENTIONAL_LOGOUT_EVENT_KEY);
+  });
+};
+
+if (typeof window !== "undefined") {
+  window.addEventListener("storage", (event) => {
+    if (event.key !== INTENTIONAL_LOGOUT_EVENT_KEY || !event.newValue) return;
+    try {
+      const payload = JSON.parse(event.newValue) as {
+        type?: unknown;
+        markedAt?: unknown;
+      };
+      if (payload.type === "mark" && typeof payload.markedAt === "number") {
+        setLocalMarker(payload.markedAt);
+      } else if (payload.type === "clear") {
+        setLocalMarker(null);
+      }
+    } catch {
+      // Ignore malformed cross-tab events.
+    }
+  });
+}
+
+export const markIntentionalLogout = () => {
+  const markedAt = Date.now();
+  setLocalMarker(markedAt);
+  broadcastIntent({ type: "mark", markedAt });
+};
+
+export const clearIntentionalLogout = () => {
+  setLocalMarker(null);
+  broadcastIntent({ type: "clear" });
+};
+
+export const isIntentionalLogout = () => {
+  let markedAt = memoryMarkedAt;
+  withStorage("sessionStorage", (storage) => {
+    const stored = Number(storage.getItem(INTENTIONAL_LOGOUT_STORAGE_KEY));
+    if (Number.isFinite(stored) && stored > 0) markedAt = stored;
+  });
+  if (markedAt === null) return false;
+  const age = Date.now() - markedAt;
+  if (age < 0 || age > INTENTIONAL_LOGOUT_TTL_MS) {
+    setLocalMarker(null);
+    return false;
+  }
+  return true;
+};

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 };
+};

src/store/authStore.test.ts

@@ -0,0 +1,45 @@
+import {
+  clearIntentionalLogout,
+  markIntentionalLogout,
+} from "@/lib/logoutIntent";
+
+import { useAuthStore } from "./authStore";
+
+describe("authStore intentional logout boundary", () => {
+  beforeEach(() => {
+    clearIntentionalLogout();
+    useAuthStore.setState({
+      accessToken: "access-token",
+      sessionExpired: false,
+      sessionExpiryReason: null,
+    });
+  });
+
+  afterEach(() => {
+    clearIntentionalLogout();
+  });
+
+  it("ignores late expiry signals after an intentional logout", () => {
+    markIntentionalLogout();
+
+    useAuthStore.getState().markSessionExpired("unauthorized");
+
+    expect(useAuthStore.getState()).toMatchObject({
+      accessToken: null,
+      sessionExpired: false,
+      sessionExpiryReason: null,
+    });
+  });
+
+  it("keeps real refresh failures visible after an intentional logout", () => {
+    markIntentionalLogout();
+
+    useAuthStore.getState().markSessionExpired("refresh_failed");
+
+    expect(useAuthStore.getState()).toMatchObject({
+      accessToken: null,
+      sessionExpired: true,
+      sessionExpiryReason: "refresh_failed",
+    });
+  });
+});

src/store/authStore.ts

@@ -1,5 +1,7 @@
 import { create } from "zustand";
 
+import { isIntentionalLogout } from "@/lib/logoutIntent";
+
 interface AuthState {
   accessToken: string | null;
   sessionExpired: boolean;
@@ -16,11 +18,21 @@ export const useAuthStore = create<AuthState>((set) => ({
   sessionExpired: false,
   sessionExpiryReason: null,
   setAccessToken: (token) => set({ accessToken: token }),
-  markSessionExpired: (reason) => set({
+  markSessionExpired: (reason) => {
+    if (reason === "unauthorized" && isIntentionalLogout()) {
+      set({
+        accessToken: null,
+        sessionExpired: false,
+        sessionExpiryReason: null,
+      });
+      return;
+    }
+    set({
       accessToken: null,
       sessionExpired: true,
       sessionExpiryReason: reason,
-  }),
+    });
+  },
   clearSessionExpired: () => set({
     sessionExpired: false,
     sessionExpiryReason: null,