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

tests/server/db/settings.test.ts

@@ -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);
+    });
+  });
+});

tests/server/routes/settings.test.ts

@@ -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" });
+    });
+  });
+});

tests/web/App.test.tsx

@@ -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));
 

tests/web/components/ConsoleShell.test.tsx

@@ -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();
+  });
+});

tests/web/features/settings/SettingsPage.test.tsx

@@ -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();
+    });
+  });
+});

tests/web/routes/workbench.test.tsx

@@ -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;
 }