refactor: 前端 antd 组件使用最佳实践重构

- 修正 API 响应类型，增加 ProjectResponse 包装类型
- ConfigProvider 配置中文 locale (zhCN)
- 生产入口启用 ErrorBoundary，使用 Result 组件
- ReactQueryDevtools 仅开发环境渲染
- Sider 增加 collapsible 配置，使用 antd 默认折叠行为
- 项目页面拆分为 ProjectToolbar/ProjectTable/ProjectFormModal
- 搜索改用 Input.Search，表单增加 whitespace 校验
- 404/ErrorBoundary/Dashboard 使用 antd Result/Typography/Card/Descriptions
- 清理未使用的 ProtectedRoute 和冗余样式类
- styles.css 仅保留必要布局样式，无 antd 内部类覆盖
- 更新测试覆盖，避免依赖 antd 内部类名
- 更新 docs/development/frontend.md 开发规范

bun.lock

@@ -7,11 +7,11 @@
       "dependencies": {
         "@ant-design/icons": "^6.2.3",
         "@sinclair/typebox": "^0.34.49",
-        "@tanstack/react-query": "^5.100.10",
+        "@tanstack/react-query": "^5.100.14",
         "ajv": "^8.20.0",
         "antd": "^6.4.3",
         "drizzle-orm": "^0.45.2",
-        "es-toolkit": "^1.46.1",
+        "es-toolkit": "^1.47.0",
         "pino": "^10.3.1",
         "pino-pretty": "^13.1.3",
         "pino-roll": "^4.0.0",
@@ -24,15 +24,15 @@
         "@commitlint/cli": "^21.0.1",
         "@commitlint/config-conventional": "^21.0.1",
         "@eslint/js": "^10.0.1",
-        "@tanstack/react-query-devtools": "^5.100.10",
+        "@tanstack/react-query-devtools": "^5.100.14",
         "@testing-library/react": "^16.3.2",
         "@types/bun": "^1.3.14",
         "@types/jsdom": "^28.0.3",
-        "@types/react": "^19.2.14",
+        "@types/react": "^19.2.15",
         "@types/react-dom": "^19.2.3",
         "@vitejs/plugin-react": "^6.0.2",
         "drizzle-kit": "^0.31.10",
-        "eslint": "^10.3.0",
+        "eslint": "^10.4.0",
         "eslint-config-prettier": "^10.1.8",
         "eslint-import-resolver-typescript": "^4.4.4",
         "eslint-plugin-import": "^2.32.0",
@@ -42,11 +42,11 @@
         "eslint-plugin-react-refresh": "^0.5.2",
         "husky": "^9.1.7",
         "jsdom": "^29.1.1",
-        "lint-staged": "^17.0.4",
+        "lint-staged": "^17.0.5",
         "prettier": "^3.8.3",
         "typescript": "^6.0.3",
-        "typescript-eslint": "^8.59.3",
+        "typescript-eslint": "^8.60.0",
-        "vite": "^8.0.13",
+        "vite": "^8.0.14",
       },
     },
   },

docs/development/frontend.md

@@ -22,8 +22,8 @@
 - 每个 React 组件一个 .tsx 文件，文件名使用 PascalCase
 - 组件 props 定义为 interface XxxProps，紧邻组件函数声明
 - 类型从 src/shared/api.ts 导入，使用 import type
-- 展示组件放在 components/，通过 props 接收数据，通过回调返回事件
+- 展示组件放在 components/，通过 props 接收数据，通过回调返回事件；页面专属展示组件可就近放在 pages/\*/components/
-- 容器逻辑放在 hooks 中，组件只做数据消费
+- 容器逻辑放在 hooks 中，组件只做数据消费；全局共享查询可提取为独立 hook（如 use-meta）
 - 工具函数放在 utils/，保持纯函数无副作用
 
 ## 样式开发规范

skills-lock.json

@@ -5,13 +5,13 @@
       "source": "ant-design/antd-skill",
       "sourceType": "github",
       "skillPath": "skills/ant-design/SKILL.md",
-      "computedHash": "4d0447d48fced080b2825ecc0fb4d7ca836c8015882899c643acca0b864d5179"
+      "computedHash": "096d4ac9513e43030f960aab49b50168a3d5eb35be86926ac6e96e5998ea9466"
     },
     "antd": {
       "source": "ant-design/antd-skill",
       "sourceType": "github",
       "skillPath": "skills/antd/SKILL.md",
-      "computedHash": "4295010f09f85855cab9e9de9ec7f96c14541474b4f3f9d6ef89006430931b94"
+      "computedHash": "5e26c8042060bb811118927b5daf637af7929a00fa973dd8f5f804f3ba6e2bf2"
     }
   }
 }

src/shared/api.ts

@@ -37,6 +37,10 @@ export interface ProjectListResponse {
   total: number;
 }
 
+export interface ProjectResponse {
+  project: Project;
+}
+
 export type ProjectStatus = "active" | "archived";
 
 export type RuntimeMode = "development" | "production" | "test";

src/web/app.tsx

@@ -1,16 +1,13 @@
 import { MenuFoldOutlined, MenuUnfoldOutlined } from "@ant-design/icons";
-import { useQuery } from "@tanstack/react-query";
 import { App as AntApp, ConfigProvider, Layout, Segmented, theme } from "antd";
+import zhCN from "antd/locale/zh_CN";
 import { useEffect } from "react";
-import { useLocation } from "react-router";
-
-import type { MetaResponse } from "../shared/api";
 
 import { APP } from "../shared/app";
 import { Sidebar } from "./components/Sidebar";
+import { useMeta } from "./hooks/use-meta";
 import { useSidebarCollapsed } from "./hooks/use-sidebar-collapsed";
 import { type ThemePreference, useThemePreference } from "./hooks/use-theme-preference";
-import { MENU_ITEMS } from "./menu";
 import { AppRoutes } from "./routes";
 
 const { Content, Header, Sider } = Layout;
@@ -24,13 +21,7 @@ const THEME_OPTIONS = [
 export function App() {
   const { effectiveTheme, preference: themePreference, setPreference: setThemePreference } = useThemePreference();
   const { collapsed, setCollapsed } = useSidebarCollapsed();
-  const location = useLocation();
+  const { data: meta } = useMeta();
-  const { data: meta } = useQuery({
-    queryFn: fetchMeta,
-    queryKey: ["meta"],
-    refetchInterval: 30000,
-    staleTime: 5000,
-  });
 
   useEffect(() => {
     document.title = APP.title;
@@ -41,15 +32,12 @@ export function App() {
     setThemePreference(value as ThemePreference);
   };
 
-  const currentPath = location.pathname;
-  const currentItem = MENU_ITEMS.find((item) => item.path === currentPath);
-  const pageTitle = currentItem?.label ?? APP.title;
   const versionDisplay = meta?.version ? `v${meta.version}` : null;
 
   const themeAlgorithm = effectiveTheme === "dark" ? theme.darkAlgorithm : theme.defaultAlgorithm;
 
   return (
-    <ConfigProvider theme={{ algorithm: themeAlgorithm }}>
+    <ConfigProvider locale={zhCN} theme={{ algorithm: themeAlgorithm }}>
       <AntApp>
         <Layout className="app-layout">
           <Header className="app-header">
@@ -58,7 +46,6 @@ export function App() {
                 <span className="app-brand">{APP.title}</span>
                 {versionDisplay && <span className="app-version">{versionDisplay}</span>}
               </span>
-              <span className="app-page-title">{pageTitle}</span>
             </div>
             <div className="app-header-right">
               <Segmented
@@ -70,10 +57,11 @@ export function App() {
           </Header>
           <Layout>
             <Sider
-              className="app-sidebar"
               collapsed={collapsed}
               collapsedWidth={64}
+              collapsible
               onCollapse={(collapsed) => setCollapsed(collapsed)}
+              theme="light"
               trigger={collapsed ? <MenuUnfoldOutlined /> : <MenuFoldOutlined />}
               width={232}
             >
@@ -90,9 +78,3 @@ export function App() {
     </ConfigProvider>
   );
 }
-
-async function fetchMeta(): Promise<MetaResponse> {
-  const response = await fetch("/api/meta");
-  if (!response.ok) throw new Error(`HTTP ${response.status}`);
-  return response.json() as Promise<MetaResponse>;
-}

src/web/components/ErrorBoundary.tsx

@@ -1,6 +1,6 @@
 import type { ErrorInfo, ReactNode } from "react";
 
-import { Alert, Button, Space } from "antd";
+import { Button, Result } from "antd";
 import { Component } from "react";
 
 interface Props {
@@ -25,12 +25,16 @@ export class ErrorBoundary extends Component<Props, State> {
   override render() {
     if (this.state.hasError) {
       return (
-        <Space align="center" className="error-boundary-fallback" size="large" vertical>
+        <Result
-          <Alert showIcon title="页面渲染出现异常，请刷新重试" type="error" />
+          extra={
-          <Button onClick={() => window.location.reload()} type="primary">
+            <Button onClick={() => window.location.reload()} type="primary">
-            刷新页面
+              刷新页面
-          </Button>
+            </Button>
-        </Space>
+          }
+          status="500"
+          subTitle="页面渲染出现异常，请刷新重试"
+          title="渲染错误"
+        />
       );
     }
     return this.props.children;

src/web/components/Sidebar/index.tsx

@@ -28,13 +28,5 @@ export function Sidebar() {
     }
   };
 
-  return (
+  return <Menu items={menuItems} mode="inline" onClick={handleMenuClick} selectedKeys={selectedKeys} />;
-    <Menu
-      className="app-sidebar-menu"
-      items={menuItems}
-      mode="inline"
-      onClick={handleMenuClick}
-      selectedKeys={selectedKeys}
-    />
-  );
 }

src/web/hooks/use-meta.ts

@@ -0,0 +1,18 @@
+import { useQuery } from "@tanstack/react-query";
+
+import type { MetaResponse } from "../../shared/api";
+
+export function useMeta() {
+  return useQuery({
+    queryFn: fetchMeta,
+    queryKey: ["meta"],
+    refetchInterval: 30000,
+    staleTime: 5000,
+  });
+}
+
+async function fetchMeta(): Promise<MetaResponse> {
+  const response = await fetch("/api/meta");
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  return response.json() as Promise<MetaResponse>;
+}

src/web/hooks/use-projects.ts

@@ -4,6 +4,7 @@ import type {
   CreateProjectRequest,
   Project,
   ProjectListResponse,
+  ProjectResponse,
   ProjectStatus,
   UpdateProjectRequest,
 } from "../../shared/api";
@@ -81,7 +82,8 @@ async function archiveProject(id: string): Promise<Project> {
     const body = (await response.json().catch(() => null)) as null | { error?: string };
     throw new Error(body?.error ?? `HTTP ${response.status}`);
   }
-  return response.json() as Promise<Project>;
+  const data = (await response.json()) as ProjectResponse;
+  return data.project;
 }
 
 async function createProject(data: CreateProjectRequest): Promise<Project> {
@@ -94,7 +96,8 @@ async function createProject(data: CreateProjectRequest): Promise<Project> {
     const body = (await response.json().catch(() => null)) as null | { error?: string };
     throw new Error(body?.error ?? `HTTP ${response.status}`);
   }
-  return response.json() as Promise<Project>;
+  const result = (await response.json()) as ProjectResponse;
+  return result.project;
 }
 
 async function deleteProject(id: string): Promise<void> {
@@ -111,7 +114,8 @@ async function fetchProject(id: string): Promise<Project> {
     const body = (await response.json().catch(() => null)) as null | { error?: string };
     throw new Error(body?.error ?? `HTTP ${response.status}`);
   }
-  return response.json() as Promise<Project>;
+  const data = (await response.json()) as ProjectResponse;
+  return data.project;
 }
 
 async function fetchProjectList(params: {
@@ -141,7 +145,8 @@ async function restoreProject(id: string): Promise<Project> {
     const body = (await response.json().catch(() => null)) as null | { error?: string };
     throw new Error(body?.error ?? `HTTP ${response.status}`);
   }
-  return response.json() as Promise<Project>;
+  const data = (await response.json()) as ProjectResponse;
+  return data.project;
 }
 
 async function updateProject(id: string, data: UpdateProjectRequest): Promise<Project> {
@@ -154,5 +159,6 @@ async function updateProject(id: string, data: UpdateProjectRequest): Promise<Pr
     const body = (await response.json().catch(() => null)) as null | { error?: string };
     throw new Error(body?.error ?? `HTTP ${response.status}`);
   }
-  return response.json() as Promise<Project>;
+  const result = (await response.json()) as ProjectResponse;
+  return result.project;
 }

src/web/hooks/use-sidebar-collapsed.ts

@@ -22,11 +22,7 @@ export function useSidebarCollapsed() {
     writeSidebarCollapsed(nextCollapsed);
   };
 
-  const toggleCollapsed = () => {
+  return { collapsed, setCollapsed };
-    setCollapsed(!collapsed);
-  };
-
-  return { collapsed, setCollapsed, toggleCollapsed };
 }
 
 export function writeSidebarCollapsed(collapsed: boolean, storage: Storage = window.localStorage) {

src/web/main.tsx

@@ -5,6 +5,7 @@ import { createRoot } from "react-dom/client";
 import { BrowserRouter } from "react-router";
 
 import { App } from "./app";
+import { ErrorBoundary } from "./components/ErrorBoundary";
 import "./styles.css";
 
 const queryClient = new QueryClient({
@@ -25,11 +26,13 @@ if (!rootElement) {
 
 createRoot(rootElement).render(
   <StrictMode>
-    <QueryClientProvider client={queryClient}>
+    <ErrorBoundary>
-      <BrowserRouter>
+      <QueryClientProvider client={queryClient}>
-        <App />
+        <BrowserRouter>
-      </BrowserRouter>
+          <App />
-      <ReactQueryDevtools initialIsOpen={false} />
+        </BrowserRouter>
-    </QueryClientProvider>
+        {import.meta.env["DEV"] && <ReactQueryDevtools initialIsOpen={false} />}
+      </QueryClientProvider>
+    </ErrorBoundary>
   </StrictMode>,
 );

src/web/pages/404/index.tsx

@@ -1,22 +1,19 @@
-import { ExclamationCircleOutlined } from "@ant-design/icons";
+import { Button, Result } from "antd";
-import { Button, Space } from "antd";
 import { useNavigate } from "react-router";
 
 export function NotFoundPage() {
   const navigate = useNavigate();
 
-  const handleGoHome = () => {
-    void navigate("/");
-  };
-
   return (
-    <Space align="center" className="not-found-page" size="large" vertical>
+    <Result
-      <ExclamationCircleOutlined className="not-found-icon" />
+      extra={
-      <h1>404</h1>
+        <Button onClick={() => void navigate("/")} type="primary">
-      <p>您访问的页面不存在</p>
+          返回首页
-      <Button onClick={handleGoHome} type="primary">
+        </Button>
-        返回首页
+      }
-      </Button>
+      status="404"
-    </Space>
+      subTitle="您访问的页面不存在"
+      title="404"
+    />
   );
 }

src/web/pages/dashboard/index.tsx

@@ -1,29 +1,32 @@
-import { useQuery } from "@tanstack/react-query";
+import type { DescriptionsProps } from "antd";
-import { Space } from "antd";
 
-import type { MetaResponse } from "../../../shared/api";
+import { Alert, Card, Descriptions, Space, Spin, Typography } from "antd";
 
 import { APP } from "../../../shared/app";
+import { useMeta } from "../../hooks/use-meta";
 
 export function DashboardPage() {
-  const { data: meta } = useQuery({
+  const { data: meta, error, isLoading } = useMeta();
-    queryFn: fetchMeta,
+
-    queryKey: ["meta"],
+  const descriptionItems: DescriptionsProps["items"] = meta
-    refetchInterval: 30000,
+    ? [
-    staleTime: 5000,
+        { children: meta.service, key: "service", label: "服务" },
-  });
+        { children: meta.version, key: "version", label: "版本" },
+        { children: meta.timestamp, key: "timestamp", label: "时间戳" },
+      ]
+    : [];
 
   return (
-    <Space className="full-width-space" size="large" vertical>
+    <Space size="large" vertical>
-      <h2>欢迎使用 {APP.title}</h2>
+      <Typography.Title level={2}>欢迎使用 {APP.title}</Typography.Title>
-      <p>在此构建你的应用。以下是 /api/meta 的返回数据（前后端联调示例）：</p>
+      <Typography.Paragraph>在此构建你的应用。以下是 /api/meta 的返回数据（前后端联调示例）：</Typography.Paragraph>
-      {meta && <pre className="meta-response">{JSON.stringify(meta, null, 2)}</pre>}
+      {isLoading && <Spin size="large" />}
+      {error && <Alert description={error.message} showIcon title="加载失败" type="error" />}
+      {meta && (
+        <Card>
+          <Descriptions column={1} items={descriptionItems} title="服务信息" />
+        </Card>
+      )}
     </Space>
   );
 }
-
-async function fetchMeta(): Promise<MetaResponse> {
-  const response = await fetch("/api/meta");
-  if (!response.ok) throw new Error(`HTTP ${response.status}`);
-  return response.json() as Promise<MetaResponse>;
-}

src/web/pages/projects/components/ProjectFormModal.tsx

@@ -0,0 +1,86 @@
+import { App as AntApp, Form, Input, Modal } from "antd";
+
+import type { CreateProjectRequest, Project, UpdateProjectRequest } from "../../../../shared/api";
+
+interface FormValues {
+  description?: string;
+  name: string;
+}
+
+interface ProjectFormModalProps {
+  editingProject: null | Project;
+  onCancel: () => void;
+  onCreate: (data: CreateProjectRequest) => Promise<unknown>;
+  onOpenChange: (open: boolean) => void;
+  onUpdate: (args: { data: UpdateProjectRequest; id: string }) => Promise<unknown>;
+  open: boolean;
+  submitting: boolean;
+}
+
+export function ProjectFormModal({
+  editingProject,
+  onCancel,
+  onCreate,
+  onOpenChange,
+  onUpdate,
+  open,
+  submitting,
+}: ProjectFormModalProps) {
+  const { message } = AntApp.useApp();
+  const [form] = Form.useForm<FormValues>();
+
+  const handleFinish = async (values: FormValues) => {
+    try {
+      if (editingProject) {
+        const reqData: UpdateProjectRequest = {};
+        if (values.name !== editingProject.name) reqData.name = values.name;
+        if ((values.description ?? "") !== (editingProject.description ?? "")) reqData.description = values.description;
+        await onUpdate({ data: reqData, id: editingProject.id });
+        message.success("项目已更新");
+      } else {
+        const reqData: CreateProjectRequest = { description: values.description, name: values.name };
+        await onCreate(reqData);
+        message.success("项目已创建");
+      }
+      onOpenChange(false);
+    } catch (err) {
+      if (err instanceof Error) {
+        message.error(err.message);
+      }
+    }
+  };
+
+  return (
+    <Modal
+      afterOpenChange={(visible) => {
+        if (visible) {
+          if (editingProject) {
+            form.setFieldsValue({ description: editingProject.description, name: editingProject.name });
+          } else {
+            form.resetFields();
+          }
+        }
+      }}
+      confirmLoading={submitting}
+      destroyOnHidden
+      okText="确定"
+      onCancel={onCancel}
+      onOk={() => void form.submit()}
+      open={open}
+      title={editingProject ? "编辑项目" : "新建项目"}
+    >
+      <Form form={form} layout="vertical" onFinish={(values) => void handleFinish(values)}>
+        <Form.Item
+          label="项目名称"
+          name="name"
+          rules={[{ message: "项目名称不能为空", required: true, whitespace: true }]}
+        >
+          <Input maxLength={100} placeholder="请输入项目名称" />
+        </Form.Item>
+        <Form.Item label="项目描述" name="description">
+          <Input.TextArea autoSize={{ minRows: 5 }} maxLength={500} placeholder="请输入项目描述" />
+        </Form.Item>
+      </Form>
+    </Modal>
+  );
+}

src/web/pages/projects/components/ProjectTable.tsx

@@ -0,0 +1,159 @@
+import type { ColumnsType } from "antd/es/table";
+
+import { DeleteOutlined, EditOutlined, InboxOutlined, RedoOutlined } from "@ant-design/icons";
+import { App as AntApp, Button, Popconfirm, Space, Table, Tag } from "antd";
+
+import type { Project, ProjectListResponse } from "../../../../shared/api";
+
+interface ProjectTableProps {
+  data: ProjectListResponse | undefined;
+  loading: boolean;
+  onArchive: (id: string) => Promise<unknown>;
+  onDelete: (id: string) => Promise<unknown>;
+  onEdit: (project: Project) => void;
+  onPageChange: (page: number, pageSize: number) => void;
+  onRestore: (id: string) => Promise<unknown>;
+  page: number;
+  pageSize: number;
+}
+
+const COLUMNS: ColumnsType<Project> = [
+  { dataIndex: "name", ellipsis: true, title: "项目名称", width: 160 },
+  { dataIndex: "description", ellipsis: true, title: "项目描述" },
+  {
+    align: "center",
+    dataIndex: "status",
+    render: (_value, record: Project) => {
+      if (record.status === "archived") {
+        return <Tag>已归档</Tag>;
+      }
+      return <Tag color="blue">进行中</Tag>;
+    },
+    title: "状态",
+    width: 100,
+  },
+  {
+    align: "center",
+    dataIndex: "createdAt",
+    render: (_value, record: Project) => formatDatetime(record.createdAt),
+    title: "创建时间",
+    width: 185,
+  },
+  {
+    align: "center",
+    dataIndex: "updatedAt",
+    render: (_value, record: Project) => formatDatetime(record.updatedAt),
+    title: "更新时间",
+    width: 185,
+  },
+];
+
+export function ProjectTable({
+  data,
+  loading,
+  onArchive,
+  onDelete,
+  onEdit,
+  onPageChange,
+  onRestore,
+  page,
+  pageSize,
+}: ProjectTableProps) {
+  const { message } = AntApp.useApp();
+
+  const handleArchive = async (id: string) => {
+    try {
+      await onArchive(id);
+      message.success("项目已归档");
+    } catch (err) {
+      message.error((err as Error).message);
+    }
+  };
+
+  const handleRestore = async (id: string) => {
+    try {
+      await onRestore(id);
+      message.success("项目已恢复");
+    } catch (err) {
+      message.error((err as Error).message);
+    }
+  };
+
+  const handleDelete = async (id: string) => {
+    try {
+      await onDelete(id);
+      message.success("项目已永久删除");
+    } catch (err) {
+      message.error((err as Error).message);
+    }
+  };
+
+  const operationColumn: ColumnsType<Project>[number] = {
+    dataIndex: "op",
+    fixed: "right",
+    render: (_value, record: Project) => {
+      if (record.status === "active") {
+        return (
+          <Space size="small">
+            <Button icon={<EditOutlined />} onClick={() => onEdit(record)} size="small" type="link">
+              编辑
+            </Button>
+            <Popconfirm
+              description="归档后项目将变为只读。"
+              onConfirm={() => void handleArchive(record.id)}
+              title="确认归档此项目？"
+            >
+              <Button color="orange" icon={<InboxOutlined />} size="small" variant="link">
+                归档
+              </Button>
+            </Popconfirm>
+          </Space>
+        );
+      }
+      return (
+        <Space size="small">
+          <Popconfirm onConfirm={() => void handleRestore(record.id)} title="确认恢复此项目？">
+            <Button icon={<RedoOutlined />} size="small" type="link">
+              恢复
+            </Button>
+          </Popconfirm>
+          <Popconfirm
+            description="此操作不可恢复。"
+            onConfirm={() => void handleDelete(record.id)}
+            title="确认永久删除此项目？"
+          >
+            <Button danger icon={<DeleteOutlined />} size="small" type="link">
+              删除
+            </Button>
+          </Popconfirm>
+        </Space>
+      );
+    },
+    title: "操作",
+    width: 180,
+  };
+
+  return (
+    <Table
+      columns={[...COLUMNS, operationColumn]}
+      dataSource={data?.items ?? []}
+      loading={loading}
+      pagination={{
+        current: page,
+        hideOnSinglePage: false,
+        onChange: onPageChange,
+        pageSize,
+        showSizeChanger: true,
+        total: data?.total ?? 0,
+      }}
+      rowKey="id"
+      scroll={{ x: 900 }}
+    />
+  );
+}
+
+function formatDatetime(dateStr: string): string {
+  const d = new Date(dateStr);
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}

src/web/pages/projects/components/ProjectToolbar.tsx

@@ -0,0 +1,48 @@
+import { PlusOutlined } from "@ant-design/icons";
+import { Button, Flex, Input, Tabs } from "antd";
+
+import type { ProjectStatus } from "../../../../shared/api";
+
+interface ProjectToolbarProps {
+  activeTab: ProjectStatus;
+  keyword: string;
+  onSearch: (value: string) => void;
+  onSearchClear: () => void;
+  onTabChange: (key: string) => void;
+  openCreateDialog: () => void;
+}
+
+const STATUS_TAB_ITEMS = [
+  { key: "active", label: "进行中" },
+  { key: "archived", label: "已归档" },
+];
+
+export function ProjectToolbar({
+  activeTab,
+  keyword,
+  onSearch,
+  onSearchClear,
+  onTabChange,
+  openCreateDialog,
+}: ProjectToolbarProps) {
+  return (
+    <Flex align="center" gap="var(--ant-margin-lg)" justify="space-between" wrap="wrap">
+      <Tabs activeKey={activeTab} items={STATUS_TAB_ITEMS} onChange={onTabChange} />
+      <Flex align="center" gap="small">
+        <Input.Search
+          allowClear
+          enterButton="搜索"
+          onClear={onSearchClear}
+          onSearch={onSearch}
+          placeholder="搜索项目名称或描述"
+          value={keyword}
+        />
+        {activeTab === "active" && (
+          <Button icon={<PlusOutlined />} onClick={openCreateDialog} type="primary">
+            新建项目
+          </Button>
+        )}
+      </Flex>
+    </Flex>
+  );
+}

src/web/pages/projects/index.tsx

@@ -1,17 +1,7 @@
-import type { ColumnsType } from "antd/es/table";
+import { Flex } from "antd";
-
-import {
-  DeleteOutlined,
-  EditOutlined,
-  InboxOutlined,
-  PlusOutlined,
-  RedoOutlined,
-  SearchOutlined,
-} from "@ant-design/icons";
-import { App as AntApp, Button, Form, Input, Modal, Popconfirm, Space, Table, Tabs, Tag } from "antd";
 import { useState } from "react";
 
-import type { CreateProjectRequest, Project, ProjectStatus, UpdateProjectRequest } from "../../../shared/api";
+import type { Project, ProjectStatus } from "../../../shared/api";
 
 import {
   useArchiveProject,
@@ -21,29 +11,18 @@ import {
   useRestoreProject,
   useUpdateProject,
 } from "../../hooks/use-projects";
-
+import { ProjectFormModal } from "./components/ProjectFormModal";
-const STATUS_TAB_ITEMS = [
+import { ProjectTable } from "./components/ProjectTable";
-  { key: "active", label: "进行中" },
+import { ProjectToolbar } from "./components/ProjectToolbar";
-  { key: "archived", label: "已归档" },
-];
-
-interface FormValues {
-  description?: string;
-  name: string;
-}
 
 export function ProjectsPage() {
-  const { message } = AntApp.useApp();
-
   const [tabValue, setTabValue] = useState<ProjectStatus>("active");
   const [page, setPage] = useState(1);
   const [pageSize, setPageSize] = useState(20);
   const [keyword, setKeyword] = useState("");
-  const [searchValue, setSearchValue] = useState("");
 
   const [dialogOpen, setDialogOpen] = useState(false);
   const [editingProject, setEditingProject] = useState<null | Project>(null);
-  const [form] = Form.useForm<FormValues>();
 
   const { data, isLoading } = useProjectList({ keyword: keyword || undefined, page, pageSize, status: tabValue });
   const createMutation = useCreateProject();
@@ -52,236 +31,59 @@ export function ProjectsPage() {
   const restoreMutation = useRestoreProject();
   const deleteMutation = useDeleteProject();
 
-  const handleSearch = () => {
-    setKeyword(searchValue);
-    setPage(1);
-  };
-
-  const handleSearchKeydown = (e: React.KeyboardEvent<HTMLInputElement>) => {
-    if (e.key === "Enter") {
-      handleSearch();
-    }
-  };
-
-  const handleTabChange = (key: string) => {
-    setTabValue(key as ProjectStatus);
-    setPage(1);
-  };
-
-  const openCreateDialog = () => {
-    setEditingProject(null);
-    setDialogOpen(true);
-  };
-
-  const openEditDialog = (project: Project) => {
-    setEditingProject(project);
-    setDialogOpen(true);
-  };
-
-  const handleDialogOk = async () => {
-    try {
-      const values = await form.validateFields();
-      if (editingProject) {
-        const reqData: UpdateProjectRequest = {};
-        if (values.name !== editingProject.name) reqData.name = values.name;
-        if ((values.description ?? "") !== (editingProject.description ?? "")) reqData.description = values.description;
-        await updateMutation.mutateAsync({ data: reqData, id: editingProject.id });
-        message.success("项目已更新");
-      } else {
-        const reqData: CreateProjectRequest = { description: values.description, name: values.name };
-        await createMutation.mutateAsync(reqData);
-        message.success("项目已创建");
-      }
-      setDialogOpen(false);
-    } catch (err) {
-      if (err instanceof Error) {
-        message.error(err.message);
-      }
-    }
-  };
-
-  const handleArchive = async (id: string) => {
-    try {
-      await archiveMutation.mutateAsync(id);
-      message.success("项目已归档");
-    } catch (err) {
-      message.error((err as Error).message);
-    }
-  };
-
-  const handleRestore = async (id: string) => {
-    try {
-      await restoreMutation.mutateAsync(id);
-      message.success("项目已恢复");
-    } catch (err) {
-      message.error((err as Error).message);
-    }
-  };
-
-  const handleDelete = async (id: string) => {
-    try {
-      await deleteMutation.mutateAsync(id);
-      message.success("项目已永久删除");
-    } catch (err) {
-      message.error((err as Error).message);
-    }
-  };
-
-  const columns: ColumnsType<Project> = [
-    { dataIndex: "name", ellipsis: true, title: "项目名称", width: 160 },
-    { dataIndex: "description", ellipsis: true, title: "项目描述" },
-    {
-      align: "center",
-      dataIndex: "status",
-      render: (_value, record: Project) => {
-        if (record.status === "archived") {
-          return <Tag>已归档</Tag>;
-        }
-        return <Tag color="blue">进行中</Tag>;
-      },
-      title: "状态",
-      width: 100,
-    },
-    {
-      align: "center",
-      dataIndex: "createdAt",
-      render: (_value, record: Project) => formatDatetime(record.createdAt),
-      title: "创建时间",
-      width: 185,
-    },
-    {
-      align: "center",
-      dataIndex: "updatedAt",
-      render: (_value, record: Project) => formatDatetime(record.updatedAt),
-      title: "更新时间",
-      width: 185,
-    },
-    {
-      dataIndex: "op",
-      fixed: "right",
-      render: (_value, record: Project) => {
-        if (record.status === "active") {
-          return (
-            <Space size="small">
-              <Button icon={<EditOutlined />} onClick={() => openEditDialog(record)} size="small" type="link">
-                编辑
-              </Button>
-              <Popconfirm
-                description="归档后项目将变为只读。"
-                onConfirm={() => void handleArchive(record.id)}
-                title="确认归档此项目？"
-              >
-                <Button icon={<InboxOutlined />} size="small" type="link">
-                  归档
-                </Button>
-              </Popconfirm>
-            </Space>
-          );
-        }
-        return (
-          <Space size="small">
-            <Popconfirm onConfirm={() => void handleRestore(record.id)} title="确认恢复此项目？">
-              <Button icon={<RedoOutlined />} size="small" type="link">
-                恢复
-              </Button>
-            </Popconfirm>
-            <Popconfirm
-              description="此操作不可恢复。"
-              onConfirm={() => void handleDelete(record.id)}
-              title="确认永久删除此项目？"
-            >
-              <Button danger icon={<DeleteOutlined />} size="small" type="link">
-                删除
-              </Button>
-            </Popconfirm>
-          </Space>
-        );
-      },
-      title: "操作",
-      width: 180,
-    },
-  ];
-
   const isSubmitting = createMutation.isPending || updateMutation.isPending;
+  const isRowActionPending = archiveMutation.isPending || restoreMutation.isPending || deleteMutation.isPending;
 
   return (
-    <Space className="full-width-space" size="large" vertical>
+    <Flex flex={1} gap="var(--ant-margin-lg)" vertical>
-      <div className="projects-header">
+      <ProjectToolbar
-        <Tabs activeKey={tabValue} items={STATUS_TAB_ITEMS} onChange={handleTabChange} />
+        activeTab={tabValue}
-        <Space>
+        keyword={keyword}
-          <Input
+        onSearch={(value) => {
-            allowClear
+          setKeyword(value);
-            onChange={(e) => setSearchValue(e.target.value)}
+          setPage(1);
-            onClear={() => {
+        }}
-              setKeyword("");
+        onSearchClear={() => {
-              setSearchValue("");
+          setKeyword("");
-              setPage(1);
+          setPage(1);
-            }}
+        }}
-            onKeyDown={handleSearchKeydown}
+        onTabChange={(key) => {
-            placeholder="搜索项目名称或描述"
+          setTabValue(key as ProjectStatus);
-            value={searchValue}
+          setPage(1);
-          />
+        }}
-          <Button icon={<SearchOutlined />} onClick={handleSearch}>
+        openCreateDialog={() => {
-            搜索
+          setEditingProject(null);
-          </Button>
+          setDialogOpen(true);
-          {tabValue === "active" && (
-            <Button icon={<PlusOutlined />} onClick={openCreateDialog} type="primary">
-              新建项目
-            </Button>
-          )}
-        </Space>
-      </div>
-
-      <Table
-        columns={columns}
-        dataSource={data?.items ?? []}
-        loading={isLoading || archiveMutation.isPending || restoreMutation.isPending || deleteMutation.isPending}
-        pagination={{
-          current: page,
-          onChange: (p, ps) => {
-            setPage(p);
-            setPageSize(ps);
-          },
-          pageSize,
-          total: data?.total ?? 0,
         }}
-        rowKey="id"
       />
 
-      <Modal
+      <ProjectTable
-        afterOpenChange={(open) => {
+        data={data}
-          if (open) {
+        loading={isLoading || isRowActionPending}
-            if (editingProject) {
+        onArchive={(id) => archiveMutation.mutateAsync(id)}
-              form.setFieldsValue({ description: editingProject.description, name: editingProject.name });
+        onDelete={(id) => deleteMutation.mutateAsync(id)}
-            } else {
+        onEdit={(project) => {
-              form.resetFields();
+          setEditingProject(project);
-            }
+          setDialogOpen(true);
-          }
         }}
-        confirmLoading={isSubmitting}
+        onPageChange={(p, ps) => {
-        destroyOnHidden
+          setPage(p);
-        okText="确定"
+          setPageSize(ps);
+        }}
+        onRestore={(id) => restoreMutation.mutateAsync(id)}
+        page={page}
+        pageSize={pageSize}
+      />
+
+      <ProjectFormModal
+        editingProject={editingProject}
         onCancel={() => setDialogOpen(false)}
-        // eslint-disable-next-line @typescript-eslint/no-misused-promises -- handleDialogOk 是 async 但最终返回 void，lint 规则误报
+        onCreate={(data) => createMutation.mutateAsync(data)}
-        onOk={handleDialogOk}
+        onOpenChange={setDialogOpen}
+        onUpdate={(args) => updateMutation.mutateAsync(args)}
         open={dialogOpen}
-        title={editingProject ? "编辑项目" : "新建项目"}
+        submitting={isSubmitting}
-      >
+      />
-        <Form form={form} layout="vertical">
+    </Flex>
-          <Form.Item label="项目名称" name="name" rules={[{ message: "项目名称不能为空", required: true }]}>
-            <Input maxLength={100} placeholder="请输入项目名称" />
-          </Form.Item>
-          <Form.Item label="项目描述" name="description">
-            <Input.TextArea autoSize={{ minRows: 5 }} maxLength={500} placeholder="请输入项目描述" />
-          </Form.Item>
-        </Form>
-      </Modal>
-    </Space>
   );
 }
-
-function formatDatetime(dateStr: string): string {
-  const d = new Date(dateStr);
-  const pad = (n: number) => String(n).padStart(2, "0");
-  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
-}

src/web/routes.tsx

@@ -1,5 +1,3 @@
-import type { ReactNode } from "react";
-
 import { Route, Routes } from "react-router";
 
 import { NotFoundPage } from "./pages/404";
@@ -15,7 +13,3 @@ export function AppRoutes() {
     </Routes>
   );
 }
-
-export function ProtectedRoute({ children }: { children: ReactNode }) {
-  return children;
-}

src/web/styles.css

@@ -1,7 +1,10 @@
+html,
+body {
+  margin: 0;
+}
+
 .app-layout {
   min-height: 100vh;
-  background: var(--ant-color-bg-layout);
-  width: 100%;
 }
 
 .app-header {
@@ -11,7 +14,6 @@
   padding: 0 var(--ant-padding-lg);
   background: var(--ant-color-bg-container);
   border-bottom: 1px solid var(--ant-color-border-secondary);
-  height: 64px;
 }
 
 .app-header-left {
@@ -47,75 +49,6 @@
   line-height: 1;
 }
 
-.app-sidebar-collapse-btn {
-  width: 100%;
-  justify-content: center;
-  color: var(--ant-color-text-secondary);
-}
-
-.app-page-title {
-  color: var(--ant-color-text-secondary);
-  font-size: var(--ant-font-size-heading-3);
-  font-weight: 500;
-}
-
-.app-sidebar {
-  background: var(--ant-color-bg-container);
-  border-right: 1px solid var(--ant-color-border-secondary);
-  height: calc(100vh - 64px);
-  overflow: hidden;
-}
-
-.app-sidebar-menu {
-  height: 100%;
-  overflow-y: auto;
-}
-
 .app-content {
-  box-sizing: border-box;
   padding: var(--ant-padding-xl) var(--ant-padding-xl);
-  min-height: calc(100vh - 64px);
-}
-
-.meta-response {
-  background: var(--ant-color-fill-tertiary);
-  border-radius: var(--ant-border-radius);
-  padding: var(--ant-padding-lg) var(--ant-padding-lg);
-  font-size: var(--ant-font-size);
-  color: var(--ant-color-text);
-  overflow-x: auto;
-}
-
-.error-boundary-fallback {
-  padding-top: 20vh;
-  width: 100%;
-}
-
-.full-width {
-  width: 100%;
-}
-
-.text-disabled {
-  color: var(--ant-color-text-disabled);
-}
-
-.full-width-space {
-  width: 100%;
-}
-
-.not-found-icon {
-  color: var(--ant-color-warning);
-  font-size: 64px;
-}
-
-.tabular-nums {
-  font-variant-numeric: tabular-nums;
-}
-
-.projects-header {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  flex-wrap: wrap;
-  gap: var(--ant-margin-lg);
 }

tests/web/App.test.tsx

@@ -59,7 +59,7 @@ describe("App", () => {
 
     const sider = document.querySelector(".ant-layout-sider");
     expect(sider).not.toBeNull();
-    const menu = document.querySelector(".app-sidebar-menu");
+    const menu = document.querySelector(".ant-menu");
     expect(menu).not.toBeNull();
   });
 });

tests/web/routes/404.test.tsx

@@ -11,14 +11,13 @@ describe("NotFoundPage", () => {
 
     expect(screen.getByText("404")).not.toBeNull();
     expect(screen.getByText("您访问的页面不存在")).not.toBeNull();
-    expect(screen.getByText("返回首页")).not.toBeNull();
+    expect(screen.getByRole("button", { name: "返回首页" })).not.toBeNull();
   });
 
   test("返回首页按钮存在且可点击", () => {
     renderWithProviders(createElement(NotFoundPage));
 
-    const button = screen.getByText("返回首页");
+    const button = screen.getByRole("button", { name: "返回首页" });
     expect(button).not.toBeNull();
-    expect(button.closest("button")).not.toBeNull();
   });
 });

tests/web/routes/projects.test.tsx

@@ -11,8 +11,8 @@ describe("ProjectsPage", () => {
 
     expect(screen.getByText("进行中")).not.toBeNull();
     expect(screen.getByText("已归档")).not.toBeNull();
-    expect(screen.getByText("搜索")).not.toBeNull();
     expect(screen.getByText("新建项目")).not.toBeNull();
+    expect(screen.getByPlaceholderText("搜索项目名称或描述")).not.toBeNull();
 
     await waitFor(
       () => {