Files
perler-lab/docs/NAV-ALIGNMENT.md

197 lines
17 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# NAV-ALIGNMENT — PERLER LAB 导航结构对齐 pixel-beads 落地决策方案
> **任务**: T-090 导航结构对齐
> **角色**: PM-Agent
> **日期**: 2026-08-14
> **输入依据**:
> - `D:\拼豆\competitor-analysis\pixelbeads-nav-crawl.md`(Spider 实测:桌面 9 项 / 移动端分组抽屉 / 语言 7 项)
> - `D:\拼豆\competitor-analysis\pixelbeads-zh-detail.md`(§1.3 主导航、§1.4 页脚、差距矩阵)
> - 我方现状: `perler-lab/src/components/Nav.tsx`(2 项导航)、`src/App.tsx`(单页 #workspace + /chibi 路由)、`src/i18n/messages/{zh-CN,en}.ts`
> - 看板: `D:\拼豆\taskboard\taskboard.js`(T-090 已认领)
---
## 0. 结论速览
| 维度 | 结果 |
|---|---|
| **对齐项** | 4 项(首页 / 生成器 / 图片转像素画(合并) / 主题拼豆 dropdown) |
| **暂缓项** | 4 项(拼豆创作 / 作品展示 / 图纸库 / 帮助) |
| **不做项** | 1 项(客户端 apps) |
| **新版桌面导航** | 7 项(首页 · 图片转拼豆 · AI拼豆专区[PRO] · 主题拼豆▾ · 作品展示 · 图纸库 · 帮助)+ 右侧保留 语言切换 / 代理合作 / 状态徽标 |
| **移动端** | 参考竞品分组抽屉:主导航组 + 主题拼豆组 + 工具组 + 语言/代理 |
| **P0 任务条数** | 3 条(全部为纯导航改造,零新页面零数据依赖) |
| **P1 任务条数** | 3 条(新建 /showcase、/library、/help 页面) |
| **P2 任务条数** | 2 条(主题下拉深链 chibi 分类、帮助中心子页) |
> 核心原则:**导航先行、页面跟上**。P0 阶段只改 `Nav.tsx` + i18n + CSS,不引入任何新路由,把对齐项 4 项 + 暂缓项 3 项的**占位入口**先立起来(暂缓项指向占位区块,点击提示"建设中"),避免"裸导航点空页面"。P1 阶段补真实页面后撤下占位提示。
---
## 1. 对比表:pixel-beads 桌面 9 项 vs 我方现状
> pixel-beads 依据 `pixelbeads-nav-crawl.md` §1.2(zh 站 Playwright 实测 9 项);我方依据 `Nav.tsx` / `App.tsx` 实读。
| # | pixel-beads 桌面项 | 竞品 URL | 我方现状 | 差异标注 |
|---|---|---|---|---|
| 1 | 首页 | `/zh` | 单页顶部 `#top`(logo → `#top`,无独立首页项) | ⚠️ 我方单页,无独立首页路由;logo 承担首页锚点 |
| 2 | 拼豆图纸生成器 | `/zh/perler-bead-pattern-generator` | ✅ 已覆盖:`nav.toPattern`「图片转拼豆」→ `#workspace` 生成器 | ≈ 同名同义项已存在 |
| 3 | 拼豆创作 | `/zh/perler-bead-art` | ❌ 无(品牌主题页不存在) | 缺失:竞品为品牌故事/教程聚合页 |
| 4 | 图片转像素画 | `/zh/image-to-pixel-art` | ⚠️ 无独立工具页,但 `#workspace` 就是"图片→像素→拼豆"一体管线 | 竞品拆独立工具页;我方合并承载 |
| 5 | 作品展示 | `/zh/showcase` | ❌ 无(无社区作品库) | 缺失:竞品有 8 作品/分类/投稿入口 |
| 6 | 主题拼豆(dropdown) | trigger → 圣诞/宝可梦 2 子项 | ⚠️ 无 dropdown,但有 `/chibi` AI 专区(5 大分类可复用为主题入口) | 竞品按节日/IP 分组;我方 AI 专区分类天然适配 |
| 7 | 图纸库 | `/zh/perler-bead-pattern` | ❌ 无(有 `share-codec.ts` 分享码机制,可作种子数据源) | 缺失:竞品为独立列表页 |
| 8 | 客户端 | `/zh/apps`(含 3 端下载页) | ❌ 无(纯 Web,无客户端产品) | 竞品有 Chrome/Android/iOS 三端;我方无 |
| 9 | 帮助 | `/zh/help`(含分工具子页) | ❌ 无(无独立帮助页) | 缺失:竞品有 /help 中心 + 分工具子页 |
> 补充:竞品移动端另有「工具/指南」分组,暴露 7 个 sitemap 外页面(像素画编辑器、照片转像素、我的世界指南等),见 `pixelbeads-nav-crawl.md` §2.2——**我方暂不参考这些泛化工具页**(偏离核心拼豆生成定位)。
---
## 2. 逐项落地决策(9 项)
| # | pixel-beads 项 | 决策 | 理由 |
|---|---|---|---|
| 1 | **首页** | **对齐** | 我方是单页应用,`#top` 即首页。新版导航显式加入「首页」项(锚点 `#top`),与 logo 行为一致,补齐信息架构完整性。工作量≈0。 |
| 2 | **拼豆图纸生成器** | **对齐** | 我方 `nav.toPattern`(图片转拼豆)→ `#workspace` 即主工具,与竞品生成器语义等价。**仅需文案对齐命名**(保留「图片转拼豆」,同义不改名,避免破坏已有 SEO/习惯)。 |
| 3 | **拼豆创作** | **暂缓**(P2 评估) | 竞品为品牌故事/教程聚合页,需要内容资产(教程、品牌叙事、精选图)。我方现有 HERO 区已承载品牌感,暂不建独立页;**若后续需要 SEO 内容页再做**。 |
| 4 | **图片转像素画** | **对齐(合并承载)** | 我方 `#workspace` 即"图片 → 像素 → 拼豆"一体化管线,功能上等价于竞品「生成器 + 像素画」两个入口。**不拆独立页**(单页优势:路径更短,一次上传即出图纸);导航上不单列,避免两个入口指向同一工具。 |
| 5 | **作品展示** | **暂缓**(P1 新建 `/showcase`) | 竞品 Showcase 社区(分类/浏览量/投稿)是我们缺失的 P0 级差距(见 zh-detail §6 #25),但**依赖作品数据源**:我方已有 `share-codec.ts` 分享码机制 + 用户保存图纸能力可作为种子数据。导航占位先立(P0),页面 P1 建。 |
| 6 | **主题拼豆(dropdown)** | **对齐(改造复用)** | 竞品 dropdown 承载主题合集(圣诞/宝可梦)。我方 AI 专区 `/chibi` 已有 5 大分类(风景/人物/宠物/物品/食物)——**dropdown 直取 4 个热门分类**做子项,深链进 chibi 并预选分类;另加「全部主题 → /chibi」兜底项。零新数据,复用现有分类体系。 |
| 7 | **图纸库** | **暂缓**(P1 新建 `/library`) | 需要"已保存/已分享图纸"列表能力。我方 `share-codec` 分享码可解码渲染单张图纸,但**无列表聚合页**。导航占位先立,页面 P1 建(首版可聚合"官方精选图纸"静态数据,后续接用户保存)。 |
| 8 | **客户端** | **不做** | 我方是纯 Web 单页应用,无 Chrome 扩展/Android/iOS 客户端产品,竞品 apps 生态无从对齐。**如未来出 PWA/小程序再单独立项**,届时补入口。 |
| 9 | **帮助** | **暂缓**(P1 新建 `/help`) | 我方无独立帮助中心。竞品 `/help` 有分工具子页。我方首版可做**单页 FAQ 区块**(生成流程/兑换码/权益说明,素材已散见于 HERO 与 PassSection 文案),P1 建页;后续视需扩子页。 |
**决策统计:对齐 4 · 暂缓 4 · 不做 1**
> ⚠️ 竞品 i18n 教训(`pixelbeads-nav-crawl.md` §1.3):dropdown 子项竞品定义了 4 个主题却只渲染 2 个(万圣节页 200 存在、创意页 404)。**我方 dropdown 子项必须全部有真实可用的落地页**(chibi 分类路由全部存在),不得出现"字典有、页面无"的悬空链接。
---
## 3. 我方新版导航结构设计
### 3.1 桌面端(≥1024px,7 项)
```
┌────────────────────────────────────────────────────────────────────────────┐
│ ◆ PERLER LAB │ 首页 图片转拼豆 AI拼豆专区◈ 主题拼豆▾ 作品展示 图纸库 帮助 │ 中文|EN [代理合作] ●状态 │
└────────────────────────────────────────────────────────────────────────────┘
▲ #top ▲ #workspace ▲ /chibi(active) ▲ /showcase# ▲ /library# ▲ /help#
│(hover 展开)
▼
┌ 全部主题 → /chibi
│ 宠物世界 → /chibi?cat=pet
│ 人物肖像 → /chibi?cat=people
│ 风景美图 → /chibi?cat=landscape
│ 美食探店 → /chibi?cat=food
```
| 位序 | 项 | 目标 | 类型 | 说明 |
|---|---|---|---|---|
| — | logo PERLER LAB | `#top` | 链接 | 保留现有,承担首页锚点 |
| 1 | 首页 | `#top` | 链接 | 新增;与 logo 同锚点,active 与 logo 一致 |
| 2 | 图片转拼豆 | `#workspace` | 链接 | 现有项保留(主工具),active 高亮保留 |
| 3 | AI拼豆专区 | `/chibi` | 链接 | 现有项保留,**PRO 徽标保留** |
| 4 | 主题拼豆 | dropdown | 触发器 | 新增;hover/点击展开 4 分类 + 全部主题 |
| 5 | 作品展示 | `/showcase`(P1) | 链接 | P0 占位 → P1 真页 |
| 6 | 图纸库 | `/library`(P1) | 链接 | P0 占位 → P1 真页 |
| 7 | 帮助 | `/help`(P1) | 链接 | P0 占位 → P1 真页 |
| — | 语言切换 中文\|EN | — | 保留 | **LangSwitcher 原样保留** |
| — | 代理合作按钮 | 弹窗 | 保留 | **onAgencyClick 交互原样保留** |
| — | 状态徽标 | — | 保留 | 现有 status badge 保留 |
- 交互基准对齐竞品 `pixelbeads-nav-crawl.md` §5:吸顶 sticky + 半透明毛玻璃底 + 当前页高亮(我方沿用现有主题色即可,不强求竞品棕色系)、dropdown 卡片式 viewport + chevron 旋转。
- 路由 active 判断:`/chibi` 前缀命中(现有 `App.tsx` 逻辑 `path === '/chibi' || startsWith('/chibi/')`);`#workspace`/`#top` 用滚动监听高亮。
### 3.2 移动端(<1024px,分组抽屉,参考竞品 §2.2 但适配我方实际页面)
```
[☰] PERLER LAB · 让每一颗颜色都有位置 [中文|EN]
┌─────────── 抽屉(右侧滑入)───────────┐
│ PERLER LAB │
│ 网站导航、AI 生成和语言选项。 │
│ │
│ [H3] 主导航 │
│ ├ 首页 #top │
│ ├ 图片转拼豆 #workspace│
│ └ AI拼豆专区 ◈PRO /chibi │
│ [H3] 主题拼豆(按 AI 分类快速进入) │
│ ├ 宠物世界 /chibi?cat=pet │
│ ├ 人物肖像 /chibi?cat=people │
│ ├ 风景美图 /chibi?cat=landscape│
│ └ 美食探店 /chibi?cat=food │
│ [H3] 工具(P1 起逐步开放) │
│ ├ 作品展示 /showcase │
│ ├ 图纸库 /library │
│ └ 帮助 /help │
│ ─────────────────────────────── │
│ [代理合作 →](复用 AgencyModal) │
└─────────────────────────────────────────┘
```
- 触发:header 汉堡按钮(`lg:hidden`),与桌面导航(`hidden lg:flex`)互斥,沿用竞品断点策略。
- 底部:**保留现有移动端固定 CTA「购买 / 兑换 →」**(`App.tsx` 中 `mobile-cta`),抽屉不吞掉变现入口。
- P1 前「工具」分组整体折叠为单项「更多」或直接隐藏(3 个占位项暂不暴露给移动端,避免劣质占位体验)。
### 3.3 过渡策略(占位 → 真页)
| 阶段 | 桌面 | 移动端 | 暂缓项处理 |
|---|---|---|---|
| **P0(导航先行)** | 7 项全显示,其中 /showcase /library /help 为占位链接 | 主导航 + 主题拼豆组;工具组隐藏 | 占位项点击 → toast/弹层"页面建设中,敬请期待" |
| **P1(页面跟上)** | 7 项全真 | 工具组开放 | 占位提示全部撤下 |
---
## 4. 实施拆解
### 4.1 前置依赖(需新建/改造的页面、路由、组件)
| 依赖 | 类型 | 归属任务 | 说明 |
|---|---|---|---|
| `Nav.tsx` 改造 | 组件改造 | P0-1 | 现有 2 项扩为 7 项 + dropdown + 占位态 |
| 主题 dropdown 组件 | 新组件 | P0-1 | 参考 Radix NavigationMenu 模式(无第三方依赖则自实现 hover/click 展开) |
| 移动端抽屉组件 | 新组件 | P0-3 | 参考竞品 Sheet 模式,自实现右滑抽屉 |
| i18n keys(zh/en) | 语言资源 | P0-2 | `nav.home/showcase/library/help/theme/…` 双语言;**en.ts 以 `Messages` 类型强制键一致**(编译期校验,天然验收) |
| CSS(nav 扩展类) | 样式 | P0-1/3 | dropdown viewport、抽屉、占位态样式 |
| `/showcase` 页面 + 路由 | 新页面 | P1-1 | `App.tsx` 路由分支扩为三段式(chibi / showcase / library / help) |
| `/library` 页面 + 路由 | 新页面 | P1-2 | 首版静态精选图纸,后续接用户保存 |
| `/help` 页面 + 路由 | 新页面 | P1-3 | 单页 FAQ |
| `/chibi?cat=` 深链 | 路由参数 | P2-1 | `ChibiPage` 读 URL 参数预选分类 |
| 作品数据源(可选) | 数据 | P1-1(可选) | 先静态;接入 `share-codec` 聚合为后续增强 |
### 4.2 任务拆分(标题 + 验收标准)
| ID | 优先级 | 任务标题 | 验收标准 |
|---|---|---|---|
| **P0-1** | **P0** | Nav.tsx:扩为 7 项 + 「主题拼豆」dropdown(4 分类 + 全部主题)+ 3 个占位项 | ① 桌面 ≥1024px 渲染 7 项,AI拼豆专区保留 PRO 徽标;② 主题拼豆 hover/点击展开 4 个 chibi 分类子项 +「全部主题→/chibi」,每个子项链接可点击直达 chibi 并预选分类;③ 作品展示/图纸库/帮助 3 项为占位态,点击弹出"建设中"提示;④ 语言切换/代理合作/状态徽标交互原样保留;⑤ active 高亮:首页与 logo 同源、chibi 前缀命中;⑥ `lsp_diagnostics` 无错误 |
| **P0-2** | **P0** | i18n:新增导航 keys(zh-CN + en 成对) | ① 全部新 key 双语言文案齐全且语义一致;② `en.ts` 满足 `Messages` 类型约束(缺 key 编译报错);③ 无硬编码中文残留 |
| **P0-3** | **P0** | 移动端导航:汉堡按钮 + 分组抽屉(主导航 + 主题拼豆 + 隐藏工具组)+ 代理合作 | ① <1024px 隐藏桌面导航、显示汉堡按钮;② 抽屉含主导航 3 项 + 主题拼豆 4 项 + 代理合作按钮;③ 关闭按钮与点击遮罩可关闭;④ 底部固定 CTA「购买/兑换」保留可见;⑤ 无横向溢出滚动 |
| **P1-1** | **P1** | 新建 `/showcase` 作品展示页 + 路由 | ① `App.tsx` 新增路由分支,`/showcase` 可达;② 首版展示官方精选图纸卡片(静态数据 ≥6 张,含缩略图/尺寸/品牌);③ 桌面与移动端正常渲染;④ 导航「作品展示」占位提示撤下并真实跳转 |
| **P1-2** | **P1** | 新建 `/library` 图纸库页 + 路由 | ① `/library` 路由可达;② 列表展示精选/可分享图纸(首版静态,可复用 showcase 数据源);③ 导航「图纸库」真实跳转 |
| **P1-3** | **P1** | 新建 `/help` 帮助页 + 路由 | ① `/help` 路由可达;② 单页 FAQ 覆盖:生成流程、兑换码使用、权益说明、下载格式(文案复用 Hero/PassSection 已有表述);③ 导航「帮助」真实跳转 |
| **P2-1** | **P2** | ChibiPage 支持 `?cat=` 深链预选分类 | ① `/chibi?cat=pet` 打开即预选"宠物"分类与对应细分;② 非法 cat 回退默认;③ dropdown 子项全部指向存在页面(无悬空链接,规避竞品 i18n 字典≠渲染页教训) |
| **P2-2** | **P2** | 帮助中心子页化 / 主题页独立化(按需) | ① 若 FAQ 超一屏则拆 `/help/:tool` 子页;② 视数据积累决定是否独立主题合集页 |
### 4.3 优先级逻辑
- **P0(导航先行)**:纯 `Nav.tsx` + i18n + CSS,零新页面零数据依赖,风险低、见效快,直接消除"我方仅 2 项"的导航差距观感。
- **P1(页面跟上)**:3 个新页面依赖各自内容源(showcase 精选数据、帮助 FAQ 文案),属于内容+路由建设,周期较长。
- **P2(增强)**:深链与内容扩展,依赖 P0 dropdown 与 P1 页面先落地。
> 建议排期:P0-1 → P0-2 → P0-3(可并行 2 条)→ 验收通过后启动 P1-1 → P1-2 → P1-3 → P2 按需。
---
## 5. 风险与注意
1. **单页锚点 vs 路由共存**:`#workspace`/`#top` 是锚点,`/chibi`/`/showcase` 是路由,active 高亮判定需分两套(滚动监听 + pathname 前缀),避免误判。
2. **占位态不要裸链接**:暂缓项在 P0 必须给"建设中"反馈,绝不允许点进空白/404——这正是竞品 i18n 字典与渲染页不一致教训的反面应用。
3. **PRO 徽标与商业定位**:AI 专区是付费能力(按次计费),PRO 徽标与状态文案是现有变现心智的一部分,改导航不得移除。
4. **移动端抽屉不吞 CTA**:`mobile-cta` 购买/兑换按钮是变现入口,抽屉展开与底部 CTA 需共存。
5. **不动算法/业务**:本任务只产出决策文档;源码实施由后续任务承接,P0-1/2/3 验收时不得触碰 `lib/` 管线与付费逻辑。
---
*文档完。全部决策基于 `pixelbeads-nav-crawl.md`(Spider 实测)与我方源码实读,无推断项。*