[优化] go 引用调整

2026-10-03 23:06:36 +08:00 · 2026-06-06 10:26:20 +08:00
parent ee1110b752
commit 3cfefb4367
552 changed files with 1642 additions and 2185 deletions
@@ -0,0 +1,123 @@
+import {ApiError, apiRequest, getApiUrl} from '@/lib/api/client';
+import type {ApiEnvelope} from '@/types/api';
+
+import type {PagesDeployment, PagesProject, PagesProjectPayload,} from '@/features/pages/types';
+
+export function getPagesProjects() {
+  return apiRequest<PagesProject[]>('/pages/');
+}
+
+export function getPagesProject(id: number) {
+  return apiRequest<PagesProject>(`/pages/${id}`);
+}
+
+export function createPagesProject(payload: PagesProjectPayload) {
+  return apiRequest<PagesProject>('/pages/', {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  });
+}
+
+export function updatePagesProject(id: number, payload: PagesProjectPayload) {
+  return apiRequest<PagesProject>(`/pages/${id}/update`, {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  });
+}
+
+export function deletePagesProject(id: number) {
+  return apiRequest<void>(`/pages/${id}/delete`, {
+    method: 'POST',
+  });
+}
+
+export function getPagesDeployments(projectId: number) {
+  return apiRequest<PagesDeployment[]>(`/pages/${projectId}/deployments`);
+}
+
+export function uploadPagesDeployment(
+  projectId: number,
+  file: File,
+  rootDir = '',
+  entryFile = 'index.html',
+  onProgress?: (percent: number) => void,
+) {
+  if (!onProgress) {
+    const formData = new FormData();
+    formData.append('package', file);
+    formData.append('root_dir', rootDir);
+    formData.append('entry_file', entryFile);
+    return apiRequest<PagesDeployment>(
+      `/pages/${projectId}/deployments/upload`,
+      {
+        method: 'POST',
+        body: formData,
+      },
+    );
+  }
+
+  return new Promise<PagesDeployment>((resolve, reject) => {
+    const formData = new FormData();
+    formData.append('package', file);
+    formData.append('root_dir', rootDir);
+    formData.append('entry_file', entryFile);
+
+    const xhr = new XMLHttpRequest();
+    xhr.open('POST', getApiUrl(`/pages/${projectId}/deployments/upload`));
+    xhr.withCredentials = true;
+
+    xhr.upload.addEventListener('progress', (event) => {
+      if (event.lengthComputable) {
+        const percent = Math.round((event.loaded / event.total) * 100);
+        onProgress(percent);
+      }
+    });
+
+    xhr.onload = () => {
+      let payload: ApiEnvelope<PagesDeployment> | null = null;
+      try {
+        payload = JSON.parse(xhr.responseText) as ApiEnvelope<PagesDeployment>;
+      } catch {
+        payload = null;
+      }
+
+      if (xhr.status >= 200 && xhr.status < 300) {
+        if (payload && payload.success) {
+          resolve(payload.data);
+        } else {
+          reject(new ApiError(payload?.message || '请求失败', xhr.status));
+        }
+      } else {
+        reject(
+          new ApiError(
+            payload?.message || `请求失败（${xhr.status}）`,
+            xhr.status,
+          ),
+        );
+      }
+    };
+
+    xhr.onerror = () => {
+      reject(new ApiError('网络请求失败', 0));
+    };
+
+    xhr.send(formData);
+  });
+}
+
+export function activatePagesDeployment(
+  projectId: number,
+  deploymentId: number,
+) {
+  return apiRequest<PagesProject>(
+    `/pages/${projectId}/deployments/${deploymentId}/activate`,
+    { method: 'POST' },
+  );
+}
+
+export function deletePagesDeployment(projectId: number, deploymentId: number) {
+  return apiRequest<void>(
+    `/pages/${projectId}/deployments/${deploymentId}/delete`,
+    { method: 'POST' },
+  );
+}
@@ -0,0 +1,278 @@
+'use client';
+
+import {useMutation, useQueryClient} from '@tanstack/react-query';
+import {useRef, useState} from 'react';
+import {File as FileIcon, UploadCloud, X} from 'lucide-react';
+
+import {AppModal} from '@/components/ui/app-modal';
+import {activatePagesDeployment, uploadPagesDeployment,} from '@/features/pages/api/pages';
+import {PrimaryButton, SecondaryButton,} from '@/features/shared/components/resource-primitives';
+import {cn} from '@/lib/utils/cn';
+import {deploymentsQueryKey, projectQueryKey, projectsQueryKey,} from '../utils';
+
+interface PagesDeploymentUploadModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  projectId: number;
+}
+
+function formatBytes(bytes: number, decimals = 2) {
+  if (bytes === 0) return '0 Bytes';
+  const k = 1024;
+  const dm = decimals < 0 ? 0 : decimals;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i];
+}
+
+export function PagesDeploymentUploadModal({
+  isOpen,
+  onClose,
+  projectId,
+}: PagesDeploymentUploadModalProps) {
+  const queryClient = useQueryClient();
+  const [file, setFile] = useState<File | null>(null);
+  const [isDragActive, setIsDragActive] = useState(false);
+  const [uploadProgress, setUploadProgress] = useState<number | null>(null);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+
+  const resetForm = () => {
+    setFile(null);
+    setIsDragActive(false);
+    setUploadProgress(null);
+    setErrorMessage(null);
+    if (fileInputRef.current) {
+      fileInputRef.current.value = '';
+    }
+  };
+
+  const handleClose = () => {
+    resetForm();
+    onClose();
+  };
+
+  const handleDrag = (e: React.DragEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    if (e.type === 'dragenter' || e.type === 'dragover') {
+      setIsDragActive(true);
+    } else if (e.type === 'dragleave') {
+      setIsDragActive(false);
+    }
+  };
+
+  const handleDrop = (e: React.DragEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setIsDragActive(false);
+    if (e.dataTransfer.files && e.dataTransfer.files[0]) {
+      const droppedFile = e.dataTransfer.files[0];
+      if (droppedFile.name.toLowerCase().endsWith('.zip')) {
+        setFile(droppedFile);
+        setErrorMessage(null);
+      } else {
+        setErrorMessage('仅支持 zip 格式的文件');
+      }
+    }
+  };
+
+  const uploadMutation = useMutation({
+    mutationFn: async ({ shouldActivate }: { shouldActivate: boolean }) => {
+      if (!file) {
+        throw new Error('请选择 zip 文件');
+      }
+      setUploadProgress(0);
+      setErrorMessage(null);
+
+      const deployment = await uploadPagesDeployment(
+        projectId,
+        file,
+        '',
+        'index.html',
+        (percent) => {
+          setUploadProgress(percent);
+        },
+      );
+
+      if (shouldActivate) {
+        await activatePagesDeployment(projectId, deployment.id);
+      }
+      return deployment;
+    },
+    onSuccess: () => {
+      resetForm();
+      queryClient.invalidateQueries({
+        queryKey: deploymentsQueryKey(projectId),
+      });
+      queryClient.invalidateQueries({
+        queryKey: projectQueryKey(projectId),
+      });
+      queryClient.invalidateQueries({
+        queryKey: projectsQueryKey,
+      });
+      onClose();
+    },
+    onError: (error) => {
+      setUploadProgress(null);
+      setErrorMessage(error instanceof Error ? error.message : '上传失败');
+    },
+  });
+
+  const handleUploadOnly = () => {
+    uploadMutation.mutate({ shouldActivate: false });
+  };
+
+  const handleUploadAndDeploy = () => {
+    uploadMutation.mutate({ shouldActivate: true });
+  };
+
+  return (
+    <AppModal
+      isOpen={isOpen}
+      onClose={handleClose}
+      title="上传部署包"
+      description="上传已构建的 zip 静态资源包。项目将使用配置的根目录与入口文件路径。"
+      footer={
+        <div className="flex flex-wrap justify-end gap-3">
+          <SecondaryButton
+            type="button"
+            onClick={handleClose}
+            disabled={uploadMutation.isPending}
+          >
+            取消
+          </SecondaryButton>
+          <SecondaryButton
+            type="button"
+            disabled={!file || uploadMutation.isPending}
+            onClick={handleUploadOnly}
+          >
+            {uploadMutation.isPending &&
+            !uploadMutation.variables?.shouldActivate
+              ? `上传中 (${uploadProgress ?? 0}%)...`
+              : '上传'}
+          </SecondaryButton>
+          <PrimaryButton
+            type="button"
+            disabled={!file || uploadMutation.isPending}
+            onClick={handleUploadAndDeploy}
+          >
+            {uploadMutation.isPending &&
+            uploadMutation.variables?.shouldActivate
+              ? `上传并部署中 (${uploadProgress ?? 0}%)...`
+              : '上传并部署'}
+          </PrimaryButton>
+        </div>
+      }
+    >
+      <div className="space-y-4">
+        {/* Hidden File Input */}
+        <input
+          ref={fileInputRef}
+          type="file"
+          accept=".zip,application/zip"
+          onChange={(event) => {
+            const selectedFile = event.target.files?.[0] ?? null;
+            if (selectedFile) {
+              if (selectedFile.name.toLowerCase().endsWith('.zip')) {
+                setFile(selectedFile);
+                setErrorMessage(null);
+              } else {
+                setErrorMessage('仅支持 zip 格式的文件');
+              }
+            }
+          }}
+          className="hidden"
+        />
+
+        <div className="block space-y-2">
+          <span className="flex items-center gap-2 text-sm font-medium text-[var(--foreground-primary)]">
+            <span>部署包</span>
+          </span>
+
+          <div
+            onDragEnter={handleDrag}
+            onDragOver={handleDrag}
+            onDragLeave={handleDrag}
+            onDrop={handleDrop}
+            onClick={() => fileInputRef.current?.click()}
+            className={cn(
+              'group relative flex min-h-48 cursor-pointer flex-col items-center justify-center rounded-2xl border-2 border-dashed border-[var(--border-default)] bg-[var(--surface-elevated)] p-6 text-center transition-all duration-200 hover:border-[var(--brand-primary)] hover:bg-[var(--surface-hover)]',
+              isDragActive &&
+                'scale-[0.99] border-[var(--brand-primary)] bg-[var(--accent-soft)]/20 shadow-inner',
+              file && 'border-solid border-[var(--brand-primary)]',
+            )}
+          >
+            {file ? (
+              <div
+                className="flex flex-col items-center space-y-3"
+                onClick={(e) => e.stopPropagation()}
+              >
+                <div className="flex h-12 w-12 items-center justify-center rounded-full bg-[var(--accent-soft)] text-[var(--brand-primary)] transition duration-200 group-hover:scale-110">
+                  <FileIcon className="h-6 w-6" />
+                </div>
+                <div className="space-y-1">
+                  <p className="max-w-[300px] truncate text-sm font-medium text-[var(--foreground-primary)]">
+                    {file.name}
+                  </p>
+                  <p className="text-xs text-[var(--foreground-secondary)]">
+                    大小: {formatBytes(file.size)}
+                  </p>
+                </div>
+                <div className="flex items-center gap-2">
+                  <button
+                    type="button"
+                    onClick={() => {
+                      setFile(null);
+                      if (fileInputRef.current) {
+                        fileInputRef.current.value = '';
+                      }
+                    }}
+                    className="inline-flex h-8 items-center gap-1.5 rounded-lg border border-[var(--border-default)] bg-[var(--control-background)] px-3 text-xs font-medium text-[var(--foreground-primary)] transition hover:border-[var(--status-danger-border)] hover:bg-[var(--status-danger-soft)] hover:text-[var(--status-danger-foreground)]"
+                  >
+                    <X className="h-3 w-3" />
+                    清除文件
+                  </button>
+                </div>
+              </div>
+            ) : (
+              <div className="pointer-events-none flex flex-col items-center space-y-3">
+                <div className="flex h-12 w-12 items-center justify-center rounded-full bg-[var(--surface-muted)] text-[var(--foreground-muted)] transition duration-200 group-hover:scale-110 group-hover:bg-[var(--accent-soft)] group-hover:text-[var(--brand-primary)]">
+                  <UploadCloud className="h-6 w-6" />
+                </div>
+                <div className="space-y-1">
+                  <p className="text-sm font-medium text-[var(--foreground-primary)]">
+                    点击或拖拽 zip 部署包到此处
+                  </p>
+                  <p className="text-xs text-[var(--foreground-secondary)]">
+                    仅支持 zip，Server 会校验文件数量、体积、路径逃逸和入口文件
+                  </p>
+                </div>
+              </div>
+            )}
+          </div>
+          {errorMessage && (
+            <span className="mt-1 block text-xs text-[var(--status-danger-foreground)]">
+              {errorMessage}
+            </span>
+          )}
+        </div>
+
+        {uploadProgress !== null && (
+          <div className="space-y-2">
+            <div className="flex items-center justify-between text-xs font-medium text-[var(--foreground-secondary)]">
+              <span>上传进度</span>
+              <span>{uploadProgress}%</span>
+            </div>
+            <div className="h-2 w-full overflow-hidden rounded-full bg-[var(--surface-muted)]">
+              <div
+                className="h-full rounded-full bg-[var(--brand-primary)] transition-all duration-300 ease-out"
+                style={{ width: `${uploadProgress}%` }}
+              />
+            </div>
+          </div>
+        )}
+      </div>
+    </AppModal>
+  );
+}
@@ -0,0 +1,243 @@
+'use client';
+
+import {useMutation, useQuery, useQueryClient} from '@tanstack/react-query';
+import Link from 'next/link';
+import {useRouter} from 'next/navigation';
+import {useState} from 'react';
+
+import {EmptyState} from '@/components/feedback/empty-state';
+import {ErrorState} from '@/components/feedback/error-state';
+import {LoadingState} from '@/components/feedback/loading-state';
+import {PageHeader} from '@/components/layout/page-header';
+import {AppCard} from '@/components/ui/app-card';
+import {
+    activatePagesDeployment,
+    deletePagesDeployment,
+    deletePagesProject,
+    getPagesDeployments,
+    getPagesProject,
+} from '@/features/pages/api/pages';
+import {DangerButton, PrimaryButton, SecondaryButton,} from '@/features/shared/components/resource-primitives';
+import {PagesProjectEditorModal} from './pages-project-editor-modal';
+import {PagesDeploymentUploadModal} from './pages-deployment-upload-modal';
+import {formatBytes} from '@/lib/utils/metrics';
+import {deploymentsQueryKey, projectQueryKey, projectsQueryKey,} from '../utils';
+
+export function PagesProjectDetailPage({ projectId }: { projectId: string }) {
+  const router = useRouter();
+  const queryClient = useQueryClient();
+  const [isEditModalOpen, setEditModalOpen] = useState(false);
+  const [isUploadModalOpen, setUploadModalOpen] = useState(false);
+
+  const parsedProjectId = Number(projectId);
+  const projectQuery = useQuery({
+    queryKey: projectQueryKey(projectId),
+    queryFn: () => getPagesProject(parsedProjectId),
+    enabled: projectId !== '' && Number.isFinite(parsedProjectId),
+  });
+  const deploymentsQuery = useQuery({
+    queryKey: deploymentsQueryKey(parsedProjectId),
+    queryFn: () => getPagesDeployments(parsedProjectId),
+    enabled: projectId !== '' && Number.isFinite(parsedProjectId),
+  });
+
+  const activateMutation = useMutation({
+    mutationFn: (deploymentId: number) =>
+      activatePagesDeployment(parsedProjectId, deploymentId),
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: deploymentsQueryKey(parsedProjectId),
+      });
+      queryClient.invalidateQueries({ queryKey: projectQueryKey(projectId) });
+      queryClient.invalidateQueries({ queryKey: projectsQueryKey });
+    },
+  });
+
+  const deleteDeploymentMutation = useMutation({
+    mutationFn: (deploymentId: number) =>
+      deletePagesDeployment(parsedProjectId, deploymentId),
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: deploymentsQueryKey(parsedProjectId),
+      });
+      queryClient.invalidateQueries({ queryKey: projectQueryKey(projectId) });
+      queryClient.invalidateQueries({ queryKey: projectsQueryKey });
+    },
+  });
+
+  const deleteProjectMutation = useMutation({
+    mutationFn: () => deletePagesProject(parsedProjectId),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: projectsQueryKey });
+      router.push('/pages');
+    },
+  });
+
+  if (projectId === '' || !Number.isFinite(parsedProjectId)) {
+    return (
+      <EmptyState
+        title="Pages 项目不存在"
+        description="缺少有效的 Pages 项目 ID，请从项目列表重新进入。"
+      />
+    );
+  }
+
+  if (projectQuery.isLoading) {
+    return <LoadingState />;
+  }
+
+  if (projectQuery.isError) {
+    return (
+      <ErrorState
+        title="Pages 项目加载失败"
+        description={projectQuery.error.message}
+      />
+    );
+  }
+
+  const project = projectQuery.data;
+  if (!project) {
+    return (
+      <EmptyState
+        title="Pages 项目不存在"
+        description="该项目可能已被删除，或当前 ID 无法匹配到项目记录。"
+      />
+    );
+  }
+
+  const handleDeleteProject = () => {
+    if (!window.confirm(`确认删除 Pages 项目 ${project.name} 吗？`)) {
+      return;
+    }
+    deleteProjectMutation.mutate();
+  };
+
+  return (
+    <div className="space-y-6">
+      <PageHeader
+        title={project.name}
+        description={`${project.slug} · Pages 静态站点项目详情`}
+        action={
+          <>
+            <Link
+              href="/pages"
+              className="inline-flex items-center justify-center rounded-2xl border border-[var(--border-default)] bg-[var(--control-background)] px-4 py-3 text-sm font-medium text-[var(--foreground-primary)] transition hover:bg-[var(--control-background-hover)]"
+            >
+              返回列表
+            </Link>
+            <SecondaryButton
+              type="button"
+              onClick={() => setEditModalOpen(true)}
+            >
+              编辑项目
+            </SecondaryButton>
+            <PrimaryButton
+              type="button"
+              onClick={() => setUploadModalOpen(true)}
+            >
+              上传部署包
+            </PrimaryButton>
+            <DangerButton
+              type="button"
+              disabled={deleteProjectMutation.isPending}
+              onClick={handleDeleteProject}
+            >
+              删除项目
+            </DangerButton>
+          </>
+        }
+      />
+
+      <AppCard
+        title="部署历史"
+        description="部署不可变；激活后发布配置，Agent 才会拉取并切换静态资源。"
+      >
+        {deploymentsQuery.isLoading ? (
+          <p className="text-sm text-[var(--foreground-secondary)]">
+            加载中...
+          </p>
+        ) : deploymentsQuery.isError ? (
+          <p className="text-sm text-[var(--status-danger-foreground)]">
+            {deploymentsQuery.error.message}
+          </p>
+        ) : (deploymentsQuery.data ?? []).length === 0 ? (
+          <EmptyState
+            title="暂无部署"
+            description="上传 zip 部署包后，可以在这里激活某个部署版本。"
+          >
+          </EmptyState>
+        ) : (
+          <div className="overflow-hidden rounded-2xl border border-[var(--border-default)]">
+            {(deploymentsQuery.data ?? []).map((deployment) => (
+              <div
+                key={deployment.id}
+                className="flex flex-col gap-3 border-b border-[var(--border-default)] p-4 last:border-b-0 md:flex-row md:items-center md:justify-between"
+              >
+                <div>
+                  <p className="text-sm font-medium text-[var(--foreground-primary)]">
+                    #{deployment.deployment_number}{' '}
+                    {deployment.status === 'active' ? '· 已激活' : ''}
+                  </p>
+                  <p className="mt-1 text-xs text-[var(--foreground-secondary)]">
+                    {deployment.checksum.slice(0, 16)} · {deployment.file_count}{' '}
+                    files · {formatBytes(deployment.total_size)}
+                  </p>
+                </div>
+                <div className="flex gap-2">
+                  <SecondaryButton
+                    type="button"
+                    disabled={
+                      deployment.status === 'active' ||
+                      activateMutation.isPending
+                    }
+                    onClick={() => {
+                      if (
+                        window.confirm(
+                          `确认激活部署 #${deployment.deployment_number} 吗？`,
+                        )
+                      ) {
+                        activateMutation.mutate(deployment.id);
+                      }
+                    }}
+                  >
+                    激活
+                  </SecondaryButton>
+                  <DangerButton
+                    type="button"
+                    disabled={
+                      deployment.status === 'active' ||
+                      deleteDeploymentMutation.isPending
+                    }
+                    onClick={() => {
+                      if (
+                        window.confirm(
+                          `确认删除部署 #${deployment.deployment_number} 吗？`,
+                        )
+                      ) {
+                        deleteDeploymentMutation.mutate(deployment.id);
+                      }
+                    }}
+                  >
+                    删除
+                  </DangerButton>
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+      </AppCard>
+
+      <PagesProjectEditorModal
+        isOpen={isEditModalOpen}
+        onClose={() => setEditModalOpen(false)}
+        project={project}
+      />
+
+      <PagesDeploymentUploadModal
+        isOpen={isUploadModalOpen}
+        onClose={() => setUploadModalOpen(false)}
+        projectId={parsedProjectId}
+      />
+    </div>
+  );
+}
@@ -0,0 +1,75 @@
+'use client';
+
+import {useQuery} from '@tanstack/react-query';
+import {useState} from 'react';
+
+import {AppCard} from '@/components/ui/app-card';
+import {getPagesProjects} from '@/features/pages/api/pages';
+import {PrimaryButton,} from '@/features/shared/components/resource-primitives';
+import {PagesProjectEditorModal} from './pages-project-editor-modal';
+import {PagesProjectListItem} from './pages-project-list-item';
+import {projectsQueryKey} from '../utils';
+
+export { PagesProjectDetailPage } from './pages-detail-page';
+
+export function PagesPage() {
+  const [isCreateModalOpen, setCreateModalOpen] = useState(false);
+
+  const projectsQuery = useQuery({
+    queryKey: projectsQueryKey,
+    queryFn: getPagesProjects,
+  });
+
+  return (
+    <div className="space-y-6">
+      <div className="flex flex-col gap-4 lg:flex-row lg:items-start lg:justify-between">
+        <div className="space-y-2">
+          <p className="text-sm font-medium text-[var(--foreground-secondary)]">
+            OpenFlare Pages
+          </p>
+          <h1 className="text-2xl font-semibold text-[var(--foreground-primary)]">
+            边缘静态站点托管
+          </h1>
+          <p className="max-w-3xl text-sm leading-6 text-[var(--foreground-secondary)]">
+            创建 Pages 项目，上传已构建 of zip 静态资源包，然后在规则中选择
+            Pages 项目作为上游。发布后 Agent
+            会拉取部署包并在边缘节点本地服务静态文件。
+          </p>
+        </div>
+        <PrimaryButton
+          type="button"
+          className="w-full lg:w-auto"
+          onClick={() => setCreateModalOpen(true)}
+        >
+          新建 Pages 项目
+        </PrimaryButton>
+      </div>
+
+      <div className="space-y-4">
+        {projectsQuery.isLoading ? (
+          <AppCard>正在加载 Pages 项目...</AppCard>
+        ) : projectsQuery.error ? (
+          <AppCard>
+            <p className="text-sm text-[var(--status-danger-foreground)]">
+              {projectsQuery.error.message}
+            </p>
+          </AppCard>
+        ) : (projectsQuery.data ?? []).length === 0 ? (
+          <AppCard
+            title="还没有 Pages 项目"
+            description="先创建一个项目，再上传静态资源包。"
+          />
+        ) : (
+          (projectsQuery.data ?? []).map((project) => (
+            <PagesProjectListItem key={project.id} project={project} />
+          ))
+        )}
+      </div>
+
+      <PagesProjectEditorModal
+        isOpen={isCreateModalOpen}
+        onClose={() => setCreateModalOpen(false)}
+      />
+    </div>
+  );
+}
@@ -0,0 +1,289 @@
+'use client';
+
+import {zodResolver} from '@hookform/resolvers/zod';
+import {useMutation, useQueryClient} from '@tanstack/react-query';
+import {useEffect} from 'react';
+import {useForm} from 'react-hook-form';
+
+import {AppModal} from '@/components/ui/app-modal';
+import {createPagesProject, updatePagesProject,} from '@/features/pages/api/pages';
+import type {PagesProject} from '@/features/pages/types';
+import {
+    PrimaryButton,
+    ResourceField,
+    ResourceInput,
+    SecondaryButton,
+    ToggleField,
+} from '@/features/shared/components/resource-primitives';
+import {projectQueryKey, projectsQueryKey} from '../utils';
+import {type PagesProjectFormValues, pagesProjectSchema} from '../schemas';
+
+interface PagesProjectEditorModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  project?: PagesProject | null;
+  onSaved?: (project: PagesProject, mode: 'create' | 'update') => void;
+}
+
+function toFormValues(project?: PagesProject | null): PagesProjectFormValues {
+  if (!project) {
+    return {
+      name: '',
+      slug: '',
+      description: '',
+      spa_fallback_enabled: false,
+      spa_fallback_path: '/index.html',
+      api_proxy_enabled: false,
+      api_proxy_path: '',
+      api_proxy_pass: '',
+      api_proxy_rewrite: '',
+      root_dir: '',
+      entry_file: 'index.html',
+    };
+  }
+  return {
+    name: project.name,
+    slug: project.slug,
+    description: project.description || '',
+    spa_fallback_enabled: project.spa_fallback_enabled,
+    spa_fallback_path: project.spa_fallback_path,
+    api_proxy_enabled: project.api_proxy_enabled || false,
+    api_proxy_path: project.api_proxy_path || '',
+    api_proxy_pass: project.api_proxy_pass || '',
+    api_proxy_rewrite: project.api_proxy_rewrite || '',
+    root_dir: project.root_dir || '',
+    entry_file: project.entry_file || 'index.html',
+  };
+}
+
+export function PagesProjectEditorModal({
+  isOpen,
+  onClose,
+  project,
+  onSaved,
+}: PagesProjectEditorModalProps) {
+  const queryClient = useQueryClient();
+
+  const form = useForm<PagesProjectFormValues>({
+    resolver: zodResolver(pagesProjectSchema),
+    defaultValues: toFormValues(project),
+  });
+
+  useEffect(() => {
+    if (isOpen) {
+      form.reset(toFormValues(project));
+    }
+  }, [form, project, isOpen]);
+
+  const mutation = useMutation({
+    mutationFn: (values: PagesProjectFormValues) => {
+      const payload = {
+        name: values.name.trim(),
+        slug: values.slug?.trim() || '',
+        description: values.description?.trim() || '',
+        enabled: project ? project.enabled : true,
+        spa_fallback_enabled: values.spa_fallback_enabled,
+        spa_fallback_path: values.spa_fallback_enabled
+          ? values.spa_fallback_path.trim()
+          : project
+            ? project.spa_fallback_path
+            : '/index.html',
+        api_proxy_enabled: values.api_proxy_enabled,
+        api_proxy_path: values.api_proxy_enabled
+          ? values.api_proxy_path.trim()
+          : '',
+        api_proxy_pass: values.api_proxy_enabled
+          ? values.api_proxy_pass.trim()
+          : '',
+        api_proxy_rewrite: values.api_proxy_enabled
+          ? values.api_proxy_rewrite.trim()
+          : '',
+        root_dir: values.root_dir?.trim() || '',
+        entry_file: values.entry_file?.trim() || 'index.html',
+      };
+      return project
+        ? updatePagesProject(project.id, payload)
+        : createPagesProject(payload);
+    },
+    onSuccess: (savedProject) => {
+      onClose();
+      if (project) {
+        queryClient.invalidateQueries({
+          queryKey: projectQueryKey(project.id),
+        });
+      }
+      queryClient.invalidateQueries({ queryKey: projectsQueryKey });
+      onSaved?.(savedProject, project ? 'update' : 'create');
+    },
+  });
+
+  const handleSubmit = form.handleSubmit((values) => {
+    mutation.mutate(values);
+  });
+
+  const spaFallbackEnabled = form.watch('spa_fallback_enabled');
+  const apiProxyEnabled = form.watch('api_proxy_enabled');
+
+  return (
+    <AppModal
+      isOpen={isOpen}
+      onClose={onClose}
+      title={project ? '编辑 Pages 项目' : '新建 Pages 项目'}
+      description={
+        project
+          ? '修改静态站点项目的基础配置与高级反代规则。'
+          : '配置静态站点项目的基础信息与高级反代规则。创建后再上传已构建的 zip 部署包。'
+      }
+      footer={
+        <div className="flex flex-wrap justify-end gap-3">
+          <SecondaryButton type="button" onClick={onClose}>
+            取消
+          </SecondaryButton>
+          <PrimaryButton
+            type="submit"
+            form="pages-project-editor-form"
+            disabled={mutation.isPending || !form.formState.isValid}
+          >
+            {mutation.isPending
+              ? '保存中...'
+              : project
+                ? '保存修改'
+                : '创建项目'}
+          </PrimaryButton>
+        </div>
+      }
+    >
+      <form
+        id="pages-project-editor-form"
+        className="grid gap-4 md:grid-cols-2"
+        onSubmit={handleSubmit}
+      >
+        <ResourceField
+          label="项目名称"
+          error={form.formState.errors.name?.message}
+        >
+          <ResourceInput
+            placeholder="Marketing Site"
+            {...form.register('name')}
+            required
+          />
+        </ResourceField>
+        <ResourceField
+          label="项目标识"
+          hint="留空时会按名称自动生成。"
+          error={form.formState.errors.slug?.message}
+        >
+          <ResourceInput
+            placeholder="marketing-site"
+            {...form.register('slug')}
+          />
+        </ResourceField>
+        <ResourceField
+          label="描述"
+          className="md:col-span-2"
+          error={form.formState.errors.description?.message}
+        >
+          <ResourceInput
+            placeholder="这个项目托管的静态站点用途"
+            {...form.register('description')}
+          />
+        </ResourceField>
+        <ResourceField
+          label="根目录 (可选)"
+          hint="静态资源的根文件夹路径 (例如 build 或 dist)，若为空则默认为 zip 包根目录。"
+          error={form.formState.errors.root_dir?.message}
+        >
+          <ResourceInput
+            placeholder="例如: build"
+            {...form.register('root_dir')}
+          />
+        </ResourceField>
+        <ResourceField
+          label="入口文件"
+          hint="基于根目录下的入口文件路径。"
+          error={form.formState.errors.entry_file?.message}
+        >
+          <ResourceInput
+            placeholder="index.html"
+            {...form.register('entry_file')}
+            required
+          />
+        </ResourceField>
+        <ToggleField
+          label="启用 SPA fallback"
+          description="开启后未命中的路径会回退到指定文件，适合 React/Vue history 路由。"
+          checked={spaFallbackEnabled}
+          onChange={(checked) =>
+            form.setValue('spa_fallback_enabled', checked, {
+              shouldValidate: true,
+            })
+          }
+        />
+        <ResourceField
+          label="SPA 回退路径"
+          hint="以 / 开头，例如 /index.html 或 /app.html。关闭 fallback 时不会生效。"
+          error={form.formState.errors.spa_fallback_path?.message}
+        >
+          <ResourceInput
+            placeholder="/index.html"
+            disabled={!spaFallbackEnabled}
+            {...form.register('spa_fallback_path')}
+          />
+        </ResourceField>
+        <ToggleField
+          label="启用 API 反向代理"
+          description="允许为该静态站点配置反代后端（例如反代指定 API 路径至您的后端服务）。"
+          checked={apiProxyEnabled}
+          onChange={(checked) =>
+            form.setValue('api_proxy_enabled', checked, {
+              shouldValidate: true,
+            })
+          }
+        />
+        {apiProxyEnabled && (
+          <>
+            <ResourceField
+              label="反代匹配路径"
+              hint="以 / 开头，例如 /api 或 /api/v1。匹配该前缀的请求将被转发。"
+              error={form.formState.errors.api_proxy_path?.message}
+            >
+              <ResourceInput
+                placeholder="/api"
+                {...form.register('api_proxy_path')}
+                required
+              />
+            </ResourceField>
+            <ResourceField
+              label="后端服务地址"
+              hint="包含协议和主机的完整 URL，例如 http://127.0.0.1:8080。"
+              error={form.formState.errors.api_proxy_pass?.message}
+            >
+              <ResourceInput
+                placeholder="http://127.0.0.1:8080"
+                {...form.register('api_proxy_pass')}
+                required
+              />
+            </ResourceField>
+            <ResourceField
+              label="路径重写目标"
+              hint="可选。如果配置为 /，请求 /api/users 将被重写转发至后端 /users 路径。"
+              error={form.formState.errors.api_proxy_rewrite?.message}
+            >
+              <ResourceInput
+                placeholder="/"
+                {...form.register('api_proxy_rewrite')}
+              />
+            </ResourceField>
+          </>
+        )}
+        {mutation.isError ? (
+          <p className="text-sm text-[var(--status-danger-foreground)] md:col-span-2">
+            {mutation.error instanceof Error
+              ? mutation.error.message
+              : '操作失败，请稍后重试。'}
+          </p>
+        ) : null}
+      </form>
+    </AppModal>
+  );
+}
@@ -0,0 +1,71 @@
+'use client';
+
+import Link from 'next/link';
+
+import {StatusBadge} from '@/components/ui/status-badge';
+import type {PagesProject} from '@/features/pages/types';
+import {formatDateTime} from '@/lib/utils/date';
+
+export function PagesProjectListItem({ project }: { project: PagesProject }) {
+  return (
+    <Link
+      href={`/pages/detail?id=${project.id}`}
+      className="group block rounded-[28px] border border-[var(--border-default)] bg-[var(--surface-panel)] p-5 shadow-[var(--shadow-card)] transition hover:-translate-y-0.5 hover:border-[var(--border-strong)] hover:shadow-[var(--shadow-soft)]"
+    >
+      <div className="flex flex-col gap-4 md:flex-row md:items-center md:justify-between">
+        <div className="min-w-0 space-y-2">
+          <div className="flex flex-wrap items-center gap-2">
+            <h2 className="text-lg font-semibold text-[var(--foreground-primary)]">
+              {project.name}
+            </h2>
+            <StatusBadge
+              label={project.enabled ? '已启用' : '已停用'}
+              variant={project.enabled ? 'success' : 'warning'}
+            />
+            <StatusBadge
+              label={project.spa_fallback_enabled ? 'SPA fallback' : '严格 404'}
+              variant={project.spa_fallback_enabled ? 'info' : 'warning'}
+            />
+          </div>
+          <p className="text-sm text-[var(--foreground-secondary)]">
+            {project.slug}
+          </p>
+          {project.description ? (
+            <p className="line-clamp-2 text-sm leading-6 text-[var(--foreground-secondary)]">
+              {project.description}
+            </p>
+          ) : null}
+          {project.spa_fallback_enabled ? (
+            <p className="text-xs text-[var(--foreground-secondary)]">
+              回退路径：{project.spa_fallback_path || '/index.html'}
+            </p>
+          ) : null}
+        </div>
+
+        <div className="grid shrink-0 grid-cols-1 gap-3 text-sm md:min-w-40">
+          <div className="rounded-2xl border border-[var(--border-default)] bg-[var(--surface-muted)] px-4 py-3">
+            <p className="text-xs text-[var(--foreground-secondary)]">
+              当前激活
+            </p>
+            <p className="mt-1 font-semibold text-[var(--foreground-primary)]">
+              {project.active_deployment
+                ? `#${project.active_deployment.deployment_number}`
+                : '暂无'}
+            </p>
+          </div>
+        </div>
+      </div>
+      <div className="mt-4 flex items-center justify-between border-t border-[var(--border-default)] pt-4">
+        <p className="text-xs text-[var(--foreground-secondary)]">
+          激活时间：
+          {project.active_deployment?.activated_at
+            ? formatDateTime(project.active_deployment.activated_at)
+            : '未激活'}
+        </p>
+        <span className="text-sm font-medium text-[var(--brand-primary)] transition group-hover:translate-x-1">
+          查看详情 →
+        </span>
+      </div>
+    </Link>
+  );
+}
@@ -0,0 +1,88 @@
+import {z} from 'zod';
+
+export const pagesProjectSchema = z
+  .object({
+    name: z
+      .string()
+      .trim()
+      .min(1, '请输入项目名称')
+      .max(255, '项目名称不能超过 255 个字符'),
+    slug: z
+      .string()
+      .trim()
+      .max(255, '项目标识不能超过 255 个字符')
+      .optional()
+      .or(z.literal('')),
+    description: z
+      .string()
+      .trim()
+      .max(1000, '描述不能超过 1000 个字符')
+      .optional()
+      .or(z.literal('')),
+    spa_fallback_enabled: z.boolean(),
+    spa_fallback_path: z.string().trim(),
+    api_proxy_enabled: z.boolean(),
+    api_proxy_path: z.string().trim(),
+    api_proxy_pass: z.string().trim(),
+    api_proxy_rewrite: z.string().trim(),
+    root_dir: z
+      .string()
+      .trim()
+      .max(512, '根目录不能超过 512 个字符')
+      .optional()
+      .or(z.literal('')),
+    entry_file: z
+      .string()
+      .trim()
+      .min(1, '请输入入口文件')
+      .max(512, '入口文件不能超过 512 个字符'),
+  })
+  .superRefine((data, ctx) => {
+    if (data.spa_fallback_enabled) {
+      if (!data.spa_fallback_path) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['spa_fallback_path'],
+          message: '启用 SPA fallback 时必须输入回退路径',
+        });
+      } else if (!data.spa_fallback_path.startsWith('/')) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['spa_fallback_path'],
+          message: '回退路径必须以 / 开头，例如 /index.html',
+        });
+      }
+    }
+
+    if (data.api_proxy_enabled) {
+      if (!data.api_proxy_path) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['api_proxy_path'],
+          message: '启用 API 反向代理时必须输入匹配路径',
+        });
+      } else if (!data.api_proxy_path.startsWith('/')) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['api_proxy_path'],
+          message: '匹配路径必须以 / 开头，例如 /api',
+        });
+      }
+
+      if (!data.api_proxy_pass) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['api_proxy_pass'],
+          message: '启用 API 反向代理时必须输入后端服务地址',
+        });
+      } else if (!/^https?:\/\//i.test(data.api_proxy_pass)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['api_proxy_pass'],
+          message: '后端服务地址必须以 http:// 或 https:// 开头',
+        });
+      }
+    }
+  });
+
+export type PagesProjectFormValues = z.infer<typeof pagesProjectSchema>;
@@ -0,0 +1,50 @@
+export interface PagesDeployment {
+  id: number;
+  project_id: number;
+  deployment_number: number;
+  checksum: string;
+  status: 'uploaded' | 'active';
+  file_count: number;
+  total_size: number;
+  root_dir?: string;
+  entry_file: string;
+  created_by: string;
+  created_at: string;
+  activated_at?: string | null;
+}
+
+export interface PagesProject {
+  id: number;
+  name: string;
+  slug: string;
+  description: string;
+  enabled: boolean;
+  spa_fallback_enabled: boolean;
+  spa_fallback_path: string;
+  api_proxy_enabled: boolean;
+  api_proxy_path: string;
+  api_proxy_pass: string;
+  api_proxy_rewrite: string;
+  root_dir?: string;
+  entry_file: string;
+  active_deployment_id?: number | null;
+  active_deployment?: PagesDeployment | null;
+  deployment_count: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface PagesProjectPayload {
+  name: string;
+  slug: string;
+  description: string;
+  enabled: boolean;
+  spa_fallback_enabled: boolean;
+  spa_fallback_path: string;
+  api_proxy_enabled: boolean;
+  api_proxy_path: string;
+  api_proxy_pass: string;
+  api_proxy_rewrite: string;
+  root_dir?: string;
+  entry_file: string;
+}
@@ -0,0 +1,9 @@
+export const projectsQueryKey = ['pages-projects'];
+
+export function projectQueryKey(projectId: string | number) {
+  return ['pages-project', String(projectId)];
+}
+
+export function deploymentsQueryKey(projectId: string | number) {
+  return ['pages-deployments', Number(projectId)];
+}