terry/Arkie-Library-Frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
efc41fbd2ff2235d5f4d5446b528214b377b1570
Arkie-Library-Frontend/.unipi/docs/plans/2026-05-25-telegram-style-resource-stream-plan.md
TerryM a784f159fe feat: add telegram-style resource stream
2026-05-25 05:25:57 +08:00

12 KiB
Raw Blame History

title, type, date, workbranch, specs
title type date workbranch specs
Telegram-style Resource Stream — Implementation Plan plan 2026-05-25 feat/telegram-stream
.unipi/docs/specs/2026-05-25-telegram-style-resource-stream-design.md

Telegram-style Resource Stream — Implementation Plan

Overview

实现 /browse 与 /category/:slug 的 Telegram-style 消息流重构。前端先用 mock data 完成全部视觉与交互，等后端 /api/posts 系列接口 ready 后切换。同时收尾删除收藏功能与 ResourceDetail 详情页。

分支：feat/telegram-stream（在当前目录新建，不走 worktree）。完成后由 Terry 显式确认才 merge。

Sequencing

Task 1 (基础类型 + mock + utils)
        ↓
Task 2 (hooks) ─────────────────┐
                                │
Task 3 (overlays) ─────┐        │
                       ↓        │
                   Task 4 (bubbles)
                       ↓
                   Task 5 (stream 容器)
                       ↓
                   Task 6 (页面改写)
                       
Task 7 (清理收藏 / 详情页) ── 可与 1-5 并行，但合并到 Task 6 之前完成
Task 8 (验证 + 文档 + API 契约) ── 最后

依赖关键路径：1 → 2/3 → 4 → 5 → 6 → 8。Task 7 独立，建议早做以减少 imports 残留。

Tasks

  • unstarted: Task 0 — 创建分支

    • Description: 在当前目录创建并切到 feat/telegram-stream 分支
    • Dependencies: 无
    • Acceptance Criteria: git branch --show-current 输出 feat/telegram-stream；git status 干净
    • Steps:
      1. git status --short --branch 确认无未提交改动
      2. git checkout -b feat/telegram-stream
      3. 确认 .unipi/docs/specs/2026-05-25-telegram-style-resource-stream-design.md 与 .unipi/docs/plans/2026-05-25-telegram-style-resource-stream-plan.md 已在该分支

  • unstarted: Task 1 — 类型定义 + Mock data + 纯函数 utils

    • Description: 建立 Post / Attachment 类型，写覆盖 7 种 bubble 的 mock 样本，写 3 个无依赖纯函数 util
    • Dependencies: Task 0
    • Acceptance Criteria:
      • src/types/post.ts 导出 Post、Attachment、PostListResponse、PostScope
      • src/mocks/mockPosts.ts 至少 12 条 Post 覆盖：2 图片当文档 + 2 PDF/AI + 2 纯文本+链接 + 1 视频 + 2 单图 + 1 图+文 + 1 三图相册 + 1 七图相册；publishedAt 跨 ≥3 个不同日期
      • formatBytes(3549239) → "3.4 MB"（unit tests pass）
      • autolink("点 https://x.com 看") 返回 React 节点数组，链接处为 <a target="_blank" rel="noopener noreferrer">（unit tests pass）
      • fileIcon({ mime, filename }) 返回 { Icon, color }，PDF 红、AI 橙、PPT 红、图片走 thumbnail 不返回 Icon
      • npx tsc --noEmit 通过
    • Steps:
      1. 写 src/types/post.ts
      2. 写 src/components/messageStream/utils/formatBytes.ts + .test.ts
      3. 写 src/components/messageStream/utils/autolink.tsx + .test.tsx
      4. 写 src/components/messageStream/utils/fileIcon.ts
      5. 写 src/mocks/mockPosts.ts（图片用 picsum.photos 占位，视频用公开 sample mp4 + 一张占位 poster）
      6. 跑 npm test 与 npx tsc --noEmit

  • unstarted: Task 2 — Stream hooks（usePostStream + useGroupedByDay）

    • Description: 数据层抽象，mock/real 双模式 + 按日期分组
    • Dependencies: Task 1
    • Acceptance Criteria:
      • usePostStream({ scope, type, language }) 在 VITE_USE_MOCK_POSTS !== "false" 时从 MOCK_POSTS 过滤 + 倒序 + cursor 切片（每页 20）+ 200ms 假延迟
      • 真接口分支调用 getJSON</api/posts?...>（占位即可，后端未 ready 时不会走到）
      • 返回 { items, isLoading, error, hasMore, loadMore, reset }
      • useGroupedByDay(posts, lang) 返回 Array<{ dayLabel: string; items: Post[] }>，按本地时区日期分组，dayLabel 通过 Intl.DateTimeFormat 按 lang 切换（zh-TW/zh-CN/en）
      • 单元测试：useGroupedByDay 在跨天数据上分出正确组数
    • Steps:
      1. 写 src/components/messageStream/hooks/usePostStream.ts
      2. 写 src/components/messageStream/hooks/useGroupedByDay.ts + .test.ts
      3. 在 .env.example 加 VITE_USE_MOCK_POSTS=true 注释
      4. 跑 npm test 与 npx tsc --noEmit

  • unstarted: Task 3 — Overlay 基础设施（ImageLightbox + VideoPlayer）

    • Description: 全屏画廊与视频播放器，portal 渲染，单一入口 context
    • Dependencies: Task 1
    • Acceptance Criteria:
      • <ImageLightboxProvider> 包在 App 根，暴露 useLightbox() → openLightbox(images, startIndex)
      • ImageLightbox 支持：左右切换（按钮 + 键盘 ← → + 触屏左右滑）、ESC/点遮罩关闭、右上角下载按钮
      • VideoPlayer 支持：全屏遮罩 + <video controls autoPlay>、接 currentTime 参数避免重新加载、ESC/点遮罩关闭
      • 两个 overlay 在手机端不溢出、不被底部 nav 遮挡
      • npx tsc --noEmit 通过
    • Steps:
      1. 写 src/components/messageStream/overlays/ImageLightbox.tsx + Provider/Context
      2. 写 src/components/messageStream/overlays/VideoPlayer.tsx
      3. 在 App.tsx / 根布局挂 Provider
      4. 手动验证：在 dev console 临时调用 openLightbox 看是否正确呈现

  • unstarted: Task 4 — Bubble 子组件（6 个 + 分发器）

    • Description: 按截图实现 6 种气泡 + MessageBubble 分发
    • Dependencies: Task 1, Task 3
    • Acceptance Criteria:
      • FileDocBubble 处理 kind: "document"：
        • 若 mime.startsWith("image/") → 左侧用 thumbnailUrl 缩略 + ↓ 覆盖；右侧 filename.ext + size（截图 1）
        • 否则 → 左侧蓝圆 ↓ 图标（按 mime 取色）+ 右侧 filename + size（截图 2）
      • TextBubble 渲染 text，调 autolink（截图 3）
      • VideoBubble 初始显示 posterUrl + ▶️ + 时长，第一次点 inline <video controls autoPlay>，第二次点（已播放）调 openVideoPlayer（截图 4）
      • ImageBubble 单张图，点击调 openLightbox([att], 0)（截图 5）
      • ImageWithTextBubble 单图 + 下方文本（autolink）（截图 6）
      • AlbumBubble 2-4 格 grid，间距 2px；attachments.length > 4 时第 4 格 bg-black/45 backdrop-blur-sm 覆盖 +N；点任一格调 openLightbox(images, index)（截图 7）
      • MessageBubble 实现 spec §4 的 pickBubble 分发，右下角绝对定位时间戳 text-[11px] text-neutral-500
      • 所有 bubble 容器：rounded-2xl bg-ark-panel p-3（文本气泡 px-4 py-2.5），左对齐，无头像
      • npx tsc --noEmit 通过
    • Steps:
      1. 写 MessageBubble.tsx（含 pickBubble）
      2. 写 bubbles/TextBubble.tsx
      3. 写 bubbles/FileDocBubble.tsx
      4. 写 bubbles/ImageBubble.tsx
      5. 写 bubbles/ImageWithTextBubble.tsx
      6. 写 bubbles/AlbumBubble.tsx
      7. 写 bubbles/VideoBubble.tsx
      8. 在 dev 中临时挂一个 demo route 跑 MOCK_POSTS 全量渲染，目视检查 7 张截图对照

  • unstarted: Task 5 — Stream 容器 + FilterChips + DaySeparator

    • Description: 顶层组件接管 fetch、分组、无限滚动、sticky 筛选
    • Dependencies: Task 2, Task 4
    • Acceptance Criteria:
      • FilterChips：sticky top，横向滚动 overflow-x-auto whitespace-nowrap，类型 chips（all/image/video/ppt/pdf/text/link/archive，沿用 typeFilterLabel）+ 语言 chips（all/zh-TW/zh-CN/en），改变时 reset cursor 并同步 URL ?type=&language=
      • DaySeparator：胶囊样式，居中
      • MessageStream：
        • 接 scope: { kind: "all" } | { kind: "category", slug: string }
        • 调用 usePostStream + useGroupedByDay
        • 用 IntersectionObserver 监听底部 sentinel，触发 loadMore（loadingRef 守护避免重复）
        • 容器：手机 max-w-full px-3 mx-auto，md+ max-w-[640px] mx-auto
        • 空状态用 t("noResults")，错误用红色 inline 横幅 + 重试按钮
      • npx tsc --noEmit 通过
    • Steps:
      1. 写 FilterChips.tsx
      2. 写 DaySeparator.tsx
      3. 写 MessageStream.tsx
      4. 在 dev demo route 挂 <MessageStream scope={{ kind: "all" }} /> 验证滚动 + 筛选 + 分组

  • unstarted: Task 6 — 重写 CategoryPage 与 Browse

    • Description: 两个页面瘦身为单一组件调用
    • Dependencies: Task 5, Task 7
    • Acceptance Criteria:
      • src/pages/CategoryPage.tsx：仅渲染分类标题 + <MessageStream scope={{ kind: "category", slug }} />，行数 < 30
      • src/pages/Browse.tsx：仅渲染页面标题 + <MessageStream scope={{ kind: "all" }} />，行数 < 30；不再读 sort / tag / page 参数
      • 排序 tabs 全部去掉
      • 移除对 ResourceCard / ResourceListFooter 的 import
      • App.tsx 路由保持 /browse 与 /category/:slug 不变
      • npx tsc --noEmit 通过
    • Steps:
      1. 改写 CategoryPage.tsx
      2. 改写 Browse.tsx
      3. 跑 dev server 在 /browse 与 /category/<slug> 验证

  • unstarted: Task 7 — 移除收藏功能 + ResourceDetail

    • Description: 整套清理
    • Dependencies: Task 0（可与 Task 1-5 并行）
    • Acceptance Criteria:
      • 删除文件：src/pages/FavoritesPage.tsx、src/pages/ResourceDetail.tsx、src/components/ResourceCard.tsx、src/components/ResourceListFooter.tsx
      • App.tsx 移除 /favorites 路由；/r/:id 改为新组件 PostRedirect（mock 模式下从 MOCK_POSTS 找 slug；找不到 → navigate /browse）
      • src/api.ts 移除 postFavoriteDelta
      • 全代码无 postFavoriteDelta / FavoritesPage / ResourceDetail / ResourceCard / ResourceListFooter 引用
      • Home 中的 /favorites 入口（如有）移除
      • src/i18n.tsx 移除 favorites / addFavorite / removeFavorite 等收藏 key（三语言同步）
      • npx tsc --noEmit 通过（无 unused / 未引用错误）
    • Steps:
      1. grep -rn "postFavoriteDelta\|FavoritesPage\|ResourceDetail\|ResourceCard\|ResourceListFooter\|/favorites\|/r/:id" src/ 列出所有引用点
      2. 写 src/pages/PostRedirect.tsx，挂到 /r/:id 路由
      3. 删除 4 个文件 + 修改 App.tsx + api.ts + i18n.tsx
      4. 再 grep 一次确认清零
      5. npx tsc --noEmit

  • unstarted: Task 8 — 验证 + 文档 + API 契约抽出

    • Description: 全量验证 + 给后端的接口文档
    • Dependencies: Task 6, Task 7
    • Acceptance Criteria:
      • npx tsc --noEmit 通过
      • npm run format:check 通过（若不通过先 npm run format）
      • npm test 全绿
      • npm run build 成功
      • 手动视觉验证：Chrome DevTools iPhone 14 Pro 视口逐一对照 7 张参考截图
      • 新增 .unipi/docs/specs/2026-05-25-posts-api-contract.md：从主 spec §1-§2 抽出后端需要的所有内容（Post/Attachment schema、6 个 endpoint、删除清单、迁移要求）
      • 更新 README.md 增加 VITE_USE_MOCK_POSTS 段落
      • 不 commit、不 push（等 Terry 显式确认）
    • Steps:
      1. 跑全套检查命令
      2. dev server 手机视口检查
      3. 写 API 契约文档
      4. 改 README
      5. 报告完成，等 Terry 审阅与 commit 指令

Risks

  • mock 数据视觉与真实数据偏差：mock 用 picsum 占位图，可能掩盖真实图片不同宽高比的边界情况。缓解：mockPosts 中包含横图 / 竖图 / 接近正方形三种比例样本。
  • video poster 在 mock 模式不易获取：用一张本地 SVG 占位即可，避免依赖外部链接。
  • i18n 删除收藏 key 后未使用的引用：tsconfig 的 noUnusedLocals 不覆盖 i18n key 的字符串引用，需手动 grep。
  • PostRedirect 在真接口模式下的实现：当前先写 mock 分支，真接口分支 TODO 注释标明等 /api/posts/:id ready 后补。
  • infinite scroll + URL 同步：用户改 filter chip 时既要 reset cursor 又要更新 URL，注意避免 setSearchParams 触发额外 effect 循环。
  • 后端最终 schema 与本 spec 偏差：如有偏差，必须先回 spec 改契约，再调前端类型，避免散点修改。

Out of Scope（本 plan 不涵盖，遵循 spec）

  • Home 页布局调整
  • Admin 后台 Post 编辑器
  • 真实后端 API 实现 + 数据迁移
  • 长按菜单 / 评论 / Reaction
  • 桌面端多列布局
  • SEO 优化
Reference in New Issue View Git Blame Copy Permalink