baozaotumao2025
33 lines
2.3 KiB
Markdown
33 lines
2.3 KiB
Markdown
# 架构与主题
|
||
|
||
## 数据流
|
||
|
||
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()`。
|
||
|
||
```text
|
||
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 才清理会话，续约成功不刷新路由、当前用户查询或业务状态。
|