# 智绘微刻小程序 - 遮罩尺寸配置指南

## 📌 概述

本小程序的 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` | 遮罩样式（一般不需要改） |