lanyuanxiaoyao/Alfred
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 全局设置系统 — settings 表、CRUD 路由、主题偏好持久化

Browse Source
This commit is contained in:
兰缘小妖
2026-06-05 23:10:32 +08:00
parent e2eba6dc1f
commit 3f88e33bd1
23 changed files with 652 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
docs/development/architecture.md
View File

@@ -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` |
## 更新触发条件

7
docs/development/frontend.md
View File

@@ -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` | 当前是否暗色主题 |

7
drizzle/0005_add_settings.sql Normal file
View File

@@ -0,0 +1,7 @@
CREATE TABLE settings (
id TEXT PRIMARY KEY,
created_at TEXT NOT NULL,
updated_at TEXT NOT NULL,
deleted_at TEXT,
data TEXT NOT NULL DEFAULT '{}'
);

3
src/server/db/index.ts
View File

@@ -20,4 +20,5 @@ export {
listModels,
updateModel,
} from "./models";
export { conversations, messages, projects, schemaMigrations } from "./schema";
export { conversations, messages, projects, schemaMigrations, settings } from "./schema";
export { getSettings, updateSettings } from "./settings";

5
src/server/db/schema.ts
View File

@@ -86,3 +86,8 @@ export const schemaMigrations = sqliteTable("schema_migrations", {
checksum: text("checksum").notNull(),
id: text("id").primaryKey(),
});
export const settings = sqliteTable("settings", {
...baseColumns,
data: text("data").notNull().default("{}"),
});

72
src/server/db/settings.ts Normal file
View File

@@ -0,0 +1,72 @@
import type Database from "bun:sqlite";
import { and, eq } from "drizzle-orm";
import type { SettingsData } from "../../shared/api";
import type { Logger } from "../logger";
import { notDeleted, timestamp, wrap } from "./connection";
import { settings } from "./schema";
const SETTINGS_ID = "default";
export function getSettings(raw: Database): SettingsData {
const db = wrap(raw);
const row = db
.select()
.from(settings)
.where(and(eq(settings.id, SETTINGS_ID), notDeleted(settings)))
.get();
if (!row) {
return { theme: "system" };
}
try {
const parsed = JSON.parse(row.data) as Partial<SettingsData>;
return {
theme: parsed.theme === "dark" || parsed.theme === "light" || parsed.theme === "system" ? parsed.theme : "system",
};
} catch {
return { theme: "system" };
}
}
export function updateSettings(raw: Database, data: Partial<SettingsData>, _logger: Logger): SettingsData {
const db = wrap(raw);
const existing = db
.select()
.from(settings)
.where(and(eq(settings.id, SETTINGS_ID), notDeleted(settings)))
.get();
let currentData: SettingsData = { theme: "system" };
if (existing) {
try {
currentData = JSON.parse(existing.data) as SettingsData;
} catch {
// 解析失败时使用默认值
}
}
const merged: SettingsData = { ...currentData, ...data };
if (existing) {
db.update(settings)
.set({ data: JSON.stringify(merged), updatedAt: timestamp() })
.where(eq(settings.id, SETTINGS_ID))
.run();
} else {
const now = timestamp();
db.insert(settings)
.values({
createdAt: now,
data: JSON.stringify(merged),
id: SETTINGS_ID,
updatedAt: now,
})
.run();
}
return merged;
}

38
src/server/routes/settings.ts Normal file
View File

@@ -0,0 +1,38 @@
import type Database from "bun:sqlite";
import type { RuntimeMode, SettingsData } from "../../shared/api";
import type { Logger } from "../logger";
import { getSettings, updateSettings } from "../db/settings";
import { createApiError, jsonResponse } from "../helpers";
export function handleGetSettings(_req: Request, db: Database, mode: RuntimeMode, _logger: Logger): Response {
const data = getSettings(db);
return jsonResponse(data, { mode });
}
export async function handleUpdateSettings(
req: Request,
db: Database,
mode: RuntimeMode,
logger: Logger,
): Promise<Response> {
let body: Partial<SettingsData>;
try {
body = (await req.json()) as Partial<SettingsData>;
} catch {
return jsonResponse(createApiError("Invalid JSON body", 400), { mode, status: 400 });
}
if (body.theme !== undefined && typeof body.theme !== "string") {
return jsonResponse(createApiError("theme must be a string", 400), { mode, status: 400 });
}
if (body.theme !== undefined && body.theme !== "dark" && body.theme !== "light" && body.theme !== "system") {
return jsonResponse(createApiError("theme 仅支持 dark、light、system", 400), { mode, status: 400 });
}
const result = updateSettings(db, body, logger);
logger.info({ data: result }, "设置已更新");
return jsonResponse(result, { mode });
}

18
src/server/server.ts
View File

@@ -330,6 +330,24 @@ export function startServer(options: StartServerOptions) {
logger,
),
},
"/api/settings": {
GET: withErrorHandler(
async (req) => {
const { handleGetSettings } = await import("./routes/settings");
return handleGetSettings(req, db, mode, logger);
},
mode,
logger,
),
PUT: withErrorHandler(
async (req) => {
const { handleUpdateSettings } = await import("./routes/settings");
return handleUpdateSettings(req, db, mode, logger);
},
mode,
logger,
),
},
},
});

6
src/shared/api.ts
View File

@@ -237,11 +237,17 @@ export type ProviderType = "anthropic" | "openai" | "openai-compatible";
export type RuntimeMode = "development" | "production" | "test";
export interface SettingsData {
theme: ThemePreference;
}
export interface TestModelRequest {
externalId: string;
providerId: string;
}
export type ThemePreference = "dark" | "light" | "system";
export interface UpdateModelRequest {
capabilities?: ModelCapability[];
contextLength?: null | number;

38
src/web/features/settings/index.tsx Normal file
View File

@@ -0,0 +1,38 @@
import { Card, Segmented } from "antd";
import { useSettings } from "../../shared/hooks/use-settings";
import { parseThemePreference, useThemePreference } from "../../shared/hooks/use-theme-preference";
const THEME_OPTIONS = [
{ label: "系统", value: "system" },
{ label: "明亮", value: "light" },
{ label: "黑暗", value: "dark" },
] as const;
export function SettingsPage() {
const { preference, setPreference } = useThemePreference();
const { isUpdating, updateSettings } = useSettings();
const handleThemeChange = (value: string) => {
const theme = parseThemePreference(value);
updateSettings(
{ theme },
{
onSuccess: () => {
setPreference(theme);
},
},
);
};
return (
<Card extra={isUpdating ? "保存中..." : undefined} title="主题" type="inner">
<Segmented
block
onChange={(value) => handleThemeChange(value)}
options={THEME_OPTIONS.map((option) => ({ label: option.label, value: option.value }))}
value={preference}
/>
</Card>
);
}

10
src/web/layouts/admin-layout/menu.tsx
View File

@@ -1,4 +1,11 @@
import { ApiOutlined, CloudServerOutlined, DashboardOutlined, FolderOutlined, RobotOutlined } from "@ant-design/icons";
import {
ApiOutlined,
CloudServerOutlined,
DashboardOutlined,
FolderOutlined,
RobotOutlined,
SettingOutlined,
} from "@ant-design/icons";
import { createElement } from "react";
import type { MenuItemConfig } from "../../menu";
@@ -16,4 +23,5 @@ export const ADMIN_MENU_ITEMS: readonly MenuItemConfig[] = [
path: "",
value: "model-management",
},
{ icon: createElement(SettingOutlined), label: "设置", path: "/settings", value: "settings" },
] as const;

2
src/web/routes.tsx
View File

@@ -7,6 +7,7 @@ import { ModelListPage } from "./features/models/ModelListPage";
import { ProviderListPage } from "./features/models/ProviderListPage";
import { NotFoundPage } from "./features/not-found";
import { ProjectsPage } from "./features/projects";
import { SettingsPage } from "./features/settings";
import { AdminConsoleLayout } from "./layouts/admin-layout/AdminConsoleLayout";
import { WorkbenchProjectGate } from "./layouts/workbench-layout/WorkbenchProjectGate";
import { RouteError } from "./shared/components/RouteError";
@@ -19,6 +20,7 @@ export function AppRoutes() {
<Route element={<ProjectsPage />} path="/projects" />
<Route element={<ModelListPage />} path="/models" />
<Route element={<ProviderListPage />} path="/models/providers" />
<Route element={<SettingsPage />} path="/settings" />
</Route>
<Route element={<WorkbenchProjectGate />} errorElement={<RouteError />} path="/workbench/:projectId">
<Route element={<ChatPage />} path="" />

19
src/web/shared/components/ConsoleShell/ConsoleShell.tsx
View File

@@ -1,7 +1,7 @@
import { MenuFoldOutlined, MenuUnfoldOutlined } from "@ant-design/icons";
import { XProvider } from "@ant-design/x";
import zhCN_X from "@ant-design/x/locale/zh_CN";
import { App as AntApp, Layout, Segmented } from "antd";
import { App as AntApp, Layout } from "antd";
import zhCN from "antd/locale/zh_CN";
import { useMemo } from "react";
@@ -17,14 +17,8 @@ import { ConsoleOutlet } from "./ConsoleOutlet";
const { Content, Header, Sider } = Layout;
const THEME_OPTIONS = [
{ label: "系统", value: "system" },
{ label: "明亮", value: "light" },
{ label: "黑暗", value: "dark" },
] as const;
export function ConsoleShell({ headerExtra, menuItems, title }: ConsoleShellProps) {
const { effectiveTheme, preference: themePreference, setPreference: setThemePreference } = useThemePreference();
const { effectiveTheme } = useThemePreference();
const { collapsed, setCollapsed } = useSidebarCollapsed();
const { data: meta } = useMeta();
@@ -43,14 +37,7 @@ export function ConsoleShell({ headerExtra, menuItems, title }: ConsoleShellProp
<span className="app-console-title">{title}</span>
</span>
</div>
<div className="app-header-right">
{headerExtra}
<Segmented
onChange={(value) => setThemePreference(value)}
options={THEME_OPTIONS.map((option) => ({ label: option.label, value: option.value }))}
value={themePreference}
/>
</div>
<div className="app-header-right">{headerExtra}</div>
</Header>
<Layout>
<Sider

44
src/web/shared/hooks/use-settings.ts Normal file
View File

@@ -0,0 +1,44 @@
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import type { SettingsData } from "../../../shared/api";
export function useSettings() {
const queryClient = useQueryClient();
const query = useQuery({
queryFn: fetchSettings,
queryKey: ["settings"],
staleTime: 60000,
});
const mutation = useMutation({
mutationFn: updateSettings,
onSuccess: (data) => {
queryClient.setQueryData(["settings"], data);
},
});
return {
data: query.data,
error: query.error,
isLoading: query.isLoading,
isUpdating: mutation.isPending,
updateSettings: mutation.mutate,
};
}
async function fetchSettings(): Promise<SettingsData> {
const response = await fetch("/api/settings");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return response.json() as Promise<SettingsData>;
}
async function updateSettings(data: Partial<SettingsData>): Promise<SettingsData> {
const response = await fetch("/api/settings", {
body: JSON.stringify(data),
headers: { "Content-Type": "application/json" },
method: "PUT",
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return response.json() as Promise<SettingsData>;
}

23
src/web/shared/hooks/use-theme-preference.ts
View File

@@ -1,5 +1,7 @@
import { useCallback, useEffect, useState } from "react";
import type { SettingsData } from "../../../shared/api";
export type EffectiveTheme = "dark" | "light";
export type ThemePreference = "dark" | "light" | "system";
@@ -38,6 +40,27 @@ export function useThemePreference() {
const [systemPrefersDark, setSystemPrefersDark] = useState(() => getSystemPrefersDark());
const effectiveTheme = resolveEffectiveTheme(preference, systemPrefersDark);
useEffect(() => {
let cancelled = false;
fetch("/api/settings")
.then((res) => {
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return res.json() as Promise<SettingsData>;
})
.then((data) => {
if (cancelled) return;
const apiTheme = parseThemePreference(data.theme);
setPreferenceState((prev) => (prev !== apiTheme ? apiTheme : prev));
writeThemePreference(apiTheme);
})
.catch(() => {
// API 不可用时维持 localStorage 缓存值
});
return () => {
cancelled = true;
};
}, []);
useEffect(() => {
const mediaQueryList = window.matchMedia(THEME_MEDIA_QUERY);

2
src/web/shared/theme/theme-config.ts
View File

@@ -12,7 +12,7 @@ export function buildThemeConfig(effectiveTheme: EffectiveTheme) {
Layout: {
bodyBg: isDark ? "#0a0a0a" : "transparent",
headerBg: "transparent",
siderBg: isDark ? "#0a0a0a" : "#ffffff",
siderBg: isDark ? "#141414" : "#ffffff",
triggerBg: isDark ? "#141414" : "#ffffff",
},
Menu: {

1
src/web/styles.css
View File

@@ -65,6 +65,7 @@ body {
color: var(--ant-color-text-secondary);
font-size: var(--ant-font-size);
font-weight: 400;
line-height: 1;
}
.app-unavailable {

78
tests/server/db/settings.test.ts Normal file
View File

@@ -0,0 +1,78 @@
import type Database from "bun:sqlite";
import { describe, expect, test } from "bun:test";
import { getSettings, updateSettings } from "../../../src/server/db/settings";
import { createNoopLogger } from "../../../src/server/logger";
import { createMigratedTestDatabase } from "../../helpers";
function withSettingsDb(callback: (db: Database) => void): void {
const handle = createMigratedTestDatabase("settings-test");
try {
callback(handle.db);
handle.close();
} finally {
handle.cleanup();
}
}
describe("设置数据访问层", () => {
test("getSettings 无数据时返回默认值", () => {
withSettingsDb((db) => {
const result = getSettings(db);
expect(result).toEqual({ theme: "system" });
});
});
test("updateSettings 写入并读取", () => {
withSettingsDb((db) => {
const updated = updateSettings(db, { theme: "dark" }, createNoopLogger());
expect(updated).toEqual({ theme: "dark" });
const read = getSettings(db);
expect(read).toEqual({ theme: "dark" });
});
});
test("updateSettings 部分更新合并", () => {
withSettingsDb((db) => {
updateSettings(db, { theme: "dark" }, createNoopLogger());
const result = updateSettings(db, { theme: "light" }, createNoopLogger());
expect(result).toEqual({ theme: "light" });
});
});
test("getSettings 解析非法 JSON 返回默认值", () => {
withSettingsDb((db) => {
db.run(
"INSERT INTO settings (id, created_at, updated_at, data) VALUES ('default', '2024-01-01T00:00:00.000Z', '2024-01-01T00:00:00.000Z', 'not-json')",
);
const result = getSettings(db);
expect(result).toEqual({ theme: "system" });
});
});
test("getSettings 未知 theme 值返回默认值", () => {
withSettingsDb((db) => {
db.run(
"INSERT INTO settings (id, created_at, updated_at, data) VALUES ('default', '2024-01-01T00:00:00.000Z', '2024-01-01T00:00:00.000Z', '{\"theme\":\"unknown\"}')",
);
const result = getSettings(db);
expect(result).toEqual({ theme: "system" });
});
});
test("updateSettings 幂等覆盖", () => {
withSettingsDb((db) => {
const a = updateSettings(db, { theme: "dark" }, createNoopLogger());
const b = updateSettings(db, { theme: "dark" }, createNoopLogger());
expect(a).toEqual({ theme: "dark" });
expect(b).toEqual({ theme: "dark" });
const row = db
.query("SELECT COUNT(*) as cnt FROM settings WHERE id = 'default' AND deleted_at IS NULL")
.get() as { cnt: number };
expect(row.cnt).toBe(1);
});
});
});

146
tests/server/routes/settings.test.ts Normal file
View File

@@ -0,0 +1,146 @@
import type Database from "bun:sqlite";
import { describe, expect, test } from "bun:test";
import type { RuntimeMode } from "../../../src/shared/api";
import { createNoopLogger } from "../../../src/server/logger";
import { createMigratedMemoryTestDatabase } from "../../helpers";
const MODE: RuntimeMode = "test";
const LOG = createNoopLogger();
async function getSettingsViaHandler(req: Request, db: Database): Promise<Response> {
const { handleGetSettings: h } = await import("../../../src/server/routes/settings");
return h(req, db, MODE, LOG);
}
async function updateSettingsViaHandler(req: Request, db: Database): Promise<Response> {
const { handleUpdateSettings: h } = await import("../../../src/server/routes/settings");
return h(req, db, MODE, LOG);
}
async function withRouteDb(callback: (db: Database) => Promise<void>): Promise<void> {
const handle = createMigratedMemoryTestDatabase("route-settings-test");
try {
await callback(handle.db);
handle.close();
} finally {
handle.cleanup();
}
}
describe("设置 API 路由", () => {
test("GET /api/settings 返回默认值", async () => {
await withRouteDb(async (db) => {
const req = new Request("http://localhost/api/settings");
const res = await getSettingsViaHandler(req, db);
expect(res.status).toBe(200);
const body = (await res.json()) as { theme: string };
expect(body).toEqual({ theme: "system" });
});
});
test("PUT /api/settings 写入后 GET 验证一致性", async () => {
await withRouteDb(async (db) => {
const putReq = new Request("http://localhost/api/settings", {
body: JSON.stringify({ theme: "dark" }),
headers: { "Content-Type": "application/json" },
method: "PUT",
});
const putRes = await updateSettingsViaHandler(putReq, db);
expect(putRes.status).toBe(200);
const putBody = (await putRes.json()) as { theme: string };
expect(putBody).toEqual({ theme: "dark" });
const getReq = new Request("http://localhost/api/settings");
const getRes = await getSettingsViaHandler(getReq, db);
expect(getRes.status).toBe(200);
const getBody = (await getRes.json()) as { theme: string };
expect(getBody).toEqual({ theme: "dark" });
});
});
test("PUT /api/settings 部分更新", async () => {
await withRouteDb(async (db) => {
const req1 = new Request("http://localhost/api/settings", {
body: JSON.stringify({ theme: "dark" }),
headers: { "Content-Type": "application/json" },
method: "PUT",
});
await updateSettingsViaHandler(req1, db);
const req2 = new Request("http://localhost/api/settings", {
body: JSON.stringify({ theme: "light" }),
headers: { "Content-Type": "application/json" },
method: "PUT",
});
const res2 = await updateSettingsViaHandler(req2, db);
expect(res2.status).toBe(200);
const body = (await res2.json()) as { theme: string };
expect(body).toEqual({ theme: "light" });
});
});
test("PUT /api/settings 非法 JSON 返回 400", async () => {
await withRouteDb(async (db) => {
const req = new Request("http://localhost/api/settings", {
body: "not-json",
headers: { "Content-Type": "application/json" },
method: "PUT",
});
const res = await updateSettingsViaHandler(req, db);
expect(res.status).toBe(400);
});
});
test("PUT /api/settings theme 非字符串返回 400", async () => {
await withRouteDb(async (db) => {
const req = new Request("http://localhost/api/settings", {
body: JSON.stringify({ theme: 123 }),
headers: { "Content-Type": "application/json" },
method: "PUT",
});
const res = await updateSettingsViaHandler(req, db);
expect(res.status).toBe(400);
});
});
test("PUT /api/settings 非法 theme 值返回 400", async () => {
await withRouteDb(async (db) => {
const req = new Request("http://localhost/api/settings", {
body: JSON.stringify({ theme: "auto" }),
headers: { "Content-Type": "application/json" },
method: "PUT",
});
const res = await updateSettingsViaHandler(req, db);
expect(res.status).toBe(400);
});
});
test("PUT /api/settings theme=system 合法", async () => {
await withRouteDb(async (db) => {
const req = new Request("http://localhost/api/settings", {
body: JSON.stringify({ theme: "system" }),
headers: { "Content-Type": "application/json" },
method: "PUT",
});
const res = await updateSettingsViaHandler(req, db);
expect(res.status).toBe(200);
});
});
test("PUT /api/settings 空 body 不报错", async () => {
await withRouteDb(async (db) => {
const req = new Request("http://localhost/api/settings", {
body: JSON.stringify({}),
headers: { "Content-Type": "application/json" },
method: "PUT",
});
const res = await updateSettingsViaHandler(req, db);
expect(res.status).toBe(200);
const body = (await res.json()) as { theme: string };
expect(body).toEqual({ theme: "system" });
});
});
});

23
tests/web/App.test.tsx
View File

@@ -4,23 +4,30 @@ import { createElement } from "react";
import { APP } from "../../src/shared/app";
import { App } from "../../src/web/app";
import { installFetchMock, mockMetaResponse, renderWithProviders } from "./test-utils";
import { installFetchMock, jsonResponse, mockMetaResponse, renderWithProviders } from "./test-utils";
function mockSettingsResponse(): Response {
return jsonResponse({ theme: "system" });
}
describe("App", () => {
test("渲染管理台入口、品牌和主题切换项", () => {
installFetchMock(() => mockMetaResponse());
test("渲染管理台入口和品牌", () => {
installFetchMock((call) => {
if (call.url.includes("/api/settings")) return mockSettingsResponse();
return mockMetaResponse();
});
renderWithProviders(createElement(App));
expect(screen.getByText(APP.title)).not.toBeNull();
expect(screen.getByText("管理台")).not.toBeNull();
expect(screen.getByText("系统")).not.toBeNull();
expect(screen.getByText("明亮")).not.toBeNull();
expect(screen.getByText("黑暗")).not.toBeNull();
});
test("渲染 Admin 导航菜单项", () => {
installFetchMock(() => mockMetaResponse());
test("渲染管理台侧边栏菜单项", () => {
installFetchMock((call) => {
if (call.url.includes("/api/settings")) return mockSettingsResponse();
return mockMetaResponse();
});
renderWithProviders(createElement(App));

36
tests/web/components/ConsoleShell.test.tsx Normal file
View File

@@ -0,0 +1,36 @@
import { screen } from "@testing-library/react";
import { describe, expect, test } from "bun:test";
import { createElement } from "react";
import { ConsoleShell } from "../../../src/web/shared/components/ConsoleShell/ConsoleShell";
import { installFetchMock, jsonResponse, mockMetaResponse, renderWithProviders } from "../test-utils";
function mockSettingsResponse(): Response {
return jsonResponse({ theme: "system" });
}
describe("ConsoleShell", () => {
test("Header 不再渲染主题 Segmented", () => {
installFetchMock((call) => {
if (call.url.includes("/api/settings")) return mockSettingsResponse();
if (call.url.includes("/api/meta")) return mockMetaResponse();
return jsonResponse({});
});
renderWithProviders(createElement(ConsoleShell, { menuItems: [], title: "测试" }));
expect(screen.queryByText("系统")).toBeNull();
});
test("渲染品牌标题", () => {
installFetchMock((call) => {
if (call.url.includes("/api/settings")) return mockSettingsResponse();
if (call.url.includes("/api/meta")) return mockMetaResponse();
return jsonResponse({});
});
renderWithProviders(createElement(ConsoleShell, { menuItems: [], title: "控制台" }));
expect(screen.getByText("控制台")).not.toBeNull();
});
});

61
tests/web/features/settings/SettingsPage.test.tsx Normal file
View File

@@ -0,0 +1,61 @@
import { screen, waitFor } from "@testing-library/react";
import { describe, expect, test } from "bun:test";
import { createElement } from "react";
import { SettingsPage } from "../../../../src/web/features/settings/index";
import { installFetchMock, jsonResponse, renderWithProviders } from "../../test-utils";
function mockSettingsResponse(theme = "system"): Response {
return jsonResponse({ theme });
}
describe("SettingsPage", () => {
test("渲染主题卡片", () => {
installFetchMock((call) => {
if (call.url.includes("/api/settings")) return mockSettingsResponse();
return jsonResponse({});
});
renderWithProviders(createElement(SettingsPage));
expect(screen.getByText("主题")).not.toBeNull();
});
test("渲染主题 Segmented 选项", () => {
installFetchMock((call) => {
if (call.url.includes("/api/settings")) return mockSettingsResponse();
return jsonResponse({});
});
renderWithProviders(createElement(SettingsPage));
expect(screen.getByText("系统")).not.toBeNull();
expect(screen.getByText("明亮")).not.toBeNull();
expect(screen.getByText("黑暗")).not.toBeNull();
});
test("API 加载中时不显示保存状态", () => {
installFetchMock((call) => {
if (call.url.includes("/api/settings")) return mockSettingsResponse();
return jsonResponse({});
});
renderWithProviders(createElement(SettingsPage));
expect(screen.queryByText("保存中...")).toBeNull();
});
test("GET /api/settings 获取已保存主题", async () => {
installFetchMock((call) => {
if (call.url.includes("/api/settings")) return mockSettingsResponse("dark");
return jsonResponse({});
});
renderWithProviders(createElement(SettingsPage));
await waitFor(() => {
const segmented = document.querySelector(".ant-segmented");
expect(segmented).not.toBeNull();
});
});
});

9
tests/web/routes/workbench.test.tsx
View File

@@ -18,6 +18,12 @@ function createMockHandler(overrides?: { status?: "active" | "archived" }) {
const project = { ...MOCK_PROJECT, ...overrides };
const handler = (input: RequestInfo | URL) => {
const url = input instanceof Request ? input.url : typeof input === "string" ? input : input.toString();
if (url.includes("/api/settings")) {
return new Response(JSON.stringify({ theme: "system" }), {
headers: { "Content-Type": "application/json" },
status: 200,
});
}
if (url.includes("/api/meta")) {
return new Response(
JSON.stringify({ ok: true, service: "test-app", timestamp: new Date().toISOString(), version: "0.1.0" }),
@@ -38,7 +44,8 @@ function createMockHandler(overrides?: { status?: "active" | "archived" }) {
}
return new Response(JSON.stringify({ error: "Not Found" }), { status: 404 });
};
const mocked = handler as unknown as typeof fetch;
const mocked = ((input: RequestInfo | URL, _init?: RequestInit) =>
Promise.resolve(handler(input))) as unknown as typeof fetch;
globalThis.fetch = mocked;
window.fetch = mocked;
}