# Boardware Genius Frontend

这是 `Boardware Genius` 的前端项目，基于 Next.js 13 App Router 构建，提供聊天工作台、登录注册、系统状态、定时任务、技能、插件、智能体、MCP、文件管理等页面。

这个仓库只负责前端界面和浏览器侧交互，不包含后端服务实现。前端通过 HTTP 和 WebSocket 与后端网关通信。

## 项目定位

- 面向 `Boardware Genius` 的 Web 控制台
- 提供统一的聊天入口和运维入口
- 支持多页面管理能力：
  - 对话与会话管理
  - 系统状态查看
  - 定时任务管理
  - 技能 / 插件 / 智能体 / MCP 管理
  - 工作区文件浏览与上传下载

## 主要功能

### 1. 聊天工作台

- 左侧会话列表，支持切换、新建、删除会话
- 主聊天区支持文本输入、文件上传、命令提示
- WebSocket 实时接收消息和过程事件
- 展示任务执行过程、结构化事件和执行产物

### 2. 认证与访问控制

- 提供登录、注册页面
- 业务页与认证页使用不同 layout
- 通过 `AuthGuard` 保护业务页访问
- Access Token / Refresh Token 存在浏览器本地存储

### 3. 平台管理页面

- `状态`：查看后端配置、模型、Provider、通道、调度器状态
- `定时任务`：新增、启停、执行、删除 Cron 任务
- `技能`：查看、上传、下载、删除技能包
- `插件`：查看已安装插件及其命令、技能、智能体
- `智能体`：新增和管理工作区智能体
- `MCP`：配置 MCP 服务、测试连接、查看发现的工具
- `市场`：浏览和安装市场中的插件
- `文件`：浏览工作区目录，上传、下载、删除文件/目录
- `帮助`：查看使用说明

## 页面路由

| 路由 | 说明 |
| --- | --- |
| `/` | 聊天工作台 |
| `/login` | 登录页 |
| `/register` | 注册页 |
| `/status` | 系统状态 |
| `/cron` | 定时任务 |
| `/skills` | 技能管理 |
| `/agents` | 智能体管理 |
| `/mcp` | MCP 服务管理 |
| `/marketplace` | 技能市场 |
| `/files` | 工作区文件管理 |
| `/help` | 帮助说明 |

## 技术栈

- Next.js 13.5
- React 18
- TypeScript
- Tailwind CSS
- Radix UI
- Zustand
- Lucide React

补充说明：

- 生产构建输出为 `standalone`
- 首页做了按需加载和请求链路优化
- 登录/注册与业务页已拆为不同 route group layout

## 目录结构

```text
app/
  (app)/               业务页面与业务布局
  (auth)/              登录/注册页面与认证布局
  globals.css          全局样式
  layout.tsx           根布局

components/
  chat-workbench/      聊天工作台组件
  ui/                  通用 UI 组件
  AuthGuard.tsx        认证守卫
  Header.tsx           顶部导航

lib/
  api.ts               前端 API / WebSocket 客户端
  store.ts             Zustand 状态管理

types/
  index.ts             全局类型定义
```

## 本地开发

### 环境要求

- Node.js 20
- npm
- 可访问的后端服务

### 安装依赖

```bash
npm install
```

### 配置环境变量

可以参考 `env_template`：

```env
NEXT_PUBLIC_API_URL=http://127.0.0.1:10000
NEXT_PUBLIC_WS_URL=wss://127.0.0.1:10000
NEXT_PUBLIC_KEYCLOAK_ISSUER=https://keycloak.bwgdi.com/realms/beaver
NEXT_PUBLIC_KEYCLOAK_CLIENT_ID=beaver-agnet
NEXT_PUBLIC_KEYCLOAK_REDIRECT_URI=http://172.19.0.245:18080/auth/callback
NEXT_PUBLIC_KEYCLOAK_POST_LOGOUT_REDIRECT_URI=http://172.19.0.245:18080/logout/callback
```

当前前端的地址策略是：

- 如果配置了 `NEXT_PUBLIC_API_URL` / `NEXT_PUBLIC_WS_URL`，优先使用显式配置
- 未登录会跳转到 `NEXT_PUBLIC_KEYCLOAK_ISSUER` 的 Authorization Code + PKCE 登录页
- 退出登录会跳转到 Keycloak logout endpoint，并通过 `NEXT_PUBLIC_KEYCLOAK_POST_LOGOUT_REDIRECT_URI` 回到前端
- 如果未配置，浏览器端会优先使用当前站点同源地址

### 启动开发环境

```bash
npm run dev
```

默认监听：

- `http://0.0.0.0:3080`

## 构建与运行

### 本地生产构建

```bash
npm run build
npm run start
```

### 常用脚本

```bash
npm run dev
npm run build
npm run start
npm run lint
npm run typecheck
```

## Docker 运行

项目内已提供 `Dockerfile`，生产镜像基于 Next.js standalone 输出运行。

注意：

- 当前 `Dockerfile` 里包含 `npm run -s verify:modules` 校验步骤，但 `package.json` 里暂时没有这个脚本
- 如果你直接执行镜像构建，需要先补上该脚本，或者移除这一步校验

在修正上述校验步骤后，可按下面方式构建：

```bash
docker build -t boardware-genius-frontend .
docker run --rm -p 3000:3000 boardware-genius-frontend
```

如果你需要在构建时显式注入后端地址：

```bash
docker build \
  --build-arg NEXT_PUBLIC_API_URL=https://api.example.com \
  --build-arg NEXT_PUBLIC_WS_URL=wss://api.example.com \
  -t boardware-genius-frontend .
```

## 部署建议

### 推荐：前后端同域部署

生产环境建议让前端页面与后端 API / WebSocket 走同一域名，例如：

- 前端页面：`https://boardware.example.com`
- API：`https://boardware.example.com/api/...`
- WebSocket：`wss://boardware.example.com/ws/...`

这样可以避免：

- 跨域预检
- 混合内容问题
- 证书域名不匹配
- 额外的浏览器安全限制

### 反向代理建议

推荐在 Nginx / Caddy / 网关层代理：

- `/api` -> 后端 HTTP 服务
- `/ws` -> 后端 WebSocket 服务

如果已经做了同域代理，前端可以不显式配置 `NEXT_PUBLIC_API_URL` 和 `NEXT_PUBLIC_WS_URL`。

## 前端交互约定

### 认证

- 登录成功后，前端把 token 存在本地
- 业务页通过 `AuthGuard` 做访问控制
- 认证页与业务页已拆分布局，避免登录页加载业务导航

### 聊天

- 聊天页优先使用 WebSocket 实时通信
- 非关键数据采用延迟加载或空闲检查
- Markdown 渲染做了拆包，减少首页首包体积

### 状态管理

- 全局状态使用 Zustand
- 聊天消息、会话、连接状态、过程事件等都在 `lib/store.ts` 中维护

## 注意事项

### 1. 这是前端仓库

如果页面能打开但功能不可用，优先检查后端是否已启动并暴露：

- 认证接口
- 聊天接口
- 会话接口
- 状态接口
- WebSocket 连接

### 2. 技术标识

当前前端使用 Beaver 技术命名，本地 token、语言和 Keycloak 登录状态都使用 `beaver_*` key。

### 3. 动态内容可能仍包含英文

来自后端、插件、技能包或外部市场的数据描述，可能仍然带有英文内容。当前仓库已经把前端固定文案尽量中文化，但动态数据仍以实际返回为准。

## 维护建议

- 新增页面时优先放进合适的 route group：`(app)` 或 `(auth)`
- 新增接口统一走 `lib/api.ts`
- 新增全局状态统一放到 `lib/store.ts`
- 新增用户可见文案优先使用中文，避免再次出现中英混杂

## 当前状态

- 页面品牌：`Boardware Genius`
- 中文化：已覆盖主要固定文案
- 布局拆分：已完成
- 生产构建：可通过 `npm run build`