跳转到内容
GitHub

工作台与界面

登录后的首页是工作台:一组卡片(待我处理、我发起的、快速发起、常用入口、消息、公告、需要你留意、服务状态、近 14 天访问),每个人自己选显示哪些、怎么排、多宽,布局存在服务端,换台电脑登录还是自己那一套;没有权限的卡片根本不出现。工作台之外,整个界面还有几样通用的东西:⌘K 命令面板、快捷键、功能引导、个人中心里的外观设置、列表的列显隐与排序、每人自己的时区和语言,以及发了新版本时的刷新提示。多页签单独写在多页签保活。

工作台
入口在哪存在哪
工作台、「自定义」按钮仪表盘 /dashboard,所有登录用户服务端,按人(跨设备)
命令面板任意页面按 ⌘K / Ctrl+K——
快捷键帮助按 ?,或顶栏「帮助」——
功能引导顶栏「帮助 → 功能引导」或命令面板里打开,不自动弹出不保存
外观与布局偏好个人中心 → 主题 / 布局 / 多标签页浏览器本地
显示时区个人中心 → 资料服务端,按人
界面语言右上角用户菜单 → 界面语言;登录页也能切浏览器本地
列表的「列」各列表页表头右侧地址栏

工作台有哪些卡片?谁看得到?

Section titled “工作台有哪些卡片?谁看得到?”
卡片内容谁看得到默认
待我处理最多 6 条,分「全部 / 待审批 / 退回给我 / 草稿」侧边栏里有审批中心的人2/3 宽,显示
我发起的最近 3 张单子的进度条;超过 1 天没动静的可以「催办」同上1/3,显示
快速发起4 个能发起的流程同上1/3,显示
常用入口从自己侧边栏里挑的页面,默认 6 个、最多 12 个所有人1/3,显示
和我有关的消息4 条未读,和铃铛同一份数据所有人1/3,显示
公告5 条公告所有人整行,默认隐藏
需要你留意被自动停用的 Webhook、近 24 小时失败的任务、今天登录失败的异常增长有 open:webhook:list、task:scheduler:edit、log:login:list 任一的人一半,显示
服务状态API / 数据库 / 缓存 / 定时调度 / 后台任务,加三端在线会话数超级管理员一半,显示
近 14 天访问每天登录成功 / 失败的柱状图log:login:list整行,显示

没有权限的卡片不渲染,而不是渲染一个「无权限」的空壳;后端取数接口按同一套条件拦。「系统运行」这一组只对能看到其中至少一张卡片的人出现。

点右上角「自定义」进入编辑模式(地址栏里多一个 edit=true,刷新还在):

  • 每张卡片可以显示或隐藏
  • 拖拽排序,也可以用键盘(空格拿起、方向键移动、空格放下);每组各排各的
  • 宽度四档:三分之一 / 一半 / 三分之二 / 整行
  • 挑「常用入口」里放哪些页面
  • 「恢复默认」

布局按人存在服务端(sys_user_preference 表,键 dashboard.layout),换浏览器、换电脑登录都一样。兼容规则保证布局不会因为升级坏掉:认不出的卡片忽略、新加的卡片排到最后、某个字段坏了只回落那一个字段;整份都认不出来时显示一条提醒,用默认布局。读布局失败时显示错误、用默认布局,并且不许编辑(否则一保存就把服务端那份真的布局覆盖掉了);保存失败时错误留在编辑器里,草稿不丢。

按 ⌘K(Windows / Linux 上是 Ctrl+K)打开命令面板,能搜三类东西:

  • 已打开的标签页
  • 页面:自己侧边栏里有的页面(已经开着的不重复列),外链也在里面
  • 操作:重新加载当前页、关闭其它标签页、关闭全部标签页、快捷键、功能引导;当下做不了的操作不列出来

按顺序匹配(输入的字按顺序出现在名称、路径或说明里就算命中),名称匹配排在前面。命令面板不搜业务数据,也没有「最近使用」。

快捷键:

键作用
⌘K / Ctrl+K打开命令面板
⌘B / Ctrl+B折叠 / 展开侧边栏
?快捷键帮助(在输入框里打问号不会触发)
↑ ↓ · Enter · Esc命令面板里选择、打开、关闭
鼠标中键点页签关闭页签(可以在偏好里关掉)
右键点页签页签菜单

一段七步引导:侧边栏 → 多页签 → 页面内容 → 命令面板 → 通知中心 → 个人中心 → 帮助。它不会自动弹出,要看的时候在顶栏「帮助 → 功能引导」或命令面板里点。关掉了多页签的人,引导自动跳过那一步。引导开着时新到的公告弹窗会等它结束再出来。

在「个人中心」的主题、布局、多标签页几栏里,改了立即生效,没有保存按钮:

项默认可选
主题模式浅色浅色 / 深色 / 系统
主题色靛蓝7 种
圆角大小柔和6 档
界面密度标准5 档(控件高 24–36 px)
滚动方式内容区域内容区域(顶栏和页签条不动)/ 整页
显示多标签页开
标签页外观卡片按钮 / 卡片 / 柔和 / 下划线
显示标签页图标 · 中键关闭 · 拖拽排序开

这些存在浏览器本地(localStorage 的 admin:prefs),不跟着账号走:换浏览器要重新设。「恢复默认」会把这些全部还原。登录页也跟随主题,并且有自己的主题和语言切换。

  • 列:表头右侧的「列」按钮里勾选显示哪些列、拖动调整顺序。设置写进地址栏(hide= 是隐藏的列,cols= 是和默认不同的顺序),所以刷新还在、发链接给别人也是同样的列;「恢复默认」清掉这两个参数。
  • 分页:每页 10 / 20 / 30 / 50 条,默认 20;改过之后才写进地址栏。
  • 查询区:回车查询;条件改了还没查时有一行提示「条件已改,按回车应用」,查询前先校验;可以添加条件、折叠。条件写进地址栏,「重置」清掉。筛选视图(把一组条件存起来)只存在浏览器本地,界面上写明了这一点。
  • 时区每人一个,在「个人中心 → 资料」里设,默认 Asia/Shanghai。它只影响界面上的时间怎么显示(列表、详情、工作台的问候与「今天」的边界、导出文件里的时间),不影响日志记录的时刻、也不影响定时任务按哪个时区跑。改完之后,已经打开的页签要刷新一下数据才会换算。
  • 语言有简体中文和 English,在右上角用户菜单或登录页切换,存在浏览器本地;切换后发给后端的请求带上 Accept-Language,后端的提示信息、参数配置名、接口说明等跟着换语言。用户自己录入的业务数据不翻译。

发了新版本,正在用的人怎么知道?

Section titled “发了新版本,正在用的人怎么知道?”

前端每 10 分钟、以及每次切回这个浏览器标签(最多每分钟一次)去取一次 /version.json,和自己打包时的版本号比;也会捕获「加载页面代码失败」这种发版后才会出现的错误。发现新版本时弹一条不会自动消失的提示「已发布新版本」,带「刷新」按钮。不会自己刷新 —— 用户可能正填着表单。

  1. 在 dashboard/cards/registry.ts 加一项:id、所在分组、标题、available(谁看得到)、默认宽度、默认是否显示。
  2. 在 cards/ 下写组件,外面套 DashboardCard。
  3. available 的判断要和取数接口的权限检查一致,一张卡片一个接口 —— 否则会出现「卡片显示了、接口 403」。
  4. 两份语言包加文案。
  5. 卡片的 id 永远不要改:用户存的布局按它认卡片,改了就等于删掉一张、加了一张新的。

命令面板加一个操作:往 shell/command-menu.tsx 的 actionItems 里加;新页面只要有菜单行就会自动出现。加快捷键没有注册表:自己挂监听,组合键要 preventDefault,单键要先判断是不是在输入框里,再到 shortcuts-dialog.tsx 里加一行说明。加一步功能引导:在 shell/tour/shell-tour.ts 里加步骤、给目标元素加 data-tour(目标不存在时 pnpm arch:check 会报错)。

  • 外观偏好、语言、筛选视图都只存在当前浏览器,不跟账号同步;只有工作台布局和时区存在服务端。
  • 只有外壳这一套功能引导,还没有按页面的引导。
  • 命令面板不支持拼音首字母搜索。
  • 改了时区,已打开的页签不会自动换算,要刷新数据。
  • 查询区里「今天」这类快捷时间按浏览器本地时间算,工作台的「今天」按显示时区算;两者不同时,从工作台跳过去的明细可能差一天(从代码推断,没有测试覆盖)。
  • 单元测试(Vitest):dashboard/layout.test.ts(17 条:新卡片排到最后、整份认不出来时回落默认并标出来……)、card-rules.test.ts、查询区的 params.test.ts(38 条)。
  • 后端:test_user_preference.py(没存过的键读出来是 null 而不是 404、只能读写自己的)、test_dashboard_ops.py(访问统计按看的人的时区切天)。
  • 浏览器端(Playwright):dashboard-personalize.spec.ts(10 条,含第二个浏览器登录同一个人看到同样的布局、读布局失败时显示错误且不能编辑)、command-palette.spec.ts(? 打开快捷键帮助,但在输入框里打问号不弹)、tour.spec.ts、new-version.spec.ts、query-bar.spec.ts。
  • 没有 E2E 的:外观偏好、切换时区、列显隐。

在线演示(admin / 123456):在工作台点「自定义」,把「公告」打开、拖到最前面、改成一半宽,保存;再开一个无痕窗口登录,看到的是同一套布局。按 ⌘K 输入「用户」直接跳到用户管理;按 ? 看全部快捷键。演示站所有人共用 admin,工作台布局也是共用的,试完点「恢复默认」。