--- sidebar_position: 4 title: 前端架构 sidebar_label: 前端架构 description: Plaza Next.js 前端架构、页面规范、组件设计、渲染策略和交互规则 --- # 前端架构 ## 项目初始化 ```bash cd ui/ pnpm create next-app@latest plaza --typescript --tailwind --app --no-src-dir cd plaza pnpm add swr ``` `.env.local`： ```bash NEXT_PUBLIC_API_BASE=https://go.tkmind.cn NEXT_PUBLIC_PLAZA_BASE=/plaza ``` --- ## 目录结构 ```text ui/plaza/ ├── app/ │ ├── layout.tsx # 根布局：全局 Header、Footer、主题 │ ├── plaza/ │ │ ├── page.tsx # /plaza 广场首页（SSR） │ │ ├── cat/ │ │ │ └── [slug]/ │ │ │ └── page.tsx # /plaza/cat/:slug 分类页（SSR） │ │ └── p/ │ │ └── [id]/ │ │ └── page.tsx # /plaza/p/:id 帖子详情（SSR） │ └── u/ │ └── [slug]/ │ └── page.tsx # /u/:slug 用户主页（SSR） ├── components/ │ ├── layout/ │ │ ├── Header.tsx # 顶部导航：Logo、分类、登录入口 │ │ ├── Footer.tsx # 底部：关于、版权、「用 MindSpace 制作」 │ │ └── MobileNav.tsx # 移动端底部导航 │ ├── feed/ │ │ ├── PostGrid.tsx # 响应式瀑布流容器 │ │ ├── PostCard.tsx # 单张卡片 │ │ ├── CategoryNav.tsx # 分类导航 Tab │ │ ├── FeedTabs.tsx # 「热门」/「最新」切换 │ │ └── InfiniteScroll.tsx # 无限滚动加载 │ ├── post/ │ │ ├── PostEmbed.tsx # 帖子详情页嵌入发布 bundle 的 iframe │ │ ├── PostMeta.tsx # 标题、作者、发布时间 │ │ ├── PostActions.tsx # 点赞、收藏、分享按钮 │ │ └── CommentSection.tsx # 评论区 │ ├── comment/ │ │ ├── CommentList.tsx │ │ ├── CommentItem.tsx │ │ └── CommentInput.tsx │ └── user/ │ ├── UserCard.tsx # 用户主页头部：头像、粉丝数、关注按钮 │ └── UserPostGrid.tsx # 用户发布的帖子网格 ├── lib/ │ ├── api.ts # 封装 fetch，调用 /api/plaza/v1/* │ ├── cache.ts # Next.js fetch 缓存策略常量 │ └── format.ts # 数字格式化（1.2万、3.4k） └── types/ └── plaza.ts # PlazaPost、PlazaComment 等类型定义 ``` --- ## 页面规范 ### /plaza 广场首页 **渲染方式**：SSR + ISR（每 60 秒重新生成） **布局**： ```text ┌─────────────────────────────────────────┐ │ Header：Logo 分类导航 搜索 登录 │ ├─────────────────────────────────────────┤ │ FeedTabs：[ 热门 ] [ 最新 ] │ │ FeaturedBanner（Sprint 5，精选轮播） │ ├─────────────────────────────────────────┤ │ │ │ PostGrid（瀑布流，2列移动/3列平板/4列桌面）│ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │ 卡片 │ │ 卡片 │ │ 卡片 │ │ 卡片 │ │ │ └──────┘ └──────┘ └──────┘ └──────┘ │ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │ 卡片 │ │ 卡片 │ │ 卡片 │ │ 卡片 │ │ │ └──────┘ └──────┘ └──────┘ └──────┘ │ │ [ 加载更多 / 无限滚动 ] │ ├─────────────────────────────────────────┤ │ Footer │ └─────────────────────────────────────────┘ ``` **首屏数据**：服务端获取第一页 20 条热门帖子，直接注入 HTML。后续翻页由客户端 SWR 请求。 --- ### /plaza/cat/:slug 分类页 **渲染方式**：SSR + `generateStaticParams`（所有分类在构建时预生成） 与首页布局相同，增加分类标题和描述，CategoryNav 高亮当前分类。 --- ### /plaza/p/:id 帖子详情 **渲染方式**：SSR，`cache: 'no-store'`（实时获取最新互动数据） **布局**： ```text ┌─────────────────────────────────────────┐ │ Header │ ├─────────────────────────────────────────┤ │ 作者信息：头像 名字 发布时间 关注按钮 │ ├─────────────────────────────────────────┤ │ │ │ PostEmbed │ │ ┌───────────────────────────────────┐ │ │ │ iframe src={bundle_url} │ │ │ │ sandbox="allow-scripts │ │ │ │ allow-same-origin" │ │ │ │ height 自适应内容高度 │ │ │ └───────────────────────────────────┘ │ │ │ ├─────────────────────────────────────────┤ │ PostActions：👍 1.2k 🔖 234 📤 分享 │ ├─────────────────────────────────────────┤ │ CommentSection（客户端渲染，登录后可写）│ ├─────────────────────────────────────────┤ │ Footer：「用 MindSpace 制作 →」 │ └─────────────────────────────────────────┘ ``` **iframe 规则**： - `src` 直接指向 `publications.bundle_url`，不通过广场服务转发。 - `sandbox` 属性限制：`allow-scripts allow-same-origin`，禁止 `allow-forms allow-popups allow-top-navigation`。 - `width: 100%`，高度通过 `postMessage` 从 bundle 内部上报，iframe 动态调整。 - bundle 域名与广场域名不同（`assets.go.tkmind.cn`）时，CSP 已在 MindSpace 发布流程中配置，无需广场额外处理。 --- ### /u/:slug 用户主页 **渲染方式**：SSR，`revalidate: 300`（5 分钟缓存） **布局**： ```text ┌─────────────────────────────────────────┐ │ Header │ ├─────────────────────────────────────────┤ │ 用户信息区 │ │ 头像（大） 显示名 @slug │ │ 简介文字 │ │ 📝 N 篇作品 👥 N 粉丝 ❤️ N 点赞 │ │ [ 关注 ] [ 发消息（占位）] │ ├─────────────────────────────────────────┤ │ 作品网格（同 PostGrid） │ └─────────────────────────────────────────┘ ``` --- ## PostCard 卡片组件规范 ```text ┌──────────────────────────┐ │ 封面图（16:9 或 4:3） │ │ cover_url │ ├──────────────────────────┤ │ 标题（最多 2 行截断） │ │ 摘要（最多 2 行截断） │ ├──────────────────────────┤ │ 头像 显示名 发布时间 │ ├──────────────────────────┤ │ 👍 1.2k 💬 34 │ └──────────────────────────┘ ``` **必须处理的状态**： - 封面图加载失败 → 显示分类颜色背景 + 标题首字 - 封面图未生成（`cover_url` 为空）→ 同上 - 标题超长 → CSS `line-clamp-2` - 数字格式：`1000` → `1k`，`10000` → `1万`，`100000` → `10万` --- ## 全局交互规则 ### 登录态感知 广场页面游客可以完整浏览，但以下操作需要登录： - 点赞、收藏、分享（分享本身可以不登录，但计数写入需要） - 发表评论 - 关注创作者 触发时弹出引导注册/登录浮层，不跳转页面（不打断浏览体验）。 ### 水印入口 每个帖子详情页底部 Footer 固定展示： ``` 用 MindSpace 制作 → [立即免费体验] ``` 点击跳转到 MindSpace 注册页，URL 附带 UTM 参数： ``` https://go.tkmind.cn/?utm_source=plaza&utm_medium=footer&utm_campaign=post_watermark&ref={post_id} ``` ### 分享 分享按钮提供三种方式： 1. 复制链接（`/plaza/p/{id}`） 2. 生成分享图片（封面 + 标题 + 作者名，服务端生成 OG 图） 3. 微信分享（JS-SDK，需要公众号配置） --- ## SEO meta 规范 完整规范（Open Graph、JSON-LD、canonical、robots）以 [07-seo](./07-seo) 为**唯一权威来源**。前端实现时： - 每个 SSR 页面在 `generateMetadata` 中调用共享 helper（`lib/metadata.ts`），避免在组件内重复字段。 - [03-frontend](./03-frontend) 只描述页面结构与布局；修改 meta 时只改 `07-seo` 与 helper。 --- ## 响应式断点 | 断点 | 卡片列数 | 说明 | | --- | --- | --- | | < 640px | 2 列 | 手机竖屏 | | 640px – 1024px | 3 列 | 手机横屏 / 平板 | | > 1024px | 4 列 | 桌面 | 移动端底部导航固定展示：首页、分类、发布（跳转 MindSpace）、我的。 --- ## 性能目标 | 指标 | 目标 | | --- | --- | | 首页 LCP | < 2.5s | | 首页 INP | < 200ms | | 首页 CLS | < 0.1 | | 帖子详情首字节时间 | < 500ms | | 图片格式 | WebP，next/image 自动优化 | | 首屏帖子数 | 20 条，图片懒加载 |