Arkie-Library-Frontend/.unipi/docs/specs/2026-05-25-telegram-style-resource-stream-design.md

---
title: "Telegram-style Resource Stream（资料分类查看全部 UI 重构）"
type: brainstorm
date: 2026-05-25
---

# Telegram-style Resource Stream

## Problem Statement

当前"查看全部"打开的资料列表（`/browse` 和 `/category/:slug`）使用统一的卡片网格，无法表达"admin 上传的内容本质是不同类型的消息"（一张图、一段文字+链接、一个视频、一个 PDF、4+ 张图相册等）。手机端用户体验偏弱，缺少 Telegram 那种按类型差异化呈现的直观感受。

本次重构目标：把 `/browse` 与 `/category/:slug` 改成**单列、按时间倒序、按日期分组、按上传类型差异化渲染**的 Telegram-style 消息流，手机优先，保留 ARK 既有色系（深底 + 金色高亮）。

> 后端 endpoint 尚未实现。本次前端先用 mock data 完成视觉与交互，验收后再交接 API 契约给后端。

## Context

### 当前实现

- `src/pages/Home.tsx`：分类 section 头部"查看全部" → `/browse`；分类卡片 → `/category/<slug>`。
- `src/pages/Browse.tsx`（221 行）：含排序 tabs（最新/推荐/热门/发布）+ 类型 chips + 语言 chips + tag 过滤 + 分页（每页 24）。
- `src/pages/CategoryPage.tsx`（156 行）：含类型 chips + 语言 chips + 分页。
- `src/pages/ResourceDetail.tsx`（229 行）：`/r/:id` 资源详情独立路由。
- `src/pages/FavoritesPage.tsx` + `postFavoriteDelta`：收藏功能。
- `src/components/ResourceCard.tsx`：统一卡片，不区分资源类型。
- `Resource` schema（`src/api.ts`）扁平：1 个 resource = 1 个文件（`coverImage` / `fileUrl`），无 attachments 数组。

### 设计参考（用户提供 7 张 Telegram 截图）

1. 图片当文档上传：缩略图 + ↓ + filename.ext + size + 右下时间，无头像、无 reaction。
2. PDF / AI / PPT 等文档：蓝圆 ↓ + filename + size。
3. 纯文本 + 链接：`https://...` 自动识别为可点链接。
4. 视频：海报 + ▶️，第一次点 inline 播放预览，第二次点全屏；下方可有 admin 写的说明文字。
5. 单张图片：直接显示，点全屏。
6. 图片 + 文字：图片上方/下方文字，文字内链接 autolink。
7. 4+ 张图相册：1-4 格 grid，第 4 张模糊 + `+N`；点开后全屏画廊。

## Chosen Approach

**方案 A：自建 `MessageStream` + 多态 `MessageBubble` 家族 + Mock-data layer**

- 新建一个 `MessageStream` 容器组件，被 `Browse.tsx` 和 `CategoryPage.tsx` 共用，差异通过 `scope` props 注入。
- `MessageBubble` 内根据 `Post.attachments` 的形状分发到 6 个子组件（FileDoc / Text / Video / Image / ImageWithText / Album）。
- 全屏交互（图片画廊 / 视频全屏）走 portal overlay。
- 数据层用 `usePostStream` hook 抽象，默认走 `src/mocks/mockPosts.ts`（受 `VITE_USE_MOCK_POSTS` 控制），后端 ready 后切换为真 API。
- 同时**收尾**收藏功能与详情页：删除 `/favorites`、`/r/:id`、heart 按钮、`postFavoriteDelta`。

## Why This Approach

### 拒绝方案 B（聊天 UI 库 `@chatscope/chat-ui-kit-react` 等）

- 默认主题与 ARK 深底+金色严重冲突，改主题成本 ≈ 自己写。
- 不支持"4+ 图相册 +N 模糊"自定义。
- 增加包体积与灰盒 bug 风险。

### 拒绝方案 C（重样 `ResourceCard`）

- 当前卡片统一渲染，无法满足"按类型差异化"（视频内嵌播放器 vs 多图相册 vs 文本+链接）。
- 改动表面但不达 Telegram 风格。

### 拒绝其他子选项

- **保留排序 tabs**：Telegram 流天然按时间倒序，多余 tabs 破坏隐喻。Home 页仍保留"官方推荐 / 最新更新" section 作为入口。
- **保留收藏功能在列表/详情页**：用户明确要求"不需要 reaction"，且收藏与 Telegram 隐喻不符；整体下线最干净。
- **保留 `ResourceDetail` 作 fallback**：所有交互（下载 / 全屏 / 链接）都能就地完成，独立详情页冗余；老 `/r/:id` 改 301 重定向到 `/category/<slug>#post-<id>` 锚点。
- **`kind` 枚举铺开**：后端枚举膨胀难维护；前端按 `mime` / 文件后缀做细分图标更灵活。

## Design

### 1. 数据模型（前端使用 + 后端接口契约）

```ts
type Post = {
  id: string;
  categoryId: number;
  categorySlug: string;
  language: string;             // zh-TW | zh-CN | en
  text?: string;                // 可选；纯文本/图说，前端自动识别 https 链接
  attachments: Attachment[];    // 0~N；text-only post 时为 []
  isRecommended: boolean;
  publishedAt: string;          // ISO，用于排序 + 日期分组
  updatedAt: string;
};

type Attachment = {
  id: string;
  kind: "image" | "video" | "document";
  url: string;
  mime: string;                 // image/jpeg | application/pdf | video/mp4 | ...
  filename: string;             // "ARK项目一图读懂-01.jpg"
  sizeBytes: number;
  width?: number;
  height?: number;
  durationSec?: number;         // video 专用
  posterUrl?: string;           // video 海报
  thumbnailUrl?: string;        // image 缩略
};
```

关键约定：
- `kind: "document" + mime.startsWith("image/")` = 图片当文档上传（截图 1）。
- `kind: "image"` = 图片当图片呈现（截图 5、6、7）。该开关在 admin 上传 UI 决定，传到后端落库。
- 多图相册 = 一个 Post 带多个 `kind: "image"` 的 attachments。
- 图片+文字 = Post 同时有 `text` 与 attachments。
- 纯文本+链接 = Post 仅有 `text`，`attachments: []`。

### 2. 后端 API 契约（移交给后端）

| 方法 | 路径 | 用途 |
|---|---|---|
| GET | `/api/posts?category=<slug>&lang=&type=&language=&cursor=&limit=20` | 分类内消息流 |
| GET | `/api/posts?lang=&type=&language=&cursor=&limit=20` | 全部消息流（`/browse`） |
| GET | `/api/posts/recommended?lang=&limit=` | Home 推荐 section |
| GET | `/api/posts/latest?lang=&limit=` | Home 最新 section |
| GET | `/api/posts/:id` | 单条（用于老 `/r/:id` 301 重定向落地，前端拿到 `categorySlug` 后跳锚点） |
| GET | `/api/categories` | 不变 |
| POST/PUT/DELETE | `/api/admin/posts/...` | Admin CRUD，支持多附件 + 文本 + "图片是否以文档呈现"开关 |

废弃：
- `/api/resources/:id/favorite`
- 老 `/api/resources*` 系列保留过渡期，由后端写迁移脚本：每个老 Resource → 一个 Post。

返回结构：`{ items: Post[], nextCursor?: string }`，cursor 由后端不透明字符串提供。

`type` 参数语义：`all` / `image` / `video` / `pdf` / `ppt` / `text` / `link` / `archive`。一个 Post 命中条件 = `attachments[*].mime` 或 `text` 满足；具体由后端定义。

### 3. 组件结构

```
src/pages/
  CategoryPage.tsx           ← 重写：<MessageStream scope={{ kind:'category', slug }} />
  Browse.tsx                 ← 重写：<MessageStream scope={{ kind:'all' }} />

src/components/messageStream/
  MessageStream.tsx          顶层：fetch + 无限滚动 + 日期分组 + sticky filter chips
  FilterChips.tsx            类型 + 语言 chips（横向滚动，sticky top）
  DaySeparator.tsx           "2 月 27 日" 胶囊
  MessageBubble.tsx          单条 Post 容器：决定子组件 + 右下角时间戳
  bubbles/
    FileDocBubble.tsx        截图 1 + 2：文档（图片当文档 / pdf / ai / ppt / docx）
    TextBubble.tsx           截图 3：纯文本 + autolink
    VideoBubble.tsx          截图 4：海报 + ▶️，先 inline 后全屏
    ImageBubble.tsx          截图 5：单张图片
    ImageWithTextBubble.tsx  截图 6：图片 + 文本 + autolink
    AlbumBubble.tsx          截图 7：2-4 格 grid，4+ 时第 4 格模糊 + `+N`
  overlays/
    ImageLightbox.tsx        全屏画廊（左右滑、缩放、关闭、下载）
    VideoPlayer.tsx          全屏视频播放器
  hooks/
    usePostStream.ts         cursor 分页 + IntersectionObserver；mock/real 切换
    useGroupedByDay.ts       按 publishedAt 本地日期分组
  utils/
    autolink.tsx             文本中 https?://... → <a target="_blank" rel="noopener">
    fileIcon.ts              按 mime/扩展名返回图标 + 颜色
    formatBytes.ts           3,549,239 → "3.5 MB"

src/mocks/
  mockPosts.ts               覆盖 7 种 bubble 类型的样本数据（图片用 picsum 占位或本地）
```

### 4. Bubble 分发逻辑

```ts
function pickBubble(post: Post) {
  const a = post.attachments;
  if (a.length === 0) return TextBubble;
  if (a.length >= 2 && a.every(x => x.kind === "image")) return AlbumBubble;
  const only = a[0];
  if (only.kind === "video") return VideoBubble;
  if (only.kind === "image") {
    return post.text ? ImageWithTextBubble : ImageBubble;
  }
  return FileDocBubble;   // document（含图片当文档：内部用 thumbnail 替代蓝圆图标）
}
```

### 5. 移动端布局规范

- 容器宽度：手机 `max-w-full px-3`；md+ `max-w-[640px] mx-auto`。桌面端不做多列，保持单列聊天流（左右大留白）。
- 气泡：`rounded-2xl bg-ark-panel`，左对齐，无头像，内边距 `p-3`（文本 `px-4 py-2.5`）。
- 时间戳：右下角 `text-[11px] text-neutral-500`，绝对定位。
- 文档下载按钮：圆形 36×36，金色 `bg-ark-gold` + 黑色 ↓。
- Day separator：胶囊 `rounded-full bg-ark-panel/70 backdrop-blur px-3 py-1 text-xs text-neutral-400`，居中、sticky 在 FilterChips 下。
- 多图 grid：宽度 100%，2×2，间距 2px；4+ 时第 4 格 `relative` 叠 `bg-black/45 backdrop-blur-sm` + `+N` 居中文字。
- FilterChips 容器：`sticky top-0 z-10 bg-ark-bg/90 backdrop-blur` + 横向滚动 `overflow-x-auto whitespace-nowrap`。

### 6. 交互

| 交互 | 行为 |
|---|---|
| 点击文档下载按钮 | `window.open(attachment.url, "_blank")` 触发浏览器下载 |
| 点击单张图片 | 打开 `ImageLightbox`（单图） |
| 点击相册任一图 / `+N` | 打开 `ImageLightbox`，可左右切换 |
| 点击视频海报 | 第一次：bubble 内 `<video controls autoPlay>` inline 播放 |
| 点击播放中的视频 | 打开 `VideoPlayer` 全屏 overlay |
| 文本中的链接 | `target="_blank" rel="noopener noreferrer"` 新标签打开 |
| 滚动到底部 | IntersectionObserver 触发下一页 cursor 拉取 |
| 筛选 chips 变化 | 重置 cursor，重新拉取；同步 URL `?type=&language=` |
| 长按气泡 | 暂不做，列入 Open Questions |

### 7. Mock data 层

`src/mocks/mockPosts.ts` 导出 `MOCK_POSTS: Post[]`，至少包含：

- 2 条"图片当文档"（不同 mime：jpg、png）
- 2 条文档（pdf、ai）
- 2 条纯文本+链接（含中文 + 多链接 + emoji）
- 1 条视频（带 posterUrl + duration）
- 2 条单图（不同宽高比）
- 1 条图+文字
- 1 条 3 图相册
- 1 条 7 图相册（验证 `+N` 行为）
- 跨多天的 `publishedAt`，验证 DaySeparator

`usePostStream` 行为：

```ts
const useMock = import.meta.env.VITE_USE_MOCK_POSTS !== "false";
if (useMock) {
  // 1. 按 scope.slug / type / language 过滤 MOCK_POSTS
  // 2. 按 publishedAt 倒序
  // 3. 按 cursor（数字 offset 字符串）切 20 条
  // 4. setTimeout 200ms 模拟延迟
  // 5. 返回 nextCursor = offset+20 或 undefined
} else {
  // fetch /api/posts?... 真接口
}
```

切真接口时只需在部署环境设 `VITE_USE_MOCK_POSTS=false`（或干脆删 mock 分支）。

### 8. 锚点 + 分享

- 每个 bubble 渲染为 `<article id="post-${post.id}">`。
- 老路由 `/r/:id` 改为一个轻量重定向组件：fetch `/api/posts/:id` 拿到 `categorySlug` → `navigate(/category/${slug}#post-${id}, { replace: true })` → `scrollIntoView`。
- Mock 模式下从 `MOCK_POSTS` 找。

### 9. 移除清单

文件：
- `src/pages/ResourceDetail.tsx`
- `src/pages/FavoritesPage.tsx`
- `src/components/ResourceCard.tsx`
- `src/components/ResourceListFooter.tsx`

代码：
- `postFavoriteDelta` 及所有调用点
- i18n keys：`favorites`, `addFavorite`, `removeFavorite` 等收藏相关
- Home 中的 `/favorites` 入口

路由：
- `/favorites`：删除
- `/r/:id`：保留为轻量重定向

### 10. 测试 / 验证策略

- 视觉验证：本地 `npm run dev`，手机模拟器（Chrome DevTools iPhone 14 Pro 视口）逐一对照 7 张截图。
- 单元测试：`pickBubble` 分发逻辑、`autolink` 正则、`formatBytes`、`useGroupedByDay`。
- 类型检查：`npx tsc --noEmit`（项目 strict）。
- 格式化：`npm run format`。
- 删除后回归：确认 `/favorites` 与 `/r/:id` 老链接不报 404 而是合理跳转或 410。

### 11. 风险与缓解

- **真接口 schema 与 mock 不一致**：spec 是合同；后端实现时若需偏离，必须先回来改 spec。前端 hook 内 `Post` 类型从 `src/types/post.ts` 单一来源导入。
- **`+N` 相册和单图 lightbox 的状态管理混乱**：用 React Context（`<ImageLightboxProvider>`）暴露 `openLightbox(images, startIndex)` 单一入口，所有 bubble 调它。
- **视频 inline → 全屏切换的状态丢失**：全屏 overlay 接 `currentTime` 参数，避免重新加载。
- **scroll restoration**：cursor 分页页内来回滑动时 IntersectionObserver 容易重复触发；用 `loadingRef` 守护。

## Implementation Checklist

> 全部项已被 `.unipi/docs/plans/2026-05-25-telegram-style-resource-stream-plan.md` 覆盖。

- [x] 定义 `src/types/post.ts`：`Post`、`Attachment`、`PostListResponse`
- [x] 创建 `src/mocks/mockPosts.ts`：覆盖 7 种 bubble 类型 + 跨日期样本
- [x] 创建 `src/components/messageStream/hooks/usePostStream.ts`（mock + real 双模式 + cursor 分页 + IntersectionObserver）
- [x] 创建 `src/components/messageStream/hooks/useGroupedByDay.ts`
- [x] 创建 `src/components/messageStream/utils/autolink.tsx`
- [x] 创建 `src/components/messageStream/utils/fileIcon.ts`
- [x] 创建 `src/components/messageStream/utils/formatBytes.ts`
- [x] 创建 `FilterChips.tsx`（sticky + 横向滚动）
- [x] 创建 `DaySeparator.tsx`
- [x] 创建 `MessageBubble.tsx`（含 `pickBubble` 分发）
- [x] 创建 `bubbles/FileDocBubble.tsx`（图片当文档 + pdf/ai/ppt）
- [x] 创建 `bubbles/TextBubble.tsx`（autolink）
- [x] 创建 `bubbles/VideoBubble.tsx`（inline 播放 + 全屏触发）
- [x] 创建 `bubbles/ImageBubble.tsx`
- [x] 创建 `bubbles/ImageWithTextBubble.tsx`
- [x] 创建 `bubbles/AlbumBubble.tsx`（2-4 grid + `+N`）
- [x] 创建 `overlays/ImageLightbox.tsx` + `ImageLightboxProvider` context
- [x] 创建 `overlays/VideoPlayer.tsx`
- [x] 创建 `MessageStream.tsx` 顶层组件
- [x] 重写 `src/pages/CategoryPage.tsx` 为 `<MessageStream scope={{ kind:'category', slug }} />`
- [x] 重写 `src/pages/Browse.tsx` 为 `<MessageStream scope={{ kind:'all' }} />`
- [x] 删除 `src/pages/ResourceDetail.tsx`，将 `/r/:id` 改为重定向组件（mock 模式下从 `MOCK_POSTS` 查）
- [x] 删除 `src/pages/FavoritesPage.tsx`、`src/components/ResourceCard.tsx`、`src/components/ResourceListFooter.tsx`
- [x] 移除 `postFavoriteDelta` 及全部调用点
- [x] 移除 `App.tsx` 中 `/favorites` 路由 + Home 入口
- [x] 清理 i18n favorites 相关 keys
- [x] 单元测试：`pickBubble`、`autolink`、`formatBytes`、`useGroupedByDay`
- [x] 视觉对照 7 张参考截图（iPhone 14 Pro 视口）
- [x] 运行 `npx tsc --noEmit && npm run format:check && npm test`
- [x] 文档：在 README 注明 `VITE_USE_MOCK_POSTS` 用法
- [x] 交付后端 API 契约文档（本 spec 的 §2 部分单独抽出 markdown 给后端）

## Open Questions

- **长按 / 右键菜单**：是否需要"复制链接"、"举报"、"分享"？v2 决定。
- **`type` 筛选语义边界**：一个 Post 含多种 attachment 时（图+视频混合，目前 mock 不出现），`type=video` 命中规则由后端定，前端按返回展示即可。
- **空状态文案**：消息流为空时显示什么？目前沿用 `t("noResults")`。
- **错误重试**：网络失败时是否提供"重试"按钮？建议下方加一个 inline 重试条。
- **视频自动暂停**：滚出视口时是否自动暂停？建议做，体验更顺。
- **i18n 时间戳格式**：是否需要适配繁体/简体/英文不同的日期分组格式？沿用 `Intl.DateTimeFormat` 按 `lang` 切换。
- **SEO**：删除 `/r/:id` 详情页后，搜索引擎抓取深度受影响吗？目前站点未做强 SEO，可忽略；如需保留可让 `/r/:id` 渲染服务端可解析的 `<noscript>` 摘要后再 JS 重定向。
- **Admin 上传 UI 改造**：本次只覆盖前台浏览端；admin 端 Post 编辑器（多附件 + 文本 + 图片呈现方式开关）需要单独的 spec / 任务。

## Out of Scope

- Home 页面布局调整（分类卡片网格、推荐/最新 section 保持不变）
- Admin 后台 UI 改造（单独 spec）
- 真实 API 实现（后端工作）
- 后端数据迁移脚本
- 长按菜单、举报、分享等社交功能
- 评论 / Reaction
- 离线缓存 / Service Worker
- 桌面端多列布局