first commit

docs/mask-config-guide.md

@@ -0,0 +1,121 @@
+# 智绘微刻小程序 - 遮罩尺寸配置指南
+
+## 📌 概述
+
+本小程序的 DIY 工作台使用**遮罩层（Mask）**来模拟实际产品的雕刻区域。用户在画布上看到的半透明黑色区域之外的部分，即为该产品的实际外形轮廓；白色/透明区域则是激光雕刻的可用范围。
+
+当你们确定了各品类的真实尺寸后，**只需修改一个配置文件**，所有页面的渲染就会自动更新。
+
+---
+
+## 🎯 修改位置
+
+**文件路径：**
+```
+src/utils/productConfig.ts
+```
+
+此文件导出一个 `PRODUCTS` 数组，每个品类对象中都有一个 `mask` 属性，就是遮罩的配置。
+
+---
+
+## 📐 尺寸单位说明
+
+| 项目 | 说明 |
+|---|---|
+| 单位 | `px`（像素） |
+| 基准 | 基于 **750px 宽度** 的设计稿 |
+| 换算建议 | 实际尺寸（mm）÷ 实物最大宽度（mm）× 画布宽度（px） |
+
+### 举例
+假设铜质杯垫实际直径为 **90mm**，画布区域在手机上显示为 **300px 宽**：
+```
+先量出杯垫实际直径对应的像素比例：
+90mm ÷ 90mm × 280 = 280px
+（如果直接按1:1在画布上展示，就填280）
+```
+
+**更简单的方式**：等真实的样品拿到后，直接用手机截图量一下在 375px 逻辑像素下应该占多大，然后把数值填进去即可。
+
+---
+
+## 🔧 遮罩类型
+
+### 1. 矩形遮罩（rect）
+适用于：笔记本、笔盒、书本灯等方形/圆角矩形产品
+
+```typescript
+mask: {
+  type: 'rect',
+  width: 300,    // 遮罩宽度（px）
+  height: 420,   // 遮罩高度（px）
+  radius: 8      // 圆角半径（px），不需要圆角填 0
+}
+```
+
+### 2. 圆形遮罩（circle）
+适用于：杯垫、徽章等圆形产品
+
+```typescript
+mask: {
+  type: 'circle',
+  width: 280,    // 椭圆外接矩形宽度（px）
+  height: 280    // 椭圆外接矩形高度（px）
+}
+```
+
+> 如果 `width === height`，即为正圆；如果不相等，则为椭圆。
+
+---
+
+## 📋 当前品类与待填尺寸
+
+| 品类ID | 品类名称 | 当前尺寸 | 状态 |
+|---|---|---|---|
+| `notebook-small` | 微雕笔记本（小） | 300 × 420 px | 占位待改 |
+| `notebook-large` | 微雕笔记本（大） | 340 × 480 px | 占位待改 |
+| `coaster` | 铜质杯垫 | 280 px 直径 | 占位待改 |
+| `penbox` | 竹制笔盒 | 320 × 160 px | 占位待改 |
+| `booklamp` | 书本型灯 | 320 × 240 px | 占位待改 |
+
+---
+
+## 💡 修改步骤
+
+1. 测量实际样品的雕刻区域尺寸（建议用卡尺精确到 mm）
+2. 在手机上打开小程序 DIY 页面，截图量出画布的实际显示像素
+3. 按比例换算：`(实际尺寸 mm / 画布对应的实际物理宽度 mm) × 画布像素宽度`
+4. 打开 `src/utils/productConfig.ts`
+5. 修改对应产品 `mask` 对象的 `width`、`height`、`radius` 数值
+6. 保存文件，重新编译小程序即可看到效果
+
+---
+
+## 🎨 效果说明
+
+遮罩在 UI 上的表现：
+- 遮罩区域：**透明/白色**，可看到用户上传的图片，表示这是雕刻范围
+- 遮罩外部：**半透明黑色蒙层**，提示用户图片在这个范围之外的部分不会被雕刻到产品上
+- 遮罩边框：**白色虚线框**，清晰标识边界
+
+用户上传图片后，可以通过**拖拽**调整图片在遮罩内的位置，通过**缩放按钮**调整图片大小，确保想要雕刻的内容落在白色遮罩区域内。
+
+---
+
+## ⚠️ 注意事项
+
+1. **修改后需重新编译**：Taro 会热更新，但在微信开发者工具中建议点击「编译」确保生效
+2. **尺寸不宜过大**：遮罩面积建议不超过画布面积的 80%，否则用户难以感受到「边缘」
+3. **留足边距**：设计时建议遮罩四周至少留出 20px 的安全边距，避免用户把图片贴得太边
+4. **圆形产品**：如果杯垫等产品有固定内圈雕刻区域（而非整个圆面），可以将 `width/height` 设小一点，模拟内圈
+
+---
+
+## 🔗 相关文件
+
+| 文件 | 作用 |
+|---|---|
+| `src/utils/productConfig.ts` | 品类与遮罩配置（修改这里） |
+| `src/types/index.ts` | 类型定义（一般不需要改） |
+| `src/pages/diy/index.tsx` | DIY 工作台页面（读取配置自动渲染） |
+| `src/pages/diy/index.scss` | 遮罩样式（一般不需要改） |