refactor(web): 前端目录重构 — consoles/pages → layouts/features + shared
- consoles/admin/ → layouts/admin-layout/ - consoles/workbench/ → layouts/workbench-layout/ + features/chat/ - pages/ → features/ (dashboard, models, projects, not-found) - components/ → shared/components/ - hooks/ → shared/hooks/ - utils/ → shared/utils/ - 更新所有 import 路径 (src/web/ + tests/web/) - 更新开发文档 (README.md, frontend.md, architecture.md)
This commit is contained in:
@@ -2,26 +2,35 @@
|
||||
|
||||
开发规范见 [开发规范文档](README.md)。
|
||||
|
||||
## 控制台架构
|
||||
## 布局架构
|
||||
|
||||
两个控制台入口共享 ConsoleShell（`src/web/components/ConsoleShell/`）：
|
||||
两个布局入口共享 ConsoleShell（`src/web/shared/components/ConsoleShell/`）：
|
||||
|
||||
- **Admin**（`src/web/consoles/admin/`）：路由 `/`（总览）、`/projects`、`/models`。
|
||||
- **Workbench**（`src/web/consoles/workbench/`）：路由 `/workbench/:projectId`、`/workbench/:projectId/chat`。`WorkbenchProjectGate` 从 URL 读 projectId，通过 `ProjectContext` 提供项目上下文，仅 active 项目渲染。
|
||||
- **AdminLayout**（`src/web/layouts/admin-layout/`）：路由 `/`（总览）、`/projects`、`/models`。
|
||||
- **WorkbenchLayout**（`src/web/layouts/workbench-layout/`）：路由 `/workbench/:projectId`、`/workbench/:projectId/chat`。`WorkbenchProjectGate` 从 URL 读 projectId，通过 `ProjectContext` 提供项目上下文，仅 active 项目渲染。
|
||||
|
||||
ConsoleShell 包含：`XProvider(zhCN + zhCN_X)` + `AntApp` + `Layout`(Header/Sider/Content) + 主题切换（明亮/黑暗/系统）+ 侧边栏折叠。Header 显示品牌名、版本号和控制台标题。
|
||||
ConsoleShell 包含：`XProvider(zhCN + zhCN_X)` + `AntApp` + `Layout`(Header/Sider/Content) + 主题切换（明亮/黑暗/系统）+ 侧边栏折叠。Header 显示品牌名、版本号和布局标题。
|
||||
|
||||
`Sidebar`（`src/web/components/Sidebar/`）纯展示组件，通过 `menuItems` props 接收配置。
|
||||
`Sidebar`（`src/web/shared/components/Sidebar/`）纯展示组件，通过 `menuItems` props 接收配置。
|
||||
|
||||
## 功能模块
|
||||
|
||||
| 功能模块 | 路径 | 说明 |
|
||||
| -------- | --------------------- | --------------------------- |
|
||||
| 仪表盘 | `features/dashboard/` | 总览页面 |
|
||||
| 项目管理 | `features/projects/` | 项目 CRUD、归档、搜索 |
|
||||
| 模型管理 | `features/models/` | 供应商/模型管理、连通性测试 |
|
||||
| 聊天 | `features/chat/` | 会话管理、消息渲染、AI 对话 |
|
||||
|
||||
## 页面
|
||||
|
||||
| 页面 | 路径 | 入口 |
|
||||
| -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| 总览 | `/` | `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` |
|
||||
| 页面 | 路径 | 入口 |
|
||||
| -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 总览 | `/` | `features/dashboard/index.tsx` |
|
||||
| 项目管理 | `/projects` | `features/projects/index.tsx` — ProjectToolbar(Tab 切换 active/archived + 搜索 + 新建) + ProjectTable + ProjectFormModal。支持创建/编辑/归档/恢复/删除，仅 active 项目可跳转工作台。 |
|
||||
| 模型管理 | `/models` | `features/models/index.tsx` — antd Tabs 切换供应商/模型视图。模型表单和表格使用 `GET /api/providers/options`。供应商表单支持预保存连通性测试（`POST /api/providers/test`），新建时 type 默认 `openai-compatible`，测试 `ok: false` 展示失败但不阻止保存。 |
|
||||
| 聊天室 | `/workbench/:id` | `features/chat/index.tsx` |
|
||||
| 404 | `*` | `features/not-found/index.tsx` |
|
||||
|
||||
### 聊天页面
|
||||
|
||||
@@ -31,19 +40,31 @@ ConsoleShell 包含：`XProvider(zhCN + zhCN_X)` + `AntApp` + `Layout`(Header/Si
|
||||
- **ChatPanel**：`useChat`（@ai-sdk/react）+ `DefaultChatTransport`（ai 包）与后端 SSE 通信。按 `part.type` 分派渲染：TextPart（XMarkdown）、ReasoningPart、ToolPart（四态）。支持编辑重发、重新生成、复制。
|
||||
- **Sender**（@ant-design/x）：输入框 + 发送/停止按钮 + 模型 Select（footer slot）。
|
||||
|
||||
## 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 持久化 |
|
||||
### 共享组件
|
||||
|
||||
## 工具函数
|
||||
| 组件 | 路径 | 说明 |
|
||||
| ------------- | ------------------------------------- | --------------------------------- |
|
||||
| ConsoleShell | `shared/components/ConsoleShell/` | 全局布局外壳（Provider + Layout） |
|
||||
| Sidebar | `shared/components/Sidebar/` | 侧边栏纯展示组件 |
|
||||
| ErrorBoundary | `shared/components/ErrorBoundary.tsx` | 生产环境错误边界 |
|
||||
|
||||
### 共享 Hooks
|
||||
|
||||
| Hook | 路径 | 说明 |
|
||||
| ----------------------- | --------------------------------------- | ----------------------------------------- |
|
||||
| `use-meta.ts` | `shared/hooks/use-meta.ts` | `/api/meta`（30s 轮询，5s staleTime） |
|
||||
| `use-providers.ts` | `shared/hooks/use-providers.ts` | 供应商 CRUD + test connection |
|
||||
| `use-models.ts` | `shared/hooks/use-models.ts` | 模型 CRUD + test connection |
|
||||
| `use-projects.ts` | `shared/hooks/use-projects.ts` | 项目 CRUD + archive/restore |
|
||||
| `use-conversations.ts` | `shared/hooks/use-conversations.ts` | 会话和消息 fetch 函数（不含 Query hooks） |
|
||||
| `use-logger` | `shared/hooks/use-logger.ts` | Logger hook（组件内使用） |
|
||||
| `use-theme-preference` | `shared/hooks/use-theme-preference.ts` | 主题偏好 localStorage 持久化 |
|
||||
| `use-sidebar-collapsed` | `shared/hooks/use-sidebar-collapsed.ts` | 侧边栏折叠 localStorage 持久化 |
|
||||
| `use-is-dark` | `shared/hooks/use-is-dark.ts` | 当前是否暗色主题 |
|
||||
|
||||
### 共享工具函数
|
||||
|
||||
| 文件 | 导出 |
|
||||
| --------------- | --------------------------------------------------------------------------------------------- |
|
||||
@@ -52,13 +73,13 @@ ConsoleShell 包含：`XProvider(zhCN + zhCN_X)` + `AntApp` + `Layout`(Header/Si
|
||||
|
||||
## 更新触发条件
|
||||
|
||||
修改前端技术栈、组件边界、数据流、样式规则、测试环境、前端验证方式、运行时代码结构、页面组成、组件索引或 hooks/工具清单时，必须更新本文档。
|
||||
修改前端技术栈、组件边界、数据流、样式规则、测试环境、前端验证方式、运行时代码结构、页面组成、组件索引、hooks/工具清单、目录结构或功能模块归属时，必须更新本文档。
|
||||
|
||||
## 日志模块
|
||||
|
||||
### Logger 接口
|
||||
|
||||
`src/web/utils/logger.ts` 提供与后端镜像的 Logger 抽象：
|
||||
`src/web/shared/utils/logger.ts` 提供与后端镜像的 Logger 抽象：
|
||||
|
||||
```typescript
|
||||
export interface Logger {
|
||||
@@ -85,7 +106,7 @@ export interface Logger {
|
||||
**组件内（推荐）：**
|
||||
|
||||
```typescript
|
||||
import { useLogger } from "../hooks/use-logger";
|
||||
import { useLogger } from "../../shared/hooks/use-logger";
|
||||
|
||||
function MyComponent() {
|
||||
const logger = useLogger({ component: "MyComponent" });
|
||||
@@ -98,7 +119,7 @@ function MyComponent() {
|
||||
**非组件纯函数：**
|
||||
|
||||
```typescript
|
||||
import { createConsoleLogger } from "../utils/logger";
|
||||
import { createConsoleLogger } from "../../shared/utils/logger";
|
||||
|
||||
const logger = createConsoleLogger();
|
||||
logger.debug("调试信息");
|
||||
|
||||
Reference in New Issue
Block a user