feat: V1.1 批次入库——色号表SEO页/Showcase/图纸库/帮助中心/JSON-LD/CI门禁/竞品分析
This commit is contained in:
1 parent
40e2342a02
commit
f53f0a2b25
104 files changed
+21760
-157
No files matched your search
@@ -0,0 +1,220 @@
|
||||
# ANIMATION-PLAN · 拼豆图纸生成器 动画落地决策文档
|
||||
|
||||
> 任务: T-086(基于 `competitor-analysis/animation-research.md` 的正式动画技术选型与落地清单)
|
||||
> 日期: 2026-08-14
|
||||
> 范围: 本任务只产出决策文档,**不含任何源码改动**(实施为后续任务)
|
||||
> 适用前端: `D:\拼豆\perler-lab`(Vite 5 + React 18 + TS 5.9,目前 **无任何动画库依赖**)
|
||||
|
||||
---
|
||||
|
||||
## 0. 决策摘要(一句话选型结论)
|
||||
|
||||
> **「CSS 动画打底,leafer.js 升级画布,anime.js 按需补序列」**——先纯 CSS 对齐竞品基准线(0 新增依赖、P0 全量可交付),V2 再引入 leafer.js(图纸画布渲染/交互)+ anime.js(豆子放置、stagger 序列)做差异化动效;**不引入** GSAP、Framer Motion、lottie-web。
|
||||
|
||||
P0 动画清单 **10 条**(全部纯 CSS 可实现,无需新增依赖)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 现状盘点(抽查 `perler-lab/src` 结论)
|
||||
|
||||
| 项 | 现状 | 结论 |
|
||||
|---|---|---|
|
||||
| 动画依赖 | `package.json` 仅 react/react-dom,**无动画库** | 0 依赖现状,P0 保持 |
|
||||
| CSS 动画 | 仅 3 个 keyframes(`spin` 0.7s、`share-toast-in` 0.18s、`chibi-spin` 0.7s)+ 大量 `transition: … 0.15s ease` hover 过渡 | 只有基础 hover/spinner,缺入场/序列/反馈类动画 |
|
||||
| `prefers-reduced-motion` | **全项目未出现** | 必补(见 §6) |
|
||||
| 运动令牌 | 有 `--space/--radius/--shadow`,**无 `--duration/--ease`** | 需新增运动令牌(见 §4.3) |
|
||||
| 图纸渲染 | `lib/drawPattern.ts` 原生 Canvas 2D `fillRect` 逐格绘制 | 竞品同款方案,P0 可不动;V2 换 leafer.js |
|
||||
| 图片处理 | `lib/usePattern.ts` 主线程调 `processImage`(**无 Web Worker**) | A1 进度动画前置条件 = 先迁移 Worker,否则主线程阻塞直接掉帧 |
|
||||
| 页面切换 | App.tsx 按 pathname 条件渲染 `/chibi` 与首页,**无过渡动画** | V2 用 View Transitions API |
|
||||
| 反馈系统 | 分享 toast 已有(`share-toast-in`),下载/错误为静态文字 | P0 补下载成功反馈 |
|
||||
|
||||
竞品基准线(来自调研报告 §1.4):「原生 Canvas 渲染 + CSS 合成层过渡 + Web Worker 过程可视化 + 克制 200-500ms 节奏」——我们 P0 即对齐此线。
|
||||
|
||||
---
|
||||
|
||||
## 2. 技术选型对比表
|
||||
|
||||
| 维度 | **CSS @keyframes/transition** | **GSAP** | **Framer Motion** | **leafer.js** | **anime.js**(调研报告推荐项) |
|
||||
|---|---|---|---|---|---|
|
||||
| 类型 | 原生动画 | JS 补间引擎(DOM/JS 对象/时间线/scrub) | React 动画组件库 | 2D Canvas 场景图渲染引擎 | JS 补间引擎(轻量) |
|
||||
| 体积 | 0 | ~23KB+ gz(core) | ~35KB+ gz | 按需模块,数百 KB 级(仅画布层承担) | 16.1KB gz(v4 按需更小) |
|
||||
| 场景适配 | hover/loading/toast/简单入场/过渡 | 复杂交错时间线、滚动驱动、scrub | React DOM 组件过渡/手势(**不作用于 canvas**) | 图纸网格渲染、豆子交互/动画(**核心差异化**) | spring 弹性、stagger 序列、属性补间 |
|
||||
| 与本项目契合 | ★★★★★ 竞品 56 处 transition 已证明足够 | ★★☆ 工具型产品无复杂时间线需求,杀鸡用牛刀 | ★★☆ 项目是纯 CSS + 原生 canvas 架构,不是 Framer 体系;只为页面过渡引入不值 | ★★★★★ 图纸本质数千~数万矩形,正是批处理强项(画布渲染**唯一**直接对标项) | ★★★★ 体积小、spring/stagger 可拉开差距 |
|
||||
| 主要风险 | 无序列化(需 animation-delay 模拟)、无 spring 物理 | 重、侵入强、学习/维护成本 | 与现有 CSS 体系并存冗余 | 引入成本高(需重写渲染层),仅 V2 承担 | 作者维护缓慢(调研报告 §2),仅按需用其时序能力 |
|
||||
| **推荐结论** | **P0 主力(立即可用)** | **不引入** | **不引入** | **V2 引入(画布层)** | **V2 按需引入(序列层)** |
|
||||
|
||||
> 另:**lottie-web**(调研报告 §3.1 第 4 层)→ **不引入**。无 AE 设计师资源,60KB runtime 成本与产出不成正比;品牌庆祝类动画后期用 CSS/SVG 手工实现(低成本版见 §5-H-02)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 推荐技术栈(分层架构)
|
||||
|
||||
```
|
||||
┌───────────────────────────────────────────────┐
|
||||
│ 第 4 层 品牌/庆祝动画 → CSS/SVG 手工(V2 可选) 无 lottie,无 AE 依赖
|
||||
├───────────────────────────────────────────────┤
|
||||
│ 第 3 层 JS 序列/弹簧微动画 → anime.js(V2 按需,16KB) 豆子放置 spring、stagger、颜色闪烁序列
|
||||
├───────────────────────────────────────────────┤
|
||||
│ 第 2 层 基础 UI 过渡 → CSS/Tailwind 风格令牌(P0) hover、loading、toast、下载反馈、入场
|
||||
├───────────────────────────────────────────────┤
|
||||
│ 第 1 层 图纸画布渲染/交互 → leafer.js(V2) 豆子网格 + 拖拽 + 实时更新(替代原生 fillRect)
|
||||
└───────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**推荐理由(结合 Vite+React+TS 现状):**
|
||||
1. **零依赖 P0 先行**:竞品"高级感"全部来自 CSS 合成层动画(56 处 transition 佐证),我们当前代码已有一致基础(`transition 0.15s`),P0 只是"补齐遗漏项",不动架构、不加依赖,风险最低。
|
||||
2. **leafer.js 是画布层的唯一直接对标**:调研报告 §3.2-1 给出迁移实测(Konva→Leafer:4K 帧率 25-30→58-60、DrawCall 800+→<50、点选 80ms→10ms),且官方 benchmark 覆盖平移/缩放/拖拽/全动态场景,正对应图纸预览。当前原生 `fillRect` 在 >1 万豆大图纸 + 动画场景下必然掉帧,leafer 的批处理 DrawCall + 脏矩形刷新是硬需求而非炫技。
|
||||
3. **anime.js 而非 GSAP/Framer Motion**:差异化动效(A2 spring 回弹、A3 闪烁序列)只需要补间 + stagger + spring 三个能力,anime 16KB 模块化刚好覆盖;GSAP 的 scrub/时间线编排在工具型产品用不上;Framer Motion 只对 React DOM 组件生效,救不了 canvas,且与现有纯 CSS 体系双轨冗余。
|
||||
4. **显式排除**:GSAP / Framer Motion / lottie —— 成本(体积/体系侵入/维护)× 收益(本产品场景用不上)不成立。
|
||||
|
||||
---
|
||||
|
||||
## 4. 落地前置:运动设计令牌(新增,属 P0 基础设施)
|
||||
|
||||
在设计系统 `:root` 新增(对齐竞品节奏:`200/500ms`):
|
||||
|
||||
```css
|
||||
:root {
|
||||
--duration-fast: 120ms; /* 按压/闪烁单拍 */
|
||||
--duration-base: 200ms; /* hover、toast(竞品默认) */
|
||||
--duration-med: 400ms; /* 遮罩淡入、进度过渡 */
|
||||
--duration-slow: 600ms; /* 图纸渐入、卡片缩放(竞品 500ms 档) */
|
||||
--ease-out: cubic-bezier(0.16, 1, 0.3, 1); /* 标准退场 */
|
||||
--ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
|
||||
--spring-bead: cubic-bezier(0.34, 1.56, 0.64, 1); /* 豆子回弹近似 */
|
||||
}
|
||||
```
|
||||
|
||||
所有动画必须引用上述令牌,禁止魔数时长(对齐设计系统纪律)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 逐页面动画清单
|
||||
|
||||
> 优先级: **P0** = V1 必须上线(纯 CSS,0 依赖,对齐竞品基准);**P1** = V1 尽量(可纯 CSS,补细节);**P2** = V2(需引库或大改)。
|
||||
> 编号沿用调研报告 A1-A5,扩展为可执行粒度。
|
||||
|
||||
### 5.1 首页 Hero(`components/Hero.tsx`)
|
||||
|
||||
| 编号 | 组件 | 动画类型 | 触发时机 | 优先级 |
|
||||
|---|---|---|---|---|
|
||||
| H-01 | hero-eyebrow / hero-title / hero-sub / hero-stats | 首屏 stagger 入场:`opacity 0→1` + `translateY(12px)→0`,依次 delay 60ms,总时长 <900ms | 页面首次加载 | **P1**(CSS `animation-delay` 即可) |
|
||||
| H-02 | hero-title `em`(accent) | 高亮词微动效:`background-position`/`opacity` 呼吸或扫光一次 | 入场后 1s 延迟 | P2(装饰,视效果定) |
|
||||
|
||||
### 5.2 首页 AI 专区 / `/chibi`(`ChibiPage.tsx` + `ChibiPage.css`)
|
||||
|
||||
| 编号 | 组件 | 动画类型 | 触发时机 | 优先级 |
|
||||
|---|---|---|---|---|
|
||||
| C-01 | chibi 上传按钮 / 卡片区 | 列表 stagger 入场(opacity+translateY,delay 60ms) | 页面加载 | **P1** |
|
||||
| C-02 | chibi-spinner(已有 `chibi-spin`) | 保留;补按钮双文案切换("处理中…"/"开始") | 生成过程 | **P1** |
|
||||
| C-03 | chibi 结果卡片 hover | 图片 `scale(1.03→1.08)` 500ms + 遮罩 opacity 淡入(竞品 §1.3-5 同款) | 桌面 hover | **P1** |
|
||||
|
||||
### 5.3 编辑画布(`PreviewPanel.tsx` + `lib/drawPattern.ts`)
|
||||
|
||||
| 编号 | 组件 | 动画类型 | 触发时机 | 优先级 |
|
||||
|---|---|---|---|---|
|
||||
| E-01 | 生成进度(**A1**) | ① 生成按钮 loading 态:图标 `spin` + 文案"处理中…";② 画布 `filter: blur(6px)→0` + `opacity 0→1` 600ms;③ 画布下细进度条 0→100% | 点击"生成图纸"后(迁移 Web Worker 后主线程才有余力跑动画) | **P0** |
|
||||
| E-02 | 编辑工具栏按钮(撤销/旋转/镜像等) | 按下按压反馈:`transform: scale(0.97)` / translateY(1px) 120ms(现只有 translateY,补 scale) | `:active` | **P0** |
|
||||
| E-03 | 编辑操作应用(旋转/镜像/翻转后) | 画布内容轻过渡:`opacity 0.4→1` 150ms(防突变闪烁) | 每次编辑变换生效 | **P0** |
|
||||
| E-04 | 豆子放置动画(**A2**,差异化核心) | leafer.js 中每颗豆 `scale 0→1` spring 回弹(stiffness 170 / damping 26)120-180ms;连续放置 `stagger 30ms` 瀑布式填充;颜色切换瞬时 + `brightness(1.4)` 120ms 发光 | 用户在画布点击/填充豆子(leafer 交互对象) | **P2** |
|
||||
| E-05 | 颜色匹配闪烁(**A3**) | 匹配豆呼吸闪烁 2 次(`opacity 1→0.4→1`,各 150ms)或描边光环扩散 300ms 消失 | 选中色与图纸豆色匹配 / 吸管取色 | **P2** |
|
||||
| E-06 | 画布拖拽(竞品 §1.3-3 对齐) | `transform: translate3d(x,y,0)` + `will-change-transform` 合成层拖拽 | 图纸拖动 | **P2**(leafer 内置交互) |
|
||||
|
||||
### 5.4 按钮 / 全局交互
|
||||
|
||||
| 编号 | 组件 | 动画类型 | 触发时机 | 优先级 |
|
||||
|---|---|---|---|---|
|
||||
| B-01 | 下载按钮反馈(**A4**) | ① 图标切换 ✓(transition-colors 变绿 200ms);② `active:scale(0.95)` 100ms;③ 导出 >500ms 时 SVG 进度环(`stroke-dashoffset`);④ toast "图纸已保存 ✓" | 点击"下载图纸" | **P0** |
|
||||
| B-02 | 上传/重置按钮 | hover 背景过渡 + active 按压(现 `transition 0.15s` 已覆盖,统一套用令牌) | hover / active | **P0** |
|
||||
| B-03 | Nav 链接 hover | 下划线滑入 / 背景过渡(现 color 过渡,补 underline) | 桌面 hover | P1 |
|
||||
| B-04 | 分享按钮成功反馈 | toast 已有(`share-toast-in`);补按钮 ✓ 变色 200ms | 分享成功 | **P0** |
|
||||
|
||||
### 5.5 页面过渡 / 弹窗
|
||||
|
||||
| 编号 | 组件 | 动画类型 | 触发时机 | 优先级 |
|
||||
|---|---|---|---|---|
|
||||
| T-01 | 弹窗(Redeem/Order/Agency Modal)打开/关闭 | fade + `scale 0.96→1` 200ms 入场 / 150ms 退场(对齐 toast 既有 keyframes 风格) | 弹窗开关 | **P0** |
|
||||
| T-02 | 页面切换(首页 ↔ /chibi)(**A5**) | View Transitions API 圆形扩散 400ms / 或 clip-path 擦除过渡 | 路由切换 | P2 |
|
||||
| T-03 | 首屏总入场 | 依 H-01/C-01,配合 Toast 入场 | 页面加载 | P1 |
|
||||
|
||||
### 5.6 优先级汇总
|
||||
|
||||
| 优先级 | 条数 | 清单 |
|
||||
|---|---|---|
|
||||
| **P0** | **10** | E-01、E-02、E-03、B-01、B-02、B-04、T-01、(+§4 运动令牌 + §6 reduced-motion 全局降级) |
|
||||
| **P1** | **5** | H-01、C-01、C-02、C-03、T-03、(B-03) |
|
||||
| **P2** | **6** | H-02、E-04、E-05、E-06、T-02 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 性能与可访问性约束(硬性要求)
|
||||
|
||||
### 6.1 可访问性
|
||||
- **`prefers-reduced-motion: reduce` 全局降级**(P0 必做):
|
||||
```css
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
*, *::before, *::after {
|
||||
animation-duration: 0.01ms !important;
|
||||
animation-iteration-count: 1 !important;
|
||||
transition-duration: 0.01ms !important;
|
||||
scroll-behavior: auto !important;
|
||||
}
|
||||
}
|
||||
```
|
||||
所有入场/闪烁/缩放类动画都必须有降级路径;信息传达(toast、进度)**不依赖动画**表达。
|
||||
- 动画不得承载关键信息(加载态必须有文字文案,不只靠 spinner)。
|
||||
|
||||
### 6.2 移动端 60fps
|
||||
- **只动画 `transform` / `opacity` / `filter`**,不碰 `width/height/top/left/margin`(避免 layout thrash 与 reflow)。
|
||||
- 动画元素加 `will-change: transform` 仅用于已知持续动画(如画布拖拽),**不滥用**(会占用内存)。
|
||||
- 进度条宽度动画改 `transform: scaleX()`(合成层)而非 `width`。
|
||||
- **图片转图纸必须先迁 Web Worker**(当前 `usePattern.ts` 主线程调用 `processImage`),否则生成期间主线程被 JS 计算占满,任何动画都会掉帧——E-01 与 Worker 迁移绑定交付。
|
||||
- 大图纸(>1 万豆)V1 画布渲染保持现有原生 `fillRect`;leafer.js 迁移(E-04/05/06)在 V2 一次性承担,避免 V1 双渲染引擎并存。
|
||||
|
||||
### 6.3 通用纪律
|
||||
- 动画时长/缓动一律走 §4 令牌,禁魔数。
|
||||
- 入场动画总时长 ≤900ms,避免拖慢首屏;首屏 FCP/LCP 不因动画代码增加而劣化(动画只在 CSS,不阻塞)。
|
||||
- hover 类动画仅桌面端生效(`@media (hover: hover)`),避免移动端误触触发。
|
||||
|
||||
---
|
||||
|
||||
## 7. 实施顺序建议
|
||||
|
||||
### V1 上线(本次动画里程碑,P0+P1,**0 新增依赖**)
|
||||
1. §4 运动令牌(`--duration-*`/`--ease-*`)写入 `:root`
|
||||
2. §6.1 `prefers-reduced-motion` 全局降级
|
||||
3. **图片处理迁 Web Worker**(E-01 前置,`usePattern.ts` → `new Worker`)
|
||||
4. E-01 生成进度动画(按钮 loading 双文案 + 画布 blur 渐入 + scaleX 进度条)
|
||||
5. E-02/E-03 编辑工具按压与变换过渡
|
||||
6. B-01/B-04 下载/分享成功反馈(✓ 变色 + toast)
|
||||
7. T-01 弹窗入场退场
|
||||
8. P1:H-01 Hero stagger 入场、C-01/C-03 专区入场与卡片 hover、B-03 Nav 下划线
|
||||
|
||||
**V1 验收口径**:移动端滚动/交互无掉帧(无 Worker 阻塞)、reduced-motion 下无动画、全部时长引用令牌。
|
||||
|
||||
### V2 上线(差异化阶段,引入依赖)
|
||||
1. 引入 **leafer.js**,重写图纸画布渲染层(替换 `drawPreview` 原生 fillRect),搭交互对象
|
||||
2. E-04 豆子放置 spring + stagger(anime.js `spring(stiffness:170, damping:26)` 或 leafer 属性补间)
|
||||
3. E-05 颜色匹配闪烁、E-06 画布拖拽合成层
|
||||
4. T-02 页面切换 View Transitions
|
||||
5. H-02 品牌装饰动效(CSS/SVG 手工)
|
||||
|
||||
**V2 验收口径**:>1 万豆图纸拖拽/放置动画保持 60fps(对齐调研报告迁移实测数据:DrawCall <50、点选 <10ms)。
|
||||
|
||||
### 决策树(后续实施时判断)
|
||||
```
|
||||
需要动画 →
|
||||
hover/loading/按压/toast/弹窗/简单入场/过渡 → CSS(永远优先,V1)
|
||||
画布网格/豆子交互/拖拽 → leafer.js(V2)
|
||||
spring 回弹 / stagger 序列(CSS 表达不了) → anime.js(V2 按需)
|
||||
复杂滚动驱动时间线/scrub → 场景未出现,届时再评估 GSAP(现不引入)
|
||||
品牌 AE 级动画 → 无设计师,不引 lottie;CSS/SVG 手工
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 附注
|
||||
|
||||
- 本文档仅决策,不含实施;实施任务引用本清单编号(E-01…、H-01…、C-01…、B-01…、T-01…)作验收依据。
|
||||
- 竞品基线出处: `competitor-analysis/animation-research.md` §1.3(Canvas 渲染 / Worker 加载态 / translate3d 拖拽 / sonner 反馈 / 卡片 500ms hover)、§3.1(分层架构)、§4(A1-A5 效果参数)。
|
||||
- 画布性能数据出处: 调研报告 §3.2-1(Konva→Leafer 迁移实测)。
|
||||
@@ -0,0 +1,216 @@
|
||||
# PERLER LAB · 商业模式细化:免费功能与兑换码付费边界
|
||||
|
||||
> 任务: T-104 | 产出角色: PM-Agent | 日期: 2026-08-14
|
||||
> 关联: PRD.md(权益体系/定价)、LAUNCH.md(冷启动/代理)、AGENT.md(代理合作)、`perler-lab-server/src/codes`(兑换码模块)、`competitor-analysis/pixelbeads-analysis.md` §6(竞品纯免费模式)
|
||||
> 结论预览: **「核心全免费、增值收兑换码」混合策略**——图纸生成全链路免费(防流失对标 pixel-beads),AI 生成 / 高清与多格式导出 / 无水印 / 高级功能走兑换码付费。共 **免费 12 项 + 付费 9 项**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景与核心矛盾
|
||||
|
||||
### 1.1 商业模式现状
|
||||
|
||||
我方基线是竞品 **xylpindou.com** 的「预览免费 + 兑换码解锁下载」模式,已建成完整兑换码模块(`PACKAGE_DEFINITIONS` 6 档套餐、`/api/codes/redeem|consume|status`、下载授权 grant、风控限流),MVP 已跑通全链路。
|
||||
|
||||
### 1.2 核心矛盾(主代理研判)
|
||||
|
||||
新竞品 **pixel-beads.com**(2026-08 深度爬取确认)是**纯免费模式**:首页明示「完全免费 / 无需注册 / 图片本地处理」,无定价页(`/pricing` 404)、无广告、无登录墙,导出 PDF/PNG/SVG/JSON 全免费、含水印/署名可选。其收入靠 SEO 流量 + 三端应用分发。
|
||||
|
||||
> **风险**: 若我方把「图纸生成核心」也做成兑换码付费,用户可零成本转投 pixel-beads,流失风险极高。
|
||||
> **结论**: 商业模式最大分水岭 = **免费核心是否足够强**。必须采用「免费核心 + 付费高级」混合策略:免费部分对齐竞品防流失,付费部分落在竞品没有或我方独特的增值点上。
|
||||
|
||||
### 1.3 本文件目标
|
||||
|
||||
1. 明确**免费功能清单**(对齐竞品、保证核心闭环不流失)。
|
||||
2. 明确**兑换码付费功能清单**(增值收费点)。
|
||||
3. 定价策略(参考竞品纯免费 + 我方兑换码差异)。
|
||||
4. 代理分成逻辑(对齐 AGENT.md 与 codes 模块)。
|
||||
5. 功能边界原则(核心免费、增值收费,可执行可验收)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 竞品商业模式对照(决策依据)
|
||||
|
||||
| 维度 | pixel-beads(纯免费) | xylpindou(兑换码,我方基线) | **我方最终策略** |
|
||||
|---|---|---|---|
|
||||
| 核心生成 | 完全免费 | 预览免费/下载付费 | **完全免费**(对齐 pixel-beads 防流失) |
|
||||
| 注册/登录 | 无登录墙 | 无 | 无登录墙 |
|
||||
| AI 生成 | **无**(图片转像素画,非 AI) | AI chibi 15 风格,付费 | **AI 生成付费**(我方独特增值点) |
|
||||
| 导出 | PDF/PNG/SVG/JSON 全免费 | 高清 PNG 付费 | **基础 PNG 免费 / 高清与多格式付费** |
|
||||
| 水印 | 无(水印/署名可选附加) | - | **无水印导出付费**(基础下载带轻水印) |
|
||||
| 高级编辑 | 图层/对称/矩形全免费 | - | **基础编辑免费;高级工具付费** |
|
||||
| 收入来源 | SEO 流量 + 应用分发 | 兑换码 | 兑换码(含代理分销) + SEO 引流 |
|
||||
|
||||
> **规则推导**: 竞品免费的功能,凡属于「完成一张可拼图纸」的必要能力(生成/预览/备料/基础导出),我方必须免费;只有「超出必要、属于增值/便利/独有」的能力才收费。这样免费用户不会因功能缺失而流失。
|
||||
|
||||
---
|
||||
|
||||
## 3. 免费功能清单(12 项,防流失底线)
|
||||
|
||||
> 原则: 免费版必须能走通「上传 → 生成 → 预览 → 基础下载」完整闭环,且预览质量不设人为限制(对齐竞品)。
|
||||
|
||||
| # | 功能 | 说明 | 对齐竞品 |
|
||||
|---|---|---|---|
|
||||
| F-01 | 图片上传 | JPG/PNG/WebP ≤10MB,拖拽+点击,浏览器本地处理 | pixel-beads 免费 |
|
||||
| F-02 | 参数调整 | 格数/色数/去背景/背景色/品牌色板切换,**不限次数反复生成** | pixel-beads 免费 |
|
||||
| F-03 | 图纸生成核心 | 采样→量化→色板匹配全算法,**无条件免费**(不得加锁) | pixel-beads 免费 |
|
||||
| F-04 | 图纸完整预览 | 豆圆+色号+网格编号+缩放,**完整质量预览**(不得加水印遮挡) | pixel-beads 免费 |
|
||||
| F-05 | 备料清单查看 | 总颗数/色数/分色用量/多备 10% 建议,**完整明细免费** | pixel-beads 免费(materials 统计) |
|
||||
| F-06 | 基础编辑器 | 画笔/橡皮/取色器/撤销重做 | pixel-beads 编辑器免费 |
|
||||
| F-07 | 基础下载 | **标准分辨率 PNG 图纸下载(带轻水印)**——免费闭环出口 | pixel-beads 免费 PNG;我方用「分辨率+水印」分层 |
|
||||
| F-08 | 兑换码兑换与权益查询 | redeem / status / consume 基础链路本身免费 | xylpindou 兑换免费 |
|
||||
| F-09 | 色号表浏览 | MARD/Artkal-C/Perler/Hama 等品牌色号页全量浏览(SEO 内容) | pixel-beads 6 品牌色号页免费 |
|
||||
| F-10 | 图纸本地保存 | localStorage 保存/重载(MVP 无账号,权益本地存储) | pixel-beads localStorage |
|
||||
| F-11 | 分享 URL | 图纸编码分享链接 | pixel-beads 作品 URL 分享 |
|
||||
| F-12 | 帮助/FAQ 中心 | 实操知识、兑换说明、熨烫/选豆指南 | pixel-beads 帮助中心 |
|
||||
|
||||
**防流失校验(F-01~F-07)**: 免费用户上传一张图,可以**不看任何付费提示**完成「生成→预览→看到色号与备料→下载一张能用的基础图纸」。付费墙只出现在"想要更高清/多格式/无水印/AI"时,绝不卡在"能不能用"上。
|
||||
|
||||
---
|
||||
|
||||
## 4. 兑换码付费功能清单(9 项,增值收费点)
|
||||
|
||||
> 每次权益按「次」计(对齐 PRD 4.1:下载/AI 均 1 次),由 codes 模块 `consumeCode` 原子扣减。
|
||||
|
||||
| # | 功能 | 消耗 | 依据/定位 |
|
||||
|---|---|---|---|
|
||||
| P-01 | **AI 拼豆生成**(chibi) | 1 次/张 | 竞品 pixel-beads 无 AI,**我方独特增值点**,MVP 已验证转化场景 |
|
||||
| P-02 | **高清 PNG 图纸下载** | 1 次/张 | 高分辨率打印级图纸(竞品免费,我方以基础版免费+高清收费分层) |
|
||||
| P-03 | **PDF 高清打印导出**(含分块/300DPI) | 1 次/张 | 对标 pixel-beads P0-导出差距;PDF 是打印刚需 |
|
||||
| P-04 | **无水印导出** | 1 次/张 | 水印是基础免费与付费的分层抓手 |
|
||||
| P-05 | **SVG / JSON 工程文件导出** | 1 次/张 | 专业用户(矢量/工程数据) |
|
||||
| P-06 | **高级编辑工具**(图层/对称/矩形选区/旋转镜像) | 1 次/次操作包 | 面向深度用户;基础编辑免费、专业工具收费 |
|
||||
| P-07 | **批量生成/批量导出**(代理场景) | 按批量次数 | 对应代理套餐消耗逻辑(AGENT.md 200/500/1000 次) |
|
||||
| P-08 | **商用授权** | 1 次/张 | 商用图纸授权(LAUNCH FAQ 已提示「商用需授权」) |
|
||||
| P-09 | **AI 结果转正式图纸并高清下载** | 1 次/张 | AI 生成已扣 1 次,转正式图纸的首次高清下载含在生成内,**再次下载不扣**(对齐 PRD 4.2) |
|
||||
|
||||
**P 与 F 的边界**:
|
||||
- F-07 基础下载(标准分辨率+水印)免费 → P-02/P-03/P-04 高清/PDF/无水印付费。
|
||||
- F-06 基础编辑免费 → P-06 高级编辑付费。
|
||||
- F-03 核心生成免费 → P-01 AI 生成付费(算法生成 ≠ AI 生成,两类不同价值)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 定价策略
|
||||
|
||||
### 5.1 个人套餐(沿用 PRD 4.1,与 codes 模块 `PACKAGE_DEFINITIONS` 一致)
|
||||
|
||||
| 套餐 | 价格 | 次数 | 单次成本 | 目标 |
|
||||
|---|---|---|---|---|
|
||||
| 体验包 | ¥4.9 | 3 | ¥1.63 | 首单钩子,降低决策门槛 |
|
||||
| 常用包 | ¥12.9 | 10 | ¥1.29 | 手工爱好者日常 |
|
||||
| 进阶包 | ¥29.9 | 30 | ¥1.00 | 深度用户 |
|
||||
|
||||
### 5.2 代理套餐(沿用 AGENT.md §4,codes 模块一致)
|
||||
|
||||
| 套餐 | 价格 | 次数 | 单次成本 |
|
||||
|---|---|---|---|
|
||||
| 入门代理 | ¥139 | 200 | ¥0.70 |
|
||||
| 标准代理 | ¥299 | 500 | ¥0.60 |
|
||||
| 核心代理 | ¥499 | 1000 | ¥0.50 |
|
||||
|
||||
### 5.3 定价逻辑(参考竞品纯免费 + 我方兑换码差异)
|
||||
|
||||
1. **免费核心 = 获客引擎**:对齐 pixel-beads 纯免费,用「免费生成完整可用」换取 SEO 流量与口碑,替代竞品的投放获客。
|
||||
2. **兑换码 = 变现引擎**:付费点全部落在「增值/独有」上(AI、高清、无水印、PDF、商用授权),不与竞品免费能力正面冲突。
|
||||
3. **单次成本递减引导升级**:¥1.63 → ¥1.29 → ¥1.00 →(代理)¥0.70/0.60/0.50,引导向大套餐/代理迁移。
|
||||
4. **代理价差 = 分销空间**:代理单次成本(0.50–0.70)显著低于个人零售(1.00–1.63),为转售留出 3–10 元/张利润空间(对齐 AGENT.md §1)。
|
||||
5. **权益按次通用**:AI 与下载等价扣 1 次,不区分用途(PRD 4.1),系统复杂度最低。
|
||||
|
||||
---
|
||||
|
||||
## 6. 代理分成逻辑
|
||||
|
||||
> 与 `AGENT.md`、`LAUNCH.md §3`、codes 模块代理套餐完全一致,此处固化分成模型。
|
||||
|
||||
### 6.1 角色与收益模型
|
||||
|
||||
| 角色 | 收入/成本 | 说明 |
|
||||
|---|---|---|
|
||||
| **平台** | 套餐全价(¥139/299/499) | 一次性收入,按次交付(兑换码核销) |
|
||||
| **代理** | 收入:接单/卖图 3–10 元/张;成本:单次 0.50–0.70 元 | 单张毛利 ≈ 2.3–9.5 元(按 10 元/张、0.50 成本计利润率 ~90%+) |
|
||||
| **代理的客户** | 向代理付费,不接触平台 | 代理承担收款与服务 |
|
||||
|
||||
### 6.2 分成/分销机制
|
||||
|
||||
1. **代理差价分成**:平台以批发价(0.50–0.70/次)售出,代理以零售价(3–10 元/张)转售,差额归代理——这是主分成。
|
||||
2. **推广返佣**:专属推广链接(带代理标识),客户经链接购买**个人套餐**,按约定比例返佣(AGENT.md FAQ-10;返佣比例由运营在系统外核定,作为 C 端补充激励)。
|
||||
3. **阶梯价**:累计采购 ≥1000 次可谈阶梯价(例:降至 ¥0.45/次档),量大从优(AGENT.md §4 补充规则)。
|
||||
4. **升级补齐**:代理升级按差价补齐、已购权益保留(AGENT.md FAQ-5),不损失存量。
|
||||
5. **风控约束**:代理码走代理通道、个人码走个人通道,不可混用(AGENT.md FAQ-7);异常核销走 codes 风控限流 + `security_events` 滥用检测(codes 模块已实现)。
|
||||
|
||||
### 6.3 平台利润率参考(成本侧)
|
||||
|
||||
- 单次权益的实际成本主要在 AI 生成(约 ¥0.02–0.05/张,LAUNCH §5.3),图纸生成纯前端零边际成本 → 高价次权益毛利极高,可支撑免费核心的运营开销。
|
||||
- 每月监控 AI 失败率(>5% 告警)与兑换码核销日志,控制成本与套利。
|
||||
|
||||
---
|
||||
|
||||
## 7. 功能边界原则(核心免费、增值收费)
|
||||
|
||||
### 7.1 三条硬原则
|
||||
|
||||
| # | 原则 | 判定法 | 举例 |
|
||||
|---|---|---|---|
|
||||
| B-01 | **核心必要能力永远免费** | 删掉该功能,用户能否完成「一张可拼图纸」?不能 → 免费 | 生成/预览/备料/基础下载(F-01~F-07) |
|
||||
| B-02 | **增值/独有能力可收费** | 竞品没有(AI)或超出必要(高清/PDF/无水印/商用)?是 → 可收费 | P-01~P-09 |
|
||||
| B-03 | **免费版可被感知为完整产品** | 免费用户能否无提示走通主流程且不感到被「阉割」? | 免费预览完整不遮挡;只有出口的清晰度/格式/水印分层 |
|
||||
|
||||
### 7.2 边界判定的反例(禁止收费项)
|
||||
|
||||
- ❌ 图纸生成次数限制(免费也要无限次,防流失)。
|
||||
- ❌ 预览加水印/模糊(免费预览必须完整清晰,对齐竞品)。
|
||||
- ❌ 备料清单隐藏分色明细(竞品免费给材料统计)。
|
||||
- ❌ 上传格式/大小人为收紧逼付费。
|
||||
- ❌ 注册/登录墙(竞品无登录墙,我方 MVP 也不设)。
|
||||
|
||||
### 7.3 兑换码模块落位(现有实现 ↔ 边界映射)
|
||||
|
||||
| 现有模块能力 | 落位 |
|
||||
|---|---|
|
||||
| `PACKAGE_DEFINITIONS`(6 档) | 5.1/5.2 套餐源,价格/次数与本文一致 |
|
||||
| `/api/codes/redeem` | F-08(兑换免费),兑换后权益入 localStorage |
|
||||
| `/api/codes/consume` | P-02~P-09 扣减;downloadGrant 防重复扣费(同一图纸首下含在生成内) |
|
||||
| `/api/chibi/generate` | P-01 AI 生成即扣 1 次,返回 downloadGrant |
|
||||
| 风控/限流/`security_events` | 代理与个人双通道保护(6.2) |
|
||||
|
||||
> 边界文档与现有代码零冲突:免费项不需要任何代码改动(本就是免费路径),付费项全部已有 consume/grant 支撑。
|
||||
|
||||
---
|
||||
|
||||
## 8. 决策记录与后续动作
|
||||
|
||||
### 8.1 本次决策
|
||||
|
||||
1. **图纸生成核心全免费**(F-01~F-07),对齐 pixel-beads 防流失——商业模型最大分水岭已定调。
|
||||
2. **付费点 9 项全部落在增值/独有**(AI/高清/PDF/无水印/SVG/JSON/高级编辑/批量/商用),不与竞品免费能力正面冲突。
|
||||
3. **定价维持 6 档**(3 个人 + 3 代理),单次成本递减引导升级,代理价差 0.50–0.70 支撑分销空间。
|
||||
4. **代理分成**:主分成=差价转售;辅分成=推广链接返佣(比例系统外核定);阶梯价+升级补齐+双通道隔离。
|
||||
|
||||
### 8.2 待办建议(转 backlog)
|
||||
|
||||
| 事项 | 说明 | 优先级 |
|
||||
|---|---|---|
|
||||
| 兑换弹窗文案增加「免费/付费边界」说明 | 明确告诉用户哪些免费、付费买什么,降低付费抵触 | P1 |
|
||||
| 基础下载水印落地 | 免费 PNG 带轻水印实现(前端导出),无水印走 P-04 | P1 |
|
||||
| 高级编辑工具(图层/对称/矩形)随 P-06 排期 | 目前编辑器仅基础工具,高级工具付费项待开发 | P1 |
|
||||
| 商用授权(P-08)规则细化 | 授权协议文案 + consume 关联订单 | P2 |
|
||||
| 免费核心转化漏斗埋点 | 对齐 ANALYTICS.md:免费下载完成率 → 付费转化率对照 | P1 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 结论
|
||||
|
||||
| 维度 | 结论 |
|
||||
|---|---|
|
||||
| 免费清单 | **12 项**(F-01~F-12),覆盖「生成→预览→备料→基础下载」完整闭环,对齐竞品防流失 |
|
||||
| 付费清单 | **9 项**(P-01~P-09),全部为增值/独有能力,走兑换码按次扣减 |
|
||||
| 定价 | 个人 3 档(¥4.9/12.9/29.9)+ 代理 3 档(¥139/299/499),与 codes 模块一致 |
|
||||
| 代理分成 | 差价转售为主 + 推广返佣为辅,批发 0.50–0.70/次 vs 零售 3–10 元/张 |
|
||||
| 边界原则 | **核心免费、增值收费**:必要能力永不收费;独有/增值能力按次收费 |
|
||||
|
||||
> 本文件为「免费/付费边界」决策文档,是 PRD §4、LAUNCH §3、AGENT.md 的统一口径。后续任何功能入免费或付费清单,均需按 §7 三条原则判定并回写本文,防止边界漂移导致流失或变相缩水。
|
||||
|
||||
---
|
||||
|
||||
*报告完。证据可复核: `competitor-analysis/pixelbeads-analysis.md` §6(纯免费模式)、`pixelbeads-zh-detail.md` §4/§8(导出免费/差距项)、`docs/PRD.md` §4(权益体系)、`docs/LAUNCH.md` §3/§5、`docs/AGENT.md` §4、`perler-lab-server/src/codes/service.ts` + `src/types/index.ts`(6 档套餐/兑换扣减实测)。*
|
||||
@@ -0,0 +1,126 @@
|
||||
# CI 门禁:色号表与 Showcase 等新页面构建检查(T-109)
|
||||
|
||||
> 维护者:GitOps-Engineer(T-109)
|
||||
> 关联文件:`.github/workflows/deploy.yml`、`perler-lab/nginx.conf`、`perler-lab/src/App.tsx`
|
||||
> 更新日期:2026-08-14
|
||||
|
||||
## 检查结论(TL;DR)
|
||||
|
||||
| 检查项 | 结论 |
|
||||
|---|---|
|
||||
| 新页面是否影响现有构建? | **不破坏**。新页面均通过 `App.tsx` 顶层静态 import 打包进同一 Vite bundle,`typecheck` + `vite build` 天然覆盖 |
|
||||
| Vite build 是否自动打包新路由页面? | **是**。路由为 `App.tsx` 内基于 `window.location.pathname` 的客户端分支(非 react-router 动态加载),无按路由分包,全部页面一次性打进 `assets/index-*.js` |
|
||||
| SPA 路由是否需要 Nginx / fallback 配置? | **已具备,无需新增**。`perler-lab/nginx.conf` 已配置 `try_files $uri $uri/ /index.html;`,新路由直访由 nginx 回退到 `index.html` 后由前端渲染 |
|
||||
| 是否需要新增 CI 门禁? | **需要小补强**。已新增「Verify SPA dist & route smoke」步骤:校验 dist 产物 + 用 `vite preview` 对每个新路由做直访冒烟,防「路由直访 404」回归 |
|
||||
| 是否改动 deploy.yml? | **是**。`test` job 的 `Frontend production build` 步骤之后新增一个产物校验 + 路由冒烟步骤(见下文) |
|
||||
|
||||
---
|
||||
|
||||
## ① 新页面构建验证清单(typecheck / build 覆盖确认)
|
||||
|
||||
### 新页面与路由清单
|
||||
|
||||
| 路由 | 页面组件 | 源码位置 |
|
||||
|---|---|---|
|
||||
| `/chibi`、`/chibi/*` | `ChibiPage` | `perler-lab/src/ChibiPage.tsx` |
|
||||
| `/color-chart`、`/color-chart/:brand` | `ColorChartPage` | `perler-lab/src/ColorChartPage.tsx`(数据 `src/lib/color-chart-data.ts` + `src/lib/palette-data/*.json`) |
|
||||
| `/showcase`、`/showcase/*` | `ShowcasePage` | `perler-lab/src/pages/ShowcasePage.tsx` |
|
||||
| `/library`、`/library/*` | `LibraryPage` | `perler-lab/src/pages/LibraryPage.tsx` |
|
||||
| 其他任意路径 | `HomePage`(兜底) | `perler-lab/src/App.tsx` |
|
||||
|
||||
### 覆盖确认
|
||||
|
||||
- **路由实现方式**:`App.tsx`(`src/App.tsx` 第 335–348 行)在顶层**静态 import** 全部页面组件(`import ColorChartPage from './ColorChartPage'` 等),再按 `window.location.pathname` 分支渲染。无 react-router、无 `React.lazy` 动态加载。
|
||||
- **typecheck 覆盖(G3)**:`npm run typecheck` = `tsc --noEmit`(`tsconfig.json` 开启 `strict`)。新增页面的 `.tsx`/`.ts` 源码全部参与编译,类型错误会直接拦截。CI 矩阵中 `perler-lab` 与 `perler-lab-server` 均执行。
|
||||
- **build 覆盖(G4)**:`npm run build` = `vite build`。由于所有页面为静态 import,新页面组件 + 色号 JSON 数据 + CSS 必然被 Rollup 打包进 `dist/assets/index-*.js`。构建产物中不存在“漏掉某个路由页面”的空间——只要 App.tsx 引用了它,就会进 bundle;引用缺失则 tsc 直接报错(`Cannot find module`)。
|
||||
- **产物校验**:CI 新增步骤显式断言 `dist/index.html` 与 `dist/assets/*.js` 存在,确认产物完整性。
|
||||
|
||||
> 结论:**无需**为新页面单独新增 build 命令。现有 G3(typecheck)+ G4(vite build)已完整覆盖;T-109 仅在其后增加产物校验与路由冒烟,作为“构建成功”之外的“构建产物可直访”门禁。
|
||||
|
||||
### 发现的问题(非阻塞)
|
||||
|
||||
- `/help` 路由在 `App.tsx` 中**不存在**(`src/App.tsx` 无 `/help` 分支),且全局无 `HelpPage` 组件。直访 `/help` 会落到 `HomePage` 兜底,不会 404,但展示内容与预期不符。若 `help` 属于已规划页面(如 T-109 上下文提到的 4 个新页面之一),需在后续任务中补充路由与组件;若为误报,可忽略。
|
||||
|
||||
---
|
||||
|
||||
## ② SPA fallback 部署配置建议
|
||||
|
||||
### 现状:已配置,无需改动
|
||||
|
||||
`perler-lab/nginx.conf` 已包含 SPA 回退:
|
||||
|
||||
```nginx
|
||||
# ── SPA 路由回退 ──
|
||||
location / {
|
||||
try_files $uri $uri/ /index.html;
|
||||
}
|
||||
```
|
||||
|
||||
行为:直访 `/color-chart/mard` → nginx 找不到对应文件 → 回退 `index.html` → 前端 `App.tsx` 读 `location.pathname` → 渲染 `ColorChartPage`。新路由**无需任何额外 Nginx 配置**。
|
||||
|
||||
### 建议(保持现状的三条纪律)
|
||||
|
||||
1. **不要把新页面做成 `public/` 下的物理 HTML 文件**。Vite 会将 `public/` 原样拷入 dist,若未来出现同名静态目录(如 `dist/showcase/`),nginx 的 `try_files $uri $uri/` 会优先命中该目录而非 SPA 回退,导致路由与静态资源语义冲突。
|
||||
2. **保持 `location /` 的 try_files 兜底不被覆盖**。新增 location 时避免写死 `try_files $uri =404` 之类的规则覆盖根 location。
|
||||
3. **若未来迁移到 Next.js / SSR**,此配置需改为上层反代(`nginx.conf` 顶部注释已说明,参考 `docs/DEPLOY.md`),届时 SPA fallback 职责转移,与本门禁解耦。
|
||||
|
||||
### 测试环境等价验证
|
||||
|
||||
CI 路由冒烟使用 `vite preview`(自带 history fallback),其行为与生产 nginx 的 `try_files $uri $uri/ /index.html` 等价:直访任意路由返回 `index.html`(HTTP 200)。**注意 `vite preview` 只验证“fallback 语义正确”,无法覆盖 nginx 语法/配置错误**——nginx 配置有效性仍需在 `build` job 的 docker 镜像构建阶段(`COPY nginx.conf` + `nginx:alpine` 启动)保证,或本地 `docker run` 验证。
|
||||
|
||||
---
|
||||
|
||||
## ③ CI 门禁建议(已落地到 deploy.yml)
|
||||
|
||||
### 建议结论
|
||||
|
||||
**需要**在 `test` job 增加路由冒烟检查。理由:
|
||||
|
||||
- typecheck/build 只能证明“代码可编译、页面已打包”,**不能**证明“直访新路由返回 200”;
|
||||
- 若未来有人误删 `try_files` 或把路由改坏,冒烟检查会在 CI 期拦截,避免部署后用户直访 404;
|
||||
- 成本极低(一次 `vite preview` + 7 个 curl),并入现有 test job 矩阵的 perler-lab 分支即可。
|
||||
|
||||
### 已新增步骤(deploy.yml → test job)
|
||||
|
||||
```yaml
|
||||
- name: Verify SPA dist & route smoke
|
||||
if: matrix.project.name == 'perler-lab'
|
||||
working-directory: perler-lab
|
||||
run: |
|
||||
set -e
|
||||
[ -f dist/index.html ] || { echo "❌ dist/index.html 缺失"; exit 1; }
|
||||
ls dist/assets/*.js > /dev/null 2>&1 || { echo "❌ dist/assets 无 JS bundle"; exit 1; }
|
||||
npx vite preview --port 4173 --strictPort > /tmp/vite-preview.log 2>&1 &
|
||||
PID=$!
|
||||
trap "kill $PID 2>/dev/null || true" EXIT
|
||||
for i in $(seq 1 30); do
|
||||
curl -sf http://localhost:4173/ > /dev/null 2>&1 && break
|
||||
sleep 0.5
|
||||
done
|
||||
curl -sf http://localhost:4173/ > /dev/null 2>&1 || {
|
||||
echo "❌ vite preview 未能启动"; cat /tmp/vite-preview.log; exit 1; }
|
||||
for route in / /chibi /color-chart /color-chart/mard /color-chart/artkal-c /showcase /library; do
|
||||
code=$(curl -s -o /dev/null -w '%{http_code}' "http://localhost:4173$route")
|
||||
echo "GET $route → $code"
|
||||
[ "$code" = "200" ] || { echo "❌ 路由 $route 返回 $code(预期 200)"; exit 1; }
|
||||
done
|
||||
```
|
||||
|
||||
要点说明:
|
||||
|
||||
- 冒烟路由集:`/`(首页)、`/chibi`、`/color-chart`(列表)、`/color-chart/mard` 与 `/color-chart/artkal-c`(品牌子路由,覆盖“带段路由直访”)、`/showcase`、`/library`。未加 `/help`(见①,该路由当前不存在)。
|
||||
- 若未来新增品牌(如 `/color-chart/perler`),建议同步追加到路由集;也可改为读取 `COLOR_CHART_BRANDS` 动态断言,但会增加 CI 脚本复杂度,暂不引入。
|
||||
- 冒烟失败(任一路由非 200 或产物缺失)→ 步骤退出码非 0 → `test` job 失败 → 阻塞 `build` / `deploy`,符合门禁语义。
|
||||
|
||||
---
|
||||
|
||||
## 变更记录(T-109)
|
||||
|
||||
| 变更 | 文件 |
|
||||
|---|---|
|
||||
| 新增「Verify SPA dist & route smoke」步骤:dist 产物校验 + vite preview 对新路由直访冒烟 | `.github/workflows/deploy.yml` |
|
||||
| 新增本文档(构建验证清单 / SPA fallback 说明 / CI 门禁建议) | `docs/CI-NEWPAGES.md` |
|
||||
|
||||
## 验证方式(CI 执行)
|
||||
|
||||
推送 `master` 后观察 Actions 流水线:`test` job(perler-lab 分支)应依次出现 `Frontend production build` → `Verify SPA dist & route smoke`,日志中 7 个 `GET <route> → 200` 全部通过后进入 `build` job。
|
||||
@@ -0,0 +1,167 @@
|
||||
# PERLER LAB · 合规页面清单(T-123)
|
||||
|
||||
> 任务: T-123 | 产出角色: PM-Agent | 日期: 2026-08-14
|
||||
> 数据来源: `competitor-analysis/pixelbeads-analysis.md`(§1.3 站点结构:about/contact/privacy-policy/terms-of-service 路由)、`pixelbeads-zh-detail.md`(§1.1 路由表:法律页 6 语言覆盖)、`docs/LAUNCH.md`(§4 FAQ:兑换码/权益/退款规则)、`docs/BUSINESS-MODEL.md`(兑换码/代理/商用授权)、`docs/PRD.md`(风险#3 设备绑定数据)
|
||||
> ⚠️ **数据待补标注**: 竞品法律与关于页的正文抓取任务为 **T-119(Spider-Agent,开发中)**,`gap-crawl.md` 尚未产出。本文 §1 竞品结构参考基于**常规合规规范推断**,待 T-119 交付后回填实测章节并复核。
|
||||
|
||||
---
|
||||
|
||||
## 1. 竞品合规页结构参考(pixel-beads.com)
|
||||
|
||||
### 1.1 路由与 i18n 覆盖(sitemap 实测,已确认)
|
||||
|
||||
| 路由 | 用途 | i18n 覆盖 | 证据 |
|
||||
|---|---|---|---|
|
||||
| `/about` | 关于我们 | 6 语言(en/zh/ja/vi/ko/de) | pixelbeads-zh-detail §1.1 |
|
||||
| `/contact` | 联系我们 | 6 语言 | 同上 |
|
||||
| `/privacy-policy` | 隐私政策 | 6 语言 | 同上 |
|
||||
| `/terms-of-service` | 服务条款 | 6 语言 | 同上 |
|
||||
|
||||
- 竞品四页在**页脚「关于与法律」栏**统一入口(首页/帮助/应用等全站页脚露出),且全语言覆盖——**合规页是站点信任基础设施,不做语言裁剪**。
|
||||
|
||||
### 1.2 必备章节推断(⏳ 待 T-119 实测回填)
|
||||
|
||||
> 以下为基于常规隐私/服务条款规范 + 我方产品特性的推断结构。T-119 交付后请按竞品实测章节增删并标注差异。
|
||||
|
||||
**About(关于我们)**
|
||||
- 产品简介(做什么、怎么用)
|
||||
- 核心特性说明(免费模式、本地处理、无需注册)
|
||||
- 创始人/团队信息(竞品可考:founder Yibai Ju,pixelbeads-analysis §6)
|
||||
- 联系方式(help@pixel-beads.com 风格)
|
||||
- 站点收录/合作说明(竞品页脚有 findly.tools 等收录目录互推)
|
||||
|
||||
**Contact(联系我们)**
|
||||
- 联系邮箱(客服通道,竞品 contactPoint schema 已确认邮箱)
|
||||
- 响应时效承诺
|
||||
- 问题分类导航(功能问题/反馈/合作)
|
||||
- 常见问题跳转(help 中心)
|
||||
|
||||
**Privacy Policy(隐私政策)——本项目重点**
|
||||
- **信息收集范围**:图片处理(本地/上传)、兑换码、权益消费记录、设备标识、分析埋点(GA)
|
||||
- **本地处理声明**:图纸生成在浏览器本地完成,图片不上传服务器(我方核心特性,也是隐私卖点)
|
||||
- **第三方数据处理**:AI 生成走服务端(模型调用),需披露第三方模型供应商
|
||||
- **存储与保留**:localStorage 权益存储、兑换码数据库(服务端)、日志保留期限
|
||||
- **数据共享**:仅在提供服务/法律规定时共享,不售卖
|
||||
- **用户权利**:查询/删除/投诉,国内按《个人信息保护法》需给出删除通道
|
||||
- **儿童隐私**:亲子使用场景,14 岁以下需监护人同意
|
||||
- **Cookie/分析技术声明**
|
||||
- **政策变更通知方式 + 生效日期 + 联系方式**
|
||||
|
||||
**Terms of Service(服务条款)**
|
||||
- 服务描述与接受条款
|
||||
- **免费/付费边界**:哪些功能免费、兑换码付费机制(对齐 BUSINESS-MODEL §3/§4)
|
||||
- **兑换码规则**:使用方式、有效期(长期有效)、退款规则(已用不退/未用可协商,LAUNCH §4.1)
|
||||
- **设备绑定权益**:权益存 localStorage、换设备丢失风险告知(PRD 风险#3)
|
||||
- **用户责任**:上传图片版权(用户保证有权使用)、禁止上传违法/侵权内容
|
||||
- **知识产权**:网站/算法/品牌内容归属我方;用户生成图纸的使用授权(商用需授权,BUSINESS-MODEL P-08)
|
||||
- **禁止行为**:滥用兑换码、批量抓取、代理转售违规
|
||||
- **免责声明与责任限制**:工具准确性不作保证、间接损失免责
|
||||
- **服务变更与终止权**
|
||||
- **适用法律与争议解决**(国内:属地法院管辖约定)
|
||||
|
||||
---
|
||||
|
||||
## 2. 我方上线合规页面清单
|
||||
|
||||
> 上线优先级: **P0** = 上线必备(缺失有直接法律/信任风险)/ **P1** = 上线后 2 周内补。
|
||||
> 当前前端路由为 SPA(App.tsx 手写路由),合规页按独立路由 `/about`、`/contact`、`/privacy-policy`、`/terms-of-service` 注册。
|
||||
|
||||
### 2.1 清单总览
|
||||
|
||||
| # | 页面 | URL | 优先级 | 工作量(人日) | 主要风险提示 |
|
||||
|---|---|---|---|---|---|
|
||||
| CP-01 | **隐私政策** | `/privacy-policy` | **P0** | 1–2(文案)+ 0.5(前端) | 覆盖兑换码/支付/设备绑定数据 |
|
||||
| CP-02 | **服务条款** | `/terms-of-service` | **P0** | 1–1.5(文案)+ 0.5(前端) | 兑换码规则/商用授权/用户上传版权 |
|
||||
| CP-03 | **联系我们** | `/contact` | **P0** | 0.5(文案)+ 0.5(前端) | 退款协商/投诉渠道必须可达 |
|
||||
| CP-04 | **关于我们** | `/about` | P1 | 0.5(文案)+ 0.5(前端) | 信任建设,缺失不违法但伤转化 |
|
||||
| CP-05 | **ICP 备案页** | 全站页脚展示 | P1(国内部署时 P0) | 0.25 | 见 §3 |
|
||||
|
||||
### 2.2 分页明细
|
||||
|
||||
**CP-01 隐私政策 `/privacy-policy`(P0)**
|
||||
|
||||
| 必备章节 | 内容要点 | 法律风险提示 |
|
||||
|---|---|---|
|
||||
| 信息收集 | ①图片:生成功能浏览器本地处理,**不上传服务器**;AI 生成(chibi)会上传图片至服务端模型 ②兑换码:服务端校验与核销记录 ③权益与消费:localStorage 权益 + 消费流水 ④设备标识/日志 ⑤分析埋点(GA/自建) | **兑换码/权益数据属个人信息或敏感信息**,须明确收集用途与保留期限;本地与上传两类图片处理路径必须分开声明,否则"本地处理"承诺与 AI 上传事实矛盾会构成虚假陈述风险 |
|
||||
| 存储与保留 | 兑换码库、消费日志、AI 生成记录的服务端保留时长与删除机制 | 国内《个保法》要求:最小必要 + 保存期限合理 + 用户可请求删除 |
|
||||
| 设备绑定数据 | **权益保存在当前浏览器 localStorage,换设备/清缓存不可恢复**(PRD 风险#3) | 必须在隐私政策中**显著告知**设备绑定限制,否则用户换设备后投诉权益丢失,构成告知不充分风险 |
|
||||
| 第三方 | AI 模型供应商、GA/CDN、域名解析 | 披露第三方名单 + 数据处理方式;若模型商在中国境外,涉数据出境合规(V2.0 真实支付与多语言前需评估) |
|
||||
| 用户权利 | 查询/更正/删除/投诉路径(联系邮箱) | 缺删除通道 = 直接违反《个保法》 |
|
||||
| 儿童隐私 | 亲子拼豆场景,14 周岁以下需监护人同意 | 涉未成年人信息处理规则 |
|
||||
| 政策更新 | 生效日期 + 变更通知方式 | 变更后未通知 = 效力争议 |
|
||||
|
||||
**CP-02 服务条款 `/terms-of-service`(P0)**
|
||||
|
||||
| 必备章节 | 内容要点 | 法律风险提示 |
|
||||
|---|---|---|
|
||||
| 服务范围与免费边界 | 免费 12 项(F-01~F-12)+ 付费 9 项(P-01~P-09)边界(BUSINESS-MODEL §3/§4) | 边界写死,防"免费变收费"客诉;对齐兑换弹窗文案(BUSINESS-MODEL §8.2) |
|
||||
| 兑换码规则 | 使用方式、长期有效、已用不退/未用可协商(LAUNCH §4.1)、代理码/个人码不可混用 | **退款规则不写清 = 高频客诉源**;虚拟权益退款规则需在付款前可见 |
|
||||
| 用户上传责任 | 用户保证上传图片拥有合法使用权、不侵犯第三方版权/肖像权;上传即授权平台处理用于生成 | **图片版权风险**(LAUNCH §6):用户上传侵权图,平台尽到告知义务可免责 |
|
||||
| 商用授权 | 图纸仅供个人手作,商用需购买 P-08 授权 | 商用边界不写清,代理商/接单用户易误用 |
|
||||
| 知识产权 | 网站/算法/色板数据/品牌内容归我方;用户生成图纸的使用规则 | 色号数据版权(色板来自品牌公开资料,需声明数据来源与使用授权) |
|
||||
| 禁止行为 | 滥用兑换码、批量抓取、逆向、转售绕过代理体系 | 与 codes 模块风控(security_events)联动 |
|
||||
| 免责与责任限制 | 工具输出准确性不作保证、间接损失免责、AI 生成结果仅供参考 | 过度免责条款在《民法典》格式条款下可能无效,需保留合理限度 |
|
||||
| 法律适用与争议解决 | 中华人民共和国法律 + 服务器所在地法院 | 与 ICP 备案主体一致(见 §3) |
|
||||
|
||||
**CP-03 联系我们 `/contact`(P0)**
|
||||
|
||||
| 必备章节 | 内容要点 | 风险提示 |
|
||||
|---|---|---|
|
||||
| 客服邮箱 | 独立客服邮箱(勿用个人邮箱) | LAUNCH §4.1「未使用可联系客服协商」的前提是客服可达;**无联系页 = 退款承诺无法兑现** |
|
||||
| 响应时效 | 明确承诺(如 1–3 个工作日) | 虚高承诺会引发投诉升级 |
|
||||
| 问题分类 | 功能问题 / 兑换码与权益 / 代理合作 / 侵权投诉 | 侵权投诉通道(DMCA/平台通知-删除规则)缺失有平台连带风险 |
|
||||
| 帮助跳转 | 指向 `/help` 常见问题 | 降低客服压力 |
|
||||
|
||||
**CP-04 关于我们 `/about`(P1)**
|
||||
- 产品定位(图片转拼豆图纸 + AI 拼豆生成器)
|
||||
- 免费核心 + 兑换码模式的透明说明
|
||||
- 本地处理 / 隐私优先的差异化卖点
|
||||
- 联系与收录信息(复用 `/contact` 邮箱)
|
||||
|
||||
---
|
||||
|
||||
## 3. ICP / 备案提示(面向国内部署)
|
||||
|
||||
### 3.1 判定条件(当前部署环境)
|
||||
|
||||
| 部署形态 | 是否需备案 | 说明 |
|
||||
|---|---|---|
|
||||
| 服务器/CDN 在中国大陆(当前 nginx+Docker,若为国内云厂商) | **必须 ICP 备案** | 域名解析至大陆服务器必须取得 ICP 备案号,否则 80/443 端口会被拦截 |
|
||||
| 服务器在中国境外(如 Cloudflare 境外 + 境外 VPS) | 暂不强制 | 但面向国内用户运营仍有**公安备案/网安**要求(经营性除外) |
|
||||
| 微信/支付宝支付接入 | **依赖 ICP 备案** | 官方商户签约要求备案号 + 企业主体(模拟支付阶段不受影响,正式支付前置条件) |
|
||||
|
||||
### 3.2 备案流程与前置(若确认国内部署)
|
||||
|
||||
1. **域名**:完成实名认证(域名注册商侧)。
|
||||
2. **ICP 备案**:主体(个人/企业)→ 域名 + 服务器 IP → 管局审核(约 7–20 工作日)。企业备案需营业执照;个人备案不支持经营性内容。
|
||||
3. **经营性 ICP 许可证**:**若上线兑换码付费,属经营性互联网信息服务**,企业主体原则上需《增值电信业务经营许可证(ICP 许可证)》;个人备案不可用于收费业务。⚠️ 兑换码业务正式商业化前需评估此条。
|
||||
4. **公安备案**:ICP 备案通过后 30 日内至全国互联网安全管理服务平台完成公安备案(页脚展示公安备案号)。
|
||||
5. **备案号展示**:页脚悬挂 ICP 备案号 + 公安备案号,链接至工信部/公安查询页。
|
||||
6. **页脚合规栏**(推荐与竞品一致):`关于我们 · 联系我们 · 隐私政策 · 服务条款 · ICP 备案号 xxx号 · 公安备案号 xxx号`。
|
||||
|
||||
### 3.3 合规时间线建议
|
||||
|
||||
| 阶段 | 动作 | 时限 |
|
||||
|---|---|---|
|
||||
| 上线前 | CP-01/02/03 上线(P0) | 与 V1.1 发布同批 |
|
||||
| 上线前 | 确认部署地域与备案责任(云厂商/AI 模型供应商地域) | T-7 |
|
||||
| 上线后 2 周 | CP-04 about 页(P1) | 上线后 |
|
||||
| 正式支付前 | ICP 备案完成 + 经营性许可证评估 | V2.0 真实支付前置 |
|
||||
| 上线后 30 日内 | 公安备案(若国内部署) | 备案通过后 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 结论
|
||||
|
||||
| 维度 | 结论 |
|
||||
|---|---|
|
||||
| 竞品参考 | 4 页(about/contact/privacy-policy/terms-of-service)全语言覆盖、页脚统一入口;正文章节 **⏳ 待 T-119/gap-crawl.md 回填实测后复核** |
|
||||
| 我方清单 | **4 页 + 备案页脚**:隐私政策 / 服务条款 / 联系我们为 P0 必备,关于我们 P1 |
|
||||
| 最大法律风险点 | ①隐私政策必须覆盖**兑换码/设备绑定(localStorage)数据**并显著告知 ②本地处理 vs AI 服务端上传的声明必须一致 ③兑换码退款规则写进条款 ④国内部署 ICP 备案 + 经营性许可评估 |
|
||||
| 下一步 | T-119 交付后回填竞品实测章节;CP-01~03 转排期为 V1.1/V1.2 上线前置任务 |
|
||||
|
||||
> 本文件为合规页面决策依据。文案落地时建议经简单法律复核(可先以模板 + 人工逐条核对清单 2.2 的章节完整度)。
|
||||
|
||||
---
|
||||
|
||||
*报告完。证据可复核: `competitor-analysis/pixelbeads-zh-detail.md` §1.1(竞品合规路由/i18n)、`docs/LAUNCH.md` §4/§6(FAQ 与风险)、`docs/BUSINESS-MODEL.md` §3/§4(免费付费边界)、`docs/PRD.md`(风险#3)、`perler-lab/src/App.tsx`(现有路由)。竞品正文章节推断待 `gap-crawl.md`(T-119)交付后回填。*
|
||||
@@ -0,0 +1,177 @@
|
||||
# 部署核对:新页面路由与静态资源部署配置(T-110)
|
||||
|
||||
> 维护者:DevOps-Engineer(T-110)
|
||||
> 关联文件:`.github/workflows/deploy.yml`、`perler-lab/nginx.conf`、
|
||||
> `perler-lab/Dockerfile`、`perler-lab-server/Dockerfile`、
|
||||
> `perler-lab-server/docker-compose.yml`、`docs/CI-NEWPAGES.md`、`docs/DEPLOY.md`
|
||||
> 更新日期:2026-08-14
|
||||
|
||||
## 核对范围
|
||||
|
||||
新页面(色号表 `/color-chart(/...)`、Showcase `/showcase`、图纸库 `/library`、
|
||||
AI 专区 `/chibi`,路由定义于 `perler-lab/src/App.tsx` 第 335–348 行)与既有
|
||||
部署配置的兼容性。部署路径为:SSH 生产 → `git pull` → `docker compose -f
|
||||
perler-lab-server/docker-compose.yml up -d --build`(`.github/workflows/deploy.yml`
|
||||
deploy job 第 101–131 行)。
|
||||
|
||||
---
|
||||
|
||||
## 核对结论(TL;DR)
|
||||
|
||||
| # | 检查项 | 结论 |
|
||||
|---|---|---|
|
||||
| ① | 前端 Nginx/静态服务是否支持 SPA 路由 fallback | ✅ **已支持,无需改动**。`nginx.conf` 已有 `try_files $uri $uri/ /index.html;`,直访 `/showcase`、`/color-chart/mard` 等返回 `index.html`(200),由前端 `App.tsx` 按 `pathname` 分支渲染 |
|
||||
| ② | 新页面静态资源是否会被 docker build 自动包含 | ✅ **已包含,无需改动**。全部页面为 `App.tsx` 顶层静态 import,`vite build` 一次性打进 `dist/assets/index-*.js`;色号 JSON 数据由 `src/lib/palette-data/*.json` 经 Rollup 打包(`vite build → dist/` → `COPY --from=build /app/dist`) |
|
||||
| ③ | 后端新接口(`/api/showcase/*`、`/api/color-chart/*`)CORS/路由放行 | ⚠️ **路由已放行**(Nginx `location /api/` 通配 + `server.ts` 已挂载两个 router);**但生产 API 基址有缺陷,已修复**(见 §2-B) |
|
||||
| ④ | 健康检查路径是否受影响 | ✅ **不受影响**。前端 `/healthz`(`location = /healthz` 精确匹配优先于 fallback)、后端 `/health` 均未变,deploy job 探测的两个路径无需调整 |
|
||||
| ⑤ | 后端色号表数据文件是否入镜像 | ❌ **发现缺陷,已修复**(见 §2-A)。`/api/color-chart/:brand` 默认读取 `/app/competitor-analysis/palettes`,该目录**不在镜像内**,会导致色号表 API 返回空列表 |
|
||||
| ⑥ | CI 对新页面路由的门禁 | ✅ **已在工作区就位**(T-109 未提交改动):deploy.yml test job 含「Verify SPA dist & route smoke」步骤(`vite preview` 对 `/ /chibi /color-chart /color-chart/mard /color-chart/artkal-c /showcase /library` 直访冒烟) |
|
||||
|
||||
---
|
||||
|
||||
## ① SPA 路由 fallback(前端 Nginx)—— 已具备,无需改动
|
||||
|
||||
`perler-lab/nginx.conf` 第 94–97 行已包含 SPA 回退,无需新增:
|
||||
|
||||
```nginx
|
||||
# ── SPA 路由回退 ──
|
||||
location / {
|
||||
try_files $uri $uri/ /index.html;
|
||||
}
|
||||
```
|
||||
|
||||
行为验证:
|
||||
|
||||
- 直访 `/showcase`、`/library`、`/color-chart/mard` → nginx 找不到对应物理文件 → 回退
|
||||
`index.html`(HTTP 200)→ 前端读取 `window.location.pathname` 渲染对应页面。
|
||||
- 不存在的路由(如 `/help`,`App.tsx` 无此分支)同样回退 `index.html` → 渲染 `HomePage`
|
||||
兜底,**不会 404**。若 `帮助` 页面在规划中,需补 `App.tsx` 分支与组件(见
|
||||
`docs/CI-NEWPAGES.md` ①第 42 行),非部署配置问题。
|
||||
- `location = /healthz`(精确匹配)优先级高于 `location /`,健康检查不受 fallback 影响。
|
||||
|
||||
生产入口路径(`docs/DEPLOY.md` §4.2 主机 Nginx)为 `location / { proxy_pass
|
||||
http://127.0.0.1:8080; }`,把任意路径透传给 frontend 容器,fallback 职责在容器内
|
||||
nginx 完成,同样无需改动。
|
||||
|
||||
## ② 静态资源 docker build 自动包含 —— 已包含,无需改动
|
||||
|
||||
`perler-lab/Dockerfile` 构建阶段执行 `vite build`(`RUN npm run build`),
|
||||
`App.tsx` 对全部新页面组件(`ChibiPage` / `ColorChartPage` / `ShowcasePage` /
|
||||
`LibraryPage`)为**静态 import**,因此:
|
||||
|
||||
- 新页面组件 + 色号 JSON 数据(`src/lib/palette-data/*.json`)+ CSS 必然进 bundle;
|
||||
- 不存在的引用会直接触发 tsc `Cannot find module` 构建失败(CI typecheck 覆盖)。
|
||||
|
||||
结论:新页面无需任何「额外 COPY / 额外构建步骤」。
|
||||
|
||||
## ③ 后端新接口 CORS / 路由放行
|
||||
|
||||
### 路由:已放行
|
||||
|
||||
- 后端 `perler-lab-server/src/server.ts` 第 69–70 行已挂载:
|
||||
`app.use("/api/color-chart", createColorChartRouter())`、
|
||||
`app.use("/api/showcase", createShowcaseRouter(db))`。
|
||||
- 前端 nginx `location /api/ { proxy_pass http://backend; }`(nginx.conf 第 70 行)为
|
||||
通配前缀,`/api/showcase/*`、`/api/color-chart/*` 自动命中,**无需新增 location**。
|
||||
- 主机层 nginx(`docs/DEPLOY.md` §4.2)的 `location /api/ → 127.0.0.1:8788` 同理。
|
||||
|
||||
### CORS:生产无需放行,开发已覆盖
|
||||
|
||||
- 生产:同源请求(见下 §2-B 修复后的 `/api` 基址)经 Nginx 反代,**不触发 CORS**。
|
||||
- 开发:后端 CORS 白名单 `http://localhost:5173` / `http://127.0.0.1:5173`
|
||||
(server.ts 第 27 行)覆盖 Vite dev server 的跨源调用,新接口走同一中间件,无需追加。
|
||||
|
||||
## ④ 健康检查路径 —— 不受影响
|
||||
|
||||
| 检查点 | 路径 | 状态 |
|
||||
|---|---|---|
|
||||
| frontend 镜像 HEALTHCHECK(Dockerfile) | `GET http://localhost:80/healthz` | 未变 |
|
||||
| compose 中 server healthcheck | `fetch('http://localhost:8788/health')` | 未变 |
|
||||
| deploy job 探测 | `http://localhost:8080/healthz` / `http://localhost:8788/health` | 未变 |
|
||||
|
||||
新路由对上述路径零影响。
|
||||
|
||||
---
|
||||
|
||||
## 已落地的配置修改(本次 T-110 直接修改,均已标注)
|
||||
|
||||
### 2-A 后端色号表数据文件入镜像(修复:镜像内无色板数据)
|
||||
|
||||
**缺陷**:`perler-lab-server/src/color-chart/routes.ts` 第 66–71 行的
|
||||
`DEFAULT_PALETTES_DIR` 解析到仓库根 `competitor-analysis/palettes/`;容器内
|
||||
等价路径为 `/app/competitor-analysis/palettes`,而后端镜像构建上下文仅为
|
||||
`perler-lab-server`,**该目录不会进入镜像** → `/api/color-chart/:brand` 在容器内
|
||||
读取失败,模块加载时告警并回退空列表,SEO JSON-LD 数据为空。
|
||||
|
||||
**修改**(纯部署配置 + 数据文件,源码未动):
|
||||
|
||||
1. `perler-lab-server/palettes/` —— 从 `competitor-analysis/palettes/` 同步 6 个品牌
|
||||
色板 JSON(`artkal-c.json` / `hama.json` / `ikea-pyssla.json` / `nabbi.json` /
|
||||
`perler.json` / `zippland-291标准色映射.json`)。**后续品牌数据变更时请同步该目录**。
|
||||
2. `perler-lab-server/Dockerfile` —— 运行阶段新增 `COPY palettes ./palettes`。
|
||||
3. `perler-lab-server/docker-compose.yml` —— `server` 服务新增环境变量
|
||||
`PALETTES_DIR: "/app/palettes"`(routes.ts 第 112 行优先读 `PALETTES_DIR`)。
|
||||
如需改用卷挂载色板,改此值为宿主机映射路径即可。
|
||||
|
||||
### 2-B 前端生产 API 基址(修复:生产浏览器 fetch 打到「用户本机」)
|
||||
|
||||
**缺陷**:`perler-lab/src/lib/api.ts` 第 87 行 `API_BASE` 默认
|
||||
`http://localhost:8788`,且全仓无 `.env.production` / build-arg 覆盖。生产环境下该
|
||||
绝对 URL 在**用户浏览器**里执行,`localhost` 指向用户本机 → 所有 API 调用
|
||||
(含 Showcase 发布 `POST /api/showcase/works`)都会失败,且即使打对也会因来源
|
||||
不在后端 CORS 白名单而被拦截。
|
||||
|
||||
**修改**(`perler-lab/Dockerfile` 构建阶段,`npm run build` 之前):
|
||||
|
||||
```dockerfile
|
||||
ARG VITE_API_BASE=/api
|
||||
ENV VITE_API_BASE=$VITE_API_BASE
|
||||
```
|
||||
|
||||
效果:生产 bundle 内 `import.meta.env.VITE_API_BASE` 变为同源 `/api`,
|
||||
`fetch('/api/...')` 走 Nginx `/api/` 反代到后端容器,**同源无 CORS**。本地
|
||||
`npm run dev`(5173)无此变量,仍回退到开发默认 `http://localhost:8788`,行为不变。
|
||||
如需指向独立 API 域名,可用 `docker compose build --build-arg VITE_API_BASE=<url>`
|
||||
覆盖。
|
||||
|
||||
---
|
||||
|
||||
## 仍需人工关注 / 建议(非本次修改)
|
||||
|
||||
| 项 | 说明 | 建议动作 |
|
||||
|---|---|---|
|
||||
| `/help` 路由 | `App.tsx` 无 `/help` 分支,直访回退 HomePage | 若属规划页面,补路由与组件;部署侧无需改动 |
|
||||
| 色板数据同步 | `perler-lab-server/palettes/` 与 `competitor-analysis/palettes/` 需保持同步 | 更新色板后手动同步(或改为卷挂载 + 单独管理) |
|
||||
| CI 冒烟步骤提交 | deploy.yml 的「Verify SPA dist & route smoke」为 T-109 工作区未提交改动,随 T-109/T-110 一起入库 | 提交时确认包含 |
|
||||
| 前端缓存 | `/assets/` 强缓存 30d(hash 文件名)保证新页面更新后无缓存残留 | 无操作 |
|
||||
|
||||
## 上线验证命令(部署后执行)
|
||||
|
||||
```bash
|
||||
# 1. 路由直访(应 200 且返回 index.html)
|
||||
for r in /showcase /library /color-chart/mard /chibi; do
|
||||
echo "$r → $(curl -s -o /dev/null -w '%{http_code}' http://localhost:8080$r)"
|
||||
done
|
||||
|
||||
# 2. 新接口(经 Nginx 反代)
|
||||
curl -s http://localhost:8080/api/color-chart/mard | head -c 200
|
||||
curl -s http://localhost:8080/api/showcase/meta
|
||||
# 预期:color-chart 返回含 colors 数组的 JSON-LD(非空),meta 返回 title/description
|
||||
|
||||
# 3. 健康检查
|
||||
curl -sf http://localhost:8080/healthz && curl -sf http://localhost:8788/health
|
||||
```
|
||||
|
||||
> 若 `curl .../api/color-chart/mard` 返回的 `colors` 为空,说明 `PALETTES_DIR` 未生效
|
||||
> 或 `perler-lab-server/palettes/` 未同步,按 §2-A 检查容器内
|
||||
> `/app/palettes` 内容(`docker exec perler-lab-server ls /app/palettes`)。
|
||||
|
||||
## 变更记录(T-110)
|
||||
|
||||
| 变更 | 文件 |
|
||||
|---|---|
|
||||
| 新增品牌色板数据目录(6 个 JSON,供色号表 API 读取) | `perler-lab-server/palettes/` |
|
||||
| 运行阶段 COPY 色板数据入镜像 | `perler-lab-server/Dockerfile` |
|
||||
| server 服务新增 `PALETTES_DIR=/app/palettes` | `perler-lab-server/docker-compose.yml` |
|
||||
| 构建阶段设置 `VITE_API_BASE=/api`(生产同源 API 基址) | `perler-lab/Dockerfile` |
|
||||
| 新增本文档(部署核对结论 + 配置清单 + fallback 片段) | `docs/DEPLOY-NEWPAGES.md` |
|
||||
+11
-5
@@ -44,8 +44,14 @@ cmd /c "D:\拼豆\start-dev.bat"
|
||||
5. 打印访问地址与健康检查命令。
|
||||
|
||||
启动成功后,两个服务分别运行在独立的 cmd 窗口中(标题分别为
|
||||
「PERLER LAB 后端」和「PERLER LAB 前端」),日志输出在各自窗口中,点击
|
||||
任务栏对应标题即可查看。
|
||||
`PERLER LAB Backend` 和 `PERLER LAB Frontend`),日志输出在各自窗口中,
|
||||
点击任务栏对应标题即可查看。
|
||||
|
||||
> **编码兼容说明(BUG-087)**:`start-dev.bat` / `stop-dev.bat` 为纯 ASCII
|
||||
> 编码 + CRLF 换行,并改用 `%~dp0` 解析项目目录,因此在任意代码页
|
||||
> (包括中文 GBK / cp936)的 Windows 下均可直接双击或命令行运行,
|
||||
> 无需依赖 `chcp` 或 UTF-8 BOM。脚本内提示信息为英文,本中文文档
|
||||
> 为唯一使用说明。
|
||||
|
||||
## 三、端口一览
|
||||
|
||||
@@ -80,8 +86,8 @@ curl http://localhost:8788/health
|
||||
|
||||
### 1. 端口被占用
|
||||
|
||||
现象:启动脚本提示「端口 8788 已被占用」或「端口 5173 已被占用」,
|
||||
或浏览器访问时报错。
|
||||
现象:启动脚本提示 `[WARNING] Port 8788 is already in use!` 或
|
||||
`[WARNING] Port 5173 is already in use!`,或浏览器访问时报错。
|
||||
|
||||
解决办法:
|
||||
|
||||
@@ -96,7 +102,7 @@ curl http://localhost:8788/health
|
||||
```
|
||||
3. 重新运行 `start-dev.bat`。
|
||||
|
||||
### 2. 提示「未检测到 Node.js」
|
||||
### 2. 提示 `[ERROR] Node.js not found`
|
||||
|
||||
- 确认 Node.js 已安装:命令行执行 `node --version`;
|
||||
- 若已安装但仍报错,说明 Node.js 未加入 PATH。重新运行安装程序勾选
|
||||
|
||||
@@ -0,0 +1,308 @@
|
||||
# 帮助中心 FAQ 数据(T-107)
|
||||
|
||||
> 任务: T-107 帮助中心:FAQ 数据内容整理
|
||||
> 用途: 供 T-106(FAQ 页面组件)读取渲染;也用于帮助中心子页内容
|
||||
> 数据来源: 竞品 `competitor-analysis/raw/home-zh-text.txt`(Homepage Help Desk 教程 5 大章节 FAQ 抽取)+ 我方产品特有问答(兑换码/代理合作/AI 专区)
|
||||
> 条数: **35**(竞品实操 24 条 + 我方产品特有 11 条)
|
||||
> 日期: 2026-08-14
|
||||
|
||||
## 使用说明
|
||||
|
||||
- 每条含 `category`(分类标签,zh+en)、`question`(zh+en)、`answer`(zh+en)。
|
||||
- 分类标签: `bead-selection` 选豆 / `color-matching` 配色 / `printing` 打印 / `ironing` 熨烫 / `framing` 裱框 / `redemption` 兑换码与权益 / `ai-zone` AI 专区 / `product` 平台与使用。
|
||||
- 数据可直接映射为前端 `<details>`/手风琴组件;`question_en/answer_en` 供后续 i18n 扩展。
|
||||
|
||||
---
|
||||
|
||||
## 一、选豆 Bead Selection(bead-selection)
|
||||
|
||||
### FAQ-01 不同品牌的拼豆可以混用吗?
|
||||
- **category**: bead-selection / 选豆
|
||||
- **question_zh**: 不同品牌的拼豆可以混用吗?
|
||||
- **question_en**: Can I mix beads from different brands?
|
||||
- **answer_zh**: 不建议混用。不同品牌在颜色编号、材质手感以及熨烫时的热缩率上可能存在差异,混用容易导致颜色不一致或熨烫后变形。为了保证成品效果,建议同一作品尽量使用同一品牌的拼豆。
|
||||
- **answer_en**: Not recommended. Different brands may differ in color codes, material feel, and heat-shrink rate during ironing, which can cause color mismatch or warping. Use one brand per project for the best result.
|
||||
|
||||
### FAQ-02 5mm 和 2.6mm 拼豆可以放在同一块拼板上吗?
|
||||
- **category**: bead-selection / 选豆
|
||||
- **question_zh**: 5mm 和 2.6mm 拼豆可以放在同一块拼板上吗?
|
||||
- **question_en**: Can 5mm and 2.6mm beads share the same pegboard?
|
||||
- **answer_zh**: 不可以。5mm 和 2.6mm 拼豆属于完全不同规格,对应的拼板孔径不同,无法通用。如果混用尺寸,会导致拼豆无法固定,图案也无法正常熨烫。
|
||||
- **answer_en**: No. 5mm and 2.6mm beads have different peg-hole sizes and are incompatible. Mixing sizes means beads won't stay in place and the design cannot be ironed properly.
|
||||
|
||||
### FAQ-03 新手应该从 5mm 还是 2.6mm 拼豆开始?
|
||||
- **category**: bead-selection / 选豆
|
||||
- **question_zh**: 新手应该从 5mm 还是 2.6mm 拼豆开始?
|
||||
- **question_en**: Should beginners start with 5mm or 2.6mm beads?
|
||||
- **answer_zh**: 建议从 5mm 开始。5mm 拼豆颗粒更大、操作难度更低,更适合新手建立信心。2.6mm 拼豆对精细操作和耐心要求较高,更适合 16 岁以上、有一定经验的用户。
|
||||
- **answer_en**: Start with 5mm. Bigger beads are easier to handle and build confidence. 2.6mm requires finer motor control and patience, better for ages 16+ or experienced makers.
|
||||
|
||||
### FAQ-04 72 色和 168 色拼豆差别大吗?需要一开始就买 168 色吗?
|
||||
- **category**: bead-selection / 选豆
|
||||
- **question_zh**: 72 色和 168 色拼豆差别大吗?需要一开始就买 168 色吗?
|
||||
- **question_en**: Is there a big difference between 72-color and 168-color sets? Should I buy 168 colors right away?
|
||||
- **answer_zh**: 差别主要体现在细节表现上。72 色可以满足大多数基础图案和练习需求,而 168 色在渐变、肤色和复杂图案上表现更自然。新手可以先从 72 色开始,熟练后再升级到 168 色。
|
||||
- **answer_en**: The difference is in detail. 72 colors cover most basic patterns and practice; 168 colors handle gradients, skin tones, and complex designs more naturally. Beginners can start with 72 and upgrade later.
|
||||
|
||||
### FAQ-05 选豆时如何确定作品需要买哪些颜色?
|
||||
- **category**: bead-selection / 选豆
|
||||
- **question_zh**: 选豆时如何确定作品需要买哪些颜色?
|
||||
- **question_en**: How do I know which bead colors a project needs?
|
||||
- **answer_zh**: 用拼豆图纸生成器生成图纸后,导出材料统计表即可看到每一色需要的豆数与总量。将颜色按「大面积主色」和「少量点缀色」区分:主色优先囤货,点缀色按单次用量购买即可,避免浪费。
|
||||
- **answer_en**: After generating a pattern, export the material list to see the bead count per color. Separate "bulk main colors" from "small accent colors": stock up on main colors, buy accents per project to avoid waste.
|
||||
|
||||
---
|
||||
|
||||
## 二、配色与图纸生成 Color Matching & Generation(color-matching)
|
||||
|
||||
### FAQ-06 为什么不建议上传过大的图片?
|
||||
- **category**: color-matching / 配色
|
||||
- **question_zh**: 为什么不建议上传过大的图片?
|
||||
- **question_en**: Why shouldn't I upload very large images?
|
||||
- **answer_zh**: 过大的图片并不会让拼豆作品效果更好,反而会增加难度。图片尺寸过大(例如上千像素)时:会产生过多拼豆颗粒、图纸结构过于复杂,制作难度明显提升、自动配色更容易出现杂色、实际完成所需的时间和成本显著增加。拼豆创作强调的是清晰的像素感,而不是高分辨率图片。
|
||||
- **answer_en**: A larger image doesn't mean a better bead project — it just adds difficulty. Very large images (e.g. thousands of pixels) produce too many beads, overly complex charts, noisier auto-matching, and much higher time/cost. Bead art is about clean pixel clarity, not resolution.
|
||||
|
||||
### FAQ-07 上传图片的推荐尺寸是多少?
|
||||
- **category**: color-matching / 配色
|
||||
- **question_zh**: 上传图片的推荐尺寸是多少?
|
||||
- **question_en**: What image size do you recommend uploading?
|
||||
- **answer_zh**: 建议图片的宽或高控制在 100–300 像素(px)之间。在这个范围内,图案清晰度、拼豆数量和制作难度更容易取得平衡,生成的图纸也更适合实际制作。
|
||||
- **answer_en**: Keep the width or height between 100–300 px. This range balances clarity, bead count, and build difficulty, and produces charts that are practical to make.
|
||||
|
||||
### FAQ-08 图片比例有要求吗?
|
||||
- **category**: color-matching / 配色
|
||||
- **question_zh**: 图片比例有要求吗?
|
||||
- **question_en**: Is there an aspect-ratio requirement for images?
|
||||
- **answer_zh**: 图片比例不限,但建议接近最终成品比例。在上传前适当裁剪主体,避免过多无关背景,有助于生成更理想的拼豆图纸。
|
||||
- **answer_en**: No strict requirement, but keep it close to the final layout ratio. Crop the subject and trim excess background before uploading for a better result.
|
||||
|
||||
### FAQ-09 5mm 拼豆适合使用多大的图片?
|
||||
- **category**: color-matching / 配色
|
||||
- **question_zh**: 5mm 拼豆适合使用多大的图片?
|
||||
- **question_en**: What image size suits 5mm beads?
|
||||
- **answer_zh**: 5mm 拼豆建议使用 100–200px 左右的图片。这个尺寸范围下,图案清晰、颗粒数量适中,非常适合儿童、新手或轻松制作的作品。
|
||||
- **answer_en**: Around 100–200 px. Within this range patterns stay clear with a moderate bead count — ideal for kids, beginners, or quick relaxing projects.
|
||||
|
||||
### FAQ-10 2.6mm 拼豆适合使用多大的图片?
|
||||
- **category**: color-matching / 配色
|
||||
- **question_zh**: 2.6mm 拼豆适合使用多大的图片?
|
||||
- **question_en**: What image size suits 2.6mm beads?
|
||||
- **answer_zh**: 2.6mm 拼豆可以使用 200–300px 的图片。由于颗粒更小,2.6mm 拼豆可以表现更多细节,适合人物、复杂图案或进阶创作。
|
||||
- **answer_en**: 200–300 px. Smaller beads capture more detail, making this range ideal for portraits, complex designs, and advanced projects.
|
||||
|
||||
### FAQ-11 自动配色出现杂色或颜色不理想怎么办?
|
||||
- **category**: color-matching / 配色
|
||||
- **question_zh**: 自动配色出现杂色或颜色不理想怎么办?
|
||||
- **question_en**: Auto color-matching produced noise or off colors. What can I do?
|
||||
- **answer_zh**: 使用左侧工具栏的三个常用修补工具:画笔(为指定像素重新上色,支持左键拖动连续绘制)、橡皮擦(清除不需要的颜色,支持批量擦除)、取色器(吸取画板中已有颜色,保持整体配色统一)。配色原则:优先保证大面积颜色的统一性、减少零散孤立的颜色点、必要时适当简化细节,更利于实际拼豆制作。
|
||||
- **answer_en**: Use the three toolbar tools: Brush (repaint specific pixels, drag to paint continuously), Eraser (bulk-erase unwanted colors), and Eyedropper (pick existing board colors to keep the palette consistent). Keep large areas uniform, reduce isolated single-color dots, and simplify details when needed.
|
||||
|
||||
---
|
||||
|
||||
## 三、打印 Printing(printing)
|
||||
|
||||
### FAQ-12 为什么要打印拼豆蓝图?
|
||||
- **category**: printing / 打印
|
||||
- **question_zh**: 为什么要打印拼豆蓝图?
|
||||
- **question_en**: Why should I print a bead blueprint?
|
||||
- **answer_zh**: 蓝图可以作为参考,保证颜色、像素和图案准确,尤其适用于复杂作品。
|
||||
- **answer_en**: A printed blueprint keeps colors, pixels, and the design accurate — especially important for complex projects.
|
||||
|
||||
### FAQ-13 打印蓝图前需要注意什么?
|
||||
- **category**: printing / 打印
|
||||
- **question_zh**: 打印蓝图前需要注意什么?
|
||||
- **question_en**: What should I check before printing a blueprint?
|
||||
- **answer_zh**: 检查图纸比例与最终成品是否一致;使用 300 DPI 高清打印,保证像素清晰;根据纸张尺寸选择合适的打印方式。
|
||||
- **answer_en**: Verify the chart scale matches the finished size; print at 300 DPI for crisp pixels; pick a print layout that fits your paper size.
|
||||
|
||||
### FAQ-14 打印比例不对怎么办?
|
||||
- **category**: printing / 打印
|
||||
- **question_zh**: 打印比例不对怎么办?
|
||||
- **question_en**: The printed scale is wrong. What should I do?
|
||||
- **answer_zh**: 检查打印设置,确保选择「实际大小」或按比例缩放;可先打印小样确认比例。
|
||||
- **answer_en**: Check print settings and choose "actual size" or scale-to-fit; print a small test swatch first to confirm the scale.
|
||||
|
||||
### FAQ-15 颜色与拼豆不完全对应怎么办?
|
||||
- **category**: printing / 打印
|
||||
- **question_zh**: 颜色与拼豆不完全对应怎么办?
|
||||
- **question_en**: The chart color doesn't exactly match my beads. What now?
|
||||
- **answer_zh**: 使用蓝图参考颜色,结合画板工具(画笔、橡皮擦、取色器)修补;尽量优先使用已有拼豆颜色,避免新增无法购买的颜色。
|
||||
- **answer_en**: Use the blueprint as a reference and adjust with the board tools (brush, eraser, eyedropper). Prefer beads you already own; avoid adding colors you can't buy.
|
||||
|
||||
### FAQ-16 打印蓝图常见失误及建议
|
||||
- **category**: printing / 打印
|
||||
- **question_zh**: 打印蓝图有哪些常见失误?
|
||||
- **question_en**: What are common blueprint printing mistakes?
|
||||
- **answer_zh**: 图案比例错误 → 调整打印设置;纸张过小 → 分块打印;铺豆顺序混乱 → 先大面积、后细节;蓝图损坏 → 保留电子备份。
|
||||
- **answer_en**: Wrong scale → fix print settings; paper too small → print in tiles; messy beading order → lay large areas first, then details; damaged blueprint → keep a digital backup.
|
||||
|
||||
---
|
||||
|
||||
## 四、熨烫 Ironing(ironing)
|
||||
|
||||
### FAQ-17 为什么熨烫这么难?
|
||||
- **category**: ironing / 熨烫
|
||||
- **question_zh**: 为什么熨烫这么难?
|
||||
- **question_en**: Why is ironing so tricky?
|
||||
- **answer_zh**: 拼豆材料是低密度聚乙烯(LDPE),熔点 105–115°C。温度过低粘合不牢,过高会完全熔化;颜色深浅吸热速度不同,导致局部熔化不均。熨烫需要控制温度、时间、压力和移动速度四个变量。
|
||||
- **answer_en**: Beads are LDPE with a melting point of 105–115°C. Too low won't fuse, too high melts them flat; dark colors absorb heat faster, causing uneven melting. You must control temperature, time, pressure, and movement speed.
|
||||
|
||||
### FAQ-18 家用熨斗可以熨烫吗?
|
||||
- **category**: ironing / 熨烫
|
||||
- **question_zh**: 家用熨斗可以熨烫拼豆吗?
|
||||
- **question_en**: Can I use a regular household iron?
|
||||
- **answer_zh**: 可以,但有局限:蒸汽孔会导致受热不均、留下印记。建议关闭蒸汽、温度中档、持续画圈移动,不要停留在同一位置超过 3 秒。进阶选择:Cricut EasyPress 或小型压烫机,平整加热、温控精准,尤其适合细节或大作品。
|
||||
- **answer_en**: Yes, with caveats — steam holes heat unevenly and leave marks. Turn steam off, use medium heat, and keep a circular motion without pausing more than 3 seconds in one spot. For better results, use a Cricut EasyPress or mini heat press for even, precise heat.
|
||||
|
||||
### FAQ-19 熨烫介质层应该选哪种?
|
||||
- **category**: ironing / 熨烫
|
||||
- **question_zh**: 熨烫介质层(助烫纸/熨烫膜)应该选哪种?
|
||||
- **question_en**: Which ironing paper should I use — parchment or ironing film?
|
||||
- **answer_zh**: 助烫纸(Parchment Paper):哑光效果,便宜易用,适合日常练习。熨烫膜(Ironing Film):透明、高光泽,适合重要作品,可观察熨烫进度。特别注意:不要用蜡纸,会融化污染作品和熨斗。
|
||||
- **answer_en**: Parchment paper: matte finish, cheap and easy, good for practice. Ironing film: transparent with a glossy finish, lets you watch the melt, great for special projects. Never use wax paper — it melts and ruins both the piece and the iron.
|
||||
|
||||
### FAQ-20 作品容易翘曲或断裂怎么办?
|
||||
- **category**: ironing / 熨烫
|
||||
- **question_zh**: 作品容易翘曲或断裂怎么办?
|
||||
- **question_en**: My piece keeps warping or breaking. What should I do?
|
||||
- **answer_zh**: 冷却时在平面上压重物 10–20 分钟;避免单面过度熨烫;熨烫不足(豆豆仅表面粘连)时,可覆盖助烫纸局部补熨。
|
||||
- **answer_en**: Press the piece flat under a weight for 10–20 minutes while cooling; avoid over-ironing one side only; if beads are only surface-fused, re-iron that area under fresh parchment.
|
||||
|
||||
### FAQ-21 胶带法(Tape Method)有什么用?
|
||||
- **category**: ironing / 熨烫
|
||||
- **question_zh**: 胶带法(Tape Method)有什么用?
|
||||
- **question_en**: What is the Tape Method for?
|
||||
- **answer_zh**: 胶带法可避免钉板受热变形,允许使用更高温度、更长时间熨烫。步骤:贴胶带 → 翻面 → 打孔排气 → 熨烫 → 冷却压平 → 撕胶带。注意:打孔防止空气膨胀造成爆孔。
|
||||
- **answer_en**: The Tape Method protects the pegboard from heat and allows higher temperature / longer ironing. Steps: tape the beads → flip → punch holes for venting → iron → cool and press flat → remove tape. Punching holes prevents blowouts from trapped air.
|
||||
|
||||
### FAQ-22 熨烫常见问题及解决方法
|
||||
- **category**: ironing / 熨烫
|
||||
- **question_zh**: 熨烫有哪些常见问题?如何解决?
|
||||
- **question_en**: What are common ironing problems and fixes?
|
||||
- **answer_zh**: ① 爆孔(Blowouts):胶带未打孔或温度过高 → 打孔、降低温度、延长熨烫时间。② 胶带残留:温度过高或熨烫过久 → 用酒精或清洁剂擦拭。③ 作品翘曲:冷却未压平、单面受热过度 → 重新加热局部、重物压平。④ 熔化不均:熨斗移动不均、纸张皱褶、桌面不平 → 加强圆周运动、局部补熨。⑤ 作品断裂:熨烫不足 → 覆盖助烫纸重新熨烫。⑥ 表面哑/亮混合:介质层不平整、过早撕除 → 新助烫纸局部再熨,完全冷却后撕。
|
||||
- **answer_en**: ① Blowouts: tape not vented or heat too high → vent, lower heat, iron longer. ② Tape residue: too hot / too long → wipe with alcohol or cleaner. ③ Warping: cooled without pressure / one side over-heated → reheat locally and press flat. ④ Uneven melt: uneven motion, wrinkled paper, uneven surface → circle more, touch up locally. ⑤ Breakage: not fused enough → re-iron under fresh parchment. ⑥ Matte/glossy mix: uneven medium or removed too early → re-iron with new parchment, remove only after fully cooled.
|
||||
|
||||
### FAQ-23 熨烫风格选择有哪些?
|
||||
- **category**: ironing / 熨烫
|
||||
- **question_zh**: 熨烫风格有哪几种?怎么选?
|
||||
- **question_en**: What ironing styles are there and how do I choose?
|
||||
- **answer_zh**: ① 部分熨烫(Partial Melt):保留圆形孔洞,立体感强,新手易操作。② 完全平融(Flat Melt / Pixel Melt):豆豆闭合、表面平滑,视觉震撼,难度高。③ 混合风格(Back Melt):背面平融、正面保留立体,兼顾坚固与质感。
|
||||
- **answer_en**: ① Partial Melt — keeps round holes, 3D feel, beginner-friendly. ② Flat/Pixel Melt — beads fully closed into a smooth surface, striking look, harder. ③ Back Melt — flat back for strength, dimensional front for texture.
|
||||
|
||||
### FAQ-24 新手熨烫的黄金法则
|
||||
- **category**: ironing / 熨烫
|
||||
- **question_zh**: 新手熨烫有什么黄金法则?
|
||||
- **question_en**: What's the golden rule for beginner ironing?
|
||||
- **answer_zh**: 低温慢熨(Low and Slow)比高温快熨更安全;大作品分区熨烫、边缘优先;使用透明熨烫膜观察熨烫进度;冷却时保持压平。
|
||||
- **answer_en**: Low and slow beats hot and fast. Iron large pieces in sections, edges first; use transparent film to watch the melt; keep it pressed flat while cooling.
|
||||
|
||||
---
|
||||
|
||||
## 五、裱框 Framing(framing)
|
||||
|
||||
### FAQ-25 一定要买定制画框吗?
|
||||
- **category**: framing / 裱框
|
||||
- **question_zh**: 一定要买定制画框来装裱吗?
|
||||
- **question_en**: Do I need a custom frame for my bead art?
|
||||
- **answer_zh**: 不需要。市面上的「5cm 深度展示框」非常通用,性价比极高。选购时注意画框需有足够深度(立体中空框,如宜家 HOVSTA),避免挤压拼豆;背景纸建议深色以突显颜色,或同色系增加质感。
|
||||
- **answer_en**: No. A common 5cm-deep shadow-box frame is affordable and works great. Make sure it has enough depth (a hollow/deep frame like IKEA HOVSTA) so beads aren't squeezed; use a dark backing for contrast or a matching color for a richer look.
|
||||
|
||||
### FAQ-26 作品可以直接贴墙上吗?
|
||||
- **category**: framing / 裱框
|
||||
- **question_zh**: 拼豆作品可以直接贴墙上吗?
|
||||
- **question_en**: Can I hang bead art directly on the wall?
|
||||
- **answer_zh**: 可以,建议使用蓝丁胶或无痕泡沫胶,在作品背面多点固定,避免损坏豆子表面;长期暴露可能积灰,可加亚克力罩保护。想营造像素悬浮感,可在作品与背板间加小块泡沫胶。
|
||||
- **answer_en**: Yes — use Blu-Tack or foam mounting dots at multiple points on the back to avoid damaging bead surfaces. Long-term display may collect dust, so consider an acrylic cover. Add small foam pads behind the piece for a floating-pixel effect.
|
||||
|
||||
---
|
||||
|
||||
## 六、兑换码与权益 Redemption & Credits(redemption)
|
||||
|
||||
### FAQ-27 兑换码怎么使用?
|
||||
- **category**: redemption / 兑换码与权益
|
||||
- **question_zh**: 兑换码怎么使用?
|
||||
- **question_en**: How do I redeem a code?
|
||||
- **answer_zh**: 在首页/生成页点击「兑换」,输入兑换码即可将对应权益次数绑定到当前设备;兑换成功后会显示剩余次数,无需再次输入。注意:兑换码需未过期、未耗尽,且单设备绑定。
|
||||
- **answer_en**: Click "Redeem" on the home/generator page and enter your code — the credits are bound to your current device. You'll see your remaining count immediately, no re-entry needed. Codes must be valid, unused, and are device-bound.
|
||||
|
||||
### FAQ-28 兑换码可以多个设备共用吗?
|
||||
- **category**: redemption / 兑换码与权益
|
||||
- **question_zh**: 兑换码可以多个设备共用吗?
|
||||
- **question_en**: Can I use my code on multiple devices?
|
||||
- **answer_zh**: 兑换码为单设备绑定。兑换后权益次数记录在当前浏览器(localStorage)中,请在主要创作设备上兑换;如需更换设备,建议联系客服协助迁移。
|
||||
- **answer_en**: Codes are bound to one device. Credits are stored locally in your browser, so redeem on the device you'll mainly use. Contact support if you need to move credits to another device.
|
||||
|
||||
### FAQ-29 购买套餐后如何拿到兑换码?
|
||||
- **category**: redemption / 兑换码与权益
|
||||
- **question_zh**: 购买套餐后如何拿到兑换码?
|
||||
- **question_en**: How do I receive my code after purchasing a plan?
|
||||
- **answer_zh**: 支付成功后系统会自动完成兑换(自动 redeem),无需手动输入兑换码;同时订单结果页会展示兑换码与剩余次数,可截图留存。如支付未回调成功,请联系客服手动处理。
|
||||
- **answer_en**: After payment succeeds the code is redeemed automatically — no manual entry needed. The order page shows your code and remaining credits for reference. If the callback fails, contact support for manual processing.
|
||||
|
||||
### FAQ-30 权益次数是怎么扣减的?
|
||||
- **category**: redemption / 兑换码与权益
|
||||
- **question_zh**: 权益次数是怎么扣减的?
|
||||
- **question_en**: How are credits consumed?
|
||||
- **answer_zh**: 每次下载高清图纸(含 AI 生成)扣除 1 次权益;免费预览、参数调整不扣次数。扣减前会明确提示,避免误扣。剩余次数会常驻显示在顶部导航。
|
||||
- **answer_en**: Each HD pattern download (including AI generation) consumes 1 credit. Free previews and parameter tweaks never consume credits. You'll be prompted before any deduction, and remaining credits always show in the top nav.
|
||||
|
||||
---
|
||||
|
||||
## 七、AI 专区 AI Zone(ai-zone)
|
||||
|
||||
### FAQ-31 AI 拼豆专区是什么?怎么用?
|
||||
- **category**: ai-zone / AI 专区
|
||||
- **question_zh**: AI 拼豆专区是什么?怎么用?
|
||||
- **question_en**: What is the AI bead zone and how do I use it?
|
||||
- **answer_zh**: AI 专区(/chibi)提供 5 大风格(风景/人物/宠物/物品/像素二创)共 15 种细分风格:选择大类与细分 → 调整格数(48/64/80/96)与色数(16/24/32/40)→ 点击生成,AI 会为你直接产出一张拼豆图纸。生成即扣 1 次权益。
|
||||
- **answer_en**: The AI zone (/chibi) offers 5 categories (landscape / portrait / pet / object / pixel remix) with 15 sub-styles. Pick a category and sub-style, set grid size (48/64/80/96) and color count (16/24/32/40), then hit generate — AI produces a ready-to-iron bead chart. Each generation consumes 1 credit.
|
||||
|
||||
### FAQ-32 AI 生成前需要准备什么?生成的图纸能用吗?
|
||||
- **category**: ai-zone / AI 专区
|
||||
- **question_zh**: AI 生成前需要准备什么?生成的图纸能用吗?
|
||||
- **question_en**: What do I need before generating with AI? Is the output usable?
|
||||
- **answer_zh**: 需要已兑换的权益(≥1 次)。AI 会返回带色号标注的图纸,可照图买豆、直接打印/下载,也支持微调格数与色数重新生成。建议描述场景关键词(如「童话森林,晨雾中的小屋」)以获得更贴合需求的效果。
|
||||
- **answer_en**: You need at least 1 credit. AI returns a bead chart with color codes that you can print or download directly; you can also tweak grid size / color count and regenerate. Descriptive keywords (e.g. "fairy forest cottage in morning mist") get closer to what you want.
|
||||
|
||||
---
|
||||
|
||||
## 八、平台与使用 Platform & Usage(product)
|
||||
|
||||
### FAQ-33 平台收费吗?需要注册吗?
|
||||
- **category**: product / 平台与使用
|
||||
- **question_zh**: 平台收费吗?需要注册吗?
|
||||
- **question_en**: Is the platform free? Do I need to register?
|
||||
- **answer_zh**: 完全免费使用、无需注册。图片处理在浏览器本地完成,你的图片不会上传服务器。只有「高清图纸下载」和「AI 生成」消耗兑换码权益。
|
||||
- **answer_en**: Completely free, no registration required. Images are processed locally in your browser and never leave your device. Only HD downloads and AI generation consume credits.
|
||||
|
||||
### FAQ-34 代理合作怎么开展?
|
||||
- **category**: product / 平台与使用
|
||||
- **question_zh**: 代理合作怎么开展?
|
||||
- **question_en**: How does agent/affiliate cooperation work?
|
||||
- **answer_zh**: 平台提供面向微商/手工博主的代理套餐(¥139/200 次、¥299/500 次、¥499/1000 次,单价低至 ¥0.5/次),支持批量采购并分发给学员/客户赚取差价;代理可查看名下兑换码、剩余库存与核销记录。联系客服提交代理合作申请即可开通。
|
||||
- **answer_en**: We offer affiliate plans for resellers and craft bloggers (¥139/200 uses, ¥299/500 uses, ¥499/1000 uses, down to ¥0.5/use) for bulk purchase and resale at a margin. Agents can view their codes, stock, and redemption history. Contact support to apply.
|
||||
|
||||
### FAQ-35 图纸可以导成什么格式?如何高质量打印?
|
||||
- **category**: product / 平台与使用
|
||||
- **question_zh**: 图纸可以导成什么格式?如何高质量打印?
|
||||
- **question_en**: What export formats are available? How do I print at high quality?
|
||||
- **answer_zh**: 图纸支持高清 PNG/PDF 导出(兑换权益后);PDF 建议 300 DPI、标准 A4 或更大纸张打印,必要时分块打印。打印后把蓝图放在拼板下方(透明板)或旁边参考,先铺大面积色块、再铺细节区域,每完成一个区域确认颜色与图纸一致。
|
||||
- **answer_en**: Export HD PNG/PDF after redemption. For PDF, print at 300 DPI on A4 or larger, tiling if needed. Place the blueprint under a transparent pegboard or beside it; lay large color areas first, then details, checking each section as you go.
|
||||
|
||||
---
|
||||
|
||||
## 附录:分类统计
|
||||
|
||||
| 分类 | 标签 | 条数 |
|
||||
|---|---|---|
|
||||
| 选豆 | bead-selection | 5 |
|
||||
| 配色与图纸生成 | color-matching | 6 |
|
||||
| 打印 | printing | 5 |
|
||||
| 熨烫 | ironing | 8 |
|
||||
| 裱框 | framing | 2 |
|
||||
| 兑换码与权益 | redemption | 4 |
|
||||
| AI 专区 | ai-zone | 2 |
|
||||
| 平台与使用 | product | 3 |
|
||||
| **合计** | — | **35** |
|
||||
|
||||
> 竞品实操 FAQ 24 条(§一–§五)+ 我方产品特有 FAQ 11 条(§六–§八),总计 **35 条**,满足 20+ 要求。en 字段为 i18n 预留,供 T-106 组件按语言渲染。
|
||||
@@ -0,0 +1,149 @@
|
||||
# GAP-PRIORITY · 竞品外围 12 类缺口落地优先级评估(V1.2)
|
||||
|
||||
> **任务**: T-124 | 产出角色: Oracle-Architect-Agent | 日期: 2026-08-14
|
||||
> **输入依据**:
|
||||
> - `docs/NAV-ALIGNMENT.md`(导航对齐决策:对齐 4 / 暂缓 4 / 不做 1)
|
||||
> - `docs/BUSINESS-MODEL.md`(商业模式:免费 12 项 + 付费 9 项边界)
|
||||
> - `docs/I18N-ROI.md`(i18n 结论:zh-tw 扩展、ja 暂缓)
|
||||
> - `docs/ANIMATION-PLAN.md`(动画决策:P0 纯 CSS 零依赖)
|
||||
> - `docs/RELEASE-V1.1.md`(V1.1 范围:色号表×6 / showcase / library / help 已交付)
|
||||
> - `docs/ROADMAP.md`(V1.2 账号版范围:账号/云端同步/素材社区/代理管理)
|
||||
> - `competitor-analysis/pixelbeads-analysis.md` §7(20+ 项差距清单)、`pixelbeads-zh-detail.md` §8(Top10 优先级)
|
||||
> - 看板实时状态:T-090~T-111 全部验收通过(V1.1 交付完成);T-113~T-123 为 Spider 补爬与产品评估任务(开发中)
|
||||
|
||||
---
|
||||
|
||||
## 0. 结论速览
|
||||
|
||||
| 维度 | 结果 |
|
||||
|---|---|
|
||||
| **12 类缺口评估** | 落地 7 · 借鉴 3 · 忽略 1 · 已落地 1 |
|
||||
| **V1.2 推荐落地** | **P0 共 2 项**(⑦法律/关于页、⑤作品详情页) |
|
||||
| **P1 落地** | 4 项(②blog 矩阵·轻量、⑫JSON-LD 全量、⑩zh-tw、③帮助子页化) |
|
||||
| **P2 条件落地** | 1 项(⑥showcase 主题合集) |
|
||||
| **借鉴/忽略** | ①/perler-beads、⑧色号变体 2 页、⑪blog 文章详情 → 借鉴;④apps 生态页 → 忽略;⑨图纸库页 → V1.1 已交付 |
|
||||
| **一致性校验** | 12/12 与既有决策零冲突(NAV-ALIGNMENT / BUSINESS-MODEL / I18N-ROI 全对齐) |
|
||||
|
||||
> 核心原则:**V1.2 是账号版**(ROADMAP §3),缺口落地必须优先服务于「素材社区(P0)+ 合规(V1.0 遗留阻塞项 #5)」两条主线,而非机械对齐竞品全量页面。SEO 内容型缺口(blog/详情页/神秘页)多数顺延至 V2.0 英文站。
|
||||
|
||||
---
|
||||
|
||||
## 1. 逐缺口评估表(12 类)
|
||||
|
||||
> 评估口径:竞品价值(pixel-beads 实测证据)|我方现状(源码/看板实读)|落地成本|收益(SEO/留存/变现)|推荐动作。
|
||||
|
||||
| # | 缺口 | 竞品价值(证据) | 我方现状 | 落地成本 | 收益 | 推荐动作 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| ① | **/perler-beads 神秘页** | 拼豆通用关键词 SEO 落地页,仅默认(en)语言存在(zh-detail §1.1「⭐新发现」) | 无;en 关键词覆盖归 V2.0 英文站(ROADMAP §4) | 低(单页内容) | 低(en 流量 V2.0 才考核:自然访问 ≥10%) | **借鉴**(en SEO 页模式;V2.0 落地,V1.2 不做) |
|
||||
| ② | **blog 内容矩阵** | `/blog` 全语言 + 250+ 篇实操知识(熨烫温度/爆孔/选豆,analysis §2.4),SEO 流量主力 | 无 blog;已有 FAQ-DATA.md 35 条双语言(T-107)+ /help 页(T-106) | 中(内容生产是瓶颈) | 高(长尾流量/留存) | **落地(轻量版)**:blog 首页 + 首批文章以 FAQ-DATA 35 条与 SEO 关键词为种子(P1) |
|
||||
| ③ | **帮助细分页** | `/help/perler-bead-art`、`/help/perler-bead-pattern-generator` 分工具子页(zh-detail §1.1) | /help 单页 FAQ 35 条 8 分类(T-106/107 已交付) | 低(复用 FAQ 数据拆路由) | 中(分工具长尾 SEO + 使用引导) | **落地**:按 NAV-ALIGNMENT P2-2「帮助中心子页化(按需)」条件已满足(FAQ 超一屏)(P1) |
|
||||
| ④ | **apps 生态页** | `/apps` + android/ios/chrome-extension 三端下载页(zh-detail §1.1) | 纯 Web,无客户端产品;PWA 评估 T-105 已产出(V2.0 立项) | 高(需配套产品) | 无(无客户端无从变现) | **忽略**(NAV-ALIGNMENT 决策「不做」;待 PWA/客户端立项再评估) |
|
||||
| ⑤ | **作品详情页** | `/perler-bead-pattern/<slug>-pt_<id>` 单作品详情 + JSON-LD + 作者页(analysis §1.1,zh-detail §1.4) | showcase_works 表 + 发布/列表/SEO 接口已建(T-099~T-102),/showcase 列表页已交付(T-097/098);**缺详情页路由与内容** | 中(详情路由 + slug 化 + 复用 T-101 meta) | 高(UGC 长尾 SEO + 素材社区 P0 天然组成) | **落地**:V1.2 素材社区(ROADMAP P0)的必备组成(P0) |
|
||||
| ⑥ | **showcase 主题合集** | `/showcase/christmas-perler-bead-patterns`、`/showcase/pokemon-champions-…` 主题合集页(zh-detail §1.1「⭐新发现」) | /showcase 已有 7 分类标签前端筛选(T-098);无独立主题合集路由 | 低(复用作品数据按分类/标签聚合) | 中(节日/IP 长尾,依赖作品量) | **落地(条件)**:作品数据积累后按标签建合集路由(P2,依赖 V1.2 素材社区内容量) |
|
||||
| ⑦ | **法律/关于页** | `/about`、`/contact`、`/privacy-policy`、`/terms-of-service` 四页(zh-detail §1.1,I18N-ROI §2.2 指出缺信任页是转化链断档) | **无任何法律/关于页**;ROADMAP V1.0 遗留阻塞项 #5「用户协议与版权声明」未清;AgencyModal 代理合作入口已有 | 低(静态内容页) | 高(合规刚需 + 信任 + 代理合作落地页) | **落地**:清 ROADMAP V1.0 阻塞项 #5,一次补齐 privacy/terms/about/contact(P0) |
|
||||
| ⑧ | **色号表缺口 2 页** | 竞品 10 品牌变体含 Hama-Midi / Perler-Midi / Artkal-M-2.6mm 迷你豆(zh-detail §3.1 `kl` 映射表) | 我方 6 品牌(mard 221 / artkal-c 174 / perler 103 / hama 92 / pyssla 18 / nabbi 30,T-092)已交付;缺 Midi/2.6mm 变体页 | 中(需补 Midi/2.6mm 色号数据) | 低(窄长尾,迷你豆细分市场尚小) | **借鉴**:等 T-120 爬虫数据结论,数据齐备再补 2.6mm 变体页(P2) |
|
||||
| ⑨ | **图纸库页** | `/perler-bead-pattern` 图纸库入口(NAV-ALIGNMENT §1 #7) | **已交付**:/library 路由 + 列表页(T-108 验收通过,复用 showcase 数据源) | — | — | **已落地**(V1.1 交付,V1.2 无新动作;后续可挂作品详情链接增强) |
|
||||
| ⑩ | **6 语言首页** | 竞品 7 语言(zh/zh-tw/ja/vi/ko/de + en 默认),zh-tw 仅 16 URL 是最弱档(zh-detail §1.2) | 我方 zh-CN + en 各 349 key(I18N-ROI §3) | zh-tw ~1 人日/¥0(I18N-ROI §4.1) | 中(台湾 SEO 占位,竞品该语言最弱) | **落地 zh-tw**(I18N-ROI 已决策);ja/vi/ko/de 不落地(支付链路未通/竞品已深耕)(P1) |
|
||||
| ⑪ | **blog 文章详情** | `/blog` 文章详情页(每篇独立 URL) | 无 | 中(跟随 ② blog 矩阵) | 中(依赖内容生产) | **借鉴**:随 ② 落地后自然承接;V1.2 不单独立项(P2) |
|
||||
| ⑫ | **JSON-LD 全量** | 竞品 6 类 schema:Organization/SoftwareApplication/HowTo/Offer/Person/ContactPoint(zh-detail §0.10) | 仅 /color-chart(CollectionPage+ItemList,T-094)与 /showcase(CollectionPage,T-101) | 低(首页注入 Organization/WebSite/SoftwareApplication/HowTo) | 中(结构化数据提升 SERP 展示) | **落地**:首页 + 生成器补 Organization/SoftwareApplication/HowTo,复用 T-094 注入模式(P1) |
|
||||
|
||||
**动作统计:落地 7 · 借鉴 3 · 忽略 1 · 已落地 1**
|
||||
|
||||
---
|
||||
|
||||
## 2. V1.2 优先级排序
|
||||
|
||||
> 优先级定义沿用 PRD/ROADMAP:**P0** = V1.2 必须上线;**P1** = V1.2 内争取;**P2** = 观察数据后进入后续版本。V1.2 主题为「账号版」(ROADMAP §3:账号体系/云端同步/素材社区/代理管理),以下排序以服务该主题为准绳。
|
||||
|
||||
### 2.1 P0(必须上线,共 2 项)
|
||||
|
||||
| 排名 | 缺口 | 理由 |
|
||||
|---|---|---|
|
||||
| **P0-1** | ⑦ 法律/关于页(privacy / terms / about / contact) | ① ROADMAP V1.0 阻塞项 #5「用户协议与版权声明」为上线遗留欠账,V1.2 账号体系上线后**隐私政策成为硬合规前提**(收集手机号/云端同步数据);② 成本极低(静态页);③ 代理合作(AGENT.md)缺落地页入口,contact/about 补齐信任与转化链(I18N-ROI §2.2 实证:信任页断档=转化断档) |
|
||||
| **P0-2** | ⑤ 作品详情页 | V1.2 素材社区(ROADMAP §3.2 项3)是 P0,「用户分享图纸 → 图纸页」天然需要**详情页 + slug URL + 分享链接**。底层已就绪(showcase_works 表 + T-099~T-102 接口 + T-101 SEO meta),只差详情路由与渲染,成本集中在内容而非基建;落地即同时拿到 UGC 长尾 SEO 与社区闭环 |
|
||||
|
||||
### 2.2 P1(V1.2 内争取,共 4 项)
|
||||
|
||||
| 排名 | 缺口 | 理由 |
|
||||
|---|---|---|
|
||||
| **P1-1** | ② blog 内容矩阵(轻量版) | 竞品 250+ 篇是 SEO 流量主力,我方 FAQ-DATA 35 条已具备种子内容;轻量落地(blog 首页 + 首批 10~20 篇)成本可控,与 P0-2 作品详情页共享内容生产管线。全量内容矩阵(250+ 篇)不承诺 |
|
||||
| **P1-2** | ⑫ JSON-LD 全量 | 成本最低(首页注入 3~4 类 schema,复用 T-094 注入模式),收益确定(SERP 富展示);与 P0-2 详情页 JSON-LD 一并做,边际成本趋零 |
|
||||
| **P1-3** | ⑩ zh-tw 语言首页 | I18N-ROI 已正式决策「扩展」(~1 人日/¥0),竞品 zh-tw 仅 16 URL 是我方竞争窗口;V1.1 未及落地,顺延 V1.2 执行(随新页面文案一起简转繁) |
|
||||
| **P1-4** | ③ 帮助细分页 | NAV-ALIGNMENT P2-2 已定义「帮助中心子页化(按需)」且条件已满足(FAQ 35 条超一屏);复用 FAQ-DATA 按分类/工具拆 `/help/:tool`,成本低、SEO 长尾直接 |
|
||||
|
||||
### 2.3 P2(条件触发,共 1 项落地 + 3 项借鉴)
|
||||
|
||||
| 缺口 | 触发条件 | 说明 |
|
||||
|---|---|---|
|
||||
| ⑥ showcase 主题合集 | V1.2 素材社区作品量 > 50 件且标签数据充分 | 复用 /showcase 分类数据建 christmas/pokemon 式合集路由,纯内容聚合零新基建 |
|
||||
| ① /perler-beads 神秘页 | V2.0 英文站立项(ROADMAP §4.2 项4) | en 关键词页归属英文站统一规划,V1.2 不建 |
|
||||
| ⑧ 色号变体 2 页 | T-120 爬虫数据结论 + Midi/2.6mm 色号数据齐备 | 迷你豆细分市场尚未验证,数据先行、页面随数据 |
|
||||
| ⑪ blog 文章详情 | ② blog 矩阵落地后 | 详情路由是 ② 的随附能力,不单独立项 |
|
||||
|
||||
### 2.4 忽略 / 已落地
|
||||
|
||||
| 缺口 | 决策 | 依据 |
|
||||
|---|---|---|
|
||||
| ④ apps 生态页 | **忽略** | NAV-ALIGNMENT §2 #8 决策「不做」(无客户端产品);PWA 评估 T-105 建议 V2.0 立项,届时单独立项补入口 |
|
||||
| ⑨ 图纸库页 | **已落地** | /library 已于 V1.1(T-108)交付,V1.2 无新动作 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 每项落地的依赖
|
||||
|
||||
| 缺口 | 依赖 | 现状 | 就绪度 |
|
||||
|---|---|---|---|
|
||||
| ⑦ 法律/关于页 | 内容源(隐私/条款文案,需结合账号体系数据范围);T-123 合规页面清单(开发中) | ROADMAP V1.0 阻塞项 #5 文案素材存在(PRD 风险 #5) | 高(文案可先静态落盘,账号上线后补数据范围条款) |
|
||||
| ⑤ 作品详情页 | **showcase_works 表**(已建 T-099)+ 发布/列表/SEO 接口(T-100/101/102)+ slug 生成与详情路由 | 全部接口已验收,仅缺前端详情路由与 slug 规则 | **高**(基建全就绪,剩 UI) |
|
||||
| ② blog 矩阵(轻量) | 内容生产(FAQ-DATA 35 条为种子)+ T-122 SEO 内容矩阵对标建议(开发中) | FAQ-DATA.md 双语言 35 条已交付 | 中(内容生产是唯一瓶颈) |
|
||||
| ⑫ JSON-LD 全量 | 首页/生成器 schema 数据(Organization/WebSite/SoftwareApplication/HowTo) | T-094 注入模式已实现,可复用 | 高 |
|
||||
| ⑩ zh-tw | i18n 框架(349 key×2 已就绪)+ 路由前缀机制(I18N-ROI §7.3 预留) | 框架零重构即可扩展(I18N-ROI §3) | 高 |
|
||||
| ③ 帮助子页化 | FAQ-DATA.md 分类数据(8 分类)+ /help 现有页 | T-106/107 已交付 | 高 |
|
||||
| ⑥ 主题合集 | showcase_works 作品量 + 标签数据积累 | V1.2 素材社区 P0 提供内容 | 低(等数据) |
|
||||
| ⑧ 色号变体 2 页 | T-120 爬虫数据 + Midi/2.6mm 色号源 | 爬虫任务开发中 | 低 |
|
||||
| ① /perler-beads | V2.0 英文站 | — | 低(V2.0 再评估) |
|
||||
| ⑪ blog 文章详情 | ② blog 矩阵先行 | — | 中(跟随 ②) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 与既有决策的一致性校验
|
||||
|
||||
> 逐项核对 NAV-ALIGNMENT / BUSINESS-MODEL / I18N-ROI / ROADMAP,12 项缺口 **零冲突**。详见下表。
|
||||
|
||||
| # | 缺口 | NAV-ALIGNMENT | BUSINESS-MODEL | I18N-ROI | ROADMAP | 校验结论 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| ① | /perler-beads | 未涉及(竞品主导航无此项,页脚/内容页) | 不冲突(en SEO 内容) | 一致(en 是 V2.0 重心) | V2.0 项4 多语言/en 站 | ✅ 无冲突(顺延 V2.0) |
|
||||
| ② | blog 矩阵 | 未涉及(竞品主导航无 blog,仅页脚) | **一致**(F-12 帮助/FAQ 免费,blog 属免费内容获客,B 原则 F-01~F-12 免费) | 不冲突 | V1.2 素材社区内容沉淀可复用 | ✅ 无冲突 |
|
||||
| ③ | 帮助子页化 | **一致**(P2-2「帮助中心子页化(按需)」已定义) | **一致**(F-12 帮助中心免费) | 不冲突 | 不冲突 | ✅ 无冲突 |
|
||||
| ④ | apps 生态页 | **一致**(§2 #8 决策「不做」) | 不冲突 | 不冲突 | PWA 归 V2.0(T-105) | ✅ 无冲突(沿用忽略) |
|
||||
| ⑤ | 作品详情页 | **一致**(§2 #5 作品展示 P1 建 /showcase;详情页是 /showcase 延伸,不新增导航项) | 一致(社区 UGC 免费分享,符合 F-11 分享 URL 免费) | 不冲突 | **一致**(V1.2 素材社区 P0「图纸页+作者页」) | ✅ 无冲突 |
|
||||
| ⑥ | 主题合集 | **一致**(§2 #6 主题拼豆已用 chibi 分类承载;showcase 合集是内容聚合不冲突) | 一致(免费内容) | 不冲突 | 素材社区分类/搜索支持 | ✅ 无冲突 |
|
||||
| ⑦ | 法律/关于页 | 未涉及(不在导航 9 项内) | 一致(静态信任页,无变现冲突) | **一致**(I18N-ROI 指出 zh-tw 缺 about/contact 是信任缺口) | **一致**(清 V1.0 阻塞项 #5) | ✅ 无冲突(P0 最高优先级) |
|
||||
| ⑧ | 色号变体 2 页 | 未涉及 | **一致**(F-09 色号表浏览免费,新增变体页仍免费) | 不冲突 | 不冲突 | ✅ 无冲突 |
|
||||
| ⑨ | 图纸库页 | **一致**(§2 #7 P1 建 /library 已交付) | 一致 | 不冲突 | V1.1 已交付 | ✅ 无冲突(已落地) |
|
||||
| ⑩ | 6 语言首页 | 未涉及 | 不冲突(免费核心不受支付影响) | **严格一致**(zh-tw 扩展 / ja 暂缓,逐条采纳 I18N-ROI 决策) | V2.0 多语言(zh-tw 作为低成本例外顺延 V1.2) | ✅ 无冲突 |
|
||||
| ⑪ | blog 文章详情 | 未涉及 | 一致 | 不冲突 | 跟随 ② | ✅ 无冲突 |
|
||||
| ⑫ | JSON-LD 全量 | 未涉及 | 一致 | 不冲突 | V1.1 已有部分(T-094/101) | ✅ 无冲突 |
|
||||
|
||||
### 4.1 风险与注意(落地时需遵守既有纪律)
|
||||
|
||||
1. **复用而不是重建**:⑤⑥ 全部建立在已交付的 showcase_works 数据与接口之上,禁止另起数据源;⑬ JSON-LD 复用 T-094 注入模式。
|
||||
2. **导航不膨胀**:NAV-ALIGNMENT 定稿为 7 项,blog/作品详情/法律页均**不进主导航**(页脚/页面内链承载),避免破坏已验收的导航结构。
|
||||
3. **变现边界不漂移**:②③⑦⑩⑫ 全部为免费内容(对应 BUSINESS-MODEL F-09/F-12),不得在内容页引入付费墙;付费只走兑换码模块(P-01~P-09)。
|
||||
4. **占位不允许裸链接**(NAV-ALIGNMENT §5 教训):V1.2 新页面一旦入导航必须有真实内容,dropdown 子项全部指向存在路由。
|
||||
5. **不动算法/付费逻辑**:本文档只产出评估;实施时(尤其 ⑤ 详情页复用 T-099~T-102 接口)不得触碰 `lib/` 管线与 codes 扣费逻辑。
|
||||
|
||||
---
|
||||
|
||||
## 5. 回报口径
|
||||
|
||||
| 项 | 结果 |
|
||||
|---|---|
|
||||
| P0 项数量 | **2**(⑦法律/关于页、⑤作品详情页) |
|
||||
| 推荐落地项数量 | **7**(P0×2 + P1×4 + P2 条件×1;借鉴 3 · 忽略 1 · 已落地 1) |
|
||||
| 文档路径 | `D:\拼豆\docs\GAP-PRIORITY.md` |
|
||||
| 一致性校验 | 12/12 无冲突(与 NAV-ALIGNMENT / BUSINESS-MODEL / I18N-ROI / ROADMAP 全对齐) |
|
||||
|
||||
---
|
||||
|
||||
*文档完。评估依据全部来自 `competitor-analysis/pixelbeads-analysis.md` §7、`pixelbeads-zh-detail.md` §8/§1.1、`docs/` 既有决策文档与 taskboard 实时验收状态,无推断项。V1.2 落地以本文 §2 优先级为准,P2 条件项以数据积累为触发。*
|
||||
@@ -0,0 +1,174 @@
|
||||
# PERLER LAB · i18n 扩展 ROI 分析报告(zh-tw / ja)
|
||||
|
||||
> 任务: T-103 | 产出角色: PM-Agent | 日期: 2026-08-14
|
||||
> 数据来源: `competitor-analysis/pixelbeads-zh-detail.md`(2026-08-14 爬取)、`competitor-analysis/pixelbeads-analysis.md`(2026-08-13 爬取)、`docs/ROADMAP.md`、前端 i18n 模块实测
|
||||
> 结论预览: **zh-tw 建议扩展(低成本顺水推舟);ja 建议暂缓(支付/本地化链路未通,ROI 为负)。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
我方已具备双语框架(`perler-lab/src/i18n`,zh-CN + en,349 个文案 key/语言,165 项单测通过)。本次评估是否在近期扩展 **zh-tw(繁体中文)** 与 **ja(日文)** 两个语言,作为对竞品 7 语言矩阵的追赶动作。
|
||||
|
||||
评估口径:以「翻译工作量 / 页面覆盖数」为成本轴,以「流量规模 / 市场规模 / 竞争窗口 / 商业化可行性」为收益轴,给出每语言的扩展/暂缓决策、理由与建议执行时间点。
|
||||
|
||||
---
|
||||
|
||||
## 2. 竞品 i18n 覆盖现状(sitemap 实测证据)
|
||||
|
||||
### 2.1 7 语言 URL 分布(157 URL 全量 sitemap)
|
||||
|
||||
| 语言 | 路由 | URL 数 | 色号表×6 | about/contact | showcase 合集 | 覆盖评价 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 简体中文 | `/zh` | **35** | ✅(但未入 sitemap) | ✅ | ✅ | 最完整,重点市场 |
|
||||
| 日文 | `/ja` | **25** | ✅ | ✅ | ✅ | 次完整 |
|
||||
| 越南文 | `/vi` | **25** | ✅ | ✅ | ✅ | 次完整 |
|
||||
| 韩文 | `/ko` | **23** | ✅ | ⚠️ 仅 contact | ❌ | 中等 |
|
||||
| 德文 | `/de` | **23** | ✅ | ✅ | ❌ | 中等 |
|
||||
| 英文(默认) | `/` | **22** | ✅ | ✅ | ✅ | 基础完整 |
|
||||
| 繁体中文 | `/zh-tw` | **16** | ❌ 无 | ❌ 无 | ❌ 无 | **明显短板** |
|
||||
|
||||
### 2.2 zh-tw 缺口明细(§1.2 证据)
|
||||
|
||||
- **6 个色号表页全部缺失**(MARD 291 / Perler 57 / Hama 53 / Artkal 159 / IKEA Pyssla / Nabbi)→ 直接损失台湾长尾 SEO 流量。
|
||||
- **about / contact 缺失** → 信任与转化链路断档。
|
||||
- **showcase 圣诞/宝可梦合集缺失** → 内容流量缺口。
|
||||
- 竞品 `next-intl` 声明 7 语言,但 **zh-tw 实际建设滞后**,仅 16 个 URL,是竞品 7 语言中最薄弱的一档。
|
||||
|
||||
> **解读**: 竞品自己也没把 zh-tw 做厚。这意味着 zh-tw 市场不存在「先发压制」——我方现在跟进即可拿到对等甚至更好的 SEO 位置,竞争窗口是敞开的。
|
||||
|
||||
### 2.3 ja 覆盖评价
|
||||
|
||||
竞品 ja 25 URL 且色号表全齐,说明其视日本为正式市场。日本"アイロンビーズ(熨斗珠)"是成熟手工品类,搜索量大、有社区生态,**竞品在 ja 上的布局比 zh-tw 深得多**。
|
||||
|
||||
---
|
||||
|
||||
## 3. 我方 i18n 现状(前置能力盘点)
|
||||
|
||||
| 项 | 现状 | 影响 |
|
||||
|---|---|---|
|
||||
| i18n 框架 | 零依赖 runtime 已完成(`locale.ts` + `I18nProvider` + `useT`),localStorage 记忆、导航语言检测、参数插值、fallback 链 | **扩展语言无需重写框架**,成本只在文案与路由 |
|
||||
| 已支持语言 | zh-CN + en,**各 349 key**,双语测试全过 | 已有 en 全量文案可复用结构 |
|
||||
| 当前页面 | 首页(/) + /chibi + 弹窗;V1.1 新增色号表×6、showcase、图纸库、帮助中心 | 扩语言时需连带覆盖新增页面文案 |
|
||||
| 路由 | 无语言前缀(单一站点) | 若扩语言需引入 `/zh-tw/`、`/ja/` 前缀路由与 hreflang,属一次性改造 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 成本评估(翻译工作量 / 页面数)
|
||||
|
||||
### 4.1 zh-tw
|
||||
|
||||
| 成本项 | 估算 |
|
||||
|---|---|
|
||||
| 文案转换 | **349 key 简→繁**,可半自动转换 + 人工术语校对(拼豆→拼豆、兑换码→兌換碼、图纸→圖紙、下载→下載),**约 0.5–1 人日** |
|
||||
| 术语差异 | 极小(同源简体/繁体,仅用词习惯微调:如「生成」不变、「预览→預覽」) |
|
||||
| 页面改造 | 新增 `/zh-tw/` 前缀路由 + 色号表等 V1.1 页面同套文案;路由机制为一次性工作 |
|
||||
| 外部费用 | **≈ ¥0**(无专业翻译需求,AI 辅助 + 人工校对即可) |
|
||||
| 合计 | **约 1 人日,零外部成本** |
|
||||
|
||||
### 4.2 ja
|
||||
|
||||
| 成本项 | 估算 |
|
||||
|---|---|
|
||||
| 文案翻译 | 349 key **全量日译** + V1.1 新增页面文案 + FAQ/帮助内容,**约 3–5 人日**(含专业校对,日文 UI 质量要求高) |
|
||||
| 术语本地化 | 拼豆→アイロンビーズ、兑换码→引換コード、下载→ダウンロード,需与日本社区习惯对齐 |
|
||||
| SEO 内容 | 色号表 6 页、FAQ 需日文化(竞品即如此投入),内容量再 +1–2 人日 |
|
||||
| 外部费用 | **约 ¥1,500–3,000**(专业翻译或外包校对) |
|
||||
| 支付/渠道适配 | 兑换码支付依赖微信生态,**日本用户无微信支付** → 需本地支付或改走纯免费引流,链路未定义 |
|
||||
| 合计 | **约 5–7 人日 + ¥1,500–3,000 外部成本**,且伴随商业化前提未满足的隐性成本 |
|
||||
|
||||
### 4.3 成本对比小结
|
||||
|
||||
| 维度 | zh-tw | ja |
|
||||
|---|---|---|
|
||||
| 人力 | ~1 人日 | ~5–7 人日 |
|
||||
| 外部资金 | ~¥0 | ~¥1,500–3,000 |
|
||||
| 页面覆盖 | 全部现有+V1.1 页面 | 全部现有+V1.1 页面+SEO 内容 |
|
||||
| 支付适配 | 未涉及(微信支付在台湾亦不通,但免费核心不受影响) | **必须解决**(日本无微信支付) |
|
||||
|
||||
---
|
||||
|
||||
## 5. 收益评估(流量 / 市场 / 竞争窗口 / 商业化)
|
||||
|
||||
### 5.1 市场体量
|
||||
|
||||
| 维度 | zh-tw(台湾) | ja(日本) |
|
||||
|---|---|---|
|
||||
| 人口/潜在用户 | ~2,300 万,手作/DIY 受众稳定 | ~1.2 亿,手作市场成熟,アイロンビーズ有长期社区 |
|
||||
| 拼豆搜索量 | 「拼豆 圖案」「拼豆 製作」量级中等 | 「アイロンビーズ 図案」量级大,品类词稳定 |
|
||||
| 竞品投入 | 16 URL(最弱)→ **我方窗口敞口** | 25 URL(正式投入)→ **已有先发优势,竞争成本高** |
|
||||
| 付费场景 | 台湾用户多走淘宝/代购/闲鱼(LAUNCH 渠道可覆盖) | 无微信支付,兑换码链路不通;需纯免费或本地支付改造 |
|
||||
| ROI 评估 | **中收益 / 极低成本** → 正向 | 潜在高收益 / 成本高 + 支付前提未通 → **现阶段负向** |
|
||||
|
||||
### 5.2 与我方战略的契合度
|
||||
|
||||
- 我方 `ROADMAP.md` 将「多语言」排在 **V2.0(半年后)**,且 V2.0 的成功指标要求「英文站自然访问 ≥10%」——官方规划的重心是 **en**,zh-tw/ja 未列入近期排期。
|
||||
- 我方当前优先级是**中国区商业模式验证**(首月转化率、AI 占比等北极星指标),不应被多语言工程稀释核心人力。
|
||||
- zh-tw 因**成本极低**,可作为一种「低成本 SEO 占位」顺带完成,不影响主线;ja 则显著挤占资源且商业化前提未满足。
|
||||
|
||||
---
|
||||
|
||||
## 6. ROI 对比与决策
|
||||
|
||||
| 语言 | 成本 | 收益 | 竞争窗口 | 商业化前提 | **决策** |
|
||||
|---|---|---|---|---|---|
|
||||
| **zh-tw** | ~1 人日 / ~¥0 | 中(台湾长尾 SEO + 品牌占位) | 敞开(竞品仅 16 URL) | 不阻塞免费核心 | **✅ 扩展(低成本执行)** |
|
||||
| **ja** | ~5–7 人日 / ¥1,500+ | 高潜(日本成熟市场) | 已收窄(竞品 25 URL) | **未满足(无支付/兑换码链路)** | **⏸ 暂缓(条件触发再启)** |
|
||||
|
||||
### 决策依据
|
||||
|
||||
**zh-tw → 扩展**
|
||||
1. 简繁转换半自动,349 key 成本约 1 人日,几乎不占用主线资源。
|
||||
2. 竞品 zh-tw 建设最弱(16 URL、无色号表、无 about/contact),我方以完整色号表 + 全部页面入场即可拿到对等乃至更好的台湾 SEO 位。
|
||||
3. 台湾用户可经淘宝/闲鱼/代购渠道购买兑换码(LAUNCH.md 已定义),免费核心(生成/预览/备料)不受支付影响,先圈流量后议变现。
|
||||
4. 与 V1.1 新增页面(色号表×6 / showcase / 帮助中心)一同落地,边际成本最低。
|
||||
|
||||
**ja → 暂缓**
|
||||
1. 兑换码商业模式强依赖微信支付,日本市场支付/渠道链路未定义——**流量进来也无法变现**,ROI 为负。
|
||||
2. 竞品已在 ja 正式投入(25 URL + 全色号表),我方以弱姿态进入难占优,且需要日文 SEO 内容体系(额外 1–2 人日),资源投入与收益不对等。
|
||||
3. 日文翻译质量门槛高,贸然上线劣质日文会损害品牌,不如不做。
|
||||
4. `ROADMAP.md` 将多语言排在 V2.0(en 优先),ja 应顺延至该阶段统一规划。
|
||||
|
||||
---
|
||||
|
||||
## 7. 执行建议与时间点
|
||||
|
||||
### 7.1 zh-tw 扩展建议执行方案
|
||||
|
||||
| 项 | 建议 |
|
||||
|---|---|
|
||||
| 时间点 | **V1.1 随新增页面(色号表×6 / showcase / 帮助中心)一并落地**,或中国区转化率达标(≥3%)后 2 周内启动 |
|
||||
| 范围 | 全部现有 + V1.1 页面文案简→繁;新增 `/zh-tw/` 路由前缀 + hreflang + 独立 sitemap |
|
||||
| 术语 | 人工校对台湾用词(图纸/圖紙、兑换/兌換、备料/備料),对齐台湾拼豆圈习惯 |
|
||||
| 验收 | 349 key 全覆盖、台湾用词抽查 ≥95% 通过、hreflang 与 sitemap 生效 |
|
||||
| 预估工作量 | **1–1.5 人日**(前端 + 内容校对) |
|
||||
|
||||
### 7.2 ja 暂缓 + 重启条件
|
||||
|
||||
| 触发条件(任一满足即重启评估) | 说明 |
|
||||
|---|---|
|
||||
| ① V2.0 多语言规划正式立项(ROADMAP §4.2 项4) | 与 en 统一规划,共享 i18n 重构成果 |
|
||||
| ② 日本/海外支付或渠道方案确定(如接 Stripe / 本地支付代收) | 商业化链路打通是 ja 落地的前置条件 |
|
||||
| ③ 竞品 ja 站出现重大功能升级(monitor.js 双指纹告警触发) | 需跟进竞争态势时提前评估 |
|
||||
| ④ 英文站海外投放数据证明海外市场空间(V2.0 指标: 自然访问≥10%) | 以真实数据支撑日文投入决策 |
|
||||
|
||||
### 7.3 对工程的要求(无论扩展与否)
|
||||
|
||||
- 前端 i18n 需在 V1.1 页面开发时**坚持全部文案走 `useT()` 与消息表**,杜绝硬编码,保证后续任意语言扩展零重构成本。
|
||||
- 路由层预留语言前缀机制(`/zh-tw/`、`/ja/` 等),避免后期迁移。
|
||||
- 色号表数据(品牌/色号/hex)与语言无关,可全语言共用,**数据层无需翻译**,仅页面文案与 SEO 元数据需要本地化。
|
||||
|
||||
---
|
||||
|
||||
## 8. 结论
|
||||
|
||||
| 语言 | 决策 | 核心理由 | 时间点 |
|
||||
|---|---|---|---|
|
||||
| **zh-tw** | **扩展** | 成本 ~1 人日/零资金;竞品该语言最弱,我方窗口敞开;免费核心不受支付影响 | V1.1 随新增页面一并落地 |
|
||||
| **ja** | **暂缓** | 支付/兑换码链路未通,流量无法变现;竞品已深耕;ROI 现阶段为负 | V2.0 多语言立项或支付方案确定后重启 |
|
||||
|
||||
> 本报告为 PM-Agent 决策依据。如需将 zh-tw 正式立项,请转排期为工程任务(预估 1–1.5 人日);ja 保持监控挂起状态,由 `monitor.js` 与 ROADMAP 里程碑联合触发重启评估。
|
||||
|
||||
---
|
||||
|
||||
*报告完。证据可复核: `competitor-analysis/pixelbeads-zh-detail.md` §1.2/§8、`competitor-analysis/pixelbeads-analysis.md` §1.3/§6、`docs/ROADMAP.md` §4.2-4.4、`perler-lab/src/i18n` 实测(349 key × 2 语言)。*
|
||||
@@ -0,0 +1,224 @@
|
||||
# LEAFER-EVAL · leafer.js 图纸渲染引擎评估报告
|
||||
|
||||
> 任务: T-085(前端:leafer.js 图纸渲染引擎评估——替代/对比现有 Canvas 2D 渲染的可行性、性能、成本)
|
||||
> 日期: 2026-08-14
|
||||
> 范围: 本任务只产出评估文档,**不含任何源码改动、不引依赖入库**
|
||||
> 适用前端: `D:\拼豆\perler-lab`(Vite 5 + React 18 + TS 5.9,当前 **0 渲染库依赖**,原生 Canvas 2D)
|
||||
> 交叉引用: `docs/ANIMATION-PLAN.md`(§动画选型,已评估 leafer.js 用于 V2 画布升级)→ 本任务聚焦**图纸渲染引擎替换**评估,非动画
|
||||
|
||||
---
|
||||
|
||||
## 0. 决策摘要(一句话结论)
|
||||
|
||||
> **V1 不换(保留原生 Canvas 2D 全链路);V2 编辑画布升级时引入 leafer.js 替换预览渲染层;PNG/PDF 导出通道保留 Canvas 2D——即「混合引入,分层边界」,与 ANIMATION-PLAN.md 选型一致。**
|
||||
|
||||
理由三句:
|
||||
1. **当前规模(最大 128×128=16,384 豆)远低于 leafer 的性能优势起点**(官方基准是 100 万对象),静态预览 + 一次性导出场景下,原生 Canvas 2D 单帧重绘 ≈ 1–5ms,leafer 的「百万对象、批处理 DrawCall」优势无感。
|
||||
2. **leafer 的真正价值在本项目的交互与动画**:内置拖拽/缩放/毫秒级点选命中、脏矩形局部刷新、属性补间(对应 ANIMATION-PLAN E-04/E-05/E-06)——这些是 V2 编辑画布升级的硬需求,V1 不出现。
|
||||
3. **引入成本真实存在**:leafer-ui 2.2.9(unpacked ≈ 4.2MB,核心裁剪 ≈ 70KB min+gzip)、无官方 React 绑定(需自维护 useEffect+ref 桥接)、渲染层整树重建。V1 为不存在的需求付这笔成本不成立。
|
||||
|
||||
---
|
||||
|
||||
## 1. 现状盘点:现有图纸渲染链路
|
||||
|
||||
### 1.1 代码链路
|
||||
|
||||
| 模块 | 职责 | 机制 |
|
||||
|---|---|---|
|
||||
| `src/lib/pattern-renderer.ts` | 基础绘制:`renderPattern` 逐格 `fillRect`(20px 格)+ `drawPaletteLegend` + `rgbToCss` | Canvas 2D |
|
||||
| `src/lib/drawPattern.ts` | 预览 `drawPreview`:逐格 `arc`(圆豆,radius=cell×0.42)+ 网格线(每 5 格加粗、每 10 格标号)+ PNG 导出 `buildExportCanvas`(cell 22/28px + 标题 + 备豆清单) | Canvas 2D |
|
||||
| `src/components/PreviewPanel.tsx` | 预览画布宿主:`useEffect` 监听 `result / gridSize / showGrid` 变化 → 全量调 `drawPreview` | 全量重绘 |
|
||||
| `src/App.tsx` | `applyEdit`(撤销/重做/旋转/镜像/翻转)→ 改 `editedResult` 的 grid 数组 → 触发 PreviewPanel 全量重绘 | 数据层数组变换 + 全量重绘 |
|
||||
| 导出 | `buildExportCanvas` 离屏一次性渲染 → `canvas.toBlob` PNG | 一次性渲染 |
|
||||
|
||||
### 1.2 场景规模(实测自 `ControlsPanel.tsx` / `ChibiPage.tsx`)
|
||||
|
||||
- `GRID_MIN=16`,`GRID_MAX=128`,预置 `[32, 64, 96, 128]`,chibi 默认 64。
|
||||
- **最大格数 128×128 = 16,384 格**,即 ≤16,384 颗豆(每格 1 圆)。
|
||||
- 预览 canvas:`gridSize×8px + 18×2px` 边框(128 格 ≈ 1,060px);**当前无缩放/平移交互**。
|
||||
- 导出 canvas:`gridSize≥96 时 cell=22px`(128 格 ≈ 2,816px 宽)。
|
||||
|
||||
### 1.3 当前性能瓶颈(任务描述「放大/编辑时」)
|
||||
|
||||
- **编辑路径**:每次旋转/镜像/翻转/撤销 → grid 数组整体变换 → `drawPreview` 全量重绘(≤16,384 次 `beginPath+arc+fill` + 网格线)。单次约 5–15ms,无肉眼卡顿,但**无局部更新、无场景缓存**,编辑粒度与渲染粒度脱节。
|
||||
- **放大路径**:预览无缩放,用户感知的「放大」实际是导出(22/28px 大格)——属一次性渲染,非交互热点。
|
||||
- **结论**:现有瓶颈是「全量重绘架构 + 无交互层」的结构性问题,不是 fillRect/arc 吞吐量问题。
|
||||
|
||||
---
|
||||
|
||||
## 2. leafer.js 调研(2026-08-14 npm 实测 + 官方文档抓取)
|
||||
|
||||
### 2.1 是什么
|
||||
|
||||
leafer.js(LeaferUI)是国产原创 2D Canvas 渲染引擎,场景树(scene graph)架构,定位「大规模、高密度、海量图层」生产力工具(Figma 级编辑器 / 无限画布)。5 年沉淀,GitHub 4.3k stars,官方 benchmark 对标 Pixi/Konva/Fabric。
|
||||
|
||||
### 2.2 版本与体积(npm 实测)
|
||||
|
||||
| 包 | 版本 | unpackedSize | 说明 |
|
||||
|---|---|---|---|
|
||||
| `leafer-ui` | **2.2.9**(latest stable) | 4,356,846 B(≈4.2MB) | 全量 UI(含 Editor 插件/动画/布局) |
|
||||
| `@leafer-ui/core` | 2.2.9 | 445,514 B(≈435KB) | 跨平台渲染核心(可裁剪) |
|
||||
| `@leafer-ui/draw` | 2.2.9 | — | 基础绘制模块 |
|
||||
| `leaferjs` | 2.0.1-**beta**.0 | 2.2MB | 主集成包(beta,不推荐生产) |
|
||||
| `@leafer-ui/react` | **不存在**(E404) | — | 无官方 React 绑定 |
|
||||
| `@leafer-ui/webgl` | **不存在**(E404) | — | **渲染后端为 Canvas 2D,无 WebGL 包** |
|
||||
|
||||
官方 README 声明核心场景 **70KB min+gzip、零依赖**。体积可按需裁剪(只引 `@leafer-ui/core` + 所需显示对象)。
|
||||
|
||||
### 2.3 核心能力(官方文档确认)
|
||||
|
||||
- **图形系统**:完整场景树,矢量图形 / SVG 路径 / 像素操作;`Rect`、`Circle`/`Ellipse`、`Group` 等显示对象;类 DOM API(`add/remove/clear`)。
|
||||
- **极致性能**:官方 benchmark——**100 万个可交互矩形**:首屏创建 1.28s vs 传统 Canvas 库 9–15s(约快 8x);内存 320MB vs 2–4GB(约省 8x);单元素拖拽 60FPS vs 0–4FPS(约流畅 15x)。
|
||||
- **技术机制**:批处理 DrawCall + **脏矩形局部刷新** + 毫秒级命中检测(Hit Testing)。
|
||||
- **内置交互**:原生 `draggable`、缩放、多点触控;Editor 插件一键开旋转/缩放/多选。
|
||||
- **导出**:`Export.png/jpeg/webp/canvas/download(element, …)`,支持 `scale` 缩放导出。
|
||||
- **动画**:内置状态驱动属性补间(`transition`)+ 路径动画(V2 E-04/E-05 可直接用)。
|
||||
- **跨平台**:Web / Node.js(离屏渲染、SSR 出图)/ 微信小程序 / H5,一套代码。
|
||||
- **许可**:**MIT,永久开源,可免费商用**;商业插件(PxGrow 编辑器套件/性能优化)为**可选**,非必需。
|
||||
|
||||
### 2.4 迁移实证(竞品调研,`competitor-analysis/animation-research.md` §3.2-1)
|
||||
|
||||
> 像素编辑器 Konva→Leafer 迁移实录:**1000 元素、4K 屏,帧率 25–30→58–60 FPS、内存 120MB→40MB、DrawCall 800+→<50、点选命中 80ms→10ms**。
|
||||
> 佐证:百度像素风编辑器迁移文章 + 开源 Canva 平替 Gzm Design 均选 LeaferJS。
|
||||
|
||||
---
|
||||
|
||||
## 3. leafer.js vs 现有 Canvas 2D 对比表
|
||||
|
||||
| 维度 | **现有原生 Canvas 2D**(fillRect/arc 逐格) | **leafer.js(leafer-ui 2.2.9)** | 判定 |
|
||||
|---|---|---|---|
|
||||
| 渲染性能(静态一次性) | 16k 格重绘 ≈ 1–5ms,**完全够用** | 场景树 + 脏矩形,静态一次性场景收益 ≈ 0 | **平手**(本项目规模) |
|
||||
| 渲染性能(持续交互/动画) | 全量重绘,>1 万豆 + 逐帧动画必掉帧 | 局部刷新 + 批处理 DrawCall,官方 1M 对象 60FPS | **leafer 大幅胜** |
|
||||
| 内存 | 一次性像素缓冲,无对象开销 | 每豆一显示对象(16k Circle),静态场景反而略重 | **Canvas 略胜**(静态) |
|
||||
| 缩放/平移/点选命中 | **无内置**,需手写 | 内置 `draggable`/缩放/毫秒级命中 | **leafer 大幅胜** |
|
||||
| 局部更新(编辑单格/单豆) | 无场景缓存,只能全量重绘 | 脏矩形局部刷新 + 对象级属性更新 | **leafer 大幅胜** |
|
||||
| API 友好度 | 命令式(`ctx.fillRect`),300 行自维护 | 类 DOM 场景树,`leafer.add(rect)` 声明式 | **leafer 胜** |
|
||||
| React 集成 | 原生,`canvasRef` 直接可用 | **无官方绑定**,需自建 `useEffect`+ref 桥接层 | **Canvas 胜** |
|
||||
| 包体积 | **0** | core 裁剪 ≈ 70KB min+gzip;全量 4.2MB | **Canvas 胜** |
|
||||
| 导出能力 | `buildExportCanvas`+`toBlob` 已验证(PNG/PDF 复用) | `Export.png/canvas` 内置(支持 scale) | 平手(导出需重写) |
|
||||
| 学习成本 | 已有存量代码,团队已会 | 新 API,现代类 Fabric/Konva 但更简,文档中文友好 | Canvas 略胜(存量) |
|
||||
| 许可 | 自有 MIT | **MIT 永久开源、免费商用** | 平手 |
|
||||
| 生态成熟度 | — | 较新(4.3k stars),第三方插件少,版本演进快(2.2.x) | Canvas 稳,leafer 需锁版本 |
|
||||
| 动画能力 | 无(动画靠 CSS 层) | 内置属性补间 + 路径动画(E-04/E-05/E-06 直接可用) | **leafer 大幅胜** |
|
||||
|
||||
**对比表结论**:在「静态预览 + 一次性导出」的当前 V1 场景,leafer 对 Canvas 2D **无性能优势、有体积与集成成本**;在「交互编辑 + 动画」的 V2 场景,leafer **全面胜出**。胜负完全取决于是否引入交互层。
|
||||
|
||||
---
|
||||
|
||||
## 4. 拼豆图纸渲染场景适配性分析
|
||||
|
||||
### 4.1 场景 A:大量矩形/圆形豆子绘制(静态预览)——**不匹配 leafer 优势**
|
||||
|
||||
- 本项目最大 16,384 豆;leafer 官方基准是 **100 万对象**(约 60 倍差距)。
|
||||
- 原生 Canvas 2D 一次性绘制 16k 圆 ≈ 1–5ms;leafer 引入 16k 显示对象建树 + 序列化场景,静态首帧**不会更快**,内存反而更高(对象元数据开销)。
|
||||
- **结论**:纯静态预览 = 不换。
|
||||
|
||||
### 4.2 场景 B:缩放平移(画布拖拽,对齐竞品基线 / ANIMATION-PLAN E-06)——**leafer 强项**
|
||||
|
||||
- 当前预览**无任何缩放/平移**,竞品基线明确要求 `translate3d` 合成层拖拽(E-06 P2)。
|
||||
- leafer 内置 `draggable` + view 缩放 + 毫秒级命中,一个 `drag` 示例即覆盖需求,无需手写矩阵变换 + 反算命中。
|
||||
- **结论**:引入交互层时,leafer 直接解决。
|
||||
|
||||
### 4.3 场景 C:局部更新(编辑画布场景)——**关键认知修正**
|
||||
|
||||
- 当前编辑操作(旋转/镜像/翻转/撤销)是 **grid 数组级变换**(`rotateGrid` 等),不是单豆级修改 → 在 leafer 下也只能**整树重建**(数组变换 → 重建场景),脏矩形局部刷新优势被抵消。
|
||||
- leafer 的局部更新优势只对 **E-04 逐豆放置/编辑**(用户点一格改一颗)生效——这才是 leafer 真正发挥的场景。
|
||||
- **结论**:leafer 对「整图变换」无加速,对「逐豆交互编辑」显著加速。实施时应把编辑交互拆成「整图变换(全量重建)」与「逐豆操作(对象级更新)」两条路径。
|
||||
|
||||
### 4.4 场景 D:导出(PNG/PDF)——**不换**
|
||||
|
||||
- 导出是一次性离屏渲染(cell 22/28px),非交互热点;`buildExportCanvas` 已验收(含标题/备豆清单/PDF 复用)。
|
||||
- leafer 的 `Export` 可替代但**无必要**:为一次性操作引入依赖 + 重写导出逻辑 + 回归测试,收益为负。
|
||||
- **结论**:导出通道保持 Canvas 2D,与 leafer 分层隔离(leafer 只做编辑画布交互层)。
|
||||
|
||||
### 4.5 适配性评分
|
||||
|
||||
| 场景 | 原生 Canvas 2D | leafer.js | 优势方 |
|
||||
|---|---|---|---|
|
||||
| 静态预览(≤16k 豆) | ★★★★★ | ★★★☆ | Canvas 2D |
|
||||
| PNG/PDF 一次性导出 | ★★★★★ | ★★★☆ | Canvas 2D |
|
||||
| 缩放/平移/点选交互 | ★★☆(手写) | ★★★★★ | leafer |
|
||||
| 逐豆放置/编辑(E-04/E-05) | ★★☆(全量重绘) | ★★★★★ | leafer |
|
||||
| 动画(E-04/05/06 补间) | ★(靠 CSS 层) | ★★★★★ | leafer |
|
||||
|
||||
---
|
||||
|
||||
## 5. 推荐结论 + 理由
|
||||
|
||||
> **结论:混合引入(V1 不换 → V2 编辑画布升级引入 leafer.js,导出保留 Canvas 2D)。**
|
||||
|
||||
### 5.1 为什么不是「立即替换」?
|
||||
|
||||
1. **规模不匹配**:16,384 豆 vs leafer 百万对象基准,静态渲染零收益。
|
||||
2. **编辑操作是数组变换**:旋转/镜像等走整树重建路径,leafer 脏矩形优势用不上(§4.3)。
|
||||
3. **导出已验证**:`buildExportCanvas`/`downloadCanvas` 全链路已验收(含设计规范 §5),为一次性操作重写不划算。
|
||||
4. **成本真实**:70KB+ min+gzip 依赖、渲染层重写、无官方 React 绑定需自建桥接、2.2.x 版本演进快需锁版本。
|
||||
|
||||
### 5.2 为什么是「V2 引入」(而不是永远不换)?
|
||||
|
||||
1. **交互是差异化刚需**:竞品基线(拖拽/缩放/命中)与 ANIMATION-PLAN E-04/05/06 都指向画布交互层,leafer 内置能力直接覆盖,自写方案(矩阵变换+反算命中+局部刷新)成本更高。
|
||||
2. **性能天花板**:>1 万豆 + 逐帧动画 + 持续拖拽时,原生全量重绘必然掉帧;leafer 迁移实证(帧率 25→60、DrawCall 800+→<50、点选 80→10ms)正是该场景的对症数据。
|
||||
3. **动画层依赖**:ANIMATION-PLAN 分层架构把 leafer 定为「第 1 层 画布渲染/交互」,anime.js 在其上做 spring/stagger——不引入 leafer,E-04/E-05 差异化动效无落地载体。
|
||||
4. **MIT 永久开源、免费商用**:无许可/供应商锁定风险。
|
||||
|
||||
### 5.3 边界(防止双引擎并存混乱)
|
||||
|
||||
- **leafer 只接管「预览编辑画布」**(有交互/动画诉求的实时视图)。
|
||||
- **Canvas 2D 保留「导出」**(PNG/PDF 一次性离屏)与「后端/其他业务渲染」。
|
||||
- 二者通过数据层隔离:leafer 读同一 `ProcessResult`/`editedResult`,导出复用现有 `buildExportCanvas`,**同一数据源、双输出端**。
|
||||
|
||||
---
|
||||
|
||||
## 6. 实施路径(若 V2 引入)
|
||||
|
||||
### 6.1 迁移步骤
|
||||
|
||||
1. **引入依赖**:`leafer-ui@^2.2.9` + `@leafer-ui/core@^2.2.9`(同步版本,防版本漂移);锁定精确版本,评估裁剪 `@leafer-ui/draw` 等子包。
|
||||
2. **React 桥接层**:新建 `LeaferCanvas.tsx`(`useRef` + `useEffect`,挂载建 `Leafer({ view })`、卸载 `leafer.destroy()`、重绘节流)——无官方绑定,桥接自维护,API 面收窄到 `Leafer/Rect/Circle/Group`。
|
||||
3. **渲染替换**:`drawPreview` 的场景化重写:
|
||||
- `Group(Beans)`:每豆 1 个 `Circle`(fill=rgb,radius=cell×0.42);
|
||||
- `Group(GridLines)`:网格线(5/10 加粗标号沿用现有 drawGrid 逻辑);
|
||||
- 监听 `editedResult` 变化 → 整图变换(旋转/镜像)走全量重建;逐豆操作走对象级更新。
|
||||
4. **交互层**(E-06):`draggable` 平移 + 滚轮缩放 + 点选命中(leafer 内置)。
|
||||
5. **动画接入**(E-04/E-05):leafer `transition` 属性补间或 anime.js `spring`/`stagger`,对齐 ANIMATION-PLAN §5.3 参数(spring stiffness 170/damping 26、120–180ms)。
|
||||
6. **导出不动**:`buildExportCanvas`/`downloadCanvas` 保持 Canvas 2D,`Export` 仅作可选评估项。
|
||||
7. **验收口径**(对齐 ANIMATION-PLAN §7 V2):>1 万豆拖拽/放置保持 60FPS;DrawCall <50、点选命中 <10ms;双引擎边界清晰(预览=leafer,导出=Canvas 2D)。
|
||||
|
||||
### 6.2 风险与缓解
|
||||
|
||||
| 风险 | 缓解 |
|
||||
|---|---|
|
||||
| 无官方 React 绑定,桥接自维护 | 收窄 API 面(仅 4 个类);卸载清理 `destroy()`;重绘防抖/节流 |
|
||||
| 版本演进快(2.2.x,leaferjs 主包还在 beta),API 漂移 | 锁精确版本;只依赖稳定核心类;升级走独立任务 + 回归 |
|
||||
| 每豆一对象的静态开销(16k 对象 vs 一次性 fillRect) | 静态首帧仍可走全量批量;对象化收益留待交互/动画路径 |
|
||||
| 编辑=数组变换时无加速(§4.3) | 明确拆分:整图变换全量重建、逐豆操作对象级更新;验收锚定后者 |
|
||||
| 双引擎并存职责混淆 | §5.3 边界写入代码结构:预览组件只依赖 leafer,导出只依赖 Canvas 2D |
|
||||
| 社区较新、第三方插件少 | 仅用官方核心能力,不依赖第三方插件 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 与 ANIMATION-PLAN.md 一致性校验
|
||||
|
||||
| ANIMATION-PLAN.md 结论 | 本评估 | 一致性 |
|
||||
|---|---|---|
|
||||
| §2/§3:leafer.js 定为「V2 引入(画布层)」,「图纸网格渲染/豆子交互/拖拽(**核心差异化**)」 | V2 引入 leafer 替换预览渲染层(交互+动画) | ✅ 一致 |
|
||||
| §6.2:「>1 万豆 V1 保持原生 fillRect;leafer.js 迁移 V2 一次性承担,**避免 V1 双渲染引擎并存**」 | V1 不换、导出保留 Canvas 2D、V2 一次性引入并划定「预览=leafer / 导出=Canvas 2D」边界 | ✅ 一致(并细化边界) |
|
||||
| §2 体积评估:「leafer 按需模块,数百 KB 级(仅画布层承担)」 | npm 实测 core 435KB unpacked / 核心场景 70KB min+gzip,按需裁剪成立 | ✅ 一致(数据落实) |
|
||||
| §7 V2 验收:「>1 万豆拖拽/放置 60fps、DrawCall <50、点选 <10ms」 | 本评估 §6.1-7 采纳为 leafer 引入验收口径 | ✅ 一致 |
|
||||
| §5.3 E-04/E-05/E-06(豆子 spring、闪烁、拖拽) | leafer 内置交互/补间覆盖,anime.js 按需叠加 | ✅ 一致 |
|
||||
|
||||
**一致性结论:无冲突。** 本评估补充两点增量认知(不改变 ANIMATION-PLAN 选型):
|
||||
1. **导出通道保留 Canvas 2D**(ANIMATION-PLAN 未明确导出层归属,本评估划定边界,防止双引擎并存混乱);
|
||||
2. **编辑操作为数组级变换时 leafer 整树重建无加速**(纠正「引入 leafer 即解决编辑瓶颈」的朴素预期,把收益锚定在逐豆交互/动画)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 数据来源
|
||||
|
||||
- **npm 实测**(2026-08-14):`leafer-ui@2.2.9` / `@leafer-ui/core@2.2.9` / `@leafer-ui/draw` 版本与 unpackedSize;`@leafer-ui/react`、`@leafer-ui/webgl` 不存在(E404 实证)。
|
||||
- **leafer-ui 官方 README / GitHub**(github.com/leaferjs/leafer-ui):MIT 许可、70KB min+gzip、100 万矩形 benchmark(1.28s / 320MB / 60FPS)、Export 模块、React/WebGL 无官方包。
|
||||
- **官方文档**(context7 /leaferjs/leafer-ui):场景树 API、`Group/Rect`、`Export.png/canvas`、`new Leafer({ view })`、`draggable`。
|
||||
- **竞品调研**(`competitor-analysis/animation-research.md` §3.2-1):Konva→Leafer 迁移实测(1000 元素 4K:帧率 25–30→58–60、内存 120→40MB、DrawCall 800+→<50、点选 80→10ms)。
|
||||
- **本项目现状**(`perler-lab/src` 抽查):`drawPattern.ts` / `pattern-renderer.ts` / `PreviewPanel.tsx` / `App.tsx` / `ControlsPanel.tsx`(GRID_MIN=16、GRID_MAX=128、预置 [32,64,96,128])。
|
||||
|
||||
> 附注:本报告为纯评估文档,不构成实施;后续实施任务引用本报告 §5/§6 作选型与验收依据。
|
||||
@@ -0,0 +1,285 @@
|
||||
# MOBILE-ECOSYSTEM — 移动端生态入口设计参考
|
||||
|
||||
> **任务**: T-125 移动端生态入口设计参考
|
||||
> **角色**: UI-Designer-Agent
|
||||
> **日期**: 2026-08-14
|
||||
> **输入依据**:
|
||||
> - `competitor-analysis/pixelbeads-nav-crawl.md`(§2.2 移动端分组抽屉实测:主导航 9 项 + 主题 2 项 + 工具 6 项 + 指南 2 项;§1.2 桌面第 8/9 项 = 客户端 /zh/apps + 帮助 /zh/help;§3.1 页脚 apps×3 子页 Chrome/Android/iOS)
|
||||
> - `docs/NAV-ALIGNMENT.md`(§3.2 移动端分组抽屉设计、§4 优先级、§5 风险——含「工具/指南分组暂不参考泛化工具页」决策)
|
||||
> - `docs/DESIGN.md`(设计令牌:色彩/字体/间距/圆角/触控目标)
|
||||
> - `docs/PWA-PLAN.md`(T-105:manifest / SW / 安装提示 deferredPrompt / P0–P3 拆解)
|
||||
> - 我方源码实读: `src/components/Nav.tsx`(首页导航)、`src/components/SubNav.tsx`(子页导航)、`src/App.tsx`(mobile-cta)、`src/i18n/messages/{zh-CN,en}.ts`(nav.* keys)
|
||||
> - 看板: `D:\拼豆\taskboard\taskboard.js`(T-125 已认领;T-116 apps 落地页爬取**开发中未产出**,gap-crawl.md 不存在)
|
||||
|
||||
---
|
||||
|
||||
## 0. 结论速览
|
||||
|
||||
| 维度 | 结论 |
|
||||
|---|---|
|
||||
| **竞品生态入口** | 竞品有 3 个生态入口:①导航第 8 项「客户端」/zh/apps(Chrome 扩展 + Android + iOS 三端下载页)②帮助中心 /zh/help(分工具子页)③移动端「工具/指南」分组(7 个泛化工具页)。apps 是**独立导航项 + 页脚三子页**,帮助是**导航项 + 单页中心** |
|
||||
| **我方定位** | 纯 Web 无客户端产品 → **apps 页明确暂缓**(沿用 NAV-ALIGNMENT「不做」决策);生态入口聚焦 **PWA 安装提示 + 帮助中心入口 + 分享入口** |
|
||||
| **移动端结构建议** | 复用现有 SubNav 8 入口(首页/生成器/chibi/色号表/showcase/图纸库/帮助),**不引入竞品「工具/指南」泛化分组**;抽屉底部新增「生态区」:PWA 安装横幅 + 分享 + 帮助(可折叠进分组标题下) |
|
||||
| **P0** | 移动端 PWA 安装提示横幅(依赖 PWA-PLAN P3-1 的 deferredPrompt 链路) |
|
||||
| **P1** | 帮助中心入口强化(SubNav 已含 help,补抽屉内 FAQ 直达分类)+ 分享入口(复制链接/分享图纸) |
|
||||
| **P2** | 生成结果页内嵌「安装到主屏」图文引导(iOS 无 prompt API 场景)、离线 banner |
|
||||
|
||||
> 核心原则:**竞品 apps 三端是"有产品才有的入口",我方无客户端 → 不空建下载页**。我方生态入口 = PWA(把现有 Web 变"可安装应用")+ 帮助中心(服务已有用户)+ 分享(社交传播)。全部复用现有页面与令牌,零新路由、零新页面。
|
||||
|
||||
---
|
||||
|
||||
## 1. 竞品生态入口分析(apps 页 / 帮助页在移动端的呈现)
|
||||
|
||||
> 数据源:`pixelbeads-nav-crawl.md`(Spider 实测,Playwright 验证)。T-116(apps 四落地页抓取)开发中,本节基于导航结构层数据;落地页内容细节留待 T-116 产出后补充。
|
||||
|
||||
### 1.1 「客户端」apps 页(/zh/apps)
|
||||
|
||||
| 维度 | 实测值 | 移动端呈现 |
|
||||
|---|---|---|
|
||||
| 入口层级 | 桌面导航第 8 项「客户端」+ 移动端抽屉主导航项 | 抽屉内为普通列表项(无图标无角标),与首页/生成器平级 |
|
||||
| 落地页 | `/zh/apps` 总入口 + 页脚三子页:`/apps/chrome-extension`、`/apps/android`、`/apps/ios` | 页脚「应用与支持」栏 4 链接(apps + 3 子页) |
|
||||
| 产品形态 | Chrome 扩展 + Android 应用 + iOS 应用(三端原生) | — |
|
||||
| 与 Web 关系 | 原生能力补充(本地文件、独立窗口、离线),与 Web 生成器同品牌 | — |
|
||||
|
||||
**移动端呈现要点**:
|
||||
- apps 在抽屉中是**普通列表项**,与主导航 9 项混排,无"生态/应用"专组——竞品把客户端当作与生成器并列的一级能力入口。
|
||||
- 移动端抽屉另有「工具」「指南」两组(§2.2),与 apps 分开:工具组 = 泛化工具页(像素画编辑器/Minecraft 指南等 7 个 sitemap 外页面),指南组 = 教程页。
|
||||
|
||||
### 1.2 帮助中心(/zh/help)
|
||||
|
||||
| 维度 | 实测值 |
|
||||
|---|---|
|
||||
| 入口层级 | 桌面导航第 9 项「帮助」+ 移动端抽屉主导航项 + 页脚「应用与支持」栏 |
|
||||
| 页面形态 | 帮助中心单页,含**分工具子页**结构(生成器/像素画等各工具独立 FAQ) |
|
||||
| 多语言 | 全部 7 语言均建 `/help`(语言前缀矩阵全 ✅) |
|
||||
| 移动端 | 抽屉内普通列表项,无折叠、无描述 |
|
||||
|
||||
### 1.3 竞品移动端抽屉完整结构回顾(nav-crawl §2.2)
|
||||
|
||||
```
|
||||
[H2] 拼豆艺术 + 副标题「网站导航、拼豆工具、指南和语言选项。」
|
||||
主导航 9 项:首页 / 生成器 / 创作 / 像素画 / 图纸库 / 展示 / 客户端 / 帮助
|
||||
[H3] 主题拼豆:圣诞 + 宝可梦(带描述)
|
||||
[H3] 工具:拼豆图纸工具 / 像素画编辑器 / 拼豆豆生成工具 / 照片转像素 / Minecraft 指南 / r/place 工具
|
||||
[H3] 指南:拼豆完全指南 / Hama 拼豆
|
||||
[语言] 简体中文(复用语言下拉)
|
||||
```
|
||||
|
||||
### 1.4 竞品生态策略提炼(可借鉴 / 不可借鉴)
|
||||
|
||||
| 策略 | 借鉴价值 | 判断 |
|
||||
|---|---|---|
|
||||
| 客户端作为一级导航项 | 我方无客户端 → **不借鉴**(NAV-ALIGNMENT 已定「不做」) |
|
||||
| 帮助中心独立导航项 + 页脚常驻 | ✅ **借鉴**:帮助是低成本高信任入口,我方 SubNav 已含 `help` |
|
||||
| 「工具/指南」泛化分组 | ❌ **不借鉴**:7 个泛化工具页偏离核心拼豆定位,NAV-ALIGNMENT §1 已明确排除 |
|
||||
| 主题分组(按节日/IP) | ✅ 借鉴(已在 NAV-ALIGNMENT §3.2 落地为 chibi 分类深链) |
|
||||
| 移动端抽屉分组标题 + 描述 | ✅ 借鉴:分组 H3 + 一行描述提升信息架构可读性 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 我方移动端生态入口现状与差距
|
||||
|
||||
### 2.1 当前移动端结构(源码实读)
|
||||
|
||||
| 载体 | 入口 | 说明 |
|
||||
|---|---|---|
|
||||
| `Nav.tsx`(首页) | 图片转拼豆 `#workspace` / AI拼豆专区 `/chibi`(PRO) / 色号表 `/color-chart` | 首页顶部导航,语言切换 + 代理合作 + 状态徽标 |
|
||||
| `SubNav.tsx`(子页) | 首页 `/` / chibi `/chibi` / showcase `/showcase` / library `/library` / help `/help` | showcase/library/help 共用子页导航 |
|
||||
| `App.tsx` | `mobile-cta` 购买/兑换固定底栏 | 移动端变现入口 |
|
||||
| 路由全集 | `/` `/chibi` `/color-chart` `/showcase` `/library` `/help` | 6 路由 |
|
||||
|
||||
> 任务口径「首页/生成器/chibi/色号表/showcase/图纸库/help」= 桌面 Nav 3 项 + SubNav 5 项的并集(生成器=#workspace,图纸库=/library)。
|
||||
|
||||
### 2.2 差距矩阵(vs 竞品 §1)
|
||||
|
||||
| 生态能力 | 竞品 | 我方 | 差距 |
|
||||
|---|---|---|---|
|
||||
| 客户端下载 | Chrome/Android/iOS 三端 | 无客户端 | **不补齐**(无产品,apps 页暂缓) |
|
||||
| PWA/安装 | 纯 Web(manifest 仅 4 字段,无安装引导) | PWA-PLAN 已设计完整 manifest+SW+安装提示(T-105 验收通过) | **我方反而领先**:竞品无自定义安装引导,我方 PWA-PLAN §5 设计了温和引导 |
|
||||
| 帮助中心 | 导航项 + 分工具子页 | SubNav 已含 `/help`(T-106 验收通过,FAQ 8 分类) | 已基本对齐;缺移动端抽屉内直达分类 |
|
||||
| 分享 | — | `share-codec.ts` 分享码(可解码渲染单张图纸) | **已有能力无入口**:缺移动端分享 UI |
|
||||
| 泛化工具分组 | 7 页 | 无 | 不补齐(定位偏离) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 我方移动端生态入口设计方案
|
||||
|
||||
### 3.1 总原则
|
||||
|
||||
1. **apps 页暂缓**:无客户端产品则不做下载页。未来若出 PWA/小程序(PWA-PLAN 已具备),届时再考虑"安装引导页"形态,不叫 apps。
|
||||
2. **生态入口 = 3 件事**:PWA 安装提示(把 Web 变应用)+ 帮助中心入口(服务已有用户)+ 分享入口(社交传播)。
|
||||
3. **零新路由零新页面**:全部入口复用现有页面/组件/令牌,只加 UI 层入口与交互。
|
||||
|
||||
### 3.2 移动端抽屉结构设计(升级版,对比 NAV-ALIGNMENT §3.2)
|
||||
|
||||
> NAV-ALIGNMENT 已定义 P0 抽屉 = 主导航 + 主题拼豆 + 工具组(P1 开放)。本设计在此基础上**追加生态区**,不推翻既有结构。
|
||||
|
||||
```
|
||||
[☰] PERLER LAB [中文|EN]
|
||||
┌──────────────── 抽屉(右侧滑入)──────────────────┐
|
||||
│ PERLER LAB │
|
||||
│ 网站导航、AI 生成、工具和安装选项。 │
|
||||
│ │
|
||||
│ [H3] 主导航 │
|
||||
│ ├ 首页 / │
|
||||
│ ├ 图片转拼豆 /#workspace │
|
||||
│ └ AI拼豆专区 ◈PRO /chibi │
|
||||
│ [H3] 主题拼豆(AI 分类快速进入) │
|
||||
│ ├ 宠物世界 /chibi?cat=pet │
|
||||
│ ├ 人物肖像 /chibi?cat=people │
|
||||
│ ├ 风景美图 /chibi?cat=landscape │
|
||||
│ └ 美食探店 /chibi?cat=food │
|
||||
│ [H3] 工具 │
|
||||
│ ├ 色号表 /color-chart │
|
||||
│ ├ 作品展示 /showcase │
|
||||
│ ├ 图纸库 /library │
|
||||
│ └ 帮助 /help │
|
||||
│ ──────────────────────── │
|
||||
│ [生态区](分隔线下方,卡片容器) │
|
||||
│ 📱 安装到主屏 / 添加到主屏幕 ← PWA 安装入口 │
|
||||
│ ↗ 分享 PERLER LAB ← 分享入口 │
|
||||
│ ? 帮助中心 /help ← 帮助入口(显式) │
|
||||
│ ──────────────────────── │
|
||||
│ [代理合作 →](复用 AgencyModal) │
|
||||
└───────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**设计说明**:
|
||||
- **主结构不变**:主导航 + 主题 + 工具三分组沿用 NAV-ALIGNMENT §3.2 与竞品分组模式(分组 H3 + 描述)。
|
||||
- **生态区独立成卡**:不与导航项混排(吸取竞品 apps 与主导航混排的缺点),用分隔线 + 浅底卡片 `--bg-subtle` 区分——生态入口是"增值项",不应抢占导航主视觉。
|
||||
- **帮助双入口**:工具组「帮助」= 位置入口(与竞品/桌面一致);生态区帮助 = 功能入口(直达 FAQ)。避免歧义时只在生态区放一次,工具组可隐藏——**推荐只在工具组保留**(SubNav 已有一致入口),生态区帮助作为移动端兜底副本,视觉弱化(icon 行)。
|
||||
- **安装入口两态**(对应 PWA-PLAN §5):
|
||||
- 未安装可安装(`beforeinstallprompt` 已捕获)→ 「📱 安装到主屏」(Chrome/Android)
|
||||
- 不可安装(iOS Safari)→ 「? 添加到主屏幕」图文指引行(`navigator.standalone` 判断)
|
||||
- 已安装(`display-mode: standalone` 或 `appinstalled`)→ 隐藏该行
|
||||
- **分享入口**:Web Share API(`navigator.share`)优先,fallback 复制链接 + toast「链接已复制」。
|
||||
|
||||
### 3.3 PWA 安装提示入口(重点,替代 apps 页)
|
||||
|
||||
> 我方无客户端,但 PWA-PLAN(T-105 验收通过)已给出完整安装链路。本入口把它落到移动端 UI。
|
||||
|
||||
| 形态 | 触发 | 内容 | 依赖 |
|
||||
|---|---|---|---|
|
||||
| **抽屉内安装行** | 打开抽屉 | icon + 「安装到主屏」+ 短说明,点击 `deferredPrompt.prompt()` | PWA-PLAN P3-1(`beforeinstallprompt` 捕获) |
|
||||
| **底部迷你横幅**(可选 P1) | 完成一次完整流程(下载/生成图纸后) | 「安装到主屏,离线也能看图纸 [稍后] [安装]」 | 同上 + `localStorage` dismissed 记录 |
|
||||
| **iOS 图文引导**(P2) | iOS 抽屉安装行点击 | 弹层图文:分享按钮 → 添加到主屏幕 | `navigator.standalone === false` |
|
||||
|
||||
**设计约束**:
|
||||
- 不拦截首屏、不弹窗打扰(PWA-PLAN §5 原则)——只做抽屉入口 + 低频迷你横幅。
|
||||
- 已安装态自动隐藏(`matchMedia('(display-mode: standalone)')`)。
|
||||
- 图标用 DESIGN 主题色系,不引入第三方图标库。
|
||||
|
||||
### 3.4 帮助中心入口(移动端)
|
||||
|
||||
现状:SubNav 已含 `/help`(T-106 交付 HelpPage,FAQ 8 分类 zh+en)。
|
||||
|
||||
| 增强点 | 优先级 | 说明 |
|
||||
|---|---|---|
|
||||
| 抽屉内帮助行(工具组) | 已有 | 与桌面导航一致的位置入口 |
|
||||
| 帮助页内「换一批」相关推荐 | P2 | FAQ 底部分类导航(手风琴已支持分类折叠) |
|
||||
| 帮助页页头加入口按钮「查看安装指南」 | P2 | 链接到 PWA 安装引导(当 PWA 落地后) |
|
||||
|
||||
### 3.5 分享入口(移动端)
|
||||
|
||||
现状:`share-codec.ts` 已有分享码机制(可解码渲染单张图纸),但无分享 UI。
|
||||
|
||||
| 场景 | 入口位置 | 行为 |
|
||||
|---|---|---|
|
||||
| 生成结果页(图纸预览区) | 下载按钮旁「分享」icon | `navigator.share({title, text, url})` → fallback 复制链接 + toast |
|
||||
| 抽屉生态区 | 「分享 PERLER LAB」 | 分享首页链接(品牌传播) |
|
||||
| Showcase/图纸详情 | 卡片操作栏「分享」 | 分享码 URL(`?code=...`) |
|
||||
|
||||
> 分享是移动端社交传播的核心生态入口,成本极低(复用 share-codec + Web Share API),建议 P1 优先。
|
||||
|
||||
---
|
||||
|
||||
## 4. 交互与视觉规范(对齐 DESIGN.md 令牌)
|
||||
|
||||
### 4.1 令牌引用(禁止硬编码)
|
||||
|
||||
| 视觉属性 | 令牌 | 值 |
|
||||
|---|---|---|
|
||||
| 抽屉背景 | `--bg-card` | `#ffffff` |
|
||||
| 分组标题 H3 | `--text-secondary` + `--text-xs`(11px) 大写加宽字距 | `#66645d` |
|
||||
| 生态区卡片底 | `--bg-subtle` | `#f0ede4` |
|
||||
| 安装行图标强调 | `--accent` | `#edb045` |
|
||||
| 正文/说明 | `--text-md`(13px) / `--text-secondary` | — |
|
||||
| 分隔线 | `--border` / `--border-dashed` | `#e6e3d9` / `#e0dccd` |
|
||||
| 触控目标 | `--touch-min`(40px) / `--touch-min-sm`(34px) | 生态区行 ≥ 40px |
|
||||
| 圆角 | `--radius-md`(10px) 卡片 / `--radius-lg`(12px) 弹层 | — |
|
||||
| 阴影 | `--shadow-float`(抽屉) / `--shadow-modal`(安装引导弹层) | — |
|
||||
| 字体 | `--font-sans`(PingFang SC / Microsoft YaHei) | — |
|
||||
|
||||
### 4.2 组件规格
|
||||
|
||||
| 元素 | 规格 |
|
||||
|---|---|
|
||||
| 抽屉 | 右侧滑入,max-width 360px,全高,`--shadow-float`,遮罩 `rgba(23,23,19,.4)`,右上 × 关闭 |
|
||||
| 分组标题 | 11px uppercase `tracking-widest` 灰字,下距 `--space-2` |
|
||||
| 导航项行 | 高 ≥ 40px,`--text-lg`(17px),hover `--bg-hover`,active `--accent` 左侧 3px 指示条 |
|
||||
| 生态区卡片 | 内边距 `--space-3`,`--bg-subtle` 底 + `--radius-md`,项间 `--border` 细分隔 |
|
||||
| 安装行 | icon(16px) + 标题(15px) + 说明(12px 灰),点击有按压态(transform scale .98) |
|
||||
| 分享行 | 同上,复用 `--accent` 强调 icon |
|
||||
| 迷你安装横幅 | 底部固定,`--shadow-float`,`--bg-card`,两按钮(次级「稍后」+ 主按钮 `--accent` 底白字) |
|
||||
|
||||
### 4.3 交互规范
|
||||
|
||||
| 交互 | 规则 |
|
||||
|---|---|
|
||||
| 抽屉开关 | 汉堡按钮(`lg:hidden`)展开;点击遮罩/×/`Escape` 关闭;关闭后可记忆上次分组展开态 |
|
||||
| 安装点击 | `deferredPrompt.prompt()`;用户选择"取消"后 24h 内不再展示(`localStorage` 记录) |
|
||||
| iOS 引导 | 弹层 `--shadow-modal` 居中,图文步骤(分享 → 添加到主屏幕),不可装时只显示此引导 |
|
||||
| 分享 | `navigator.share` 存在则调用;否则 `navigator.clipboard.writeText` + toast「链接已复制」 |
|
||||
| 无障碍 | 抽屉 `role="dialog"` `aria-modal`;安装行 `role="menuitem"`;焦点圈定在抽屉内,关闭归还焦点到汉堡按钮 |
|
||||
| 已安装态 | `display-mode: standalone` matchMedia 为真 → 隐藏安装行,生态区仅剩分享/帮助 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 优先级矩阵(P0 / P1 / P2)
|
||||
|
||||
> 依据:我方无客户端产品 → apps 页暂缓(NAV-ALIGNMENT §1 #8「不做」);聚焦 PWA 安装提示 + 帮助中心入口。
|
||||
|
||||
| ID | 优先级 | 入口 | 任务 | 验收标准 | 依赖 |
|
||||
|---|---|---|---|---|---|
|
||||
| **E-1** | **P0** | PWA 安装 | 移动端抽屉生态区:安装行(可安装态 prompt / iOS 引导态 / 已安装隐藏) | ① `beforeinstallprompt` 捕获后抽屉显示安装行,点击可 `prompt()`;② 已安装态自动隐藏;③ iOS 显示图文引导;④ 无图标无动效硬编码,全令牌 | PWA-PLAN P3-1(`pwa-install.ts`) |
|
||||
| **E-2** | **P1** | 分享 | 生成结果页 + 抽屉生态区分享入口(Web Share API + 剪贴板 fallback) | ① 结果页「分享」icon 分享当前图纸(share-codec URL);② 抽屉「分享 PERLER LAB」分享首页;③ fallback 复制链接 + toast | `share-codec.ts`(已有) |
|
||||
| **E-3** | **P1** | 帮助 | 抽屉生态区帮助行(显式入口)+ 帮助页安装指南链接 | ① 抽屉生态区含帮助入口指向 `/help`;② HelpPage 顶部含「安装到主屏」说明条目(PWA 落地后) | T-106(HelpPage 已有) |
|
||||
| **E-4** | **P1** | 安装横幅 | 完成一次完整流程后底部迷你安装横幅(可关闭,localStorage 记 dismissed) | ① 首次下载/生成图纸后展示一次;② 「稍后」关闭记 dismissed,24h 不再弹;③ 已安装不再展示 | E-1 + PWA-PLAN §5 |
|
||||
| **E-5** | **P2** | 帮助增强 | HelpPage 分类推荐 + 安装指南子条目 | ① FAQ 底部「相关问题」推荐 3 条;② 安装指南条目图文并茂 | E-3 |
|
||||
| **E-6** | **P2** | 离线态 | 离线 banner(`navigator.onLine` 检测)+ 抽屉生态区显示「离线可用」徽标 | ① 离线时顶部细条 banner;② 已安装态抽屉显示「离线可用」小徽标 | PWA-PLAN P2(SW 离线 fallback) |
|
||||
| — | **不做** | apps 页 | 客户端下载页 /zh/apps(无产品不建) | — | 未来出客户端/小程序再立项 |
|
||||
|
||||
**优先级逻辑**:
|
||||
- **P0 = 安装入口**:PWA 是唯一能把"无客户端"转成"可安装应用"的路径(T-105 已评估零依赖、已验证),抽屉安装行是投入产出比最高的生态入口。
|
||||
- **P1 = 分享 + 帮助**:分享复用已有 share-codec(成本≈0),帮助入口已存在(T-106 交付)只需强化呈现。
|
||||
- **P2 = 增强**:离线徽标与安装横幅体验优化,依赖 P0/P1 与 SW 落地。
|
||||
- **不做 apps**:竞品 apps 是"有产品才有入口",我方无客户端则下载页无内容可放,空建页面损害信任。
|
||||
|
||||
---
|
||||
|
||||
## 6. 风险与注意
|
||||
|
||||
1. **不空建 apps 页**:用户点进无产品的"客户端"页 = 体验事故。生态入口永远指向**真实可用的东西**(可安装的 PWA、可读的 FAQ、可用的分享)。
|
||||
2. **安装提示克制**:不拦截首屏、不频繁弹窗(PWA-PLAN §5 原则);用户拒绝后尊重选择(24h 冷却)。
|
||||
3. **iOS 差异**:无 `beforeinstallprompt`,SW 更新激进——iOS 只做图文引导,不做主路径投入(PWA-PLAN §8 #5)。
|
||||
4. **已安装态正确隐藏**:`display-mode: standalone` 必须判定,避免已装用户反复看到"安装"行。
|
||||
5. **分享码 URL 可解码**:分享出去的 `share-codec` URL 必须能被任意访客解码渲染(已有能力,回归测试确认)。
|
||||
6. **不引入泛化工具分组**:竞品「工具/指南」7 个泛化页面偏离拼豆核心定位,移动端抽屉不得复刻(NAV-ALIGNMENT §1 已排除)。
|
||||
7. **图标与视觉全令牌**:安装/分享 icon 用现有 CSS 绘制或 DESIGN 色系 SVG,不引入第三方图标库,不硬编码色值。
|
||||
|
||||
---
|
||||
|
||||
## 7. 落地依赖与衔接
|
||||
|
||||
| 环节 | 承接 |
|
||||
|---|---|
|
||||
| PWA manifest/SW/安装提示 | PWA-PLAN T-105 P0–P3 任务(P3-1 即 E-1 依赖) |
|
||||
| 移动端抽屉组件 | NAV-ALIGNMENT P0-3(汉堡 + 分组抽屉)——生态区是其扩展 |
|
||||
| 帮助页 | T-106 HelpPage(已交付)——E-3/E-5 在其上增强 |
|
||||
| 分享码 | `share-codec.ts`(已有)——E-2 直接复用 |
|
||||
|
||||
> 排期建议:NAV-ALIGNMENT P0-3(抽屉)→ E-1(PWA 安装行)→ E-2/E-3(分享+帮助)→ E-4(横幅)→ E-5/E-6(增强)。
|
||||
|
||||
---
|
||||
|
||||
*文档完。竞品生态入口数据基于 `pixelbeads-nav-crawl.md` Spider 实测;T-116(apps 落地页细节)开发中未产出,待其完成后可补充 §1.1 落地页内容。我方设计全部基于源码实读 + PWA-PLAN/NAV-ALIGNMENT 既有决策,无推断项。*
|
||||
@@ -0,0 +1,196 @@
|
||||
# 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 实测)与我方源码实读,无推断项。*
|
||||
@@ -0,0 +1,293 @@
|
||||
# PWA-PLAN — PERLER LAB PWA 接入评估与实施方案
|
||||
|
||||
> **任务**: T-105 PWA 接入评估:manifest 与离线缓存方案
|
||||
> **角色**: Oracle-Architect-Agent
|
||||
> **日期**: 2026-08-14
|
||||
> **输入依据**:
|
||||
> - 竞品 manifest 实测: `competitor-analysis/raw/manifest-decoded.json`(PixelBeads:standalone / 192+512 maskable 图标 / 白底)
|
||||
> - 我方现状: `perler-lab/vite.config.ts`(Vite+React SPA)、`perler-lab/index.html`、`src/main.tsx`(客户端路由按 pathname 分发)、`public/`(仅 favicon.svg,无 PNG 图标)
|
||||
> - 约束: 不引入不必要新依赖(优先手写)、不做原生应用(竞品 Chrome 插件 + Android/iOS 生态不在本次范围)
|
||||
|
||||
---
|
||||
|
||||
## 0. 结论速览(推荐方案)
|
||||
|
||||
| 维度 | 结论 |
|
||||
|---|---|
|
||||
| **方案** | **手写 `public/manifest.webmanifest` + `public/sw.js` + 手动注册**(零新依赖) |
|
||||
| 备选 | vite-plugin-pwa(工作区缓存 + 自动注入,但新增构建依赖) |
|
||||
| **首期落地** | P0 前置(PNG 图标 + HTTPS 就绪)→ P1 manifest + 注册 → P2 SW precache + 运行时缓存 → P3 安装提示 |
|
||||
| 收益 | 安装到桌面/主屏、离线可用、首屏加速(SW 接管静态资源)、竞品对齐(standalone 体验) |
|
||||
| 风险 | 缓存失效/版本管理、图标缺失导致不可安装、SW 需 HTTPS(localhost 例外) |
|
||||
|
||||
**推荐理由(手写 vs vite-plugin-pwa)**:
|
||||
|
||||
1. **零新依赖**——项目一贯原则(对比 PDF 导出 T-076 同样零依赖手写),手写 manifest + SW 只涉及 2 个静态文件 + 一段注册代码,不进入 `package.json`。
|
||||
2. **SPA 架构极简**——单页 + pathname 路由 + 构建产物 `dist/` 下 js/css 均带内容哈希,手写 precache 只需在发布时刷新一份资源清单,无复杂集成面。
|
||||
3. **可控的缓存策略**——vite-plugin-pwa 默认 generateSW 注入 workbox 运行时(额外 ~20KB),我方离线需求(静态资源 + SPA shell + 离线降级)用原生 Cache API 即可覆盖,策略完全在手。
|
||||
4. **迁移成本低**——未来若需要自动资源清单/更细粒度运行时缓存,可平滑升级到 vite-plugin-pwa,manifest 与 sw.js 内容可直接复用。
|
||||
|
||||
> 竞品对齐边界:竞品 manifest 仅 4 个核心字段(name/short_name/display/icons/theme+background)。我方在其基础上补齐 `start_url/scope/id`,保证安装与离线行为确定;**不做**竞品的三端应用生态。
|
||||
|
||||
---
|
||||
|
||||
## 1. 现状与竞品对比
|
||||
|
||||
### 1.1 我方现状
|
||||
|
||||
| 项 | 现状 | 对 PWA 的影响 |
|
||||
|---|---|---|
|
||||
| 构建 | Vite + React SPA,`dist/` 输出 | 产物含哈希,适合 SW precache |
|
||||
| 路由 | `App.tsx` 按 `window.location.pathname` 分发(/、/chibi、/color-chart、/showcase、/library、/help) | 离线需导航请求 fallback 到 SPA shell |
|
||||
| 图标 | 仅 `public/favicon.svg` | **缺少 192/512 PNG,阻断安装提示**(P0 前置) |
|
||||
| 传输 | 静态部署(nginx/Docker,见 DEPLOY.md) | 需确认 HTTPS(T-030 已含域名与 HTTPS 章节) |
|
||||
| 数据 | 图片处理在浏览器本地完成(FAQ-33),无用户体系 | 离线缓存不涉及敏感数据,风险低 |
|
||||
|
||||
### 1.2 竞品 manifest(pixel-beads,实测解码)
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "PixelBeads – Perler Bead Pattern Generator",
|
||||
"short_name": "PixelBeads",
|
||||
"description": "Create, edit, and export Perler bead patterns and pixel art in your browser.",
|
||||
"start_url": "/",
|
||||
"scope": "/",
|
||||
"icons": [
|
||||
{ "src": "/web-app-manifest-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "maskable" },
|
||||
{ "src": "/web-app-manifest-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
|
||||
],
|
||||
"theme_color": "#ffffff",
|
||||
"background_color": "#ffffff",
|
||||
"display": "standalone"
|
||||
}
|
||||
```
|
||||
|
||||
竞品要点:`display: standalone`(独立窗口,无地址栏)、maskable 图标、白底主题。我方沿用这一字段基线。
|
||||
|
||||
---
|
||||
|
||||
## 2. manifest 字段设计(建议落地值)
|
||||
|
||||
文件:`perler-lab/public/manifest.webmanifest`(MIME `application/manifest+json`,Vite 会自动把 `public/` 拷入 `dist/`)。
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "/",
|
||||
"name": "PERLER LAB · 拼豆图纸生成器",
|
||||
"short_name": "PERLER LAB",
|
||||
"description": "把喜欢的图片,变成一颗颗拼豆。免费生成、调整拼豆图纸,支持六品牌色号速查。",
|
||||
"start_url": "/",
|
||||
"scope": "/",
|
||||
"display": "standalone",
|
||||
"orientation": "portrait-primary",
|
||||
"background_color": "#f4f3ef",
|
||||
"theme_color": "#f4f3ef",
|
||||
"lang": "zh-CN",
|
||||
"categories": ["design", "art", "photography"],
|
||||
"icons": [
|
||||
{ "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
|
||||
{ "src": "/icons/icon-192-maskable.png", "sizes": "192x192", "type": "image/png", "purpose": "maskable" },
|
||||
{ "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
|
||||
{ "src": "/icons/icon-512-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
|
||||
],
|
||||
"shortcuts": [
|
||||
{ "name": "品牌色号表", "short_name": "色号表", "url": "/color-chart", "icons": [{ "src": "/icons/icon-192.png", "sizes": "192x192" }] },
|
||||
{ "name": "AI 拼豆专区", "short_name": "AI 专区", "url": "/chibi", "icons": [{ "src": "/icons/icon-192.png", "sizes": "192x192" }] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
字段说明:
|
||||
|
||||
| 字段 | 值 | 理由 |
|
||||
|---|---|---|
|
||||
| `id` | `/` | Chrome 120+ 安装身份标识,固定根路径避免随 start_url 变化重复安装 |
|
||||
| `display` | `standalone` | 对齐竞品,独立窗口体验 |
|
||||
| `theme_color` / `background_color` | `#f4f3ef` | 对齐 DESIGN.md 页面底色(`--bg-page`),启动屏与浏览器 UI 观感一致 |
|
||||
| `start_url` / `scope` | `/` | 全站可安装、可离线;scope 收紧到站内,禁止 SW 越界 |
|
||||
| `icons` | 192/512 any+maskable | **Chrome 安装硬性要求**;maskable 保证圆形裁剪安全区(图标主体留 ≥ 20% 安全边距) |
|
||||
| `shortcuts` | 色号表 / AI 专区 | 长按/右键跳转深链,复用已有路由,成本≈0 |
|
||||
|
||||
> **index.html 配套改动**:`<link rel="manifest" href="/manifest.webmanifest">` + `<meta name="theme-color" content="#f4f3ef">` + `<link rel="apple-touch-icon" href="/icons/icon-192.png">`(iOS 主屏)。iOS 需额外 `apple-mobile-web-app-capable` meta 才可全屏。
|
||||
|
||||
---
|
||||
|
||||
## 3. Service Worker 缓存策略
|
||||
|
||||
文件:`perler-lab/public/sw.js`(手写,原生 Cache API,无 workbox)。版本号 `const VERSION = 'v1'`,每次发布递增缓存名 `perler-precache-${VERSION}` / `perler-runtime-${VERSION}`。
|
||||
|
||||
### 3.1 缓存分层
|
||||
|
||||
| 缓存 | 内容 | 策略 |
|
||||
|---|---|---|
|
||||
| `perler-precache-v1` | `index.html` + `assets/*.js` + `assets/*.css`(构建产物,发布时刷新清单) | **install 时预缓存(precache)** |
|
||||
| `perler-runtime-v1` | 图片/字体/`/color-chart` 等静态资源 | **stale-while-revalidate** |
|
||||
| 导航请求(`mode: 'navigate'`) | — | **network-first → fallback 缓存的 index.html(离线 SPA shell)** |
|
||||
| `/api/*`、POST、fetch(XHR) | — | **网络优先,不缓存**(后端动态数据;POST 含支付/兑换,绝不下 SW 缓存) |
|
||||
|
||||
### 3.2 关键策略伪代码
|
||||
|
||||
```js
|
||||
// ① install:预缓存静态资源,任何一项失败即整体失败(安装不完整则中断)
|
||||
self.addEventListener('install', (e) => {
|
||||
e.waitUntil(
|
||||
caches.open(PRECACHE).then((c) => c.addAll(PRECACHE_ASSETS)),
|
||||
);
|
||||
self.skipWaiting();
|
||||
});
|
||||
|
||||
// ② activate:清理旧版本缓存,立即接管页面
|
||||
self.addEventListener('activate', (e) => {
|
||||
e.waitUntil(
|
||||
caches.keys().then((keys) =>
|
||||
Promise.all(keys.filter((k) => k !== PRECACHE && k !== RUNTIME).map((k) => caches.delete(k))),
|
||||
),
|
||||
);
|
||||
self.clients.claim();
|
||||
});
|
||||
|
||||
// ③ fetch:三类分流
|
||||
self.addEventListener('fetch', (e) => {
|
||||
const req = e.request;
|
||||
if (req.method !== 'GET') return; // 非 GET 一律放行
|
||||
const url = new URL(req.url);
|
||||
if (url.origin !== location.origin) return; // 跨域放行(可另加白名单运行时缓存)
|
||||
|
||||
if (req.mode === 'navigate') {
|
||||
// 导航:network-first,离线回退 SPA shell
|
||||
e.respondWith(
|
||||
fetch(req).then((res) => {
|
||||
const copy = res.clone();
|
||||
caches.open(RUNTIME).then((c) => c.put(req, copy));
|
||||
return res;
|
||||
}).catch(() => caches.match('/index.html')),
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
if (url.pathname.startsWith('/api/')) return; // API 网络优先,不缓存
|
||||
|
||||
// 静态资源:stale-while-revalidate(秒开体验 + 后台更新)
|
||||
e.respondWith(
|
||||
caches.match(req).then((cached) => {
|
||||
const network = fetch(req)
|
||||
.then((res) => {
|
||||
if (res.ok) {
|
||||
const copy = res.clone();
|
||||
caches.open(RUNTIME).then((c) => c.put(req, copy));
|
||||
}
|
||||
return res;
|
||||
})
|
||||
.catch(() => cached);
|
||||
return cached || network;
|
||||
}),
|
||||
);
|
||||
});
|
||||
```
|
||||
|
||||
### 3.3 资源清单(precache)维护方式
|
||||
|
||||
推荐:**发布时生成**(`dist/` 内 js/css 均含内容哈希)。提供两种维护法,二选一:
|
||||
1. 简单法:发布后在 `dist/` 手动跑 `node scripts/build-precache.mjs`(读取 `dist/index.html` 中 `assets/*` 引用 + 固定项,输出 SW 顶部 `PRECACHE_ASSETS` 数组)。
|
||||
2. 保守法:`index.html` 永远在清单首项(离线 shell),js/css 每次发布整体更新 `VERSION` 并重建清单,保证原子切换。
|
||||
|
||||
> ⚠️ 不用 cache-first 缓存 `index.html`:开发/灰度时 html 变化需即时生效,故导航用 network-first。
|
||||
|
||||
---
|
||||
|
||||
## 4. 离线页面
|
||||
|
||||
SPA 客户端渲染架构下,**导航 fallback 到缓存的 `index.html` 即自动获得离线页面**——React 应用本身可完整渲染,无需独立 `/offline.html`。
|
||||
|
||||
离线降级路径:
|
||||
|
||||
| 场景 | 行为 |
|
||||
|---|---|
|
||||
| 已访问过任意页面 + 离线 | 导航请求失败 → 返回缓存的 `index.html` → 应用正常渲染(静态资源命中 precache/runtime) |
|
||||
| 首次安装后未访问 + 离线 | 缓存中无 shell → 浏览器默认「无法连接」页(预期内,P2 后可加 first-visit 预缓存) |
|
||||
| 离线时请求 `/api/*` | 放行到网络失败,前端 api.ts 现有错误提示兜底(不缓存敏感数据) |
|
||||
|
||||
可选增强(P3):hero 区顶部 banner「当前离线,显示缓存内容」——通过 `navigator.onLine` + SW message 检测,成本低、体验完整。
|
||||
|
||||
---
|
||||
|
||||
## 5. 安装提示(Install Prompt)
|
||||
|
||||
竞品纯 Web 无自定义安装引导;我方建议**温和引导**(不弹窗打扰、不拦截首屏):
|
||||
|
||||
1. **PWA 资格预检**:`display-mode: standalone` matchMedia 判断已安装态;监听 `beforeinstallprompt`(Chrome 有资格时触发)。
|
||||
2. **触发时机**:用户已完成一次完整流程(如下载/生成图纸后)或停留 > 30s,在底部浮出「添加到主屏幕 / 安装到桌面」横幅(可关闭,`localStorage` 记 dismissed)。
|
||||
3. **deferredPrompt**:捕获 `beforeinstallprompt` 事件存入变量,点横幅时 `prompt()`;`appinstalled` 后清理横幅。
|
||||
4. **iOS Safari**:无 install prompt API,横幅展示「分享 → 添加到主屏幕」图文指引(`navigator.standalone` 判断 iOS)。
|
||||
|
||||
```ts
|
||||
// src/lib/pwa-install.ts(P3 落地,示意)
|
||||
let deferred: BeforeInstallPromptEvent | null = null;
|
||||
window.addEventListener('beforeinstallprompt', (e) => {
|
||||
e.preventDefault();
|
||||
deferred = e as BeforeInstallPromptEvent;
|
||||
window.dispatchEvent(new CustomEvent('pwa-installable', { detail: { deferred } }));
|
||||
});
|
||||
window.addEventListener('appinstalled', () => {
|
||||
window.dispatchEvent(new CustomEvent('pwa-installed'));
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 注册代码
|
||||
|
||||
文件:`perler-lab/src/main.tsx` 追加(仅生产环境注册,避免 dev 热更替被 SW 缓存干扰):
|
||||
|
||||
```ts
|
||||
// 生产环境注册 Service Worker(public/sw.js 构建后自动复制到 dist/)
|
||||
if (import.meta.env.PROD && 'serviceWorker' in navigator) {
|
||||
window.addEventListener('load', () => {
|
||||
navigator.serviceWorker.register('/sw.js').catch((err) => {
|
||||
console.warn('[PWA] SW 注册失败:', err);
|
||||
});
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
> dev 模式不注册:Vite HMR 与 SW 缓存冲突;仅 `dist/` 生产构建验证。
|
||||
|
||||
---
|
||||
|
||||
## 7. 实施拆解(建议任务拆分)
|
||||
|
||||
| ID | 优先级 | 任务 | 验收标准 |
|
||||
|---|---|---|---|
|
||||
| P0-1 | P0 | 生成 192/512 PNG 图标(any+maskable,主题色 `#f4f3ef`,可基于 favicon.svg 导出) | 4 个文件入 `public/icons/`,Chrome DevTools 安装资格无图标报错 |
|
||||
| P0-2 | P0 | 确认生产 HTTPS 就绪(T-030 已含) | 生产域名证书有效,SW 可在 https 注册 |
|
||||
| P1-1 | P1 | `public/manifest.webmanifest` + `index.html` 注入 link/meta | DevTools Application 面板读取正常,字段无警告 |
|
||||
| P1-2 | P1 | `src/main.tsx` 注册 SW(PROD 守卫) | 生产构建 `dist/` 部署后 `navigator.serviceWorker.controller` 非空 |
|
||||
| P2-1 | P2 | `public/sw.js` precache + 运行时缓存 + 离线 fallback | 离线模式(Network offline)刷新可打开站点并看到缓存内容 |
|
||||
| P2-2 | P2 | 资源清单生成脚本 `scripts/build-precache.mjs` | 发布后 dist 清单与实际产物一致 |
|
||||
| P3-1 | P3 | 安装提示横幅 + 已安装态检测 | beforeinstallprompt 触发、横幅可关闭、已安装不再出现 |
|
||||
| P3-2 | P3 | 离线 banner + 版本更新提示(skipWaiting 后刷新引导) | 新版本发布后旧标签页收到更新提示 |
|
||||
|
||||
> 本任务(T-105)交付本评估文档;P0–P3 拆为独立任务由前端承接实施。
|
||||
|
||||
---
|
||||
|
||||
## 8. 风险与注意
|
||||
|
||||
1. **SW 注册失败静默**:注册代码 try/catch 仅告警,绝不阻塞主流程。
|
||||
2. **缓存与发版不同步**:SW 有更新滞后窗口(默认 24h 检查,`updateViaCache` 与 `skipWaiting` 已缓解);发布流程需包含「递增 VERSION」动作。
|
||||
3. **HTTPS 前置**:SW 仅在 secure context 可用(localhost 例外),生产必须 HTTPS(T-030 已就绪)。
|
||||
4. **不要缓存敏感/动态数据**:`/api/*` 与 POST 一律网络优先;支付回调、兑换码相关请求严禁落入 SW 缓存。
|
||||
5. **iOS 限制**:iOS Safari 不支持 beforeinstallprompt、SW 更新较激进、旧版本不清理缓存——低优先级适配即可,不做主路径投入。
|
||||
6. **离线不等于单机可用**:AI 生成等后端能力离线不可用属预期,离线收益聚焦「浏览/查阅色号表/已缓存图纸」。
|
||||
|
||||
---
|
||||
|
||||
## 9. 部署配套(对接 T-110)
|
||||
|
||||
- `nginx` 需为 `/.webmanifest` / `manifest.webmanifest` 返回 `application/manifest+json`,`/sw.js` 返回 `application/javascript` 且 **禁止协商缓存**(`Cache-Control: no-cache`,SW 自身更新依赖每次校验)。
|
||||
- `index.html` 建议 `no-cache`(网络优先策略前提)。
|
||||
- `dist/assets/*` 内容哈希 + 长缓存不变。
|
||||
|
||||
---
|
||||
|
||||
*文档完。方案基于竞品 manifest 实测(`manifest-decoded.json`)与我方源码实读(vite.config.ts / index.html / main.tsx / App.tsx),无推断项。*
|
||||
@@ -0,0 +1,190 @@
|
||||
# PERLER LAB V1.1 发布计划(RELEASE-V1.1)
|
||||
|
||||
> 版本: v1.0 · 文档编号: RELEASE-V1.1 · 关联任务: T-111
|
||||
> 角色: Release-Manager · 日期: 2026-08-14
|
||||
> 上游依据: RELEASE-PIPELINE.md(发布流水线)、LAUNCH.md(SEO/上线)、NAV-ALIGNMENT.md(导航对齐)、ROADMAP.md(V1.1 增长版)、CI-GATES.md(质量门禁)、DEPLOY.md(部署)
|
||||
> 当前基线: V1.0 已发布(70 任务验收通过),V1.1 批次 T-091~T-111 共 21 个任务 + BUG-112 并行开发中
|
||||
|
||||
---
|
||||
|
||||
## 0. 结论速览
|
||||
|
||||
| 维度 | 结果 |
|
||||
|---|---|
|
||||
| V1.1 主题 | 导航对齐(NAV-ALIGNMENT P0/P1)+ 色号表 SEO 页 + Showcase + 图纸库 + 帮助中心 + 评估类文档 |
|
||||
| 范围条目数 | 22 条(21 任务 + BUG-112),其中代码交付 14 条、文档交付 8 条 |
|
||||
| 里程碑 | M1 前端页面 → M2 后端接口 → M3 集成联调 → M4 发布(M1/M2 可并行) |
|
||||
| 发布方式 | 沿用 RELEASE-PIPELINE.md:验收 → auto-commit 自动提交 → gitflow.js push master → CI(deploy.yml)→ 部署 |
|
||||
| 阻塞点 | T-096 不合格 → BUG-112 修复中;T-110 部署核对、T-109 CI 门禁为发布前置 |
|
||||
| 回滚手段 | git revert 重新推送;Docker 镜像回退上一版本;SQLite 备份还原 |
|
||||
|
||||
---
|
||||
|
||||
## 1. V1.1 范围清单
|
||||
|
||||
> 交付类型标注:**[代码]** = 源码/构建/CI 交付(进 git 与生产),**[文档]** = 决策/评估/文案文档交付(进 docs/,作为代码交付的依据或内容源)。
|
||||
|
||||
| # | 工作项 | 关联任务 | 交付类型 | 当前状态 | 说明 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 色号表页:六品牌页面组件实现 | T-091 | **[代码]** | 待验收 | ColorChartPage.tsx + CSS,tab 切换 + 表格 + URL 品牌段 + i18n + 响应式 |
|
||||
| 2 | 色号表页:数据层接入 | T-092 | **[代码]** | 待验收 | color-chart-data.ts,六品牌聚合(221/174/103/92/18/30 色) |
|
||||
| 3 | 色号表页:路由注册 | T-093 | **[代码]** | 待验收 | /color-chart 与 /color-chart/:brand,未知品牌回退 MARD |
|
||||
| 4 | 色号表页:JSON-LD 结构化数据 | T-094 | **[代码]** | 待验收 | GET /api/color-chart/:brand,CollectionPage+ItemList schema |
|
||||
| 5 | 色号表页:内链与导航入口 | T-095 | **[代码]** | 开发中 | 首页/页脚内链 + 导航入口,吃「拼豆色号表」长尾词 |
|
||||
| 6 | 色号表页:SEO 标题与描述 | T-096 | **[文档]** | 不合格 → BUG-112 修复中 | SEO-COLORCHARTS.md 六品牌 zh+en title/description,BUG-112 重做 |
|
||||
| 7 | Showcase:作品展示页路由与布局 | T-097 | **[代码]** | 待验收 | /showcase 路由 + 响应式卡片网格(4/3/2/1 列) |
|
||||
| 8 | Showcase:作品卡片与标签筛选 | T-098 | **[代码]** | 待验收 | WorkCard 组件 + 分类筛选,种子数据 lib/showcase.ts |
|
||||
| 9 | Showcase:发布保存接口 | T-099 | **[代码]** | 待验收 | POST /api/showcase/works,showcase_works 表 + 校验(DB schema 变更) |
|
||||
| 10 | Showcase:列表查询接口 | T-100 | **[代码]** | 待验收 | GET /api/showcase/works 分页 + 标签/来源筛选 |
|
||||
| 11 | Showcase:SEO 元数据接口 | T-101 | **[代码]** | 待验收 | GET /api/showcase/meta,title/description/ogImage/jsonLd |
|
||||
| 12 | Showcase:发布流程前端接入 | T-102 | **[代码]** | 待验收 | ChibiPage 发布入口 + publishShowcaseWork |
|
||||
| 13 | 图纸库:列表页组件与路由 | T-108 | **[代码]** | 待验收 | /library 路由,复用 showcase 数据源,空态兜底 |
|
||||
| 14 | 帮助中心:FAQ 页面组件 | T-106 | **[代码]** | 开发中 | /help 路由,单页 FAQ 区块 |
|
||||
| 15 | 帮助中心:FAQ 数据整理 | T-107 | **[文档]** | 验收通过 | FAQ-DATA.md 35 条双语言,供 T-106 渲染 |
|
||||
| 16 | PWA 接入评估 | T-105 | **[文档]** | 开发中 | manifest 与离线缓存方案评估,产出评估结论供 V2.0 立项 |
|
||||
| 17 | i18n 扩展评估(zh-tw/ja) | T-103 | **[文档]** | 待验收 | I18N-ROI.md:zh-tw 建议落地、ja 建议暂缓 |
|
||||
| 18 | 商业模式细化文档 | T-104 | **[文档]** | 待验收 | BUSINESS-MODEL.md:免费 12 项 / 付费 9 项边界 |
|
||||
| 19 | CI 门禁:新页面构建检查 | T-109 | **[代码]** | 开发中 | deploy.yml 覆盖色号表/Showcase/图纸库/帮助路由构建 |
|
||||
| 20 | 部署核对:路由与静态资源 | T-110 | **[代码]** | 开发中 | nginx SPA fallback + 静态资源部署配置核对 |
|
||||
| 21 | 发布计划:V1.1 里程碑 | T-111 | **[文档]** | 开发中(本文档) | 里程碑/范围/门禁/发布步骤/回滚 |
|
||||
| 22 | BUG 修复:色号表 SEO 元数据 | BUG-112 | **[文档]** | 开发中 | T-096 验收不合格的返工任务 |
|
||||
|
||||
**统计:代码交付 14 条(#1~5、7~14、19~20),文档交付 8 条(#6、15~18、21~22)。**
|
||||
|
||||
### 1.1 范围边界(本批次不含)
|
||||
|
||||
- **T-065 BFS 杂色清理、T-085 leafer.js 渲染引擎评估**:V1.0 遗留/独立评估任务,不在 T-091~T-111 发布闸门内,不阻塞 V1.1 发布。
|
||||
- 导航对齐 P2 项(`/chibi?cat=` 深链、帮助子页化):NAV-ALIGNMENT 定义为 P2 按需,**V1.1 不承诺交付**,随数据进入后续版本。
|
||||
- 客户端(apps)、拼豆创作独立页:NAV-ALIGNMENT 决策为「不做 / 暂缓」,不在范围内。
|
||||
- 批量生成、导出优化、埋点看板、历史记录:ROADMAP V1.1 远期功能,未进入本批次,后续迭代。
|
||||
|
||||
---
|
||||
|
||||
## 2. 里程碑阶段划分
|
||||
|
||||
> M1/M2 互不依赖可并行;M3 依赖 M1+M2 基本就绪;M4 依赖 M3 全绿。
|
||||
|
||||
### M1 前端页面(对应 NAV-ALIGNMENT P0/P1 页面跟上)
|
||||
|
||||
| 任务 | 交付物 |
|
||||
|---|---|
|
||||
| T-091/T-092/T-093 | 色号表页组件 + 数据层 + 路由 |
|
||||
| T-095 | 色号表内链与导航入口 |
|
||||
| T-097/T-098 | Showcase 页面 + 作品卡片 |
|
||||
| T-106 | 帮助中心 FAQ 页面 |
|
||||
| T-108 | 图纸库页面 |
|
||||
|
||||
**出口条件**:五个新路由(/color-chart、/showcase、/library、/help + 品牌子路由)全部可达;导航 7 项真实跳转,无「建设中」占位残留(NAV-ALIGNMENT §3.3 P1 撤下占位)。
|
||||
|
||||
### M2 后端接口
|
||||
|
||||
| 任务 | 交付物 |
|
||||
|---|---|
|
||||
| T-094 | JSON-LD 结构化数据接口 |
|
||||
| T-099 | Showcase 发布保存接口(含 schema 变更) |
|
||||
| T-100 | Showcase 列表查询接口 |
|
||||
| T-101 | Showcase SEO 元数据接口 |
|
||||
|
||||
**出口条件**:4 个新端点契约对齐;showcase_works 表迁移对旧库平滑(新增表不影响既有表);npm test 全绿。
|
||||
|
||||
### M3 集成联调
|
||||
|
||||
| 任务 | 交付物 |
|
||||
|---|---|
|
||||
| T-102 | Showcase 发布流程前端接入(端到端:发布 → 落库 → 列表展示) |
|
||||
| T-109 | CI 门禁覆盖新页面构建检查 |
|
||||
| T-110 | 部署核对:路由 fallback + 静态资源 |
|
||||
| 文档类 | T-096/BUG-112、T-103、T-104、T-105、T-107 全部验收通过 |
|
||||
|
||||
**出口条件**:发布→列表全链路可用;本地 `npm run build` + `npm run typecheck` + `npm test` 全绿;`node taskboard.js list` 无 V1.1 任务处于「不合格」状态。
|
||||
|
||||
### M4 发布
|
||||
|
||||
| 动作 | 负责人 |
|
||||
|---|---|
|
||||
| 全量验收复核 | QA-Tester-Agent |
|
||||
| 推送 master 触发 CI | GitOps-Engineer |
|
||||
| 部署与健康检查 | DevOps-Engineer |
|
||||
| 线上冒烟(新页面可达 + 导航跳转) | 主代理 / QA |
|
||||
| 版本号与文档归档 | Release-Manager(T-111) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 验收门禁(QA 验收条件)
|
||||
|
||||
> 每任务经 `node taskboard.js test <id> --pass/--fail` 验收;下述条件为 V1.1 **放行闸门**,全部满足才进入 M4。门禁细则以 CI-GATES.md G1~G9 为准。
|
||||
|
||||
### G-API 代码门禁
|
||||
- **typecheck**:`npm run typecheck`(perler-lab 与 perler-lab-server 两端),`tsc --noEmit` 0 错误,strict 开启(CI-GATES G3)。
|
||||
- **单测**:`npm test` 前后端全部通过,退出码 0(CI-GATES G1/G2,基线前端 147+ 后端 121+,当前批注实测前端 176/后端 156 用例全过)。
|
||||
- **构建**:`npm run build`(vite build)产出 dist/ 成功(CI-GATES G4)。
|
||||
- **CI 冒烟**:T-109 落地后,push 触发 deploy.yml 三阶段(test → build → deploy)全程绿(G7 并发保护、G8 超时、G9 YAML 有效)。
|
||||
|
||||
### G-PAGE 页面可达门禁
|
||||
- 五个新路由 HTTP 可达,SPA 刷新/直链不 404(nginx `try_files` fallback 由 T-110 核对)。
|
||||
- 导航 7 项点击均落在真实页面(NAV-ALIGNMENT §5 教训:不允许「字典有、页面无」的悬空链接)。
|
||||
- 移动端 <1024px 抽屉含「工具」组且无横向溢出;底部固定 CTA 保留可见。
|
||||
- JSON-LD:/color-chart 与 /showcase 源码含 `application/ld+json` 脚本(CollectionPage/WebPage schema)。
|
||||
- 未知品牌路由回退 MARD 不白屏;Showcase 空态兜底正常。
|
||||
|
||||
### G-DOC 文档门禁
|
||||
- SEO-COLORCHARTS.md(BUG-112):六品牌 zh+en title/description 全量覆盖、长度合规、URL slug 无冲突。
|
||||
- I18N-ROI.md、BUSINESS-MODEL.md、PWA 评估(T-105)结论明确且与 PRD/LAUNCH 定价无冲突。
|
||||
- FAQ-DATA.md 与 /help 页面渲染文案一致。
|
||||
|
||||
---
|
||||
|
||||
## 4. 发布步骤(git flow,沿用 RELEASE-PIPELINE.md)
|
||||
|
||||
```
|
||||
验收通过 ──▶ auto-commit.js 自动提交 ──▶ gitflow.js push master ──▶ CI(deploy.yml) ──▶ 部署验证
|
||||
(test --pass) (git add -A + commit) (人工闸门) (test→build→deploy)
|
||||
```
|
||||
|
||||
### 步骤 1:验收
|
||||
- QA 对 22 条任务逐条 `node taskboard.js test <id> --pass/--fail`,状态进入 `approved` / `rejected`(不合格自动生成 Bug,如 BUG-112)。
|
||||
|
||||
### 步骤 2:自动提交(Release-Manager 管道)
|
||||
- `auto-commit.js` 常驻轮询,检测到新 `approved` 任务后执行 `git add -A` + `git commit -m "[验收通过] <id> <标题>"`(RELEASE-PIPELINE §3)。
|
||||
- 提交记录入 `auto-commit.log`;工作区无改动则跳过,不产生空提交。
|
||||
|
||||
### 步骤 3:推送 master(人工闸门,GitOps 工程师)
|
||||
```bash
|
||||
node gitflow.js push # 或 git push -u origin master
|
||||
```
|
||||
- ⚠️ push 是对外发布动作,**必须人工确认**后执行(RELEASE-PIPELINE §4)。确认项:auto-commit.log 无失败重试、`git status` 无遗漏改动、V1.1 无不合格任务残留。
|
||||
|
||||
### 步骤 4:CI(push 触发,自动)
|
||||
- push 触发 `.github/workflows/deploy.yml`:test(前端+后端矩阵)→ build(Docker 镜像)→ deploy(SSH,需 Secrets 已配置,未配置自动跳过)。
|
||||
- 任一 job 失败:查看 Actions 日志 → 修复 → 重新推送(CI-GATES §7 故障处理)。
|
||||
|
||||
### 步骤 5:部署与验证(DevOps 工程师)
|
||||
- 生产 `docker compose -f perler-lab-server/docker-compose.yml up -d --build`,健康检查 3 次失败自动重启兜底(DEPLOY.md)。
|
||||
- 线上冒烟:/color-chart、/showcase、/library、/help 直达 200;导航 7 项逐一点击;生成→发布→列表主链路走一遍。
|
||||
- 数据库:showcase_works 新表自动建表成功(无迁移脚本残留),既有数据完好。
|
||||
|
||||
### 步骤 6:归档
|
||||
- 更新 ROADMAP.md 状态;auto-commit.log 存档;确认 V1.1 全部任务 `approved`,无遗留 `in_progress`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 风险与回滚
|
||||
|
||||
| # | 风险 | 等级 | 对策 | 回滚手段 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | 新路由 SPA 直链 404(nginx fallback 未配) | 高 | T-110 部署核对前置,压测直链刷新 | revert fallback 配置提交并重新部署 |
|
||||
| 2 | showcase_works 建表失败 / schema 冲突 | 高 | M2 验收含旧库兼容测试,T-099 单测覆盖建表 | 保留部署前 SQLite 备份(DEPLOY.md 备份机制),还原后重启 |
|
||||
| 3 | 色号表 SEO 质量不达标(T-096 已返工) | 中 | BUG-112 全量重做六品牌 zh/en,QA 按长度/覆盖度复核 | 本项为文档交付,不影响代码,延后合入不阻塞构建 |
|
||||
| 4 | CI 门禁新增后构建炸裂 | 中 | T-109 本地先验证 deploy.yml,push 前 `npm run build` 自检 | git revert 该提交 → 重新 push,Docker 回退上一镜像版本 |
|
||||
| 5 | i18n 新 key 缺失致 `Messages` 类型错误 | 低 | en.ts 受类型约束强制键全等(编译期拦截,NAV-ALIGNMENT P0-2) | typecheck 阶段即拦截,不会进生产 |
|
||||
| 6 | Showcase 发布接口被滥用(base64 注入) | 中 | T-099 已做长度/格式/标签白名单校验 + 频控 | 线上观察 publish 失败率,超阈值关停入口,回滚提交 |
|
||||
| 7 | 导航改造回归(占位残留 / 移动端溢出) | 中 | M1 出口条件强制检查 7 项真实跳转 + 抽屉无溢出 | 保留导航改造前提交点,revert 后重新推送 |
|
||||
|
||||
**通用回滚流程**(RELEASE-PIPELINE §5/§7):
|
||||
1. `git log --oneline -10` 定位问题提交 → `git revert <hash>` → `node gitflow.js push` 重新触发 CI。
|
||||
2. 生产 Docker 回退:`docker compose up -d` 前将镜像 tag 指回上一版本,或从备份还原 volume。
|
||||
3. 数据库回滚:优先使用部署前 `.backup` 还原(WAL 模式下用 `sqlite3 .backup` 命令而非直接拷贝,DEPLOY.md 明确要求)。
|
||||
|
||||
---
|
||||
|
||||
*文档完。范围与状态以 taskboard.js 实时看板为准,本计划为 V1.1 发布基线。*
|
||||
@@ -0,0 +1,101 @@
|
||||
# 六品牌拼豆色号表页 SEO 文案(T-096)
|
||||
|
||||
> 任务: T-096 色号表 SEO 页面:六品牌色号表页 SEO 标题与描述
|
||||
> 产出: 6 组 SEO 文案(title / meta description / URL slug)
|
||||
> 数据来源: `competitor-analysis/palettes/*.json` 色数 + `competitor-analysis/raw/*-chart.html` 竞品标题、描述、定位
|
||||
> 日期: 2026-08-14
|
||||
|
||||
## 色数口径(源自 palettes/ JSON 实测)
|
||||
|
||||
| 品牌 | 系列 | 色数 | 说明 |
|
||||
|---|---|---|---|
|
||||
| MARD | 标准 5mm | **221** | `mard-palette.json` 实测 221 色(官方另有 291 全量口径) |
|
||||
| Artkal | C 系列 2.6mm 迷你豆 | **174** | `palettes/artkal-c.json` |
|
||||
| Perler | Midi 5mm | **103** | `palettes/perler.json`(官方 SKU 编码) |
|
||||
| Hama | Midi 5mm | **92** | `palettes/hama.json` |
|
||||
| IKEA Pyssla | 5mm | **18** | `palettes/ikea-pyssla.json`(含 8 Pastell) |
|
||||
| Nabbi | Midi 5mm | **30** | `palettes/nabbi.json`(N01–N30) |
|
||||
|
||||
> 竞品口径参考:pixel-beads 色号页为 MARD 291 / Perler 57 / Hama 53 / Artkal-S 159;本表采用我方已落盘色板数据的色数(更全),便于后续接入 T-092 色号表数据展示。
|
||||
|
||||
---
|
||||
|
||||
## 1. MARD 拼豆色号表
|
||||
|
||||
| 项 | 文案 |
|
||||
|---|---|
|
||||
| **URL Slug** | `/color-charts/mard-bead-color-chart` |
|
||||
| **Title (zh)** | MARD 拼豆色号表 221 色全收录|MARD 拼豆色号大全(含 HEX 色值对照) |
|
||||
| **Title (en)** | MARD Bead Color Chart: 221 Colors | MARD Fuse Bead Color Codes & HEX |
|
||||
| **Meta Description (zh)** | MARD 拼豆 221 个官方色号完整对照表,色号编码、HEX 色值与 RGB 数值一应俱全,支持 72/168/221 色套装档位换算与跨品牌色差匹配,搭配拼豆图纸生成器选色更准,拼豆玩家配色必备参考。 |
|
||||
| **Meta Description (en)** | MARD bead color chart: all 221 color codes with HEX & RGB values. Convert 72/168/221 kits, cross-match brands, and pick exact shades in our generator. |
|
||||
|
||||
---
|
||||
|
||||
## 2. Artkal-C 拼豆色号表
|
||||
|
||||
| 项 | 文案 |
|
||||
|---|---|
|
||||
| **URL Slug** | `/color-charts/artkal-c-bead-color-chart` |
|
||||
| **Title (zh)** | Artkal C 拼豆色号表 174 色全收录|2.6mm 迷你拼豆色号大全(含 HEX 对照) |
|
||||
| **Title (en)** | Artkal C Bead Color Chart: 174 Colors | 2.6mm Mini Fuse Bead Color Codes & HEX |
|
||||
| **Meta Description (zh)** | Artkal C 系列 2.6mm 迷你拼豆 174 色官方色号表,色号编码、HEX 色值、RGB 数值齐全,专为高精度写实作品打造,支持跨品牌换算与图纸生成器一键选色,进阶拼豆玩家必备工具。 |
|
||||
| **Meta Description (en)** | Artkal C 2.6mm mini bead color chart: 174 colors with HEX & RGB values, built for high-detail projects, cross-brand matching, and one-click palette picking. |
|
||||
|
||||
---
|
||||
|
||||
## 3. Perler 拼豆色号表
|
||||
|
||||
| 项 | 文案 |
|
||||
|---|---|
|
||||
| **URL Slug** | `/color-charts/perler-bead-color-chart` |
|
||||
| **Title (zh)** | Perler 拼豆色号表 103 色全收录|Perler Midi 拼豆色号大全(含 SKU/HEX) |
|
||||
| **Title (en)** | Perler Bead Color Chart: 103 Colors | Perler Midi Fuse Bead Color Codes & SKU |
|
||||
| **Meta Description (zh)** | Perler Midi 拼豆 103 色官方色号表,官方 SKU 编号、HEX 色值、RGB 数值全量收录,覆盖经典色与荧光色系,支持颜色换算与图纸生成器自动匹配,Perler 玩家查色、配色一站式搞定。 |
|
||||
| **Meta Description (en)** | Perler midi bead color chart: 103 colors and SKU codes with HEX & RGB values, cross-match other brands, and auto-match colors in our generator. |
|
||||
|
||||
---
|
||||
|
||||
## 4. Hama 拼豆色号表
|
||||
|
||||
| 项 | 文案 |
|
||||
|---|---|
|
||||
| **URL Slug** | `/color-charts/hama-bead-color-chart` |
|
||||
| **Title (zh)** | Hama 拼豆色号表 92 色全收录|Hama Midi 拼豆色号大全(含 HEX 对照) |
|
||||
| **Title (en)** | Hama Bead Color Chart: 92 Colors | Hama Midi Fuse Bead Color Codes & HEX |
|
||||
| **Meta Description (zh)** | Hama Midi 拼豆 92 色官方色号表,官方色号编码、HEX 色值、RGB 数值全量收录,欧洲经典品牌、教学场景常用,支持跨品牌换算与图纸生成器自动配色,照着摆豆不迷路。 |
|
||||
| **Meta Description (en)** | Hama midi bead color chart: 92 colors with HEX & RGB values. European classroom favorite, cross-match brands, and auto-pick shades in our generator. |
|
||||
|
||||
---
|
||||
|
||||
## 5. IKEA Pyssla 拼豆色号表
|
||||
|
||||
| 项 | 文案 |
|
||||
|---|---|
|
||||
| **URL Slug** | `/color-charts/ikea-pyssla-bead-color-chart` |
|
||||
| **Title (zh)** | 宜家 Pyssla 拼豆色号表 18 色全收录|IKEA 拼豆色号大全(含 Pastell 马卡龙色) |
|
||||
| **Title (en)** | IKEA Pyssla Bead Color Chart: 18 Colors | Fuse Bead Color Codes & Pastell |
|
||||
| **Meta Description (zh)** | 宜家 Pyssla 拼豆 18 色色号表(含 8 个 Pastell 马卡龙色),色号与色值对照齐全,IKEA 亲子和儿童入门首选,支持与 MARD、Perler 等品牌换算互替,小色板也能拼出好作品。 |
|
||||
| **Meta Description (en)** | IKEA Pyssla bead color chart: 18 colors (incl. 8 Pastell) with HEX & RGB values and MARD/Perler equivalents — great for kids' first fuse-bead projects. |
|
||||
|
||||
---
|
||||
|
||||
## 6. Nabbi 拼豆色号表
|
||||
|
||||
| 项 | 文案 |
|
||||
|---|---|
|
||||
| **URL Slug** | `/color-charts/nabbi-bead-color-chart` |
|
||||
| **Title (zh)** | Nabbi 拼豆色号表 30 色全收录|Nabbi Midi 拼豆色号大全(N01–N30) |
|
||||
| **Title (en)** | Nabbi Bead Color Chart: 30 Colors | Nabbi Midi Fuse Bead Color Codes (N01–N30) |
|
||||
| **Meta Description (zh)** | Nabbi Midi 拼豆 30 色色号表(N01–N30),官方色号编码、HEX 色值、RGB 数值全收录,北欧品质儿童入门品牌,支持与主流品牌换算对照与图纸生成器自动选色,新手配色更省心。 |
|
||||
| **Meta Description (en)** | Nabbi midi bead color chart: 30 colors (N01–N30) with HEX & RGB values, Nordic quality for kids' projects, cross-brand equivalents, and auto color-matching. |
|
||||
|
||||
---
|
||||
|
||||
## 附:实施对接说明
|
||||
|
||||
1. **字数检查**:zh meta description 均落在 100–135 字区间(满足 80–160 要求);en 均 ≤160 字符;zh title ≤30 字、en title ≤70 字符(满足搜索引擎截断窗口)。
|
||||
2. **关键词布局**:每条 zh title 含「品牌名 + 色数 + 拼豆色号表」核心关键词(T-096 要求);en title 含 `Bead Color Chart` + 品牌 + 色数,覆盖英文长尾。
|
||||
3. **JSON-LD(对接 T-094)**:建议色号表页注入 `WebPage + ItemList` 结构化数据,`itemListElement` 引用 221/174/103/92/18/30 色明细。
|
||||
4. **内链(对接 T-095)**:6 个色号表页之间互相内链 + 首页「拼豆色号表」导航入口,锚文本复用 zh title 关键词。
|
||||
5. **hreflang 预留**:URL slug 与竞品 `/perler-bead-color-chart` 风格一致,便于后续扩展 en/ja 等语言路由。
|
||||
@@ -0,0 +1,197 @@
|
||||
# PERLER LAB · SEO 内容矩阵对标建议(T-122)
|
||||
|
||||
> 任务: T-122 | 产出角色: PM-Agent | 日期: 2026-08-14
|
||||
> 数据来源: `competitor-analysis/pixelbeads-analysis.md`(§1.3 站点结构 / §7 差距清单)、`pixelbeads-zh-detail.md`(§1 sitemap 157 URL / §8 Top10)、`docs/I18N-ROI.md`、`docs/LAUNCH.md`(§2 SEO 方案)、`docs/ROADMAP.md`(V1.1/V1.2 排期)、前端路由实测(App.tsx)
|
||||
> 结论预览: 竞品内容矩阵 = **5 类内容页**(色号表 / FAQ 实操 / 作品详情 / 博客 / 帮助细分),我方色号表 6 页 + FAQ 帮助中心已建(V1.1),**V1.2 建议按 6 条路线补齐作品详情页 → 博客 → 帮助细分页 → 主题合集页 → 作者页 → 品牌主题页**,内容生产节奏为「周更 2 篇 + 月更 1 套」。
|
||||
|
||||
---
|
||||
|
||||
## 1. 竞品内容矩阵拆解(pixel-beads.com,157 URL sitemap 实证)
|
||||
|
||||
### 1.1 内容页类型总览
|
||||
|
||||
竞品全站 157 个 URL 中,**非功能页面(纯内容/SEO 页)占比过半**,是流量主体。类型与 SEO 价值如下:
|
||||
|
||||
| # | 内容页类型 | 路由 | 数量(推断) | SEO 价值 |
|
||||
|---|---|---|---|---|
|
||||
| C1 | **品牌色号表页** | `/zh/*-bead-color-chart` | 6 页(MARD/Perler/Hama/Artkal/Pyssla/Nabbi) | ★★★★★ 高转化、低竞争、永久有效 |
|
||||
| C2 | **FAQ 实操知识** | 首页 FAQ + `/zh/help` | 250+ 问答 | ★★★★☆ 信息型流量 + 精选摘要 |
|
||||
| C3 | **作品详情页** | `/zh/perler-bead-pattern/<slug>-pt_<id>` | 单作品一页,随社区增长 | ★★★★☆ 长尾聚合量大、UGC 飞轮 |
|
||||
| C4 | **博客/主题合集页** | `/zh/blog`、`/showcase/christmas-*`、`/showcase/pokemon-*` | blog 1 入口 + 主题合集逐期增 | ★★★☆☆ 拉新 + 季节流量 + 内链枢纽 |
|
||||
| C5 | **帮助细分页** | `/zh/help/perler-bead-art`、`/zh/help/perler-bead-pattern-generator` | 按工具细分 | ★★★☆☆ 工具词精确流量 + 信任 |
|
||||
|
||||
### 1.2 各类别拆解与价值判断
|
||||
|
||||
**C1 色号表页(我方已对标,V1.1 落地)**
|
||||
- 模式:每品牌独立一页,标题含「品牌 + 色数 + 色号表」(如「MARD 拼豆色号表 291 色」),页面含色码→HEX 全量映射、套装档位说明。
|
||||
- 关键词:`MARD 色号表`、`Perler 色号大全`、`拼豆色号对照表` —— **搜索者已进入拼豆制作流程**,转化意图全场最强;竞争页多为论坛/贴吧旧帖,内容页几乎无正规玩家,竞争度低。
|
||||
- 竞品甚至为 zh 站色号页不做 sitemap 维护(§1.2 实测,zh 的 6 个色号页未入 sitemap),说明**这类页流量仍主要靠内链+直接搜索**,维护成本极低。
|
||||
- 我方已完成:6 品牌(MARD 221/Artkal-C 174/Perler 103/Hama 92/Pyssla 18/Nabbi 30)SEO 文案(T-096)+ 色号表页路由(T-091~T-093),JSON-LD/内链建议已在 `docs/SEO-COLORCHARTS.md` 中。
|
||||
|
||||
**C2 FAQ 实操知识(我方已对标,V1.1 落地)**
|
||||
- 模式:竞品 FAQ 不是客服问答,而是**「选豆/配色/打印/熨烫/裱框」五类实操知识**(首轮爬取确认),熨烫温度 105–115°C、LDPE 材质、爆孔处理等细节,共 250+ 条。
|
||||
- 关键词:`拼豆怎么熨`、`拼豆图纸怎么生成`、`拼豆配色技巧` —— 信息型意图,量大、竞争低,且**最容易被 Google/百度精选摘要收录**(问题即标题,答案即正文)。
|
||||
- 我方已完成:`/help` 帮助中心(T-106)+ 35 条 FAQ 数据(T-107,竞品实操 24 条 + 我方特有 11 条),zh+en 双语言。
|
||||
|
||||
**C3 作品详情页(我方缺口,V1.2 建议首批补齐)**
|
||||
- 模式:每个社区作品一个详情页,URL = `slug + pt_<id>`(拼音 slug,如 `ke-ai-mao-mi-pt_1769798328161`),页面含图纸预览、材料清单、作者署名、一键打开编辑。
|
||||
- 关键词:**图案级长尾** `可爱猫咪拼豆图纸`、`线条小狗拼豆图纸`、`宝可梦拼豆图纸`。单页流量小,但**作品数量可无限增长,长尾流量随内容量线性叠加**,且与 Showcase/素材社区天然同构。
|
||||
- SEO 佐证:sitemap 中单个作品页即独立 URL;首页精选 6 作品全部链向详情页,形成「展示页 → 详情页」内链网。竞品还在从 `pt_时间戳` 迁移到 `pt_UUID`,说明**作品页是长期资产,URL 一经发布便不轻易变**。
|
||||
|
||||
**C4 博客/主题合集页(我方缺口,V1.2 建议)**
|
||||
- 模式:`/blog` 统一入口 + 主题合集页(`/showcase/christmas-perler-bead-patterns` 圣诞、`/showcase/pokemon-champions-perler-bead-patterns` 宝可梦冠军,均 6 语言覆盖)。
|
||||
- 关键词:`圣诞拼豆图纸`、`拼豆教程`、`拼豆新手入门` —— 主题合集吃**季节/节日流量**(圣诞/万圣/新年),博客吃教程类信息流量。
|
||||
- 价值:①内链枢纽(合集页聚合 N 个作品详情页,集中传递权重)②节日流量周期性爆发 ③UGC 与官方内容双轨(竞品合集为官方策划)。
|
||||
|
||||
**C5 帮助细分页(我方缺口,低成本补)**
|
||||
- 模式:`/help/` 下按工具分页(`/help/perler-bead-art`、`/help/perler-bead-pattern-generator`),每页讲透一个工具的使用方法。
|
||||
- 关键词:`拼豆图纸生成器怎么用`、`图片转像素画工具` 类工具词。
|
||||
- 价值:①精确捕获工具使用意图流量 ②降低客服成本 ③是 FAQ 的自然扩展(FAQ 单页 → 分工具帮助)。
|
||||
|
||||
### 1.3 竞品矩阵对我们的启示
|
||||
|
||||
1. **内容页是竞品 250+ 长尾流量页的主力,且多为低维护成本静态页**(色号表、作品页),边际成本几乎为 0。
|
||||
2. **色号表与 FAQ 是「打底内容」**,我方 V1.1 已对齐,矩阵地基完成。
|
||||
3. **作品详情页是「增量引擎」**,与 V1.2 素材社区天然耦合,应优先做。
|
||||
4. **主题合集页是「季节放大器」**,成本低、见效周期可预期(节日前后)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 我方 V1.2 内容路线建议(按优先级)
|
||||
|
||||
> 优先级: **P0** = V1.2 内必做 / **P1** = V1.2 顺带 / **P2** = V2.0。
|
||||
> 工作量口径: 前端工程师人日(含模板/路由/联调),内容生产另计。
|
||||
|
||||
### 2.1 已建成(V1.1,无需再投入)
|
||||
|
||||
| 内容页 | 路由 | 状态 |
|
||||
|---|---|---|
|
||||
| 色号表 ×6 | `/color-chart/{mard,artkal-c,perler,hama,pyssla,nabbi}` | ✅ 已建(T-091~093/T-096) |
|
||||
| FAQ 帮助中心 | `/help` | ✅ 已建(T-106/T-107,35 条双语言) |
|
||||
| 作品展示 | `/showcase` | ✅ 已建(T-097/T-098) |
|
||||
| 图纸库 | `/library` | ✅ 已建(T-108) |
|
||||
|
||||
### 2.2 建议新增(按优先级排列)
|
||||
|
||||
**P0-1 · 作品详情页 `/pattern/:slug`(对标 C3,最高优先)**
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 目标关键词 | `{作品名}拼豆图纸`、`{作品名}图纸`(图案级长尾,逐作品积累) |
|
||||
| 页面类型 | 静态内容页(SSR/预渲染优先,SPA 兜底)+ 模板数据页 |
|
||||
| 内容要素 | 图纸预览图、格数/色数/用豆量、MARD 色号清单、作者署名、一键打开编辑、相关作品推荐(内链) |
|
||||
| 数据来源 | Showcase/图纸库现有作品数据 + V1.2 素材社区上传(ROADMAP V1.2 项3 图纸页) |
|
||||
| 工作量 | 前端模板 + slug 生成 + JSON-LD(`ImageObject + ItemList`)约 **2–3 人日** |
|
||||
| 预期流量价值 | 单页流量小但无限叠加;对标竞品每作品独立 URL 的做法,**内容量 = 流量量**;同时是素材社区的地基 |
|
||||
|
||||
**P0-2 · 博客 `/blog` + 首批 8 篇图文(对标 C4,教程打底)**
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 目标关键词 | `拼豆教程`、`拼豆图纸怎么生成`、`拼豆熨烫温度`、`拼豆新手入门`、`拼豆配色技巧`(信息型) |
|
||||
| 页面类型 | 图文列表页 + 文章详情页(Markdown 渲染) |
|
||||
| 首批选题 | ① 拼豆新手入门指南 ② 照片转拼豆图纸全流程 ③ 熨烫温度与爆孔处理(复刻竞品实操知识) ④ 六大品牌色板怎么选 ⑤ MARD 色号体系科普 ⑥ 拼豆图纸怎么打印 ⑦ 亲子拼豆入门 ⑧ 拼豆裱框指南 |
|
||||
| 工作量 | 博客框架(列表+详情+分页)约 **2–3 人日**;每篇内容生产约 0.5–1 人日(AI 辅助+校对) |
|
||||
| 预期流量价值 | 信息词大盘流量 + 精选摘要;博客是**唯一可持续周更的内容入口**,长尾复利最高的单点投入 |
|
||||
|
||||
**P0-3 · 主题合集页 `/showcase/{theme}`(对标 C4,季节流量)**
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 目标关键词 | `圣诞拼豆图纸`、`新年拼豆图纸`、`宠物拼豆图纸`(季节+题材词) |
|
||||
| 页面类型 | 合集模板页(复用作品卡组件,聚合 N 个作品详情页) |
|
||||
| 首批 2 套 | 圣诞主题(Q4 窗口)、宠物主题(常青,对齐小红书主打内容) |
|
||||
| 工作量 | 模板复用 Showcase,每套约 **1 人日** |
|
||||
| 预期流量价值 | 节日前后集中爆发;合集页同时是**内链枢纽**(聚合详情页权重) |
|
||||
|
||||
**P1-4 · 帮助细分页 `/help/:tool`(对标 C5,低成本)**
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 目标关键词 | `拼豆图纸生成器怎么用`、`拼豆色号表怎么看`、`AI 拼豆怎么用`(工具词) |
|
||||
| 页面类型 | 模板页,复用 HelpPage 组件分工具渲染 |
|
||||
| 首批 4 页 | `/help/generator`、`/help/color-chart`、`/help/chibi`、`/help/library` |
|
||||
| 工作量 | 模板 + 文案,约 **1 人日** |
|
||||
| 预期流量价值 | 精确工具意图 + 提升全站信任度;FAQ 已有内容可直接拆分复用 |
|
||||
|
||||
**P1-5 · 作者页 `/author/:name`(对标竞品 author 路由,素材社区前置)**
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 目标关键词 | `{作者名} 拼豆作品`(个人品牌词,量小) |
|
||||
| 页面类型 | 模板页,聚合该作者作品详情页 |
|
||||
| 依赖 | V1.2 素材社区作者标识(ROADMAP V1.2 项3 作者页);当前无账号体系,可先以「作品 ID 聚合」占位 |
|
||||
| 工作量 | 约 **0.5–1 人日** |
|
||||
| 预期流量价值 | 个人作者长尾 + 社区创作者激励(作者页是 UGC 投稿的回报) |
|
||||
|
||||
**P2-6 · 品牌主题页 `/perler-bead-art`(对标竞品品牌页)**
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 目标关键词 | `拼豆艺术`、`拼豆作品`(品牌/品类词) |
|
||||
| 页面类型 | 图文品牌页 |
|
||||
| 工作量 | 约 **1 人日** |
|
||||
| 预期流量价值 | 品类词占位;优先级低于上述全部,V2.0 或素材社区成型后再做 |
|
||||
|
||||
### 2.3 路线汇总表
|
||||
|
||||
| 优先级 | 内容页 | 路由 | 工作量 | 对标 | 目标流量词 |
|
||||
|---|---|---|---|---|---|
|
||||
| ✅ 已建 | 色号表 ×6 | `/color-chart/*` | — | C1 | `拼豆色号表`(高转化) |
|
||||
| ✅ 已建 | FAQ 帮助中心 | `/help` | — | C2 | `拼豆怎么熨`(信息) |
|
||||
| **P0-1** | 作品详情页 | `/pattern/:slug` | 2–3 人日 | C3 | `{作品}拼豆图纸`(长尾叠加) |
|
||||
| **P0-2** | 博客 | `/blog` + 8 篇 | 2–3 + 内容 | C4 | `拼豆教程`(信息大盘) |
|
||||
| **P0-3** | 主题合集页 | `/showcase/{theme}` | 1 人日/套 | C4 | `圣诞拼豆图纸`(季节) |
|
||||
| P1-4 | 帮助细分页 | `/help/:tool` | 1 人日 | C5 | `生成器怎么用`(工具) |
|
||||
| P1-5 | 作者页 | `/author/:name` | 0.5–1 人日 | 竞品 author | `{作者}拼豆作品`(个人词) |
|
||||
| P2-6 | 品牌主题页 | `/perler-bead-art` | 1 人日 | C4 | `拼豆艺术`(品类词) |
|
||||
|
||||
> 落地约束:①P0-1 作品详情页与 V1.2 素材社区(ROADMAP 项3)共享路由/数据结构,**先建模板后接社区数据**;②全部新增页沿用现有 i18n 机制(`useT()` + 消息表),数据层(作品/色号)语言无关;③每页挂 JSON-LD(对齐竞品 6 类 schema:`WebPage`/`ImageObject`/`ItemList`/`HowTo`/`BreadcrumbList`)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 内容生产节奏建议
|
||||
|
||||
### 3.1 周更(每周 2 篇,固定排期)
|
||||
|
||||
| 槽位 | 内容 | 生产方 | 建议日 |
|
||||
|---|---|---|---|
|
||||
| 周更 1 | 博客图文 1 篇(教程/技巧/品牌科普轮转) | 运营 + AI 辅助 | 周一 |
|
||||
| 周更 2 | Showcase/图纸库上新作品 3–5 个(来源:社区投稿 + 运营自制) | 运营 | 周四 |
|
||||
|
||||
- 博客选题池维持 ≥10 篇待写(选题池:新手教程 40% / 品牌科普 25% / 技巧清单 20% / 亲子场景 15%),避免灵感枯竭。
|
||||
- 每个上新作品自动生成作品详情页 URL,**「上传即建页」**,不额外占用内容排期。
|
||||
|
||||
### 3.2 月更(每月 1 套,规划性产出)
|
||||
|
||||
| 内容 | 频率 | 说明 |
|
||||
|---|---|---|
|
||||
| 主题合集页 1 套 | 月更 | 优先季节节点(提前 1–2 个月布局):9 月中秋 → 10 月万圣 → 12 月圣诞 → 1 月新年 → 2 月情人节 |
|
||||
| 色号表页复核 | 月更 | 对齐竞品「2026 修订版」做法:品牌色号若有新版,更新色号页并标注修订日期(修订也是内容更新信号) |
|
||||
| 帮助细分页迭代 | 月更 | 按客服高频问题(LAUNCH §4 FAQ)反哺新增条目 |
|
||||
|
||||
### 3.3 节奏原则
|
||||
|
||||
1. **量给长尾、质给转化**:高频更博客/作品(长尾积累),低频精修色号表/帮助(转化与信任)。
|
||||
2. **内容优先服务 SEO 关键词表**(LAUNCH §2.1):每篇博客先定目标关键词再写,标题含关键词、正文 800–1500 字、配 1 张成品图。
|
||||
3. **内链闭环**:博客 → 主题合集 → 作品详情 → 色号表 → 首页生成器,逐级导流;每篇新内容至少 2 个内链出口。
|
||||
4. **与运营渠道联动**:小红书图文 = 博客内容的短视频化素材(LAUNCH §1.4),同一批内容双平台复用,不重复生产。
|
||||
|
||||
---
|
||||
|
||||
## 4. 结论
|
||||
|
||||
| 维度 | 结论 |
|
||||
|---|---|
|
||||
| 竞品内容矩阵 | 5 类内容页:色号表 / FAQ 实操 / 作品详情 / 博客与主题合集 / 帮助细分 |
|
||||
| 我方已对齐 | 色号表 ×6 + FAQ 帮助中心(V1.1) |
|
||||
| V1.2 建议新增 | **6 条路线**:作品详情页(P0)→ 博客(P0)→ 主题合集(P0)→ 帮助细分(P1)→ 作者页(P1)→ 品牌主题页(P2) |
|
||||
| 总工作量 | 约 8–10 人日(前端 5–6 + 内容 3–4) |
|
||||
| 生产节奏 | 周更 2 篇 + 月更 1 套(合集/色号复核/帮助迭代) |
|
||||
| 内容量预期 | 3 个月后新增 40–50 个作品详情页 + 24 篇博客 + 3 套合集页,对标竞品「内容量 = 流量量」打法 |
|
||||
|
||||
> 本文件为内容矩阵决策依据。P0-1/P0-2/P0-3 建议转排期为 V1.2 工程任务;作品详情页与素材社区(ROADMAP V1.2 项3)需在排期时联调数据结构。
|
||||
|
||||
---
|
||||
|
||||
*报告完。证据可复核: `competitor-analysis/pixelbeads-analysis.md` §1.3/§7(站点结构/差距 20+ 项)、`pixelbeads-zh-detail.md` §1/§8(157 URL sitemap/Top10)、`docs/SEO-COLORCHARTS.md`(已建色号页)、`docs/LAUNCH.md` §2(关键词表)、`docs/ROADMAP.md` V1.1/V1.2、`perler-lab/src/App.tsx`(现有路由实测)。*
|
||||
Reference in new issue
Block a user