baozaotumao2025
2.3 KiB
架构与主题
数据流
UI 页面只调用 services/；service 先用 schemas/ 中的 Zod schema 校验请求，再由 api/client.ts 发起请求并用 Zod 校验响应。跨字段业务不变量也在 schema 层完成。错误统一进入 errors/，日志进入 logging/ 并在输出前递归脱敏。
API 客户端默认读取并校验 JSON；文件端点显式选择 Blob 响应类型，同时复用 Bearer Token、401 单次续约重放和 JSON 错误归一化。下载由页面使用浏览器原生 Object URL 完成，不引入额外下载依赖。
创建运行和 Token 续约统一通过 idempotencyKey.ts 生成 UUID v4 幂等键：安全上下文优先使用浏览器原生 crypto.randomUUID()，HTTP 或旧浏览器回退到 crypto.getRandomValues()；不使用可预测的 Math.random()。
pages/components → services → schemas + api client → FastAPI
↓
errors + logging
Spark Design
组件仅从官方 @agentscope-ai/design 引入。src/design/theme.ts 是主题注册表，它将 Spark/Ant Design token 与业务页分开；ThemeProvider.tsx 只负责注入主题和切换状态；styles.css 使用语义 CSS 变量，不在页面内写主题颜色。
当前主题：
blue：默认的深蓝安全控制台。light：以 Spark 官方#615CED为主色、#FAFAFA为布局底色的浅色方案。
新增主题时，扩展 ThemeName、themes 注册表和对应 [data-theme] CSS 变量，再把两态切换控件改为选择器即可，不需要修改业务页。
认证与路由
access token、refresh token 和两个过期时间作为一个 JSON 对象原子保存在 localStorage，使多标签页共享同一会话。启动时通过 /auth/me 恢复身份。AuthGuard 保护业务路由，AdminGuard 保护用户管理。
auth/activity.ts 只记录点击、键盘、触摸和导航，30 秒内最多写入一次；轮询和页面可见本身不算活动。auth/refresh.ts 在用户活跃且 access token 进入最后 30 分钟时静默续约。标签页内用共享 Promise，标签页间用 Web Locks 保证只有一个 refresh；待刷新的业务请求用新 access token 重放一次。refresh 401 才清理会话，续约成功不刷新路由、当前用户查询或业务状态。