81 lines
31 KiB
Markdown
81 lines
31 KiB
Markdown
# 管理后台 UI 与布局规范
|
||
|
||
本规范仅约束 `web/src/pages/admin/` 及对应的 `.admin-*` 样式，目标是在不改变业务流程、权限与 API 合同的前提下，统一管理界面的信息层级、密度、响应式行为和可访问性。
|
||
|
||
## 1. 视觉基线
|
||
|
||
- 颜色：继续使用 `globals.css` 的 Primitive → Semantic → Component 三层 token。管理端组件优先引用 `--admin-*`，不在页面内新增亮暗主题颜色字面值。
|
||
- 表面：页面与 PC 侧栏共用 `--admin-layer-0` 作为连续底色，表格、卡片、表单主体及当前导航项使用 `--admin-layer-1`，表头、摘要区、分页与输入底色使用 `--admin-layer-2`，强调表面使用 `--admin-layer-3`；区域关系通过细分隔线、选中表面和间距表达，不用大块异色把侧栏与内容割裂。亮暗主题均需保持相邻层级可见，不允许页面和卡片使用难以分辨的同色表面。
|
||
- 文字：标题、正文、辅助信息分别使用 `--admin-text-primary`、`--admin-text-secondary`、`--admin-text-muted`；不以低于辅助色的透明度承载必要信息。
|
||
- 浮层提示：侧栏图标、纯图标按钮等 Tooltip 必须同时声明主题背景、边框、箭头和文字色，不能只覆盖浮层背景而继续继承另一主题的文字 token。普通后台提示跟随当前主题；收起侧栏的图标提示与普通用户工作台复用同一高对比浮层类，亮色界面使用深底白字，暗色界面使用浅底深字，字号不低于 13px/650。侧栏提示尺寸必须由文字内容驱动，短文案自动收紧、长文案自然扩展，只在超过 220px 或视口安全宽度时换行；不得用固定宽高制造大面积空白，必要提示不得出现深底黑字或浅底白字。
|
||
- 密度：桌面端表格保持 42px 表头、52px 基础行高；主操作可点区不小于 32px，移动端主要导航可点区不小于 40px。
|
||
- 圆角与阴影：小控件使用 6–8px，主容器使用 10–12px；常态信息层级以底色和分隔线表达，不堆叠阴影。
|
||
|
||
## 2. 布局规则
|
||
|
||
- 大屏（≥1024px）：保留可折叠侧栏；内容区使用弹性高度，表格自身滚动，页面标题和分页保持稳定。
|
||
- PC 侧栏：与页面使用同一基底，右侧细线界定导航区域；分组标题采用“节点 + 标题 + 渐隐短线”的树状分组头，组内入口向右内缩，并用与标题节点对齐的低对比竖线连接。分组标题使用 12px/700，普通入口使用不低于 13px/500 和约 82% 前景色，不能因追求弱化而损失可读性。当前页面所属分组增强标题和节点；当前入口必须同时使用强调表面、至少 26% 前景色边框、较粗文字和左侧位置指示，确保亮暗主题与页面缩放下均能快速识别，不能只依赖轻微底色差。悬停项提升一个可见层级。顶部身份区使用单个可点击品牌信息块承载更新日志入口：展开态为左侧自适应品牌图标，右侧第一行品牌名“影策”、第二行当前版本号；点击整个信息块只打开更新日志弹窗，不执行页面导航。收起态仅保留水平居中的品牌图标，点击行为不变，并提供明确提示。底部辅助区只保留返回创作台等跨工作区动作，用分隔线与主导航区分，不额外引入整块背景；“返回创作台”固定进入 `/home`，并与普通用户端“管理员后台”使用相同的 34px 行高、图标尺寸和折叠提示。展开态宽 224px，收纳态宽 64px并保留品牌、导航和底部操作图标；展开/收纳入口放在侧栏与内容区之间的垂直中部边缘，不占用顶部品牌区。边缘把手必须用不透明侧栏表面和外围遮罩完整切断分界线，禁止线条从控件内部穿过；使用简洁左右方向箭头，默认融入边界，仅在悬停和聚焦时提升对比，并提供提示、`aria-label`、焦点反馈和与普通用户工作台即时同步的本地状态记忆。前后台展开宽度、折叠宽度和 PC 外壳外侧留白必须一致，往返页面不得发生 12px 内容宽度跳变。
|
||
- PC 后台主题入口：每个页面标题栏右上角必须提供独立明暗主题切换，不要求返回创作台；使用纯图标按钮、明确的 `aria-label` 和悬停提示，并与页面业务操作保持 8px 间距。
|
||
- 数据概览：定位为“运营健康驾驶舱”，首屏必须依次回答当前健康度、变化趋势和待处理事项，不能只是指标卡与大图表的纵向堆叠。工具栏优先提供 7 天、30 天、本月快捷范围和明确日期范围，用户、模型、渠道、能力等低频条件收进可展开筛选；刷新与导出保持在右侧。健康指标固定归纳为用户活跃、生成任务、服务质量和估算费用四域，队列、上游请求、P95 等从属信息进入对应指标卡，禁止在下一行重复展示；日变化必须写明“较前一日”，费用不可估算时明确提示价格未完整配置，不显示含义不明的 `--`。趋势区只在“用量 / 质量 / 活跃”三类中切换显示相关曲线，避免双坐标和多条曲线同时争夺注意力，高度控制在约 `280px`。CSS 视口达到 `1280px` 时趋势与“需要关注”按约 2:0.82 双列排列，关注区提前展示异常请求、排队任务和费用覆盖，并可跳转到对应分析或配置；更窄 PC 自动纵向排列。下方深度分析只保留模型、用户和异常三类读操作，模型价格作为独立配置入口进入抽屉，不与分析标签混排。所有筛选、导出、价格 CRUD、分页、接口和原始统计口径保持兼容。
|
||
- 中小屏（<1024px）：不将全部导航项平铺成长横向列表；始终显示当前页面，完整导航通过分组菜单打开。
|
||
- 页头：当前位置必须直接复用侧栏导航分组，统一显示为“分组 / 当前页面”，不得由各页面重复硬编码。分组名称使用较弱层级并可返回该分组首个入口，当前页面保留唯一 `h1` 和强调文字，原页面说明在下一行作为辅助信息；页面操作与当前位置块分离并保持右对齐，窄屏下操作区占满可用宽度并允许换行。
|
||
- 表格：表格外框使用 `--admin-card-border`，表头底色与下边线必须明显区别于数据区，每条数据行使用 `--admin-row-border`，悬停使用 `--admin-row-hover`；PC 主列表的表格卡片填满页头和筛选区之外的剩余高度，并与内容区底部保留 16px 安全间距；数据表面在内部滚动，分页保留在同一卡片内并固定于卡片底部，分页栏高度统一为 44px；少量数据时允许数据行下方保留空白表面。列宽可以保持业务可读性，窄屏通过表格容器横向滚动，分页区可换行，不强制压缩到难以点击。
|
||
- 表格对齐：名称、标题、地址和长文本等主信息列左对齐；数量、状态、角色、时间、类型、作用范围等结构化短字段的表头和内容统一居中；行操作区统一居中。操作菜单只有一个剩余动作时必须直接展示，不使用单项“更多”菜单；存在两个及以上低频或危险操作时才保留“更多”。
|
||
- 资源页筛选：用户、渠道、插件和提示词模板统一使用 `app-list-search` 搜索框与 Ant Select 下拉框；短状态/角色选择框宽 128px，类型选择框按文案使用 160–176px，控件高度沿用统一主题高度。选择框直接展示当前值，不重复生成筛选标签；存在任意筛选时仅在工具栏右侧显示统一“重置”操作。每个选择框必须提供资源明确的 `aria-label`。
|
||
- 运营工作台：系统公告、积分运营、兑换码和请求明细采用“列表优先”结构，列表与调查任务填满页头和筛选区之外的高度；发布、生成、策略和人工写入等操作放在页头，详细表单进入带固定底栏的弹窗或抽屉，不用常驻大表单压缩主列表。搜索与筛选沿用资源页规范，不重复显示筛选标签。
|
||
- 系统公告：默认主任务是发布状态与历史追踪，列表将公告主信息、类型、生命周期和操作收敛为四列；创建、编辑和重新发布进入带固定底栏的抽屉，真正写入前必须核对操作、类型、标题和用户端正文效果。编辑的真实语义是“重新发布”：恢复为发布中、刷新时间并清除旧已读状态，不得用普通静默编辑文案弱化后果。正文可使用链接、强调、列表等受控 HTML，主列表摘要、抽屉预览、最终确认和用户端必须复用同一安全渲染合同。发布或关闭的响应不确定时不得自动重试：切回未筛选列表，跨页面刷新保留核对状态，锁定全部写入口，并将“刷新完整列表”与管理员明确点击“我已核对”分为两步。创建、重新发布和关闭文案必须说明已打开用户端在下次同步后更新（当前通常为 5 分钟内），不得承诺所有客户端“立即”变化。成功响应必须校验公告 ID、状态和时间，返回未知状态的记录禁止行内写操作。
|
||
- 积分运营：默认主任务是异常计费核对；“积分策略”和“人工调账”作为页头独立操作。策略表单使用结构化模型倍率行，明确仅影响后续订单；人工调账必须显示目标用户、当前可用/冻结积分、变化量、预计余额和处理依据，并在真正写入前二次确认。计费核对使用“预授权”“实际结算”等准确口径，Token 订单不得把预授权额描述为最终扣费额。
|
||
- 兑换码运营：默认主任务是批次列表与核销追踪，生成表单进入页头触发的固定底栏抽屉。最终生成前必须核对单码积分、数量、批次总面值、过期时间和备注；“批次未到期”只表达时间条件，不能暗示仍有可用码，列表和明细均需分别展示可用、已核销、已过期和已禁用数量。生成接口没有可验证幂等结果时不得自动重试；响应不确定必须切回未筛选完整列表、持续提示并暂停再次生成，直至管理员完成一次成功刷新核对。明文兑换码只保留在当前内存会话，关闭结果层后清除；新批次可从加密记录回看，旧批次无法恢复时明确显示后四位与审计信息。批次或单码禁用后必须从服务端重载明细与父列表，写入期间锁定重复操作和浮层关闭。
|
||
- 请求明细：默认主任务是上游调用、平台任务与费用核对。默认日期范围必须作为可见筛选项展示，并明确服务端采用 UTC 日期边界；默认值也必须按 UTC 日历生成，输入需严格往返校验，两端含首尾最多 366 个自然日，不允许界面展示范围与服务端实际截取范围不一致。搜索提示只能列出后端真实支持的字段。主列表区分“调用结果”“平台任务状态”和“供应商状态”，不得把未知或未关联状态推断为成功；名称与路径保留左对齐，状态、耗时、用量、结果、费用和操作统一居中，完整技术字段进入分组详情。当前范围导出必须继承可见筛选并说明最多 10,000 条，已选导出最多 200 条；价格未配置、用量未返回和“请求固定费不计入估算”必须使用不同文案，不能以零值互相替代。请求固定费标记只控制每请求固定项，Token、媒体和视频时长仍可能产生估算费用，列表和详情必须继续展示后端返回的总估算值。列表和详情响应必须在渲染前校验关键字段、分页位置和枚举值，读取失败时清空旧数据。详情按调用概览、参与方与路由、用量与计费、追踪标识及默认收起的诊断报文分组；诊断报文只能说明服务端“尝试清理”，不得承诺完全脱敏，复制或转发前需提示再次核对。失败视频的人工查询属于可能保存媒体、恢复任务和结算费用的写操作，必须先以后端详情返回的只读资格结果确认协议、任务、归属、订单与上游标识均支持，旧后端或资格不可确认时必须安全关闭入口；仍必须二次确认、提交期间锁定、禁止自动重试，并在返回或网络结果不确定时跨刷新保留核对锁；只有成功刷新只读详情且管理员明确确认后才能解除。任务已经恢复但计费未结算时必须继续保留核对锁，并引导管理员前往积分运营核对对应订单，不能用一次性提示替代。详情、恢复确认和媒体预览均需建立正反向键盘焦点闭环，关闭后优先返回原触发器；原触发器因列表刷新或解除核对锁被卸载时，必须回到请求搜索等稳定后备焦点。
|
||
- 插件管理：PC 采用“紧凑总览条 + 统一筛选栏 + 单列管理表格”，不使用双列大卡片承载长插件清单；插件名称、版本、ID 和简述归入同一主信息列，类型、作用范围、平台状态与卸载操作分列展示。类型与状态下拉框直接显示当前筛选，不再重复生成筛选标签，存在筛选时保留统一重置操作。可信来源不在每行重复陈列，仅在来源未验证时显示警告；卸载列已有明确表头，行内只显示带无障碍名称的图标按钮，内置插件禁用并说明原因，只有上传的自定义插件允许执行。列表必须在表格内部滚动并使用统一底部分页，明暗主题下类型和状态标识均须保持可读对比度。
|
||
- 设置页：九个系统配置入口统一采用“页面标题 → 全宽状态操作栏 → 配置工作台”骨架，不再增加分区目录。CSS 视口达到 `1600px` 时，工作台使用“左侧主配置流 + 右侧配置摘要”：左侧按业务顺序纵向承载设置区，右侧摘要固定为约 `344px`、以 2×2 紧凑指标展示当前服务端状态，并在页面滚动时保持可见；摘要只保留名称和值，不重复长说明。设置区采用左侧约 `264px` 的标题、用途与状态摘要，右侧承载开关、互斥选择、表单网格、规则矩阵或列表，使管理员先理解影响再操作。左侧说明按表格单元格处理：图标、标题、说明和状态组成一个整体，在设置卡内垂直居中；状态与标题文字起始线对齐，不得把标题固定在顶部后留下大块无意义空白。说明单元与右侧控件区使用同一张卡片底色，只允许通过纵向细分隔线、图标浅底、标题和状态层级区分职责，不得形成卡片内侧栏。功能名称用标题层级表达，不将每个字段包装成同等重量的大卡片；正文按内容使用两列、三列或四列网格，单个输入不得随宽屏无限拉长。状态栏、主配置流与摘要之间统一使用 `16px` 间距，卡片圆角、边界和内外留白保持一致。`1600px` 以下自动回到“状态栏 → 横向四格摘要 → 单列设置流”，不得缩窄主配置区或产生横向滚动；设置区在更窄 PC 中再由左右结构转为上下结构。右侧摘要与设置卡在亮暗主题中必须通过相邻表面、细边界和清晰文字对比形成层级，不能依赖大块异色或阴影。
|
||
- 设置页顶部操作栏：功能状态、配置来源和刷新/撤销操作必须保持同一视觉层级。CSS 视口在 `1100–1279px` 的较窄 PC 仍优先使用单行左右布局，避免同一宽度下部分页面突然变成两层；只有低于 `1100px` 且内容确实无法容纳时才改为纵向排列。单行状态下操作组必须保持自身宽度，正文区域允许收缩，禁止产生页面级横向溢出或裁切按钮。所有新增的状态栏颜色、边界和过渡必须同时支持亮暗主题及减少动画偏好。
|
||
- 功能开放：属于全站访问控制，单个 Switch 与“系统渠道 / 前台模型目录”互斥选择在点击后立即写入，不再经过暂存按钮或二次确认。PC 工作台沿用其他系统配置入口的表格式阅读方向：左侧业务板将“用户工作台、插件策略、模型与环境”纵向排列，每个业务域使用约 `230–264px` 的说明单元和右侧紧凑控制区；图标、域标题、说明与当前数量或来源在说明单元内垂直居中，状态与标题起始线对齐。说明单元与控制区必须使用同一张卡片底色，仅以纵向细分隔线、图标浅底和文字层级区分职责，不得用整块异色把说明区做成卡片内侧栏。右侧约 `360px` 的共用详情栏展示当前选中功能的效果、控制范围和相反状态影响，并在 `1600px` 以上随滚动保持可见；低于 `1600px` 时详情回到业务板下方。卡片边界只用于业务域，不得给每个功能重复创建大卡片；内部功能使用约 58px 的紧凑控制行，用户工作台四项可在控制区保持 2×2 排列。关键影响不能只放在悬浮提示中。配置来源、更新时间与操作人并入顶部状态栏。存在依赖的控制必须用步骤、缩进和连接关系表达，插件范围在插件中心关闭时保留偏好但明确标示当前不生效。布尔开关仅用于真正的开放/关闭决策，紧凑行不在开关旁重复“开放/关闭”文字；开启状态必须使用成功色轨道与白色滑块，关闭状态使用带边界的中性灰轨道，在明暗主题中都不能只依赖滑块位置区分。依赖导致控制无效时保留“未生效”提示。模型来源详情使用完整来源名称，不以“开启/关闭”描述；运行环境决定的能力使用只读状态行，不伪装成禁用开关。页面在 PC 宽度下不得形成横向溢出；中小屏可将业务域说明与控制区恢复上下结构。提交期间锁定其他开关并显示写入状态；成功后以服务端返回值刷新全局能力，失败时恢复修改前状态且不得自动重试。读取失败提供页面级重试，已有数据刷新失败时保留上次成功状态并明确提示。保存响应必须校验七个可写字段与本次提交一致；桌面本地渠道等只读运行能力不得包含在保存请求中。
|
||
- 绘图工具：遵循系统配置统一骨架。四格概览依次展示新建默认编辑器、tldraw 可用性、已有 tldraw 绘图访问状态和配置来源；设置区按“默认编辑器、tldraw 授权”顺序纵向排列，每区使用左侧说明与状态、右侧控件。编辑器选择在可用条件满足时立即保存；选择不可用的 tldraw 必须拒绝并聚焦 License Key。授权文本仍先暂存，点击一次“保存修改”即直接提交，不再打开二次确认；移除后台授权时需在页面内持续展示对已有 tldraw 绘图的影响。提供撤销、刷新覆盖确认、浏览器刷新与后台导航保护；读取失败不得继续以旧会话状态开放保存，保存响应必须校验默认编辑器和经服务端裁剪后的授权内容与提交一致，失败不得自动重试并恢复可靠状态。
|
||
- 资源与策略：将账号配额、任务并发、任务超时、业务频控、渠道中转与熔断视为五个会立即影响运行中业务的策略域，不把 42 个数值项当作一张普通长表单。页面先展示配置来源、待保存数量和关键并发摘要，再按上述五个策略域直接纵向呈现设置区。较窄 PC 保持 1440px 以内阅读宽度和两至三列表单；1600px 以上状态、概览与策略卡随主内容扩展，右侧只保留正常页边距，1800px 以上参数再改为四列。全部数值先在本页暂存，按真实字段差异计算待保存数；点击一次“保存修改”直接校验并提交，不再打开二次确认。自用模式属于全量高上限预设，必须先解释会覆盖草稿且只填入本页；恢复默认属于立即删除管理员配置的写操作，继续二次确认。提供撤销、刷新覆盖确认、浏览器刷新与后台导航保护；读取和保存响应需校验全部 42 个整数、配置来源及与提交一致性，单文件上限不能大于账号文件总容量，失败不得自动重试。
|
||
- 登录与注册：必须把“能否创建新账号”和“Linux.do OAuth 登录”视为两个独立保存域，并在状态栏明确说明两者分别读取、分别保存。注册开关切换后立即保存，不再打开确认层；页面内必须持续说明本地注册、未绑定第三方账号和已有账号分别受到什么影响。Linux.do 入口开关在 Client、HTTPS 端点和回调地址满足服务端规则时立即保存，条件不足则恢复原状态并明确提示；凭据、OAuth 地址、Scopes 和字段映射仍在同一草稿中，点击一次“保存修改”直接提交。提供真实待保存状态、撤销、刷新覆盖确认、浏览器刷新和后台导航保护；不在界面或接口响应中展示 Client Secret。凭据、连接地址和高级字段映射使用明确二级分组，高级映射默认折叠但保留原生键盘语义。读取失败提供页面级重试，已有数据刷新失败时保留上次成功状态；保存响应必须校验除密钥明文外的全部公开字段与提交一致，失败不得自动重试。
|
||
- 邮件服务：将注册验证码投递、SMTP 服务器、身份验证和发件人身份作为一组配置域。验证码投递开关在主机、端口、发件邮箱及验证凭据满足服务端规则时立即保存；条件不足则恢复原状态并明确缺项。SMTP 文本、密码、连接安全和发件身份继续暂存，点击一次“保存修改”直接提交，不再二次确认。页面先展示投递状态、服务器、连接安全和发件身份概览，再按“验证码投递、SMTP 配置”纵向呈现；不得在后端没有探测或试发接口时提供虚假测试反馈。提供真实待保存状态、撤销、刷新覆盖确认、浏览器刷新与后台导航保护；SMTP 密码不得回显，留空明确表示保留已有值。保存响应必须校验全部公开字段与密钥存在状态，失败不得自动重试，也不得误称配置已通过连接验证。
|
||
- 站点及外观：按“品牌识别 → 登录页内容与媒体 → SEO 信息 → 首页收尾与备案 → 皮肤主题”纵向组织，复用设置页状态操作栏和 `SettingsSectionCard`，不另造视觉体系。品牌名必须投影到登录/注册/找回密码、继承型邮件发件人、用户可见导出/诊断和插件说明；内置名称只允许用于默认值与明确的恢复动作。首屏先读取公开外观再渲染应用，禁止自定义配置下闪现旧名称、Logo、海报或色系。皮肤通过 Primitive、Semantic、Component 三层 token 管理，业务页面不得按皮肤 ID 写条件样式；默认 `classic` 不覆盖既有 token 且不可删改，其他主题是可增删改名、复制和启用的数据。每套主题必须成对提供亮暗模式、按钮 hover/active、选中/焦点、开关、表面层级、图标、圆角、尺寸、动效和阴影，并同时映射 CSS Variables 与 Ant Design token。SEO 与版权允许留空后按当前品牌推导，备案展示默认关闭，开启时必须填写备案号并链接 `https://beian.miit.gov.cn/`；关键词字段不能宣称影响 Google 排名。所有字段、主题库与媒体保持单一草稿/保存/撤销/刷新覆盖保护，恢复默认不删除上传资源。
|
||
- 存储服务：必须把“新增资源默认写入位置”和“历史资源读取依据”明确区分。存储位置以可键盘选择的规则卡呈现服务器本地、阿里云 OSS、腾讯云 COS 与七牛云 Kodo；目标配置完整时选择后立即保存，缺少 Endpoint、Bucket 或凭据时只展开相应表单并明确提示补全后点击“保存修改”，不得提交无效配置。切换不得暗示会迁移、覆盖或删除已有资源；历史资源仍按自身记录读取，服务端在成功切换云厂商后归档上一厂商凭据。服务器本地与云存储使用不同表单层级；云存储按连接与读取出口、服务端凭据分组。文本和密钥调整点击一次“保存修改”直接提交，不再二次确认；没有后端检测接口时不得提供虚假验证反馈。提供撤销、刷新覆盖确认、浏览器刷新与后台导航保护，不显示 Secret 明文；读取与保存响应均需结构和一致性校验，失败不自动重试。
|
||
- 方舟素材库：该入口是 Seedance 可信参考素材的部署级同步策略和 IAM 接入配置，不得呈现为远端素材浏览列表。同步开关在 Region、ProjectName、AccessKey 与 SecretKey 条件满足时立即保存；条件不足则恢复原状态并提示缺项。项目和凭据继续暂存，点击一次“保存修改”直接提交，不再二次确认。页面必须准确说明触发条件及停用影响；Region、ProjectName 或 AccessKey 改变时说明服务端会清除默认素材组缓存并在下一次真实同步时惰性重建，保存本身不连接方舟、创建素材组、上传图片或等待审核。AccessKey 未变化时 SecretKey 留空可保留原密钥，更换 AccessKey 后启用前必须要求新的匹配 SecretKey。提供撤销、刷新覆盖确认、浏览器刷新与后台导航保护，不显示 Secret 明文；读取和保存响应需结构与字段一致性校验，失败不得自动重试。
|
||
- 模型响应拦截：必须定位为“用户可见错误文案投影”，不能暗示会修改上游响应、内部错误、失败记录或请求明细。全局开关切换后立即保存当前有效规则；规则内容和顺序继续暂存，点击一次“保存修改”直接提交，不再二次确认。规则语义必须与服务端一致：裁剪首尾空白、忽略英文大小写做包含判断、按列表顺序首条命中后整条替换。规则支持上移、下移、删除和最多 100 条限制；重复匹配文案需警告后续同文案无法命中。提供撤销、刷新覆盖确认、浏览器刷新与后台导航保护；启用但零规则不得描述为有效替换。本地预览只在浏览器内计算，不发送、不保存、不进入审计。读取和保存响应需做结构与规则顺序一致性校验，失败时即时开关恢复原状态且不得自动重试。
|
||
- 第三方参数配置：入口按外部平台组织，不能把平台凭据、用户功能开关和连接验证混成一行普通表单。LibTV 导入开关在已有服务端 Token 或当前草稿 Token 时立即保存；缺少 Token 时拒绝启用并保持原状态。Token 新增、替换或清除继续暂存，点击一次“保存修改”直接提交，不再二次确认；清除 Token 自动暂存停用入口，提交前不影响服务端。Token 留空明确表示保留已有值，明文不得回显。停用入口不得暗示会删除已导入节点与连线。连接验证是独立的真实外部只读请求，只使用服务端已保存 Token；没有已保存 Token 时关闭验证入口，保存不得顺带执行连接验证或读取外部画布。提供撤销、刷新覆盖确认、浏览器刷新与后台导航保护；读取和保存响应需做结构及启用/凭据存在状态一致性校验，失败时即时开关恢复原状态且不得自动重试。
|
||
- 弹窗：标题区、可滚动正文和底部操作栏必须是三个独立层级；标题区与底部栏使用分隔线，主要/次要按钮固定在底部右侧。弹窗宽度遵循内容类型，不得被通用宽屏类意外覆盖组件声明宽度。更新日志弹窗的产品标题只出现一次，当前版本使用中性紧凑标识，不使用主按钮色或纯黑色块；正文按“开发中 → 历史版本”顺序形成可扫描的版本时间线，每个版本标题与其变更列表使用稳定间距和边界，正文行宽、列表缩进、代码片段及滚动区域必须在亮暗主题下保持清晰。
|
||
|
||
## 3. 交互与可访问性
|
||
|
||
- 导航容器使用 `nav` 和明确的 `aria-label`；菜单触发器必须暴露当前页名称和展开含义。
|
||
- 图标不能是唯一的业务语义；仅装饰图标设置 `aria-hidden="true"`，纯图标按钮提供 `aria-label`。
|
||
- 搜索输入框必须提供与当前资源对应的明确 `aria-label`，不能只依赖会在输入后消失的占位文字传达用途。
|
||
- 分页的每页条数选择器必须提供独立的无障碍名称，不能只依赖当前值表达用途。
|
||
- 所有键盘可操作元素保留 `:focus-visible` 反馈；不用单纯颜色区分状态。
|
||
- 加载、空态、错误和已选批量状态必须有文字语义；动画尊重 `prefers-reduced-motion`。
|
||
- 财务、批量生成、重新通知和任务恢复等带业务副作用的操作，必须在确认层清楚展示对象、数量或金额、处理依据和可能后果；提交期间禁止重复执行或误关闭。确认层只用于核对，不得在用户点击最终确认前提前调用写接口。
|
||
- PC 页面切换使用约 190ms 的轻微淡入位移，主题表面、边框和控件状态使用约 180ms 的颜色过渡；顶栏明暗主题切换使用约 220ms 的整页交叉淡入，避免高反差裁剪边界扫过页面产生感知闪烁；形状揭示仅保留给明确需要的局部场景，执行时必须暂停组件级颜色过渡并固定新主题快照的初始状态；不使用影响操作节奏的大幅移动或长动画。
|
||
- 移动菜单选择后立即跳转并关闭，不改变原路由、权限和 feature flag 判断。
|
||
- 后台 PC 视觉回归按 `docs/design/admin-ui-visual-regression-baseline.md` 固定覆盖 18 个可见入口、亮色 `1600 × 1000` 和暗色 `1278 × 900`；以 CSS 视口、页面标题、文档横向溢出、主框架右边界和应用控制台为硬性通过条件，不以浏览器外框或缩放百分比代替页面实测。
|
||
|
||
## 4. 变更约束
|
||
|
||
- 管理端 UI 调整必须按批次追加到 `docs/design/admin-ui-change-log.md`。
|
||
- 每批必须在修改前保存受影响文件的原始副本或可验证基线，并记录 SHA-256。
|
||
- 不改动 API 请求、数据结构、权限判断和业务文案，除非调整直接解决 UI 可用性问题。
|
||
- 优先修改共享壳与共享组件，只在页面有独特布局需求时添加页面私有规则。
|
||
|
||
## 5. 本次审查摘要
|
||
|
||
### 覆盖范围
|
||
|
||
- 结构：核对 `AGENTS.md`、`web/package.json`、`web/src/router.tsx`、管理端页面目录、共享壳、共享 UI 组件、Ant Design 主题入口和全局样式。
|
||
- 页面：覆盖数据概览、用户、系统渠道、前台模型、插件、提示词模板、公告、积分、兑换码、请求明细以及登录、邮件、存储、运行策略、绘图工具、方舟素材、响应拦截和第三方配置。
|
||
- 交互：检查桌面/折叠/移动导航、页头操作、筛选、表格滚动、分页、批量操作、空态、骨架屏、抽屉、弹窗和设置卡。
|
||
- 可访问性：检查语义导航、标题层级、纯图标按钮名称、状态文字、键盘焦点反馈、加载语义和减少动画适配。
|
||
|
||
### 审查结论
|
||
|
||
- 优点：管理端已有清晰的路由边界、共享页面壳、共享表格/状态/设置卡组件、集中主题 token、亮暗主题以及表格滚动和焦点反馈基线。
|
||
- 本次已解决：中小屏全量导航平铺、窄屏页头/分页/批量操作挤压、设置摘要边界不清，以及唯一的管理端未定义表面 token。
|
||
- 有意保留：数据表格在小屏保持列信息并横向滚动，没有转成会丢失对比效率的卡片列表；模型能力编辑器中已有特定设计意图的亮色样式未做无关重构。
|
||
- 已解决：Tiptap 核心与扩展已经统一锁定为 `3.28.0`，Vite 锁定为 `8.1.5`，全量类型检查、前端测试和生产构建恢复通过；管理端已建立鉴权后的双尺寸、双主题 PC 视觉回归基线。
|
||
- 剩余风险：视觉基线目前依赖真实登录态执行，尚未接入 CI 的脱敏管理员账号与自动截图差异门禁；后续接入时不得提交真实业务数据或密钥截图。
|