### 1. Demo 简介
**是什么**：一款非遗螺钿漆器镶嵌工艺的 **Web H5 交互体验游戏**，用现代手势交互复现"选材 → 切割 → 镶嵌 → 打磨"的核心工艺。
**面向谁**：对传统文化、非遗工艺感兴趣的年轻群体（Z 世代），以及潜在的亲子共学用户与文化传播合作方。
**主要功能**：
- **工坊四段式核心工艺**：选材（拖拽挑贝壳）→ 切割（滑刀手势）→ 镶嵌（吸附式拼图）→ 打磨（来回推磨显光泽），每段都带即时视觉反馈与完成动效。
- **器物自由选择**：黑漆茶杯 / 朱漆茶杯 / 黑漆首饰盒三种漆胎，对应不同镶嵌图案槽位（环形花瓣 / 四叶纹）。
- **成品光影展示**：四段工艺完成后呈现完整螺钿成品，配贝壳光泽流转动画与金色粒子庆祝，可一键重做。
-–
### 2. Demo 创作思路
**灵感来源**：看到有up主做螺钿漆盘，灯光下贝壳薄片折射出七彩光泽，极为震撼——但生漆螺钿很难做，难以流传。不是年轻人不爱非遗，而是缺少一个让他们"走进去"的入口。
**想解决的问题**：传统螺钿漆器是国家级非遗，却面临****传承人老龄化、年轻人认知度极低、技艺濒临失传****的困境；想了解这门手艺，普通人只能"隔着博物馆玻璃看"，体验被动且枯燥。
**为什么做这个方向**：
- **游戏/交互是打开非遗最好的钥匙**——比纪录片更轻、比展板更活，刚好契合年轻人碎片化娱乐习惯。
- **聚焦"镶嵌"环节**：四段工艺里镶嵌最具视觉冲击力（七彩贝壳 + 漆面对比），交互设计空间最大，最适合在 Demo 中用最少成本传递最大美感。
- **选 Web H5 而非 App/小程序**：扫码即玩、便于分享传播、开发周期短，验证玩法与文化传递效果的成本最低。
-–
### 3. Demo 体验地址
-–
### 4. TRAE 实践过程
整个 Demo 从立项到上线****全部在 TRAE 中完成****，覆盖"需求规划 → 素材设计 → 工程搭建 → 核心交互 → Bug 修复 → 部署上线"全流程。技术栈 Vue 3 + TypeScript + Vite + Tailwind CSS，纯前端实现，无后端依赖。
#### 4.1 关键开发步骤
**Step 1 · 需求拆解与规格定义**
向 TRAE 抛出"做一款螺钿漆器交互体验 Demo"的需求，TRAE 建议采用轻量级规格说明而非完整 SDD，并和我一起产出 `demo-spec.md`：明确 Demo 范围（聚焦镶嵌工艺 4 段）、技术选型（Web H5 + Vue3）、8 大类 100+ 项素材清单及 P0/P1/P2 优先级。
**Step 2 · 素材系统化生成**
基于规格文档，TRAE 按统一风格生成全部 SVG 素材：5 种贝壳原料 + 18 种贝壳切片（花瓣/叶片/几何）、刻刀/镊子/打磨石/刷子工具图标（含选中态）、工坊背景、漆胎底座、UI 按钮三态等。
过程中我对贝壳风格做了一轮调优——把第一版"通体鲜艳彩色渐变、形状规则、缺纹理"的设计，统一重做为"珍珠白底色 + 局部虹彩光斑 + 贝壳生长纹 + 自然不规则边缘"的写实风格，TRAE 一次会话内重写了 9 个旧风格 SVG 文件。
**Step 3 · 工程架构搭建**
TRAE 设计了清晰的目录结构：
- `composables/` — `useGame`（场景状态机 + 工艺进度）、`useAudio`、`useParticles`、`useDraggable` 四个组合式函数；
- `data/` — `catalog.ts`（器物 / 镶嵌图案槽位 / 切片池）、`assets.ts`（素材索引）；
- `components/scenes/` — Splash / Select / Workshop / Result 四个场景；
- `components/stages/` — Material / Cut / Inlay / Polish 四段工艺。
`ringSlots()` 用极坐标生成环形花瓣槽位，由 `generatePiecesForPattern()` 反向生成对应切片序列，保证切割产出的切片与镶嵌槽位严格一一对应。
**Step 4 · 核心交互实现**
四段工艺每段一个独立 Stage 组件，全部用手势（pointer 事件）驱动：
- **切割**（CutStage）：横向滑动位移超阈值触发一刀，刻刀跟随指针，火花粒子迸发，切片飞入下方切片库；
- **镶嵌**（InlayStage）：拖拽切片吸附至图案槽位，类型匹配校验，成功闪光；
- **打磨**（PolishStage）：来回滑动推进进度条，光泽逐步显现。
**Step 5 · Bug 修复**
Playwright 端到端测试发现一个隐患：切割数达上限后，多余的滑动事件仍会触发 `doCut`，导致 `finalizeCutPieces()` 和 `nextStage()` 被重复调用、连跳两级。TRAE 定位到 `CutStage.vue:61`，在 `doCut` 入口加了 `if (count.value >= total.value) return` 防护。修复后全流程跑通，控制台零错误。
**Step 6 · 部署上线**
通过 EdgeOne Pages 部署。期间遇到构建失败：pnpm 10/11 不再读取 `package.json` 里的 `pnpm.onlyBuiltDependencies`，esbuild 的 postinstall 脚本被拦截。TRAE 协助创建 `pnpm-workspace.yaml`，同时写入 pnpm 10 的 `onlyBuiltDependencies`（列表）和 pnpm 11 的 `allowBuilds`（映射）两种格式，推送 commit `2dfb5f4` 后部署成功。
#### 4.2 关键任务对话 Session ID
以下为本次 Demo 开发中具有代表性的 TRAE 对话 Session（按时间顺序）：
| Session ID | 对话主题 | 产出 |
|—|—|—|
| `6a32b8ac365c623b12a2c333` | 想法梳理 | 报名帖和html |
| `6a53182fff69e39a8814dfae` | 需求拆解 + 素材系统化设计 | `demo-spec.md`、8 大类素材清单、23 个贝壳 SVG 风格统一重写 |
| `6a53ad5863921cf32d5e158b` | Demo 完整开发 + Bug 修复 + 部署 | Vue3 工程搭建、四段工艺交互实现、`CutStage.vue:61` 防护修复、Playwright 验证通过 |
-–
### 5. 经验总结与开发心得
- **AI 协作的关键是"先定规格，再写代码"**：用 `demo-spec.md` 把 Demo 范围、技术选型、素材清单、优先级全部固化后，后续每一步生成都更稳，避免了"AI 凭感觉发挥"的失控。
- **素材风格统一比数量更重要**：第一版贝壳素材"通体鲜艳"其实并不丑，但放进工坊背景里显得突兀；统一成"珍珠白 + 局部虹彩"后整体气质立刻拉满。一次性让 TRAE 重写 9 个 SVG，效率远高于人工。
- **AI 生成的代码要靠测试兜底**：`CutStage.vue` 的连跳 Bug 静态看完全没问题，是 Playwright 实测才暴露的——多余的滑动事件触发重复 `nextStage`。AI 写逻辑容易忽略边界防护，端到端测试不可省。
- **pnpm 版本兼容是部署隐形坑**：本地 pnpm 9 跑得好好的，EdgeOne 用 pnpm 11 直接构建失败。`onlyBuiltDependencies` vs `allowBuilds` 的字段差异是 pnpm 10/11 升级时的典型破坏性变更，提前在 `pnpm-workspace.yaml` 写双格式可一劳永逸。
- **非遗 + 交互是最划算的"文化入口"**：四段工艺用最朴素的手势（拖、滑、点）就讲清了一门濒危手艺的核心，验证了"游戏/交互是非遗破圈最佳载体"的判断。
报名链接： 生活娱乐赛道 — 螺钿生辉：非遗生漆螺钿手游