feat: 全局设置系统 — settings 表、CRUD 路由、主题偏好持久化
This commit is contained in:
@@ -31,35 +31,45 @@ Request -> Bun.serve routes 声明式匹配 -> routes/*.ts handler -> helpers/
|
||||
- 共享类型在 `src/shared/`。
|
||||
- 前端禁止 import `src/server/` 运行时实现；后端禁止依赖 `src/web/` 运行时代码（HTML import 集成除外）。
|
||||
|
||||
## 配置定位
|
||||
|
||||
| 配置类型 | 来源 | 内容 | 可变性 |
|
||||
| -------- | ------------------------------------------------------------------------ | ------------------------------ | ---------- |
|
||||
| 启动配置 | CLI 传入的 `config.yaml` | 监听地址、端口、日志、数据目录 | 进程内只读 |
|
||||
| 业务设置 | 管理台 `/settings` 页面 → `GET/PUT /api/settings` → SQLite `settings` 表 | 主题偏好等 UI/业务开关 | 运行时可变 |
|
||||
|
||||
启动配置由 `src/server/config.ts` 的 `loadServerConfig()` 在启动时加载并校验，运行时不可更改。业务设置通过独立 API 持久化，与启动配置在存储和生命周期上完全解耦。
|
||||
|
||||
## 主要模块
|
||||
|
||||
| 模块 | 职责 |
|
||||
| ------------------------- | -------------------------------------------------------- |
|
||||
| `src/server/bootstrap.ts` | 统一启动引导、DB 初始化、shutdown 编排 |
|
||||
| `src/server/config.ts` | 配置加载入口：YAML 解析、规范化、契约校验、运行时校验 |
|
||||
| `src/server/config/` | 配置子系统：types、variables、issues、normalizer、schema |
|
||||
| `src/server/logger.ts` | Logger 接口 + Pino 实现 + 测试替身 |
|
||||
| `src/server/server.ts` | Bun HTTP server + routes 注册 |
|
||||
| `src/server/routes/` | API handler，按资源端点拆分 |
|
||||
| `src/server/db/` | SQLite 连接、schema、migration、data access |
|
||||
| `src/server/ai/` | AI Provider Registry + Agent + 工具 |
|
||||
| `src/server/helpers/` | 响应格式化、URL 工具 |
|
||||
| `src/server/middleware/` | 参数校验 + 错误处理 |
|
||||
| `src/web/layouts/` | 前端布局组件（AdminLayout / WorkbenchLayout） |
|
||||
| `src/web/features/` | 前端功能模块（dashboard / projects / models / chat） |
|
||||
| `src/web/shared/` | 前端共享代码（components / hooks / utils） |
|
||||
| `src/shared/api.ts` | 前后端共享 API 类型 |
|
||||
| `src/shared/app.ts` | 应用全局常量 |
|
||||
| 模块 | 职责 |
|
||||
| ------------------------- | --------------------------------------------------------------- |
|
||||
| `src/server/bootstrap.ts` | 统一启动引导、DB 初始化、shutdown 编排 |
|
||||
| `src/server/config.ts` | 配置加载入口：YAML 解析、规范化、契约校验、运行时校验 |
|
||||
| `src/server/config/` | 配置子系统：types、variables、issues、normalizer、schema |
|
||||
| `src/server/logger.ts` | Logger 接口 + Pino 实现 + 测试替身 |
|
||||
| `src/server/server.ts` | Bun HTTP server + routes 注册 |
|
||||
| `src/server/routes/` | API handler，按资源端点拆分 |
|
||||
| `src/server/db/` | SQLite 连接、schema、migration、data access |
|
||||
| `src/server/ai/` | AI Provider Registry + Agent + 工具 |
|
||||
| `src/server/helpers/` | 响应格式化、URL 工具 |
|
||||
| `src/server/middleware/` | 参数校验 + 错误处理 |
|
||||
| `src/web/layouts/` | 前端布局组件（AdminLayout / WorkbenchLayout） |
|
||||
| `src/web/features/` | 前端功能模块（dashboard / projects / models / chat / settings） |
|
||||
| `src/web/shared/` | 前端共享代码（components / hooks / utils） |
|
||||
| `src/shared/api.ts` | 前后端共享 API 类型 |
|
||||
| `src/shared/app.ts` | 应用全局常量 |
|
||||
|
||||
## 路由分组
|
||||
|
||||
| 资源 | 路径前缀 | 文件目录 |
|
||||
| --------- | ----------------------------------------------- | ------------------- |
|
||||
| meta | `/api/meta` | `routes/meta.ts` |
|
||||
| providers | `/api/providers` | `routes/providers/` |
|
||||
| models | `/api/models` | `routes/models/` |
|
||||
| projects | `/api/projects` | `routes/projects/` |
|
||||
| chat | `/api/projects/:id/conversations` 和 `:id/chat` | `routes/chat/` |
|
||||
| 资源 | 路径前缀 | 文件目录 |
|
||||
| --------- | ----------------------------------------------- | -------------------- |
|
||||
| meta | `/api/meta` | `routes/meta.ts` |
|
||||
| providers | `/api/providers` | `routes/providers/` |
|
||||
| models | `/api/models` | `routes/models/` |
|
||||
| projects | `/api/projects` | `routes/projects/` |
|
||||
| chat | `/api/projects/:id/conversations` 和 `:id/chat` | `routes/chat/` |
|
||||
| settings | `/api/settings` | `routes/settings.ts` |
|
||||
|
||||
## 更新触发条件
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
- **AdminLayout**（`src/web/layouts/admin-layout/`）：路由 `/`（总览）、`/projects`、`/models`、`/models/providers`。
|
||||
- **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) + 主题切换（明亮/黑暗/系统），主题配置由 `shared/theme/theme-config.ts` 的 `buildThemeConfig(effectiveTheme)` 集中构建（含 `cssVar`、`borderRadius`、`controlHeight`、`components.Layout` 配色）；侧边栏折叠。Header 显示品牌名、版本号和布局标题。
|
||||
ConsoleShell 包含：`XProvider(zhCN + zhCN_X)` + `AntApp` + `Layout`(Header/Sider/Content)，主题配置由 `shared/theme/theme-config.ts` 的 `buildThemeConfig(effectiveTheme)` 集中构建（含 `cssVar`、`borderRadius`、`controlHeight`、`components.Layout` 配色）；侧边栏折叠。主题切换已迁移至设置页（`/settings`）。Header 显示品牌名、版本号和布局标题。
|
||||
|
||||
`Sidebar`（`src/web/shared/components/Sidebar/`）纯展示组件，通过 `menuItems` props 接收配置。
|
||||
|
||||
@@ -22,6 +22,7 @@ ConsoleShell 包含：`XProvider(zhCN + zhCN_X)` + `AntApp` + `Layout`(Header/Si
|
||||
| 模型管理 | `features/models/` | 供应商/模型管理、连通性测试 |
|
||||
| 聊天 | `features/chat/` | 会话管理、消息渲染、AI 对话 |
|
||||
| 收集箱 | `features/inbox/` | 素材 CRUD、持久化、列表管理 |
|
||||
| 设置 | `features/settings/` | 平台业务设置，卡片式布局 |
|
||||
|
||||
## 页面
|
||||
|
||||
@@ -30,6 +31,7 @@ ConsoleShell 包含：`XProvider(zhCN + zhCN_X)` + `AntApp` + `Layout`(Header/Si
|
||||
| 总览 | `/` | `features/dashboard/index.tsx` |
|
||||
| 项目管理 | `/projects` | `features/projects/index.tsx` — FilterToolbar（状态 Select + 搜索 + 新建/归档恢复删除） + ProjectTable + ProjectFormModal。支持创建/编辑/归档/恢复/删除、列表排序、URL 同步筛选参数。 |
|
||||
| 模型管理 | `/models` 和 `/models/providers` | 独立路由页面：`ModelListPage.tsx`（FilterToolbar + ModelTable） + `ProviderListPage.tsx`（FilterToolbar + ProviderTable）。模型支持供应商/能力筛选和列表排序，供应商支持类型筛选和列表排序。模型表单使用 `GET /api/providers/options`。供应商表单支持预保存连通性测试（`POST /api/providers/test`）。 |
|
||||
| 设置 | `/settings` | `features/settings/index.tsx` — 卡片式布局分区管理平台业务设置。当前包含"主题配置"卡片（Segmented 切换系统/明亮/黑暗），使用 `useSettings` hook 通过 `GET/PUT /api/settings` 持久化，悲观更新策略。 |
|
||||
| 聊天室 | `/workbench/:id` | `features/chat/index.tsx` |
|
||||
| 收集箱 | `/workbench/:id/inbox` | `features/inbox/index.tsx` — 协调层（selectedId + modalOpen）+ MaterialSidebar（列表容器）+ MaterialDetailPanel（详情容器）+ AddMaterialModal。素材 CRUD 通过 TanStack Query hooks 接入后端 API。 |
|
||||
| 404 | `*` | `features/not-found/index.tsx` |
|
||||
@@ -66,7 +68,8 @@ ConsoleShell 包含：`XProvider(zhCN + zhCN_X)` + `AntApp` + `Layout`(Header/Si
|
||||
| `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-theme-preference` | `shared/hooks/use-theme-preference.ts` | 主题偏好管理（localStorage + API 同步） |
|
||||
| `use-settings` | `shared/hooks/use-settings.ts` | 平台设置读写（react-query: GET/PUT /api/settings） |
|
||||
| `use-sidebar-collapsed` | `shared/hooks/use-sidebar-collapsed.ts` | 侧边栏折叠 localStorage 持久化 |
|
||||
| `use-is-dark` | `shared/hooks/use-is-dark.ts` | 当前是否暗色主题 |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user