DESIGN.md@ai-admin-front · diff
git:20261027.3e9d064 to git:20261105.548ccf4
12 added, 0 removed. Audit A to A.
# 管理端设计与组件
管理端是工作台，优先信息密度、扫描效率与可重复操作。视觉用于表达当前任务、数据和操作层级，状态、身份与业务约束来自后端。
## 页面结构
- 先核对路由、`MainLayout.vue`、共享导航与项目作用域，再调整页面；内容切换保持布局壳稳定。
- `PageHeader` 统一标题、说明与主操作，不另建重复 hero、返回栏或范围卡片。
- 列表使用连续工作面，搜索、筛选、视图切换、表格与分页形成一条任务路径。空、加载、失败、无权限和局部数据缺失分别表达。
- 项目、账号、TAB 或路由变化使旧请求与确认失效；未保存输入、冲突和写操作保持明确保护。
- 窄屏自然换行，宽表局部滚动；键盘、焦点、Escape、关闭回焦和可访问名称随改动一起验证。
## 主题的唯一维护位置
| 层 | 位置 |
| --- | --- |
| 品牌 | `src/styles/tokens/_brand.scss` |
| 语义颜色、表面、边框和状态 | `src/styles/tokens/_semantic.scss` |
| 控件密度 | `src/styles/tokens/_density.scss` |
| 页面间距与布局节奏 | `src/styles/tokens/_layout.scss` |
| 材质与回退 | `src/styles/_glass.scss` |
| Element Plus 映射与组件配方 | `_element-plus.scss`、`_components.scss`、`_overlays.scss` |
| 折射层 | `src/components/common/LiquidGlassLayer.vue` |
| 用户偏好 | `src/composables/useTheme.ts` |
业务页面使用现有 token，不散落硬编码颜色，不单独判断减少透明度，也不复制模糊、高光、厚边、阴影或实色回退。新材质先扩展公共语义与组件；减少透明度、暗色、强制颜色和不支持滤镜的回退由公共层处理。
## 公共入口
```ts
import {
LiquidGlassPage, LiquidGlassFilterBar, LiquidGlassTable,
LiquidGlassButton, LiquidGlassInput, LiquidGlassSelect,
LiquidGlassTabs, LiquidGlassDropdown,
} from '@/components/common/liquid-glass'
```
| 组件 | 用途 |
| --- | --- |
| LiquidGlassPage / PageHeaderTags | 页面布局与页头辅助信息 |
| LiquidGlassFilterBar / Input / Select | 搜索、筛选、表单输入 |
| LiquidGlassTable / Pagination | 表格、空态与分页；业务列由使用方提供 |
| LiquidGlassButton / Dropdown | 主次操作、图标按钮和菜单 |
| LiquidGlassNav / Tabs / ViewToggle | 工作区、标签和视图切换 |
| LiquidGlassCard / EmptyState / Notice | 内容分区、状态与页面提示 |
属性、事件和插槽遵循包装组件与其原生 Element Plus 控件。业务页面继续提供 loading、disabled、权限和业务处理，不因换皮肤重写操作。`class/style` 的外壳应用、原生 ref 与扩展属性以 [公共导出](src/components/common/liquid-glass/index.ts)及组件定义为准。
## 弹层与对话
普通弹窗和抽屉使用 `AppDialog` / `AppDrawer`，保留挂载、宽度、事件、焦点循环和关闭语义。非模态 Studio 面板按原挂载方式处理，不为样式统一改变交互。材质覆盖只证明外观，不代表保存、发布或认证业务已验收。
管理端与 SDK 共用的对话样式在 `src/conversation/styles/conversation-tokens.css`。SDK 只读取自身根节点主题，不被宿主的 `html.dark` 或同名变量污染；`eaf.*` 与 `Eaf*` 是兼容技术身份。
+ ### 个人工作台
+
+ 「我的首页」使用紧凑的公共 `PageHeader`，系统入口在上、对话在中、最近办事记录在下。系统卡片的「打开系统」与「AI 办事／连接 AI」分开表达，系统多时展示六个入口并提供可搜索的全部系统弹窗。欢迎态复用 `ConversationComposer`，开始办事后复用员工个人页 `EmployeeAssistant` 和 SDK 对话宿主；不另写流式消息、审批交互或鉴权逻辑。未连接时明确引导连接；推荐内容来自当前系统已发布的只读能力，点击只填入草稿。状态、连接隔离和使用边界见[产品说明](../docs/product.md)。
+
+ | Capability | Canonical owner | Source of truth | Allowed variants | Verification |
+ | --- | --- | --- | --- | --- |
+ | Select/Listbox | `LiquidGlassSelect` / Element Plus | 公共组件与主题 token | authored | 组件行为测试、浏览器打开与键盘选择 |
+ | Date | 原生日期输入或页面既有日期组件 | 当前页面契约与 locale | native / authored；工作台只格式化显示时间 | 对应页面行为测试 |
+ | Form | 公共输入组件；对话使用 `ConversationComposer` | 页面校验与共享对话控制器 | 应用校验、IME 安全提交 | 行为测试 |
+ | Scrollbar | 全局 `src/styles/index.scss` 与语义 token | 全局应用样式 | 全局基线、局部尺寸 | 主题检查与浏览器计算样式 |
+ | Toast | Element Plus `ElMessage` | 应用入口与统一主题 | success / warning / info / error；可恢复错误在页内展示 | 相关页面行为测试 |
+
## 业务能力与 Studio
Java 方法和 HTTP API 目录均为平铺分页表，分类是可选元数据。关键词与下拉分开保存，刷新或分类变化不能丢失未提交输入。普通模式隐藏批量调整控件，进入“整理 → 调整分类”后就地维护成员；失权、未知分类与确认未分类分开处理。
Studio 节点选中后在右侧直接编辑，保留一层配置/测试/调试记录；主配置优先，高级契约按需展开。名称、变量插入、提示词预览与当前节点操作贴近。运行语义与发布约束见 [Workflow](../docs/workflow.md)，不能靠画布表现新增节点能力。
## 验证
运行相关组件/行为测试和 `npm run build`，按改动检查 `check:glass-theme`、`check:dark-theme-compatibility`、`check:glass-components`、`check:overlay-migration`、`check:page-rhythm` 与 `check:page-header-family`。新断言不削弱既有契约。
浏览器覆盖桌面/窄屏、亮暗与品牌、减少透明度、加载/空/失败、键盘、焦点和取消。夹具注明范围；发布使用的 SDK 另验证宿主隔离。新增第三方算法或素材同步 [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES.md)。