docs: 开发文档面向AI精简重构，补充文档编撰规范
This commit is contained in:
@@ -1,70 +1,53 @@
|
||||
# 前端开发
|
||||
|
||||
本文档说明 alfred 前端的运行时代码结构、组件索引和页面组成。开发规范（组件规范、Ant Design 用法、样式规则、表单交互、TanStack Query、测试约定等）见 [开发规范文档](README.md#开发规范)。
|
||||
开发规范见 [开发规范文档](README.md)。
|
||||
|
||||
适用场景：修改 `src/web/`、了解现有组件和页面结构、查找 hooks 和工具函数。
|
||||
## 控制台架构
|
||||
|
||||
## 运行时外壳
|
||||
两个控制台入口共享 ConsoleShell（`src/web/components/ConsoleShell/`）：
|
||||
|
||||
前端提供两个入口外壳，共享通用 Console Shell 组件：
|
||||
- **Admin**（`src/web/consoles/admin/`）：路由 `/`（总览）、`/projects`、`/models`。
|
||||
- **Workbench**（`src/web/consoles/workbench/`）：路由 `/workbench/:projectId`、`/workbench/:projectId/chat`。`WorkbenchProjectGate` 从 URL 读 projectId，通过 `ProjectContext` 提供项目上下文，仅 active 项目渲染。
|
||||
|
||||
- **Admin（管理台）**：`src/web/consoles/admin/AdminConsoleLayout.tsx`，菜单配置在 `src/web/consoles/admin/menu.tsx`，路由 `/`（总览）、`/projects`（项目管理）、`/models`（模型管理）。
|
||||
- **Workbench（工作台）**：`src/web/consoles/workbench/WorkbenchProjectGate.tsx` → `WorkbenchConsoleLayout.tsx`，菜单配置和路由构造在 `src/web/consoles/workbench/routes.ts`，路由 `/workbench/:projectId` 和 `/workbench/:projectId/chat`。默认菜单为"聊天室"。
|
||||
ConsoleShell 包含：`ConfigProvider(zhCN)` + `AntApp` + `Layout`(Header/Sider/Content) + 主题切换（明亮/黑暗/系统）+ 侧边栏折叠。Header 显示品牌名、版本号和控制台标题。
|
||||
|
||||
通用 Console Shell（`src/web/components/ConsoleShell/ConsoleShell.tsx`）包含 `ConfigProvider`（zhCN locale）、`AntApp`、`Layout`、`Header`、`Sider`、`Content`、主题切换（明亮/黑暗/系统）和侧边栏折叠状态，由 Admin 和 Workbench 复用。Header 显示品牌名、版本号和控制台标题（Admin 显示"管理台"，Workbench 显示"工作台 · 项目名"）。
|
||||
`Sidebar`（`src/web/components/Sidebar/`）纯展示组件，通过 `menuItems` props 接收配置。
|
||||
|
||||
Menu 类型定义在 `src/web/menu.tsx` 中的 `MenuItemConfig` 接口（icon、label、path、value）。
|
||||
## 页面
|
||||
|
||||
Sidebar（`src/web/components/Sidebar/index.tsx`）是纯展示/导航组件，通过 `menuItems` props 接收菜单配置，由调用方决定菜单内容和路径。Admin 传入静态路径 `/`、`/projects`、`/models`；Workbench 通过 route builder（`buildWorkbenchPath`）将相对菜单路径拼成 `/workbench/:projectId` 的子路径。
|
||||
|
||||
Workbench 项目上下文通过 `ProjectContext`（`src/web/consoles/workbench/ProjectContext.tsx` 和 `ProjectContextValue.ts`）提供，在 `WorkbenchProjectGate` 中从 URL path param 读取 `projectId`，通过 `useProject(projectId)` 加载项目，仅 active 项目渲染工作台布局，不存在或 archived 项目显示"项目不存在或不可访问"。
|
||||
|
||||
### 页面概览
|
||||
|
||||
| 页面 | 路径 | 入口文件 |
|
||||
| -------- | ---------------- | ----------------------------------------------- |
|
||||
| 总览 | `/` | `src/web/pages/dashboard/index.tsx` |
|
||||
| 项目管理 | `/projects` | `src/web/pages/projects/index.tsx` |
|
||||
| 模型管理 | `/models` | `src/web/pages/models/index.tsx` |
|
||||
| 聊天室 | `/workbench/:id` | `src/web/consoles/workbench/pages/ChatPage.tsx` |
|
||||
| 404 | `*` | `src/web/pages/404/index.tsx` |
|
||||
|
||||
### 项目管理页面
|
||||
|
||||
项目管理页面（`src/web/pages/projects/index.tsx`）使用 `ProjectToolbar`（Tab 切换 active/archived + 搜索 + 新建按钮）、`ProjectTable`（列表展示、内联操作）和 `ProjectFormModal` 拆分职责。支持创建、编辑、归档、恢复和永久删除项目，仅 active 项目可点击跳转工作台。
|
||||
|
||||
### 模型管理页面
|
||||
|
||||
模型管理页面（`src/web/pages/models/index.tsx`）通过 antd `Tabs` 在同页组织供应商和模型两个视图。页面使用 `ModelsToolbar`、`ProviderTable`、`ProviderFormModal`、`ModelTable`、`ModelFormModal` 拆分职责；模型表单和模型表格必须使用 `GET /api/providers/options` 获取最小供应商选项。供应商表单支持未保存配置的连通性测试（`POST /api/providers/test`），新建供应商时 type 默认 `openai-compatible`，baseURL 不设默认值。连通性测试返回 `ok: false` 时展示失败反馈；`/models` 不支持属于可忽略提醒，不阻止保存。
|
||||
| 页面 | 路径 | 入口 |
|
||||
| -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| 总览 | `/` | `pages/dashboard/index.tsx` |
|
||||
| 项目管理 | `/projects` | `pages/projects/index.tsx` — ProjectToolbar(Tab 切换 active/archived + 搜索 + 新建) + ProjectTable + ProjectFormModal。支持创建/编辑/归档/恢复/删除，仅 active 项目可跳转工作台。 |
|
||||
| 模型管理 | `/models` | `pages/models/index.tsx` — antd Tabs 切换供应商/模型视图。模型表单和表格使用 `GET /api/providers/options`。供应商表单支持预保存连通性测试（`POST /api/providers/test`），新建时 type 默认 `openai-compatible`，测试 `ok: false` 展示失败但不阻止保存。 |
|
||||
| 聊天室 | `/workbench/:id` | `consoles/workbench/pages/ChatPage.tsx` |
|
||||
| 404 | `*` | `pages/404/index.tsx` |
|
||||
|
||||
### 聊天页面
|
||||
|
||||
Workbench 聊天页面位于 `src/web/consoles/workbench/pages/ChatPage.tsx`，组合 `ChatSidebar` 和 `ChatPanel` 两个子组件。
|
||||
`ChatPage` = `ChatSidebar` + `ChatPanel`。
|
||||
|
||||
- **ChatSidebar**（`src/web/consoles/workbench/components/chat/ChatSidebar.tsx`）：使用 TanStack Query 管理会话列表，提供创建和删除会话操作。
|
||||
- **ChatPanel**（`src/web/consoles/workbench/components/chat/ChatPanel.tsx`）：使用 Vercel AI SDK `useChat` hook（来自 `@ai-sdk/react`）管理聊天状态，通过 `DefaultChatTransport`（来自 `ai` 包）与后端 SSE 端点通信。采用论坛式单列垂直布局，使用 antd `Card` 组件承载每条消息，通过按 `part.type` 分派渲染（文本/推理/工具调用）。AI 文本使用 `streamdown` 流式 Markdown 渲染。支持编辑上一条用户消息后重新发送、重新生成最后一条 AI 回复、复制消息内容。
|
||||
- **ChatInputArea**（`src/web/consoles/workbench/components/chat/ChatInputArea.tsx`）：使用 antd `Input.TextArea` + `Button` + `Select` 组合，支持模型切换和发送/停止操作。
|
||||
- **Part renderers**（`src/web/consoles/workbench/components/chat/parts/`）：`TextPart.tsx`（Markdown 文本渲染）、`ReasoningPart.tsx`（推理过程）、`ToolPart.tsx`（工具调用展示，支持 input-streaming/input-available/output-available/output-error 四态）。
|
||||
- **ChatSidebar**：TanStack Query 管理会话列表，创建/删除操作。
|
||||
- **ChatPanel**：`useChat`（@ai-sdk/react）+ `DefaultChatTransport`（ai 包）与后端 SSE 通信。按 `part.type` 分派渲染：TextPart（streamdown Markdown）、ReasoningPart、ToolPart（四态）。支持编辑重发、重新生成、复制。
|
||||
- **ChatInputArea**：`Input.TextArea` + `Button` + `Select`（模型切换）。
|
||||
|
||||
`use-conversations` hook 位于 `src/web/hooks/use-conversations.ts`，封装会话 CRUD 和消息获取的 fetch 调用。
|
||||
## Hooks
|
||||
|
||||
## Hooks 索引
|
||||
| Hook | 说明 |
|
||||
| ----------------------- | ----------------------------------------- |
|
||||
| `use-meta.ts` | `/api/meta`（30s 轮询，5s staleTime） |
|
||||
| `use-projects.ts` | 项目 CRUD + archive/restore |
|
||||
| `use-providers.ts` | 供应商 CRUD + test connection |
|
||||
| `use-models.ts` | 模型 CRUD + test connection |
|
||||
| `use-conversations.ts` | 会话和消息 fetch 函数（不含 Query hooks） |
|
||||
| `use-theme-preference` | 主题偏好 localStorage 持久化 |
|
||||
| `use-sidebar-collapsed` | 侧边栏折叠 localStorage 持久化 |
|
||||
|
||||
| Hook 文件 | 说明 |
|
||||
| -------------------------- | ------------------------------------------------- |
|
||||
| `use-meta.ts` | 获取 `/api/meta`（30s 轮询，5s staleTime） |
|
||||
| `use-projects.ts` | 项目 CRUD + archive/restore API |
|
||||
| `use-providers.ts` | 供应商 CRUD + test connection API |
|
||||
| `use-models.ts` | 模型 CRUD + test connection API |
|
||||
| `use-conversations.ts` | 会话和消息 fetch 函数（不含 Query hooks） |
|
||||
| `use-theme-preference.ts` | 主题偏好（明亮/黑暗/跟随系统）localStorage 持久化 |
|
||||
| `use-sidebar-collapsed.ts` | 侧边栏折叠状态 localStorage 持久化 |
|
||||
## 工具函数
|
||||
|
||||
## 工具函数索引
|
||||
|
||||
| 文件 | 说明 |
|
||||
| 文件 | 导出 |
|
||||
| --------------- | --------------------------------------------------------------------------------------------- |
|
||||
| `utils/api.ts` | `handleResponse()`、`handleVoidResponse()` — 通用 fetch 响应处理 |
|
||||
| `utils/api.ts` | `handleResponse(response, extract)`、`handleVoidResponse(response)` |
|
||||
| `utils/time.ts` | `formatCountdown`、`formatDurationUnit`、`formatRelativeTime`、`isOlderThan`、`subtractHours` |
|
||||
|
||||
## 更新触发条件
|
||||
|
||||
Reference in New Issue
Block a user