55 lines
6.7 KiB
Markdown
55 lines
6.7 KiB
Markdown
# 工作台项目切换
|
|
|
|
2026-10-21：新增用户菜单内的项目切换，首批核对 `tjwater_v2` 与 `fengyang_v2`。
|
|
|
|
## 启动与加载状态
|
|
|
|
身份认证和授权项目加载共用启动界面：左对齐平台标识与标题，中性浅色表面和宝石蓝状态标识。认证阶段显示“检查登录状态”；项目阶段依次显示“读取授权项目”和“准备项目环境”。项目列表返回后才将第一步标为完成，并显示实际选中的授权项目名称；项目配置与访问上下文返回前不挂载工作台，不用计时器或百分比模拟进度。
|
|
|
|
加载中提供图形反馈和文字说明，系统开启减少动态效果时停止旋转。失败后移除加载状态，展示错误原因和单一重试操作；项目重试回到读取列表阶段，认证重试重新连接。桌面与手机使用同一组件，长项目名和错误信息自然换行。外观与组件选择遵循 [样式设计指南](style-design-guide.md)。
|
|
|
|
## 用户入口与选择规则
|
|
|
|
打开右上角用户菜单，点击“切换项目”进入弹窗。弹窗恢复中性乳白亚克力表面、小型平台标识、左对齐标题、当前项目说明和通栏“进入项目”按钮的布局。弹窗与下拉浮层使用 82% 中性白色亚克力底色，沿用模糊、噪点和边缘高光；遮罩保留轻微压暗与 3px 背景模糊。降低透明度或不支持背景模糊时回退为不透明白色。选择框与禁用按钮使用中性白色表面和低对比灰色边框；主按钮和选中态恢复工作台宝石蓝。
|
|
|
|
共享 Select 下拉列表显示项目名称与当前使用标记，选择区补充可用状态，后端返回角色时显示中文角色。首次打开和重新打开弹窗时，焦点显式落在“项目环境”选择框，不自动展开列表；Tab 与 Shift+Tab 保留正常焦点顺序。点击主按钮后才提交切换；选择相同项目时主按钮禁用。关闭按钮或 Escape 关闭弹窗并恢复用户菜单按钮焦点。下拉列表只列出后端授权列表中的活动项目；弹窗及下拉浮层覆盖地图工具栏，适配 1440、375 和 320px 视口。
|
|
|
|
动效使用 `motion/react`：遮罩淡入淡出，弹窗以 8px 位移进入并保留退出动画，项目列表以 4px 位移展开；键盘操作和系统“减少动态效果”设置下即时呈现。列表关闭后直接恢复选择框焦点并保留蓝色焦点边框；弹窗容器不显示浏览器默认 outline，避免选择项变化时焦点临时回落导致黑边。下拉外层只负责裁切，实际滚动统一由 Radix Viewport 管理，避免 4px 入场位移触发外层滚动条；长列表仍支持滚动与键盘定位。
|
|
|
|
浏览器保存最近一次成功选择的项目 ID。刷新后先重新加载授权列表，只有仍在列表中的 ID 才会恢复；否则使用部署默认工作空间对应的授权项目，再退到列表中的首个项目。项目查询失败显示重试入口，不凭本地存储获得权限。
|
|
|
|
切换前查询目标项目元数据和访问上下文，两者均通过项目 ID 核对后才提交选择。失败时保留原工作台、弹窗和目标选择，并显示错误提示；请求期间禁用选择与关闭操作。切换只改变浏览器正在查看的项目，不取消服务端工况任务。
|
|
|
|
## 数据与生命周期
|
|
|
|
`project-workbench.tsx` 持有唯一选中项目。它将 `WorkbenchRequestContext` 传入工作台，其中包含项目元数据、认证令牌提供器以及已取得的展示信息。现有 API 参数名 `getAccessToken` 为兼容保留，类型 `WorkbenchAccess` 同时接受旧认证提供器和显式项目上下文；主应用始终传显式上下文。
|
|
|
|
地图瓦片、WFS 定位与可用图层探测读取当前项目的 `gs_workspace`。SCADA、实时流量、运行态、事件流、任务、成果、GIS 属性与 Agent 项目会话读取同一个项目 ID。业务请求继续由后端通过 Bearer 与 `X-Project-Id` 校验权限。
|
|
|
|
项目 ID 作为工作台 SWR 边界的 React key；切换时新建业务缓存并重新挂载工作台，清理地图选择、报告、绘图和旧业务订阅，当前 Agent 视图进入新项目的空会话。登录级资源位于该边界之外，保留按归属隔离的历史、推荐、项目列表缓存和后台 Agent 会话；原会话生成、草稿及阅读位置继续由其会话实例持有。实现依据 [React 状态重置](https://react.dev/learn/preserving-and-resetting-state) 与 [SWR 缓存提供器](https://swr.vercel.app/docs/advanced/cache)。地图销毁后，绘图及要素交互不再访问旧样式；异步设施与 SCADA 图片注册受地图生命周期 AbortSignal 约束。
|
|
|
|
## 凤阳的数据边界
|
|
|
|
凤阳使用已有的 `fengyang_v2` 工作空间及元数据地图范围。固定奉贤演示工况、场景与空间覆盖不会在凤阳兜底显示。奉贤原始 GIS 图层不复制，图层入口根据当前工作空间中的实际数据探测。
|
|
|
|
地址定位支持文字搜索及地图取点反编码，两者复用当前项目的配置与服务端 Key。取点结果保留点击坐标，关闭工具或切换项目取消未完成查询。地名搜索读取 Metadata DB 的 `projects.map_config.place_search`，按当前项目的 `enabled`、`provider`、`admin_code` 和 `region` 启用查询并显示区域文案。奉贤、凤阳和其他项目使用同一实现；未配置、关闭或配置无效时显示“当前项目暂未配置地名搜索”。区域由后端从授权项目读取，浏览器不能在搜索请求中覆盖行政区。外围样板服务仍有独立项目配置；本次复制其空表结构，不复制奉贤工单，也不扩大外部服务的访问范围。
|
|
|
|
## 验证
|
|
|
|
```bash
|
|
pnpm lint
|
|
pnpm typecheck
|
|
pnpm test
|
|
pnpm build
|
|
pnpm test:browser tests/browser/project-switching.e2e.ts tests/browser/project-presentation-backend.e2e.ts --workers=2 --reporter=line
|
|
```
|
|
|
|
浏览器覆盖用户菜单切换、地图工作空间、业务与 Agent 请求项目、元数据视角、刷新恢复、切回原项目及目标访问失败；同时检查切换期间无页面异常。浏览器接口使用隔离测试数据，不代表生产身份登录验收。
|
|
|
|
数据库补齐方法与备份记录见 Server 仓库的 `docs/workbench-database-rollout.md`。
|
|
|
|
|
|
## 项目列表缓存
|
|
|
|
授权项目列表按当前登录的凭据提供器隔离，内存缓存 5 分钟，分页结果完整合并后缓存；并发读取复用同一请求，单个消费者退出只取消自身等待。窗口直接展示已加载项目，有效期内反复打开不会重新查询。目标项目进入操作继续核验其元数据及访问上下文，复用这次已验证的展示信息，避免工作台挂载后再次读取相同上下文。缓存不替代业务接口授权，退出登录清理本次登录缓存。
|