哈基哈米前端页面实现文档

一、文档目标

为开发、设计与测试提供完整、可落地的页面清单与实现细节，确保：

  1. 所有需求文档（PRD）中的用户故事都有对应页面/组件；
  2. 路由、布局、状态管理、异常处理、性能优化一次说明到位；
  3. 多人协作时可按模块并行，减少沟通成本。

技术前提：Next.js 14（App Router）+ TypeScript + TailwindCSS + Zustand + SWR。

二、全局约定

项 规则
路由风格 RESTful + 语义化，如 /chart/week，/song/[id]
布局分级 ① 根布局：html/head/font；② 业务布局：Header+Footer+Nav；③ 子布局：后台双栏
状态管理 客户端全局：Zustand（用户、播放、主题）；服务端状态：SWR；局部：useState
组件分级 ui/*（原子）→ composite/*（分子）→ feature/*（业务）→ page/*
错误处理 页面级 error.tsx + 全局 not-found.tsx + API 异常统一封装
性能 ① 图片优先 WebP + priority 属性；② 虚拟滚动（列表>100）；③ 路由懒加载；④ 音频预加载 30s
SEO 服务端渲染 + generateMetadata + JSON-LD；动态 OG 图（@vercel/og）
无障碍 按钮 aria-label；键盘导航；色彩对比≥4.5:1
主题 默认/system/light/dark 三模式，CSS 变量切换
国际化 文案全抽离 locales/zh-CN/*.json，Key 按模块前缀，如 common.play

三、页面总览（路由清单）

编号 路由 页面名称 简述 状态*
P01 / 首页 随机推荐+周榜入口+最新投稿 ✅
P02 /song/[id] 歌曲详情 播放、收藏、评论、原曲、分享 ✅
P03 /search 搜索结果 列表+筛选 sidebar ✅
P04 /chart/week 哈基周金曲 本期+历届 ✅
P05 /chart/month 本月榜单 无翻唱/AI 过滤 ✅
P06 /upload 投稿页 分步向导+草稿箱 ✅
P07 /user/[uid] 用户主页 投稿/收藏/获赞/哈气金 ✅
P08 /me 我的中心 个人资料、播放历史、草稿、消息 ✅
P09 /login 登录 邮箱+OAuth ✅
P10 /register 注册 同登录页 Tab ✅
P11 /404 未找到 全局 ✅
P12 /500 异常 全局 ✅
A01 /admin 后台入口 Dashboard ✅
A02 /admin/song 歌曲管理 批量审核、修改、下架 ✅
A03 /admin/user 用户管理 封禁、角色、积分 ✅
A04 /admin/chart 榜单运营 手动微调、发布 ✅
A05 /admin/incentive 哈气金 活动创建、发放记录 ✅
A06 /admin/stats 数据看板 图表、导出 ✅

四、页面原型 & 组件拆解

P01 首页 /

┌────────────────────────────┐
│  Header (Nav+Search+User)  │
├────────────────────────────┤
│  Hero 轮播（本周金曲*3）    │
│  ───────────────           │
│  ▶ 随机推荐（10 首）↻      │
│  ▶ 最新投稿（10 首）→更多  │
│  ▶ 表情包入口              │
│  ▶ 社群入口（QQ/频道）      │
├────────────────────────────┤
│  Footer                    │
└────────────────────────────┘

关键组件：