# 架构与主题

## 数据流

UI 页面只调用 `services/`；service 先用 `schemas/` 中的 Zod schema 校验请求，再由 `api/client.ts` 发起请求并用 Zod 校验响应。跨字段业务不变量也在 schema 层完成。错误统一进入 `errors/`，日志进入 `logging/` 并在输出前递归脱敏。

```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 才清理会话，续约成功不刷新路由、当前用户查询或业务状态。