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：顶部导航 + 左侧边栏，管理效率优先
响应式：移动端侧边栏收起为抽屉

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 处理。前端只负责：

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

4.2 登录态检测

页面加载 → 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 + 文件树）、通过/拒绝 + 意见输入。

5.6 KiB Raw Blame History Unescape Escape