# AI Safety Console Web

AI 模型内部安全测试平台的独立 React 前端。UI 使用官方 [AgentScope Spark Design](https://sparkdesign.agentscope.io/)，提供可持久化切换的蓝色安全控制台和浅色专业两套主题。

## 项目结构

```text
src/
├── api/          # Fetch 客户端与 Zod 响应校验
├── auth/         # 会话、身份恢复和登退录
├── design/       # Spark tokens、两套主题与切换状态
├── errors/       # 错误类型、归一化和 React Error Boundary
├── logging/      # 结构化日志与敏感数据脱敏
├── schemas/      # Zod 请求/响应和业务不变量
├── services/     # 与全部后端端点对应的业务服务
├── pages/        # 页面交互
└── components/   # 可复用 UI 状态和主题切换
tests/
├── unit/         # 日志、错误、schema、API 和主题单元测试
└── integration/  # 端点契约和 UI 切换集成测试
docs/               # UI、交互、架构、API、测试与部署文档
```

认证支持 access/refresh token 原子轮换、活跃用户静默续约、标签页内/跨标签页 single-flight，以及业务请求 401 后的一次续约与重放。跨标签页协调使用浏览器 Web Locks API。

## 本地开发

需要 Node.js 20–24 和 Corepack。

```bash
corepack enable
pnpm install --frozen-lockfile
cp .env.example .env
pnpm dev
```

默认访问 `http://localhost:5173`，API 默认为 `http://127.0.0.1:8000/api/v1`。不要将模型 API Key 放入前端 `.env`；密钥只由后端保管。

## 质量检查

```bash
pnpm check
```

真实后端检查（不会使用 mock，需提供测试账户）：

```bash
E2E_API_BASE_URL=http://localhost:8000/api/v1 E2E_USERNAME=admin E2E_PASSWORD=密码 pnpm test:e2e
```

该命令依次运行 ESLint、Vitest 和生产构建。

## 容器部署

```bash
VITE_API_BASE_URL=https://api.example.com/api/v1 docker compose up --build -d
```

默认映射到 `http://localhost:8080`。`VITE_API_BASE_URL` 是构建时变量，修改后需重新构建镜像。

## 文档

- [UI 规范（强制令牌与提交门禁）](docs/ui-design.md)
- [交互设计](docs/interaction-design.md)
- [架构与主题](docs/architecture.md)
- [API 映射](docs/api-contracts.md)
- [测试、安全与运维](docs/operations.md)