前端体验

Cirrus CDN 的前端是基于 Next.js 15 的运维导向单页应用（frontend/），与第 3 章记录的 REST API 使用相同契约。本章介绍应用结构、数据获取策略与 UX 模式，确保门户操作与 API 能力保持一致。

技术栈

• 框架：Next.js App Router（结合 React 服务端组件与客户端组件）。
• 语言：TypeScript，使用 pnpm 构建。
• UI 工具：基于 Shadcn 的组件，位于 frontend/components/ui。
• 状态管理：客户端组件通过 React hooks 管理局部状态；跨组件状态较少，必要时持久化于 localStorage。
• 构建产物：静态导出（pnpm build），作为 FastAPI 容器的一部分部署于 /app/static。

目录结构

路径	作用
frontend/app/	路由定义（如 /login、/sites、/users、/settings、/tokens）。
frontend/components/	可复用 UI 基础件（表格、弹窗）及业务模块（sites/、users/）。
frontend/hooks/	自定义 hook（如 use-toast 等）。
frontend/lib/api.ts	引用后端端点的类型化 API 客户端。
frontend/styles/	Tailwind 与全局样式。

需要交互的路由使用客户端组件实现（例如登录表单、域名管理）。

认证流程

• frontend/app/login/page.tsx 负责提交凭据：
  • 调用 api.login 发送用户名/密码。
  • 成功后在 localStorage 中存储 isAuthenticated 与用户信息。
  • 导航至 /sites。
  • 通过 toast 提示成功或失败。
• api.logout 清理会话 Cookie；前端同时清空 localStorage。
• api.me 获取当前用户元数据，用于填充 UI（如导航栏）。

站点管理

frontend/app/sites/page.tsx 与 components/sites/ 覆盖域名 CRUD 与观测能力：

• SitesOverview 列出域名、缓存状态、源站数量与证书可用性（在证书元数据直接暴露前使用占位标记）。
• AddSiteDialog 封装 createDomain API，完成后重新获取域名列表。
• AccessView 调用 /domains/{domain}/cname 显示分配节点与 TTL。
• OriginManagement、RuleManagement、HeaderManagement、CertificateManagement 与 DeleteSite 分别对应针对性更新的 API。
• 标签页通过查询参数（domain、tab）控制，可直达特定管理流程。

用户与令牌

• components/users/ 下的 UserManagement 负责列出、创建、更新、删除运维账号，对应 /api/v1/users。
• 服务令牌界面（app/tokens/）要求用户提供 master 令牌；API 客户端将其附加为 Bearer 头。

设置与其他页面

• app/settings 展示会话管理（修改密码）、清缓存操作与 ACME 控件。
• app/users 与 app/tokens 复用通用 UI 组件，保持表格、对话框、确认模态的一致体验。

API 客户端抽象

frontend/lib/api.ts 统一封装 HTTP 调用：

• 自动设置 Content-Type: application/json（除非传递 FormData/二进制）。
• 会话相关请求携带凭据。
• 根据返回体中的 detail 字段抛出带语义的 Error。
• 暴露域名配置（DomainConf）、用户元数据、缓存规则、ACME 状态等类型接口。
• 支持 master 令牌，通过附加 Authorization 头实现。

该抽象让 UI 组件保持声明式，也方便测试（如直接 stub API 方法）。

状态持久化与 UX 细节

• 轻量使用 localStorage 缓存已登录用户，用于 UI 个性化；敏感数据（令牌）不会跨会话持久化。
• toast 通知在异步操作结束时提供即时反馈。
• 组件使用 React hooks（useEffect、useState）获取数据；由于工作流局部化，无需全局状态管理。
• 导航使用 Next.js router 更新查询参数而不刷新整页，保持 SPA 响应性。

构建与部署

• pnpm build 生成静态导出（out 目录）。Dockerfile 将其复制至 /app/static，由 FastAPI 与 API 一并提供。
• 运行时配置（如 API 基址）通过 NEXT_PUBLIC_API_BASE 设置。Docker 默认使用相对路径。
• pnpm lint 强制 TypeScript 与 ESLint 规范；pnpm dev 则用于本地开发。

前端完全对齐后端能力，使用相同数据契约，确保操作人员无论通过门户还是自动化执行，都能获得一致体验。第 8 章将探讨保护 API 与 UI 的安全控制。