gpt-load/web/README.md

Web 工程开发说明

index.html 和 src/main.ts 是唯一构建入口。pnpm run build 一次构建两套前端，产物仍写入 internal/webui/dist，随 Go 二进制交付。

代码边界

• src/frontends/classic/：完整保留原前端，原 @/ 别名指向此目录，避免无关路径改写。除界面切换设置外，不调整原有页面、交互或功能实现。
• src/frontends/modern/：新版独立的启动、路由、布局、组件、业务功能、接口类型、样式和文案。@modern/ 指向此目录。
• src/shared/：HTTP 客户端、基础协议、语言标识和浏览器界面偏好。@shared/ 指向此目录。页面响应 DTO、业务查询编排和组件不放在这里。

两套前端都可依赖 shared，但不能互相引用；shared 不能反向引用前端或启动入口。现有 ESLint 命令检查静态导入、导出、动态导入和资源 glob 的路径边界。

两套前端分别拥有样式入口，只启动所选界面。旧版 Tailwind 的源码扫描限制在 classic 内；入口和 shared 不导入任何一套界面的样式。

界面切换

浏览器界面偏好使用 gpt-load.frontend.v2：选择经典版时保存 classic，选择新版时清除该值，默认 modern。旧键 gpt-load.frontend 在启动时清理，不再参与界面选择。登录页和访问密钥会话始终使用新版；只有管理员可以在设置页选择自己的界面。选择保存后重新加载 /settings，每次只创建一个应用和路由实例。

只有保存了经典版偏好且存在登录凭据时，启动选择器才查询 /api/auth/session，等待最多 5 秒，包含响应正文读取。确认管理员身份后加载经典版；确认访问密钥身份或收到 401 时清理界面偏好。存储读取、网络、超时、临时 HTTP 错误或响应格式异常时回到新版，并保留原选择，由新版认证界面提供恢复入口。语言和明暗模式保留既有浏览器存储约定。

旧版全局设置增加界面选择和示意缩略图。存在未保存修改或设置操作尚未结束时，需先完成原有保存/放弃流程。偏好无法保存时显示错误并保留当前界面。

当前实现范围

新版目前提供 Coral Anchor 品牌框架：位于分隔线中部的侧栏折叠控件、移动端导航抽屉、宽工作区。顶栏是各页共用的固定结构，左侧为当前页标题，随后是数据更新时间与刷新，竖线之后依次是导入密钥入口、明暗模式、语言和退出；全局设置保留界面切换。页面导航按“工作区”“运行观测”和“系统”直接展示，不通过二级 Tab 进入观测页面。

app/navigation.ts 统一描述导航入口。internal/webui/page_routes.json 保留旧版原有的 9 个页面地址；新版独有的 /monitor/usage、/monitor/logs、/monitor/health、/monitor/inspector 放在 internal/webui/modern_page_routes.json。服务端与新版合并读取两份清单，旧版只读取原清单，避免新增页面触发旧版的路由完整性检查。所有页面仍返回同一个 HTML 入口；/monitor 在新版跳转到用量页面，旧版保持原行为。

新版已提供总览、分组列表与详情、访问密钥、模型管理、请求日志、用量统计、运行健康和全局设置。总览围绕客户端接入配置、请求趋势、订阅账号额度和健康待办组织内容；客户端选择与路由检查独立。/monitor/inspector 重定向到首页的路由检查区，保留检查参数；/import 重定向到分组页的导入入口，选择新建分组或为已有分组添加凭据。路由加载失败时提供刷新重试。

分组工作区采用双行列表：分组与渠道、凭据总数及状态进度条、模型数量及计价倍率、近 24 小时请求与用量、启停与行内权重。支持本地搜索、渠道与运行视图筛选、排序、复制地址和就地展开完整模型。完整轻量快照一次读取，默认每页 20 条，可选 50 / 100；表头与底部分页固定，仅内容区滚动。基础编辑在分组详情中完成，模型和高级配置使用独立侧栏。API 密钥与订阅账号分别提供卡片、筛选、分页、详情及批量操作；订阅账号同步状态相互独立。

模型页以请求模型卡片展示上游来源、关联分组及计价规则。日志页支持游标分页、详情和字段快捷筛选；用量页提供请求成功/失败、输入/输出 Token、缓存与费用趋势及来源排行。健康页和首页待办共用 /api/health，报告返回完整异常明细，筛选与分页在浏览器中完成，不限制后端报告数量。业务数据继续由后端 principal 权限合同约束。

明暗模式和语言是本地浏览器偏好，登录页也可调整；全局设置页沿用管理员访问限制。侧栏收起状态使用 gpt-load.modern.sidebar-collapsed，所有界面偏好不读写服务端配置。两套设置页使用共享界面目录中的示意缩略图。新版品牌组件根据实际明暗状态变化触发动画，也处理侧栏折叠和展开；遵守减少动效偏好。

侧栏底部以两行两列展示外链：首行为使用文档、赞助支持，次行为 GitHub、Telegram。GitHub 使用官方 Octicons 标识。分隔线下显示版本号和管理员更新检查入口；设置页的系统信息区也提供更新检查。版本来自现有 /health，新版本只在用户点击时通过 /api/system/update 检查，传 force=true 并使用当前已验证的管理员会话。新版统一持有检查状态，侧栏与设置页共享结果，不重复检查；访问密钥用户不查询管理员更新接口。

新版页面可以独立设计展示 DTO、聚合查询及管理接口。modern/api/ 为其独立接口代码目录。分组展示使用 /api/modern/groups，当前页用量通过 /api/modern/groups/usage 批量读取，每次最多 100 个分组，复用后端精确时间窗口及最终请求归属。边界明细查询使用分组与完成时间联合索引，避免逐组扫描或计算完整排行榜。凭据展示使用 /api/modern/groups/:group_id/credentials 和其详情接口，按当前页补充活动数据。启停与编辑继续调用既有管理接口，旧接口合同及核心流程、数据面行为保持稳定。

登录与权限

新版登录独立实现于 modern/features/auth/，调用既有 GET /api/auth/session，沿用 gpt-load.auth-key 存储键。“记住登录”默认不勾选，使用 sessionStorage 保持当前标签页会话（刷新仍有效）；勾选后使用 localStorage。只在认证成功且响应身份为 admin 或 access_key 后写入所选存储，并清除另一种存储中的旧凭据。恢复时优先读取当前标签页的 sessionStorage，再读取 localStorage；退出或认证失效清理两种存储。

空值、空白字符、错误密钥、锁定、网络错误和无效响应保留各自反馈，登录失败不修改已有凭据。锁定倒计时到期后允许手动重试，/login?help=auth 可直接打开密钥来源帮助。

刷新后的密钥先重新验证，再挂载工作区和业务组件；并发恢复只发出一次验证。网络与响应异常保留密钥并显示重试入口。认证失效时清空会话、取消并清除新版查询缓存，返回登录页；权限拒绝的 403 不误登出。登录成功后只返回站内已知受保护路径，保留查询和 hash；管理员专属路径对访问密钥用户回退到总览。

app/navigation.ts 的 adminOnly 同时约束路由、侧栏和快捷导航。管理员可进入全部入口；访问密钥仅可进入总览、模型、用量和日志，身份范围仍由后端校验。右上角退出操作保留导航失败或离开受阻时的会话，成功离开后清理认证与缓存。

HTTP 客户端按请求捕获会话版本；身份已切换或请求已取消时，迟到的 401 不清除新会话。会话恢复及登录响应也检查版本和取消状态，防止退出后被旧响应重新登录。所选存储不可用时仍使用内存会话，不记住时不会回退到 localStorage；业务代码和版本检查从会话客户端取凭据，不直接读取浏览器存储。认证逻辑和组件不依赖 classic，共享 HTTP 层提供基础请求合同；服务端继续负责身份认证与接口权限。

验证

前端使用现有 lint、format、type-check 和 build；最终运行仓库 make check。不增加前端测试、浏览器验收或本地 race。