Skip to content

08-frontend-architecture.md

Latest commit

 

History

History
193 lines (146 loc) · 7.87 KB

08-frontend-architecture.md

File metadata and controls

193 lines (146 loc) · 7.87 KB
Raw

skillhub 前端架构设计

1 技术栈

类别 选型 说明
框架 React 19 + TypeScript
构建 Vite
路由 TanStack Router
数据获取 TanStack Query 管理所有服务端数据（API 响应缓存、加载/错误状态）
UI 组件 shadcn/ui + Radix UI
样式 Tailwind CSS
本地状态 Zustand 仅管理纯客户端状态
API 客户端 openapi-fetch + openapi-typescript
图标 Lucide React

1.1 Zustand 与 TanStack Query 职责边界

  • TanStack Query：管理所有服务端数据（API 响应缓存、加载/错误状态）
  • Zustand：仅管理纯客户端状态（UI 偏好、侧边栏展开、主题、当前选中的命名空间过滤等）
  • 禁止在 Zustand 中缓存服务端数据

2 页面结构

2.1 门户区（公开，匿名可访问）

页面 路径 说明
首页 / 精选/热门/最新、搜索入口
搜索页 /search 关键词搜索 + 过滤 + 排序
命名空间主页 /@{namespace} 空间介绍 + 技能列表
技能详情页 /@{namespace}/{slug} README 渲染、版本、评分、收藏、下载
版本历史 /@{namespace}/{slug}/versions 版本列表 + changelog

门户区所有 PUBLIC 技能匿名可浏览和下载，无需登录。

2.2 个人中心（需登录）

页面 路径 说明
我的技能 /dashboard/skills 我发布的技能 + 统一生命周期状态
发布技能 /dashboard/publish zip 上传 + 预览 + 提交审核
我的收藏 /dashboard/stars 收藏列表
Token 管理 /dashboard/tokens 创建/查看/吊销
我的命名空间 /dashboard/namespaces 参与的命名空间

2.3 命名空间管理（需空间 ADMIN）

页面 路径 说明
成员管理 /dashboard/namespaces/{slug}/members 成员管理
空间审核 /dashboard/namespaces/{slug}/reviews 待审核列表

2.4 平台管理（需对应平台角色）

页面 路径 所需角色 说明
审核中心 /admin/reviews SKILL_ADMIN 全局待审核列表
提升审核 /admin/promotions SKILL_ADMIN 提升到全局的申请列表
技能管理 /admin/skills SKILL_ADMIN 隐藏/恢复技能、撤回已发布版本
用户管理 /admin/users USER_ADMIN 用户列表、角色分配、准入审批、封禁/解封
审计日志 /admin/audit-logs AUDITOR 操作日志查询
命名空间管理 /admin/namespaces SUPER_ADMIN 创建/归档/冻结

SUPER_ADMIN 可访问所有管理页面。路由守卫检查用户是否持有对应角色。

3 布局结构

  • 门户区：顶部导航 + 内容区，无侧边栏，突出浏览体验
  • Dashboard / Admin：顶部导航 + 左侧边栏，管理效率优先
  • 响应式：移动端侧边栏收起为抽屉

3.1 生命周期展示模型

前端不再从 status + hidden + latestVersionStatus + viewingVersionStatus 拼装 skill 生命周期，而统一消费后端返回的 projection：

  • headlineVersion：当前页面主展示版本
  • publishedVersion：当前最新已发布版本
  • ownerPreviewVersion：owner / namespace 管理者可见的待审核版本
  • resolutionMode：PUBLISHED / OWNER_PREVIEW / NONE

约束：

  • 详情页和“我的技能”列表统一以 headlineVersion 作为主展示版本
  • 安装、下载、promotion 等公开分发相关操作只允许绑定 publishedVersion
  • hidden 是独立治理覆盖层，不属于版本生命周期状态机

4 登录与鉴权

4.1 OAuth2 登录流程（前端视角）

用户点击"登录"按钮
    │
    ▼
前端调用 GET /api/v1/auth/providers
    │
    ▼
渲染可用的 OAuth Provider 按钮（一期只有 GitHub）
    │
    ▼
用户点击 "Sign in with GitHub"
    │
    ▼
window.location.href = "/oauth2/authorization/github"
    │
    ▼
（浏览器跳转到 GitHub → 授权 → 回调后端 → 后端创建 Session）
    │
    ▼
后端重定向回前端页面（如 / 或用户之前访问的页面）
    │
    ▼
前端检测到 Session Cookie，调用 GET /api/v1/auth/me
    │
    ▼
获取用户信息，渲染登录态 UI

前端不需要任何 OAuth 库，登录完全由后端 Spring Security 处理。前端只负责：

  1. 调用 /api/v1/auth/providers 获取可用 Provider 列表
  2. 跳转到对应的 authorizationUrl
  3. 回调后通过 /api/v1/auth/me 检测登录态

4.2 预留的被动会话引导

为未来私有部署下的企业 SSO 兼容，前端可在登录页或应用初始化阶段显式调用：

  • POST /api/v1/auth/session/bootstrap

该接口在开源版默认关闭；私有版启用后，前端可在检测到用户未登录时主动调用一次，以尝试将外部 SSO Cookie 换成 skillhub Session。该流程必须保持显式触发，不默认依赖全局透明拦截器。

前端兼容接入层约束如下：

  • 默认不启用，运行时配置不打开时，登录页和全局行为与开源版完全一致
  • 账号密码登录兼容层与被动会话兼容层相互独立，可单独启用
  • 启用后，登录页会出现一个“企业 SSO”兼容入口
  • 启用密码兼容层后，登录页账号密码表单会改为调用通用直连认证接口
  • 前端应优先消费 /api/v1/auth/methods 作为统一登录方式目录；/api/v1/auth/providers 仅保留兼容
  • 可选自动尝试，但仍限定在登录页内执行，不在全站每次匿名访问时自动探测
  • bootstrap 失败时应静默回退到现有本地登录和 OAuth 登录，不打断正常流程

前端运行时配置项：

  • SKILLHUB_WEB_AUTH_DIRECT_ENABLED
  • SKILLHUB_WEB_AUTH_DIRECT_PROVIDER
  • SKILLHUB_WEB_AUTH_SESSION_BOOTSTRAP_ENABLED
  • SKILLHUB_WEB_AUTH_SESSION_BOOTSTRAP_PROVIDER
  • SKILLHUB_WEB_AUTH_SESSION_BOOTSTRAP_AUTO

推荐策略：

  • 私有版密码直连：auth_direct_enabled=true，auth_direct_provider=private-sso
  • 私有版初期：enabled=true，provider=private-sso，auto=false
  • 验证稳定后：再评估是否切到 auto=true

4.3 登录态检测

页面加载 → GET /api/v1/auth/me
              │
    ┌─────────┴──────────┐
    │ 200: 已登录          │ 401: 未登录
    │ 存入全局状态          │ 门户页正常展示（匿名浏览）
    │ 渲染登录态 UI         │ Dashboard/Admin 重定向到登录
    └────────────────────┘
  • TanStack Router beforeLoad 做路由守卫
  • Admin 路由额外检查角色
  • 前端权限控制粒度详见 03-authentication-design.md 前端权限控制粒度章节

5 API 集成工作流

后端 Springdoc → openapi.json
    → openapi-typescript 生成类型
    → openapi-fetch 创建客户端
    → TanStack Query 封装为 hooks

6 文件上传

一期 Web 端：zip 上传 → 后端解压校验 → 返回预览 → 用户确认 → 提交审核。 支持 drag-and-drop + 进度条。

7 关键交互

技能详情页：SKILL.md Markdown 渲染、右侧信息栏（版本/下载量/评分/收藏/标签/空间）、版本切换、安装命令一键复制（同时展示 skillhub CLI 格式 install @namespace/slug 和 ClawHub CLI 格式 install canonical-slug）。匿名用户可浏览和下载，收藏/评分按钮提示登录。

搜索页：实时搜索（debounce 300ms）、技能卡片、排序（相关度/下载量/评分/最新）、命名空间过滤。匿名用户可搜索 PUBLIC 技能。注意：一期搜索仅基于 latest 版本内容，不支持按 tag/version 搜索（详见 04-search-architecture.md 5.1 节）。

审核页面：左侧列表 + 右侧内容预览（Markdown + 文件树）、通过/拒绝 + 意见输入。