printbench 0.1.0 → 0.1.2

package/README.md

@@ -1,56 +1,38 @@
 # PrintBench
 
-纯浏览器 3D 打印模型工作台（Vue 3 + three.js + Manifold）。在本地解析、体检、修复网格，再导出给切片软件。几何处理在浏览器内完成，审核报告默认不上传后端。
+纯浏览器 3D 打印模型工作台（Vue 3 + three.js + Manifold）。在浏览器内解析、体检、修复网格，再导出给切片软件。几何处理在本地完成，审核报告默认不上传。
 
-开发服务路径为 `/print-bench/`（根路径会重定向到该前缀）。
+可作为 **Vue 3 组件** 嵌入其它项目。需现代浏览器（WebGL、Web Worker、WASM）。
 
-## 环境
-
-- Node.js（建议 20+）
-- 现代浏览器（需 WebGL、Web Worker、WASM）
+## 安装
 
 ```bash
-npm install
-npm run dev        # 打开提示的地址，进入 /print-bench/
-npm run build      # 产出 SPA 静态资源（写入 dist/）
-npm run build:lib  # 产出可被宿主安装的库（写入 dist/，与 SPA 互斥覆盖）
-npm run preview    # 预览 SPA 构建结果
-npm test
+npm install printbench
 ```
 
-静态部署时，站点 `base` 为 `/print-bench/`，需按该子路径托管。
-
-## 作为 npm 库嵌入（独立 Vue 宿主）
+Peer 依赖（宿主需自行安装，大版本对齐）：
 
-本仓可打成 ESM 组件包，供其它 Vue 3 项目引用。
+- `vue` ^3.5
+- `pinia` ^3
 
-### 1. 构建产物
-
-```bash
-npm run build:lib
-```
+`three`、`manifold-3d` 等运行时依赖会随本包安装。请在宿主中注册 Pinia（`app.use(createPinia())`）。
 
-产出：`dist/printbench.js`（内含内联 Worker + WASM）、`dist/printbench.css`、`dist/printbench.d.ts`。
+### Vite 宿主
 
-Worker 与 `manifold.wasm` 都打进主包，宿主 Vite 不再请求 `/@fs/.../manifold.worker.js` 或 `/@fs/.../manifold.wasm`。
+开发时建议排除预打包：
 
-### 2. 宿主安装
-
-联调（同机独立仓库）：
-
-```json
-{
-  "dependencies": {
-    "printbench": "file:../PrintBench",
-    "vue": "^3.5.0",
-    "pinia": "^3.0.0"
-  }
-}
+```ts
+// vite.config.ts
+export default defineConfig({
+  optimizeDeps: {
+    exclude: ['printbench', 'manifold-3d'],
+  },
+})
 ```
 
-安装前请先在本仓执行 `npm run build:lib`。正式环境改为私有 npm 版本号即可。
+改配置后删除 `node_modules/.vite` 再重启 `dev`。
 
-### 3. 宿主使用
+## 使用
 
 ```ts
 import { createApp } from 'vue'
@@ -63,11 +45,23 @@ createApp(App).use(createPinia()).mount('#app')
 ```
 
 ```vue
+<script setup lang="ts">
+import { PrintBench } from 'printbench'
+import type { PrintBenchExportedPayload } from 'printbench'
+import 'printbench/style.css'
+
+function onExported(payload: PrintBenchExportedPayload) {
+  // payload.action: 'download' | 'upload'
+  // payload.blob / payload.fileName / payload.format / payload.unit
+}
+</script>
+
 <template>
   <PrintBench
     height="100vh"
     upload-url="https://api.example.com/api/printbench/exports"
     :model-url="modelUrl"
+    :custom-export="false"
     @ready="onReady"
     @error="onError"
     @exported="onExported"
@@ -76,149 +70,77 @@ createApp(App).use(createPinia()).mount('#app')
 </template>
 ```
 
-| props | 说明 |
-|-------|------|
-| `uploadUrl` | 导出上传地址；优先于构建时的 `VITE_UPLOAD_URL` |
-| `modelUrl` | 挂载后自动按 URL 导入模型 |
-| `height` | 根容器高度，默认 `100%` |
-
-| emits | 说明 |
-|-------|------|
-| `ready` | 几何内核就绪 |
-| `error` | 可展示错误信息 |
-| `exported` | `{ format, fileName, blob, unit, axis? }` |
-| `report` | 审核报告对象（下载 JSON/HTML 时触发） |
+### Props
 
-peer：`vue`、`pinia`。运行时依赖（`three`、`manifold-3d` 等）随本包装入 `dependencies`，由 npm 安装传递。
+| 属性 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `height` | `string` | `'100%'` | 根容器高度 |
+| `modelUrl` | `string` | — | 挂载后按 URL 自动导入模型（需 CORS） |
+| `uploadUrl` | `string` | — | 「一键上传」的 POST 地址；未设则无法上传 |
+| `customExport` | `boolean` | `false` | 为 `true` 时，下载 / 一键上传只生成文件并触发 `exported`（用 `action` 区分），不本地下载、不 POST |
 
-宿主 Vite 建议排除预打包（避免改写 `printbench.js` 的 `import.meta.url`）：
-
-```ts
-optimizeDeps: {
-  exclude: ['printbench', 'manifold-3d'],
-},
-```
+### Events
 
-Worker 与 WASM 已内联，npm 与 `file:` 都不应再请求独立的 `manifold.worker.js` / `manifold.wasm`。
+| 事件 | 负载 | 说明 |
+|------|------|------|
+| `ready` | — | 几何内核就绪 |
+| `error` | `string` | 可展示错误 |
+| `exported` | `{ action, format, fileName, blob, unit, axis? }` | 导出完成。`action` 为 `'download'`（下载）或 `'upload'`（一键上传） |
+| `report` | 审核报告对象 | 下载 JSON / HTML 审核报告时触发 |
 
-## 推荐流程
+`exported` 的 `format` 为 `'stl' | '3mf'`；多零件 STL 时 `fileName` 为 zip，`blob` 为打包后的文件。
 
-1. **导入模型** → 确认单位（看底栏包围盒）
-2. **看右侧诊断** → 点条目飞到缺陷；需要时 **一键修复**（红绿对拍后确认）
-3. **导出** STL / 3MF → 在切片软件（Cura、PrusaSlicer 等）里按毫米（或导出时所选单位）解释坐标
+「一键上传」以 `multipart/form-data` POST，字段为 `file` 与 `meta`（JSON：fileName、format、unit 等）。
 
-存在红色阻断项时无法导出，会定位到对应缺陷。黄色警告可选择继续，但可能影响打印质量。
+## 工作台能力
 
-## 导入
+推荐流程：导入模型并确认单位 → 看右侧诊断，必要时一键修复 → 导出 STL / 3MF 给切片软件（坐标按毫米或导出时所选单位解释）。
 
-支持 **GLB / GLTF / STL / OBJ / 3MF**，以及含上述模型的 **ZIP**，单文件约 **500MB** 上限。可：
+有红色阻断项时无法导出。黄色警告可继续，但可能影响打印质量。
 
-- 顶栏 **导入** → 从本地选择
-- 拖入画布，或粘贴文件
-- 填写 **http(s) 直链**（粘贴链接也会打开导入框）
+### 导入
 
-导入后先按毫米预览包围盒，再在对话框里选真实单位（mm / cm / m）。选错会差 10–1000 倍。3MF 会读取文件内的 model unit。动画、材质不进入打印网格。
+支持 **GLB / GLTF / STL / OBJ / 3MF**，以及含上述模型的 **ZIP**，单文件约 **500MB**。可从本地选择、拖入画布、粘贴文件，或填写 http(s) 直链（需 CORS；GitHub `blob` 会改成 raw）。
 
-**网络地址**：须目标服务器允许浏览器跨域（CORS）。GitHub 的 `blob` 链接会自动改成 `raw.githubusercontent.com`。无 CORS 时请下载到本地再导入。
+导入后按毫米预览包围盒，再选真实单位（mm / cm / m）。3MF 会读文件内 model unit。动画、材质不进入打印网格。
 
-## 界面
+### 界面
 
 | 区域 | 作用 |
 |------|------|
-| 顶栏 | 见下节「顶栏菜单」 |
-| 左栏 | 零件树与编辑工具；标题栏按钮可收起/展开（默认展开） |
-| 画布 | 轨道旋转缩放；双击或 **F** 按模型自适应；**复位视角** 回到默认相机；未导入时显示引导 |
-| 右栏 | 诊断与测量；标题栏按钮可收起/展开（默认展开） |
+| 顶栏 | 导入、撤销/重做、修复、导出、显示模式、测量、草稿、设置、帮助 |
+| 左栏 | 零件树与编辑（布尔、拆件、切底座等），可收起 |
+| 画布 | 轨道旋转缩放；双击或 **F** 自适应；**复位视角** 回默认相机 |
+| 右栏 | 诊断与测量，可收起 |
 | 底栏 | 包围盒、内部单位 mm、体积、文件名 |
 
-首次打开可走三步引导；**帮助** 里可重看。发现本地草稿时会询问是否恢复。未导入模型时，除导入、草稿、设置、帮助外，顶栏多数按钮不可用。
-
-## 顶栏菜单
-
-从左到右大致是：进文件 → 看模型 → 量尺寸 → 修复与导出；最右侧是草稿、设置、帮助。左栏的零件树、布尔、切底座等不在顶栏。
-
-**文件与历史**
-
-| 项 | 说明 |
-|----|------|
-| 导入 | 本地文件或 http(s) 地址；拖放、粘贴文件或链接也可 |
-| 撤销 / 重做 | 操作树历史（Ctrl+Z / Ctrl+Y） |
-| 一键修复 | 对当前模型修复，画布红/绿对拍，确认才保留 |
-| 导出 | 红级诊断会拦截；黄级可选择继续。对话框内可下载 STL/3MF，或一键上传 |
-| 审核报告 | 体积、包围盒、校验与测量；可下 JSON/HTML；无红级时可本地标「可打印」 |
-
-**观察（不改网格）**
-
-| 项 | 说明 |
-|----|------|
-| 复位视角 | 相机回到默认朝向与距离，不改零件姿态。画布 **双击** 或 **F** 是按模型自适应取景，与复位不同 |
-| 实体 / 线框 / 半透明 / 法线 | 仅改变显示，不改变几何 |
-| 壁厚热力图 | 按设置中的最小壁厚给顶点着色，便于看薄壁 |
-| 剖切 | 画布出现高度滑条，按 Y 切开看内部。与左栏 **切割 +Y**（真裁掉底座）不是同一功能 |
+### 导出
 
-**测量**
+- **STL**：二进制；无单位字段，切片软件需与导出单位一致（推荐毫米）。单零件 `.stl`，多零件 `.zip`（每件一个 STL）
+- **3MF**：自带毫米单位；每零件单独 object
 
-关 / 长度 / 角度 / 半径。在模型上点吸附点（顶点、边中点、面心）。选「长度」时出现 **目标 mm**，用来算偏差。结果列在右栏。**Esc** 退出测量。
-
-**右侧（随时可用）**
-
-| 项 | 说明 |
-|----|------|
-| 草稿 | 命名保存 / 打开 / 删除；Ctrl+S 另有自动草稿 |
-| 设置 | 默认导入单位、默认导出格式、网格/灯光/包围盒、最小壁厚 |
-| 帮助 | 教程与快捷键，可重看引导 |
-
-## 变换与零件
-
-- 工具 **1 / 2 / 3**：移动、旋转、缩放；画布上拖手柄
-- **打印拆件**：左栏放置切面，移动/旋转后确认。沿同一平面拆成两块（默认锯缝 0 mm）。可选球形/方形卡扣：正侧挖卯、负侧加榫，原位互补对插。须先是封闭实体；与「拆分碎片」不同
-- **轴向吸附（Shift）**：移动 1 mm、旋转 15°、缩放 0.1；勾选则常开
-- **数值变换**：位移（mm）、欧拉角（度，XYZ 序）、缩放；点「应用数值」写入当前零件
-- **Ctrl** 点选 / 框选；右键菜单：显隐、复制、删除、合并所选
-- 可添加立方体 / 圆柱 / 球 / 棱柱，再做并集、差集、交集（先预览，再确认精算）
-
-## 诊断与修复
-
-导入后自动体检（封闭、流形、薄壁等）。点诊断飞到开边、薄壁等位置。
-
-**一键修复**：红为修复前、绿为修复后，确认才保留。破洞过多可先 **拆分碎片** 或 **简化对拍**。
-
-**打印拆件**：左栏放置切面并确认，Manifold 按平面裁成两块（可设锯缝）。可选球形/方形卡扣（切口互补对插）。须水密。与顶栏剖切、切底座不是同一功能。
-
-**切底座 / 切割 +Y**：按给定高度用 +Y 平面裁掉下方，便于贴床。
-
-**简化对拍**：降低面数，红绿对比后确认或撤销。
-
-顶栏 **剖切** 只改显示，不改网格。**壁厚热力图** 按设置里的最小壁厚着色。
-
-## 测量
-
-见上文「顶栏菜单 · 测量」。结果列在右栏。
-
-## 导出与审核
-
-- **STL**：二进制；轴向与当前导入或编辑后的网格一致。单个零件为 `.stl`；多个零件打包为 `.zip`（每件一个 STL），再导入可保持零件个数。STL 无单位字段，切片软件需与导出单位一致（推荐毫米）
-- **3MF**：自带毫米单位；每个零件单独写成 object，导入时按对象拆开
-- **一键上传**：生成与下载相同的文件后，以 `multipart/form-data` POST 到服务端预留接口（字段 `file`、`meta` JSON）。配置环境变量 `VITE_UPLOAD_URL`（参见 `.env.example`）后生效；未配置时提示接口已预留。
-
-**审核报告**：体积、包围盒、校验与测量；可下载 JSON / HTML。无红级阻断时可本地标记为可打印。上传走同一预留接口。
-
-## 草稿与设置
-
-- **Ctrl+S**：自动草稿到浏览器本地
-- **草稿**：命名保存 / 打开 / 删除
-- **设置**：默认导入单位、默认导出格式、网格/灯光/包围盒、最小壁厚（mm）
-
-## 快捷键
+### 快捷键
 
 | 按键 | 作用 |
 |------|------|
 | Ctrl+Z / Ctrl+Y | 撤销 / 重做 |
-| Ctrl+S | 保存自动草稿 |
+| Ctrl+S | 保存自动草稿（IndexedDB） |
 | 1 / 2 / 3 | 移动 / 旋转 / 缩放 |
 | Esc | 取消手柄、预览、测量 |
-| F | 按模型自适应视角（与「复位视角」不同） |
+| F | 按模型自适应视角 |
 | Shift | 变换吸附 |
 | Ctrl | 多选、框选 |
 
-出错时可复制错误信息；模型仍可尝试继续导出。
+草稿保存在浏览器本地。设置含默认导入单位、默认导出格式、网格/灯光、最小壁厚。
+
+## 开发本仓库
+
+```bash
+npm install
+npm run dev        # 完整站，路径 /print-bench/
+npm run build      # SPA 静态资源（写入 dist/）
+npm run build:lib  # npm 库产物（写入 dist/，与 SPA 互斥覆盖）
+npm test
+```
+
+发布前请使用 `npm run build:lib`，不要用 SPA 的 `build` 覆盖 `dist/`。

package/dist/printbench.d.ts

@@ -1,6 +1,9 @@
 import type { DefineComponent } from 'vue'
 
+export type PrintBenchExportAction = 'download' | 'upload'
+
 export interface PrintBenchExportedPayload {
+  action: PrintBenchExportAction
   format: 'stl' | '3mf'
   fileName: string
   blob: Blob
@@ -20,9 +23,10 @@ export interface PrintBenchProps {
   uploadUrl?: string
   modelUrl?: string
   height?: string
+  customExport?: boolean
 }
 
 declare const PrintBench: DefineComponent<PrintBenchProps>
 export { PrintBench }
 export default PrintBench
-export type { ReviewReport }
+export type { PrintBenchExportAction, PrintBenchExportedPayload, ReviewReport }