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

在界面上哪里找?
Section titled “在界面上哪里找?”| 入口 | 在哪 | 存在哪 |
|---|---|---|
| 工作台、「自定义」按钮 | 仪表盘 /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 | 整行,显示 |
没有权限的卡片不渲染,而不是渲染一个「无权限」的空壳;后端取数接口按同一套条件拦。「系统运行」这一组只对能看到其中至少一张卡片的人出现。
怎么自定义工作台?
Section titled “怎么自定义工作台?”点右上角「自定义」进入编辑模式(地址栏里多一个 edit=true,刷新还在):
- 每张卡片可以显示或隐藏
- 拖拽排序,也可以用键盘(空格拿起、方向键移动、空格放下);每组各排各的
- 宽度四档:三分之一 / 一半 / 三分之二 / 整行
- 挑「常用入口」里放哪些页面
- 「恢复默认」
布局按人存在服务端(sys_user_preference 表,键 dashboard.layout),换浏览器、换电脑登录都一样。兼容规则保证布局不会因为升级坏掉:认不出的卡片忽略、新加的卡片排到最后、某个字段坏了只回落那一个字段;整份都认不出来时显示一条提醒,用默认布局。读布局失败时显示错误、用默认布局,并且不许编辑(否则一保存就把服务端那份真的布局覆盖掉了);保存失败时错误留在编辑器里,草稿不丢。
命令面板和快捷键
Section titled “命令面板和快捷键”按 ⌘K(Windows / Linux 上是 Ctrl+K)打开命令面板,能搜三类东西:
- 已打开的标签页
- 页面:自己侧边栏里有的页面(已经开着的不重复列),外链也在里面
- 操作:重新加载当前页、关闭其它标签页、关闭全部标签页、快捷键、功能引导;当下做不了的操作不列出来
按顺序匹配(输入的字按顺序出现在名称、路径或说明里就算命中),名称匹配排在前面。命令面板不搜业务数据,也没有「最近使用」。
快捷键:
| 键 | 作用 |
|---|---|
| ⌘K / Ctrl+K | 打开命令面板 |
| ⌘B / Ctrl+B | 折叠 / 展开侧边栏 |
? | 快捷键帮助(在输入框里打问号不会触发) |
| ↑ ↓ · Enter · Esc | 命令面板里选择、打开、关闭 |
| 鼠标中键点页签 | 关闭页签(可以在偏好里关掉) |
| 右键点页签 | 页签菜单 |
功能引导是什么?
Section titled “功能引导是什么?”一段七步引导:侧边栏 → 多页签 → 页面内容 → 命令面板 → 通知中心 → 个人中心 → 帮助。它不会自动弹出,要看的时候在顶栏「帮助 → 功能引导」或命令面板里点。关掉了多页签的人,引导自动跳过那一步。引导开着时新到的公告弹窗会等它结束再出来。
外观能调哪些?
Section titled “外观能调哪些?”在「个人中心」的主题、布局、多标签页几栏里,改了立即生效,没有保存按钮:
| 项 | 默认 | 可选 |
|---|---|---|
| 主题模式 | 浅色 | 浅色 / 深色 / 系统 |
| 主题色 | 靛蓝 | 7 种 |
| 圆角大小 | 柔和 | 6 档 |
| 界面密度 | 标准 | 5 档(控件高 24–36 px) |
| 滚动方式 | 内容区域 | 内容区域(顶栏和页签条不动)/ 整页 |
| 显示多标签页 | 开 | |
| 标签页外观 | 卡片 | 按钮 / 卡片 / 柔和 / 下划线 |
| 显示标签页图标 · 中键关闭 · 拖拽排序 | 开 |
这些存在浏览器本地(localStorage 的 admin:prefs),不跟着账号走:换浏览器要重新设。「恢复默认」会把这些全部还原。登录页也跟随主题,并且有自己的主题和语言切换。
列表页的列、分页和筛选
Section titled “列表页的列、分页和筛选”- 列:表头右侧的「列」按钮里勾选显示哪些列、拖动调整顺序。设置写进地址栏(
hide=是隐藏的列,cols=是和默认不同的顺序),所以刷新还在、发链接给别人也是同样的列;「恢复默认」清掉这两个参数。 - 分页:每页 10 / 20 / 30 / 50 条,默认 20;改过之后才写进地址栏。
- 查询区:回车查询;条件改了还没查时有一行提示「条件已改,按回车应用」,查询前先校验;可以添加条件、折叠。条件写进地址栏,「重置」清掉。筛选视图(把一组条件存起来)只存在浏览器本地,界面上写明了这一点。
- 时区每人一个,在「个人中心 → 资料」里设,默认
Asia/Shanghai。它只影响界面上的时间怎么显示(列表、详情、工作台的问候与「今天」的边界、导出文件里的时间),不影响日志记录的时刻、也不影响定时任务按哪个时区跑。改完之后,已经打开的页签要刷新一下数据才会换算。 - 语言有简体中文和 English,在右上角用户菜单或登录页切换,存在浏览器本地;切换后发给后端的请求带上
Accept-Language,后端的提示信息、参数配置名、接口说明等跟着换语言。用户自己录入的业务数据不翻译。
发了新版本,正在用的人怎么知道?
Section titled “发了新版本,正在用的人怎么知道?”前端每 10 分钟、以及每次切回这个浏览器标签(最多每分钟一次)去取一次 /version.json,和自己打包时的版本号比;也会捕获「加载页面代码失败」这种发版后才会出现的错误。发现新版本时弹一条不会自动消失的提示「已发布新版本」,带「刷新」按钮。不会自己刷新 —— 用户可能正填着表单。
给工作台加一张卡片
Section titled “给工作台加一张卡片”- 在
dashboard/cards/registry.ts加一项:id、所在分组、标题、available(谁看得到)、默认宽度、默认是否显示。 - 在
cards/下写组件,外面套DashboardCard。 available的判断要和取数接口的权限检查一致,一张卡片一个接口 —— 否则会出现「卡片显示了、接口 403」。- 两份语言包加文案。
- 卡片的
id永远不要改:用户存的布局按它认卡片,改了就等于删掉一张、加了一张新的。
命令面板加一个操作:往 shell/command-menu.tsx 的 actionItems 里加;新页面只要有菜单行就会自动出现。加快捷键没有注册表:自己挂监听,组合键要 preventDefault,单键要先判断是不是在输入框里,再到 shortcuts-dialog.tsx 里加一行说明。加一步功能引导:在 shell/tour/shell-tour.ts 里加步骤、给目标元素加 data-tour(目标不存在时 pnpm arch:check 会报错)。
- 外观偏好、语言、筛选视图都只存在当前浏览器,不跟账号同步;只有工作台布局和时区存在服务端。
- 只有外壳这一套功能引导,还没有按页面的引导。
- 命令面板不支持拼音首字母搜索。
- 改了时区,已打开的页签不会自动换算,要刷新数据。
- 查询区里「今天」这类快捷时间按浏览器本地时间算,工作台的「今天」按显示时区算;两者不同时,从工作台跳过去的明细可能差一天(从代码推断,没有测试覆盖)。
- 工作台:
pages/dashboard/(layout.ts兼容规则、editor.tsx编辑模式、cards/)· 偏好接口api/v1/sys/user.py的/me/preferences/{key}· 规矩见dashboard/AGENTS.md - 外壳:
shell/command-menu.tsx·shell/hotkeys.ts·shell/tour/·shell/preferences.ts - 列表:
_shared/use-column-visibility.ts·_shared/use-column-order.ts· 查询区ui/components/query-bar/ - 时间显示:
i18n/src/datetime.ts· 发版提示apps/web/src/lib/app-version.ts
- 单元测试(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 的:外观偏好、切换时区、列显隐。
在演示站里试试
Section titled “在演示站里试试”在线演示(admin / 123456):在工作台点「自定义」,把「公告」打开、拖到最前面、改成一半宽,保存;再开一个无痕窗口登录,看到的是同一套布局。按 ⌘K 输入「用户」直接跳到用户管理;按 ? 看全部快捷键。演示站所有人共用 admin,工作台布局也是共用的,试完点「恢复默认」。