@zzalai/leafer-point-annotation 1.1.0 → 1.1.2

package/project-docs/ARCHITECTURE.md

@@ -1,5 +1,9 @@
 # 点标注与笔刷涂抹工具 - 功能架构文档
 
+> **版本**: v1.1.x  |  **用途**: 新开 AI 会话时快速理解项目结构与代码组织
+
+---
+
 ## 1. 架构概述
 
 ### 1.1 架构设计原则
@@ -9,436 +13,423 @@
 | **单一职责** | 每个组件/模块只负责一个功能 |
 | **分层架构** | 清晰的层次划分：UI层、业务层、数据层 |
 | **可扩展性** | 预留扩展接口，支持后续功能迭代 |
-| **响应式设计** | 使用 Vue3 Composition API |
-| **性能优先** | 优化 Canvas 渲染和事件处理 |
+| **响应式设计** | Vue3 Composition API + `<script setup>` |
+| **性能优先** | Canvas 原生绘制 + LeaferJS 渲染管线，避免频繁 DOM 操作 |
+| **类型安全** | 全量 TypeScript，核心接口（PointStyle、BrushStyle、OptionsSource）严格定义 |
 
 ### 1.2 整体架构图
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                        UI 层                               │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐ │
-│  │  BrushSize   │  │BrushStyle    │  │ PointAnnotation  │ │
-│  │ Slider.vue   │  │  Panel.vue   │  │ (主画布组件)     │ │
-│  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘ │
-│         │                 │                    │          │
-└─────────┼─────────────────┼────────────────────┼──────────┘
-          │                 │                    │
-          ▼                 ▼                    ▼
+│                        UI 层 (Vue 组件)                      │
+│  ┌──────────────┐  ┌────────────────┐  ┌─────────────────┐ │
+│  │ BrushSize    │  │ BrushStyle     │  │ PointAnnotation │ │
+│  │ Slider.vue   │  │ Panel.vue      │  │ (主画布组件)    │ │
+│  └──────┬───────┘  └───────┬────────┘  └────────┬────────┘ │
+│         │                  │                    │          │
+└─────────┼──────────────────┼────────────────────┼──────────┘
+          │                  │                    │
+          ▼                  ▼                    ▼
 ┌─────────────────────────────────────────────────────────────┐
-│                      业务逻辑层                             │
-│  ┌──────────────────────────────────────────────────────┐  │
-│  │           PointAnnotation.vue (主组件)              │  │
-│  │  ┌──────────────┐  ┌──────────────┐  ┌───────────┐  │  │
-│  │  │ 工具切换逻辑 │  │ 事件处理逻辑 │  │ 命令管理  │  │  │
-│  │  └──────────────┘  └──────────────┘  └───────────┘  │  │
-│  └──────────────────────────────────────────────────────┘  │
-└───────────────────────────┬────────────────────────────────┘
+│                    业务逻辑层 (PointAnnotation.vue)         │
+│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌─────────┐  │
+│  │ 工具切换   │ │ 事件处理   │ │ 命令管理   │ │ 数据管理│  │
+│  └────────────┘ └────────────┘ └────────────┘ └─────────┘  │
+└───────────────────────────┬─────────────────────────────────┘
                             │
-          ┌─────────────────┼─────────────────┐
-          ▼                 ▼                 ▼
-┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
-│   元素封装层    │ │   工具类层      │ │   类型定义层    │
-│ PointAnnotation │ │CanvasBrush.ts   │ │   types/index   │
-│ Element.ts      │ │PointCommands.ts │ │   .ts           │
-│                 │ │BrushCommands.ts │ │                 │
-│                 │ │COCOExporter.ts  │ │                 │
-│                 │ │YOLOExporter.ts  │ │                 │
-└─────────────────┘ └─────────────────┘ └─────────────────┘
+          ┌─────────────────┼──────────────────┐
+          ▼                 ▼                  ▼
+┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐
+│   元素封装层    │ │   工具类层       │ │   类型定义层     │
+│ PointAnnotation │ │ CanvasBrush.ts   │ │  types/index.ts  │
+│ Element.ts      │ │ BrushCommands.ts │ │                  │
+│                 │ │ PointCommands.ts │ │                  │
+│                 │ │ BrushStroke.ts   │ │                  │
+│                 │ │ COCOExporter.ts  │ │                  │
+│                 │ │ YOLOExporter.ts  │ │                  │
+└─────────────────┘ └─────────────────┘ └──────────────────┘
 ```
 
 ---
 
-## 2. 模块划分
+## 2. 模块划分（按文件）
 
-### 2.1 UI 层
+### 2.1 根目录入口
 
-| 模块 | 文件路径 | 职责 |
-|------|----------|------|
-| BrushSizeSlider | src/components/BrushSizeSlider.vue | 笔刷大小调节浮动组件 |
-| BrushStylePanel | src/components/BrushStylePanel.vue | 笔刷样式配置面板（颜色、透明度、大小等） |
-| Canvas | 集成在 PointAnnotation.vue 中 | LeaferJS 画布渲染、事件监听 |
-| App.vue (测试入口) | src/App.vue | 提供完整的测试界面和示例 |
+| 文件 | 职责 |
+|------|------|
+| `src/index.ts` | 对外导出 PointAnnotation 组件（named + default export） |
+| `src/main.ts` | dev 模式下的入口，挂载 App.vue 到 `#app` |
+| `src/App.vue` | **开发调试演示页**，集成了所有功能的测试按钮（点标注、笔刷、图层、导出、Mask、enableBrush 等） |
 
-### 2.2 业务逻辑层
+### 2.2 UI 层 - 组件
 
-| 模块 | 文件路径 | 职责 |
-|------|----------|------|
-| 工具切换 | PointAnnotation.vue | 管理 currentTool 状态、Editor 动态配置 |
-| 事件处理 | PointAnnotation.vue | 处理鼠标/键盘事件、触发相应操作 |
-| 命令管理 | PointAnnotation.vue | 集成 CommandManager、管理撤销/重做 |
-| 数据管理 | PointAnnotation.vue | 管理点标注和笔刷数据的增删改查 |
-| 导出导入 | PointAnnotation.vue | 处理数据导出和导入逻辑 |
-| 标签编辑 | PointAnnotation.vue | 管理标签编辑状态，根据工具控制可编辑性 |
+| 组件 | 文件 | 职责 |
+|------|------|------|
+| PointAnnotation | `src/components/PointAnnotation.vue` | **核心主组件**，近 1900 行，整合所有标注与笔刷能力 |
+| BrushSizeSlider | `src/components/BrushSizeSlider.vue` | 笔刷大小浮动滑块（由 BrushStylePanel 调用） |
+| BrushStylePanel | `src/components/BrushStylePanel.vue` | 笔刷样式配置面板（颜色、透明度、大小 slider、连续性） |
 
-### 2.3 元素封装层
+### 2.3 元素封装层 - LeaferJS 自定义元素
 
-| 模块 | 文件路径 | 职责 |
-|------|----------|------|
-| PointAnnotationElement | src/elements/PointAnnotationElement.ts | 封装点标注元素（Group + Ellipse + Text），支持 hover/selected 状态 |
+| 文件 | 职责 |
+|------|------|
+| `src/elements/PointAnnotationElement.ts` | 自定义点标注元素（继承 `Group`，含 `Ellipse` + `Text`），内置 hover/press/selected 状态切换、`sequenceNumber` 自动重排、`updateLabel()` 方法 |
 
-### 2.4 工具类层
+### 2.4 工具类层 - utils
 
-| 模块 | 文件路径 | 职责 |
-|------|----------|------|
-| CanvasBrush | src/utils/CanvasBrush.ts | 使用 LeaferJS Canvas 实现笔刷绘制，支持 draw/erase/clear/hasContent |
-| PointCommands | src/utils/PointCommands.ts | 点标注的 Add/Remove 命令实现 |
-| BrushCommands | src/utils/BrushCommands.ts | 笔刷的快照命令实现（BrushSnapshotCommand） |
-| COCOExporter | src/utils/COCOExporter.ts | COCO 格式数据导出 |
-| YOLOExporter | src/utils/YOLOExporter.ts | YOLO 格式数据导出 |
+| 文件 | 职责 |
+|------|------|
+| `src/utils/CanvasBrush.ts` | 笔刷底层：每个图层一个实例，含 canvas/ctx、stroke/clear/fillPolygon/getImageData/hasContent/getGroup 等 |
+| `src/utils/BrushCommands.ts` | 笔刷相关命令（撤销/重做用）：`BrushSnapshotCommand` 基于 ImageData 快照 |
+| `src/utils/PointCommands.ts` | 点标注相关命令：`AddPointCommand`、`RemovePointCommand` |
+| `src/utils/BrushStroke.ts` | 笔刷笔画数据结构与辅助函数（已由 CanvasBrush 接管核心绘制，主要供数据导出用） |
+| `src/utils/COCOExporter.ts` | 导出 COCO JSON 格式（点标注为 keypoints） |
+| `src/utils/YOLOExporter.ts` | 导出 YOLO 标注格式 |
 
 ### 2.5 类型定义层
 
-| 模块 | 文件路径 | 职责 |
-|------|----------|------|
-| Types | src/types/index.ts | 定义所有 TypeScript 类型接口（PointAnnotation、BrushStyle、ExportOptions 等） |
+| 文件 | 职责 |
+|------|------|
+| `src/types/index.ts` | **所有对外接口集中地**：`PointAnnotation`、`PointStyle`、`BrushLayerConfig`、`BrushStyle`、`BrushStrokeData`、`ToolType`、`ExportFormat`、`ExportOptions`、`Statistics`、`ExportData`，以及 `DEFAULT_POINT_STYLE` / `DEFAULT_BRUSH_STYLE` |
 
 ---
 
-## 3. 核心组件设计
-
-### 3.1 PointAnnotation.vue（主组件）
-
-**核心职责**：
-- 初始化 LeaferJS 应用和图片加载
-- 管理工具状态和切换逻辑
-- 处理用户交互事件
-- 管理撤销/重做队列
-- 提供对外 API
-- 处理数据导出/导入
+## 3. PointAnnotation 主组件内部结构（重点）
 
-**状态管理**：
-```typescript
-// 工具状态
-const currentTool = ref<ToolType>('select');
+> 位置：`src/components/PointAnnotation.vue` （~1900 行，script setup + 模板 + style 三段式）
 
-// 数据状态
-const pointAnnotations = ref<PointAnnotation[]>([]);
-const pointCounter = ref(1);
+### 3.1 Props 与 Events
 
-// 画布状态
-const loadStatus = ref('idle');
-const imageWidth = ref<number | null>(null);
-const imageHeight = ref<number | null>(null);
+```ts
+// Props（defineProps 写法）
+{
+  imageSource?: { url: string, id?: string }   // 图片来源；不传则显示上传区域（支持点击+拖拽）
+  options?: OptionsSource                       // 所有可配置项（见下方）
+  currentLayer?: string                         // 受控模式：父组件驱动当前图层
+}
 
-// 本地图片上传状态
-const hasLocalImage = ref(false);
-const localImageUrl = ref('');
-const isDragOver = ref(false);
-
-// UI 状态
-const showBrushPanel = ref(false);
-const brushButtonRect = ref({ x: 0, y: 0, width: 0, height: 0 });
-const showTools = computed(() => loadStatus.value === 'success');
-
-// 笔刷样式
-const localBrushStyle = ref<BrushStyle>({ ...DEFAULT_BRUSH_STYLE });
+// Events（defineEmits）
+pointChange | loadStart | loadSuccess | loadError
+undoStateChange | redoStateChange
+update:currentLayer | layerChange
 ```
 
-**事件处理**：
-| 事件 | 处理方法 | 触发操作 |
-|------|----------|----------|
-| pointerdown | handlePointerDown | 创建点标注/开始笔刷绘制 |
-| pointermove | handlePointerMove | 笔刷绘制/鼠标追踪 |
-| pointerup | handlePointerUp | 完成笔刷绘制 |
-| keydown | handleKeyDown | 热键处理（tinykeys） |
-| dragover | handleDragOver | 拖拽文件时高亮边框 |
-| dragleave | handleDragLeave | 拖拽离开时取消高亮 |
-| drop | handleDrop | 拖拽文件时处理上传 |
-
-**对外 API**：
-```typescript
-defineExpose({
-  getPointAnnotations,
-  getImageInfo,
-  exportCanvasJSON,
-  exportMaskImage,
-  exportCOCO,
-  exportYOLO,
-  importCanvasJSON,
-  loadImage,
-  clearBrush,
-  zoomIn,
-  zoomOut,
-  resetZoom,
-  undo,
-  redo,
-  getCurrentTool,
-  setTool,
-  createPointAnnotation,
-  removePointAnnotation,
-});
+### 3.2 OptionsSource - 完整配置项
+
+```ts
+interface OptionsSource {
+  // 点标注样式
+  pointStyle?: Partial<PointStyle>
+
+  // 笔刷样式
+  brushStyle?: Partial<BrushStyle>
+
+  // 多图层笔刷（不传则单图层）
+  brushLayers?: BrushLayerConfig[]
+  maxBrushLayers?: number
+
+  // 限制
+  maxPoints?: number
+  maxUndoSteps?: number         // 默认 100（硬编码在 init 中）
+
+  // Mask 导出默认
+  maskExportFormat?: 'png' | 'jpeg' | 'jpg'
+  maskExportForeground?: 'black' | 'white'
+
+  // UI 开关
+  showToolbar?: boolean         // 默认 true
+  showZoomController?: boolean  // 默认 true
+  canvasBackground?: string     // 画布背景色（默认 #f6f6f6）
+  zoomMin?: number              // 最小缩放比例
+  zoomMax?: number              // 最大缩放比例
+
+  // 功能开关（核心新增）
+  enableBrush?: boolean         // 默认 true；设为 false 时：
+                                //   - 笔刷/橡皮擦按钮与配置面板隐藏
+                                //   - brushTool/eraserTool 方法不生效
+                                //   - 快捷键 b/e 不生效
+                                //   - initBrushLayers 跳过 canvas 创建
+                                //   - mask 导出相关方法返回 null/{}
+                                //   - 删除确认文案不包含"笔刷"
+}
 ```
 
-### 3.2 PointAnnotationElement（点标注元素）
+### 3.3 LeaferJS 画布结构
 
-**结构设计**：
 ```
-Group (容器) - id: 点数据的 id, _element_tag: 'point-annotation'
-├── Ellipse (圆点) - 负责视觉样式、hover/selected 效果
-└── Text (标签) - 负责显示标签文本、支持编辑，带 boxStyle 背景
+App (leafer-ui)
+└── contentLayer (Group, name: "contentLayer")
+    ├── imageBox (Image)            // 背景图（由 loadImage 加载）
+    ├── pointLayer (Group)          // 所有 PointAnnotationElement 挂在此处
+    └── [canvas-brush-group-*]      // 每个笔刷图层一个 group（含 html canvas）
 ```
 
-**核心方法**：
-| 方法 | 功能 |
+### 3.4 关键 computed 状态（文档必知）
+
+| 变量 | 含义 |
 |------|------|
-| constructor | 初始化元素、绑定事件、配置 hoverStyle |
-| handlePointAnnotationSelected | 更新选中状态样式（fill/stroke/scale） |
-| handleLabelChange | 处理标签编辑变更（非空校验） |
-| updatePosition | 更新位置坐标 |
-| updateLabel | 更新标签文本 |
-| getLabel / getLastValidLabel | 获取标签值 |
-
-### 3.3 CanvasBrush（笔刷绘制）
-
-**核心职责**：
-- 使用 LeaferJS Canvas 实现笔刷绘制
-- 外层 Group 控制整体透明度（避免多次叠加）
-- 支持绘制和擦除模式
-- 连续性阈值处理（两个点之间距离过远时自动连线）
-- 图片数据导出/恢复
-- hasContent() 检测是否有内容
-
-**核心方法**：
-| 方法 | 功能 |
+| `hasImage` | `loadStatus === 'success'`；控制工具栏/画布是否可见 |
+| `showToolbar` | `hasImage && options?.showToolbar !== false` |
+| `showZoomController` | `hasImage && options?.showZoomController !== false` |
+| `effectiveEnableBrush` | `options?.enableBrush !== false` |
+| `pointStyle` | `DEFAULT_POINT_STYLE + options.pointStyle` |
+| `brushStyle` | `DEFAULT_BRUSH_STYLE + options.brushStyle` |
+| `localBrushStyle` | 本地响应式拷贝（滑块改的值存在这） |
+| `effectiveBrushLayers` | 实际使用的图层配置；无配置时返回 `[{label:'默认图层', value:'default'}]` |
+| `effectiveCurrentLayer` | 当前激活图层 value |
+| `activeCanvasBrush` | 当前图层的 `CanvasBrush` 实例（供笔刷绘制、fillPolygon、clear 用） |
+
+### 3.5 关键数据结构
+
+| 变量 | 类型 | 含义 |
+|------|------|------|
+| `pointAnnotations` | `ref<PointAnnotation[]>` | 所有点标注数据（响应式） |
+| `pointCounter` | `ref<number>` | 下一个 order 数字 |
+| `canvasBrushesByLayer` | `Record<string, CanvasBrush>` | key = layer.value；value = CanvasBrush 实例 |
+| `commandManager` | `CommandManager`（来自 @zzalai/leafer-undo-redo） | 撤销/redo 命令栈 |
+
+### 3.6 defineExpose - 父组件可调用 API（完整列表）
+
+> **重要**: 如果想自定义工具栏（隐藏组件自带工具栏），调用这些方法即可。
+
+| 方法 | 说明 |
 |------|------|
-| constructor | 初始化 Canvas 和外层 Group |
-| draw | 绘制笔刷（使用多个圆填充路径） |
-| erase | 擦除操作（destination-out） |
-| clear | 清除所有内容 |
-| getImageData | 导出为 PNG dataURL |
-| restoreImageData | 从 dataURL 恢复画布 |
-| hasContent | 检测是否有非透明像素 |
-| setPointerEvents | 控制 Canvas 是否拦截事件 |
-
-### 3.4 笔刷命令设计
-
-**BrushSnapshotCommand**：
-- 笔刷操作使用快照方式实现撤销/重做
-- 保存操作前后的完整图片状态
-- undo/redo 时恢复对应状态
-
-### 3.5 导出导入实现
-
-**导出格式**：
-1. **JSON Full**：完整数据（点标注 + 笔刷 mask）
-2. **JSON Points**：仅点标注数据
-3. **COCO**：COCO 数据集格式
-4. **YOLO**：YOLO 数据集格式
-5. **Mask**：二值图（PNG/JPEG 可选）
-
-**二值图特性**：
-- 前景色可配置（黑/白）
-- PNG 支持透明背景
-- JPG 自动处理背景色（前景黑则背景白，反之亦然）
-- 使用 getImageData() 扫描像素，重新绘制为纯二值图
+| **点标注数据** | |
+| `getPointAnnotations()` | 返回当前所有标注点 |
+| `createPointAnnotation(x, y, label?)` | 程序化添加一个点 |
+| `removePointAnnotation(id)` | 程序化删除一个点 |
+| `updatePointAnnotationLabel(id, label)` | 修改某个点的 label 文案 |
+| **图片 & 画布** | |
+| `getImageInfo()` | 返回 `{ url, width, height }` |
+| `loadImage(url)` | 动态加载图片 |
+| **工具切换** | |
+| `getCurrentTool()` | 返回 `'select'/'point'/'brush'/'eraser'` |
+| `setTool(tool)` | 切到指定工具（受 enableBrush 限制） |
+| `selectTool()` / `pointTool()` | |
+| `brushTool(openPanel?)` / `eraserTool()` | |
+| **删除 / 清空** | |
+| `deleteSelected()` | 删除当前选中的标注点 |
+| `clearAllAnnotationsAndBrush()` | 清空所有点 + 笔刷（带确认） |
+| `clearBrush()` / `clearAllBrushLayers()` | 清空当前/所有图层的笔刷 |
+| **笔刷图层** | |
+| `getCurrentLayer()` / `setActiveLayer(value)` | |
+| `getAllLayers()` | 返回 `BrushLayerConfig[]` |
+| **笔刷样式** | |
+| `getBrushStyle()` | 返回当前 localBrushStyle 的拷贝 |
+| `updateBrushStyle(partial)` | 动态更新笔刷颜色/透明度/大小/连续性 |
+| **点轨迹生成笔刷** | |
+| `createBrushFromPoints()` | 按点标注顺序连成闭合多边形，fillPolygon 填充到当前笔刷层 |
+| **缩放** | |
+| `zoomIn()` / `zoomOut()` / `resetZoom()` | |
+| **撤销 / 重做** | |
+| `undo()` / `redo()` | |
+| **导出** | |
+| `exportCanvasJSON()` / `importCanvasJSON(data)` | 全量导入导出 |
+| `exportMaskImage(format?, fg?)` | 当前图层 mask（Data URL） |
+| `exportMaskImageByLayer(layerValue, format?, fg?)` | 指定图层 mask |
+| `exportAllMaskImages(format?, fg?)` | 所有图层 mask（Record<layerValue, dataURL>） |
+| `getMaskBlob(layerValue?, format?, fg?)` | 当前/指定图层 Blob（后端上传用） |
+| `getMaskFile(layerValue?, filename?, format?, fg?)` | 当前/指定图层 File |
+| `getAllMaskBlobs(format?, fg?)` | 所有图层 Blob 集合 |
+| `exportCOCO()` / `exportYOLO()` | 导出数据集格式 |
+
+### 3.7 快捷键（tinykeys）
+
+| 按键 | 功能 | 限制 |
+|------|------|------|
+| `v` | 选择工具 | 画布 focus 或 hover 才生效 |
+| `p` | 点标注工具 | 同上 |
+| `b` | 笔刷工具 | 需 `effectiveEnableBrush=true` |
+| `e` | 橡皮擦工具 | 需 `effectiveEnableBrush=true` |
+| `Ctrl+Z` | 撤销 | |
+| `Ctrl+Y` | 重做 | |
+| `Delete` | 删除选中 | |
+| `Ctrl++` / `Ctrl+-` / `Ctrl+0` | 缩放 +/− / 重置 | |
+| `Alt` | 显示快捷键提示浮层 | |
 
 ---
 
-## 4. 数据流转
+## 4. 核心功能实现要点
 
-### 4.1 点标注数据流转
+### 4.1 点标注 (PointAnnotationElement)
 
-```
-用户点击 → handlePointerDown → createPointAnnotation → 
-  PointAnnotationElement → AddPointCommand → CommandManager → 
-  pointAnnotations (响应式数组) → 导出数据
-```
+- **继承自 `Group`**，内部包含一个 `Ellipse`（圆点）和一个 `Text`（文字）
+- **hover / press / selected 三态**：通过监听 LeaferJS 原生事件（`pointer.over`、`pointer.out`、`pointer.down`、`pointer.up`）控制填充色与缩放
+- **sequenceNumber 自动重排**：删除点后调用 `renumberSequenceNumbers()`，保证显示序号 1,2,3... 连续；同时在 Text.text 变化时判断是否为"自动序号变值"以避免把重排当作用户手动修改保存
+- **label 编辑**：`updateLabel(label)` 修改文字；label 文本不允许为空字符串
+- **命令化**：点新增/删除都通过 `AddPointCommand`/`RemovePointCommand` 进撤销栈
 
-### 4.2 笔刷数据流转
+### 4.2 多图层笔刷 (CanvasBrush)
 
-```
-用户绘制 → handlePointerMove → CanvasBrush.draw → 
-  (操作结束) → BrushSnapshotCommand → CommandManager → 
-  (内部保存 mask 图片)
-```
+- **每个图层一个 HTML canvas + CanvasBrush 实例**，挂在独立 Group 下（通过 Group.opacity 控制整体透明度，避免叠加问题）
+- `brushLayers?: BrushLayerConfig[]` 不传时 → 单图层，value 为 `"default"`
+- `canvasBrushesByLayer[layerValue] = CanvasBrush` 便于快速定位当前图层画笔
+- **绘制方式**：`stroke(x, y, color)` + `eraserStroke(x, y, size)` + `fillPolygon(points, color)`
+- **快照式撤销**：`BrushSnapshotCommand` 在操作前后保存 `getImageData()`，redo/undo 时 `putImageData()`
 
-### 4.3 导出/导入数据流转
+### 4.3 enableBrush 功能开关
 
-```
-导出：用户触发 → exportData(format) → Exporter 格式化 → 返回数据字符串/Blob
-导入：用户触发 → importCanvasJSON(json) → 解析数据 → 重建元素 → fitImageToCanvas
-```
+- 入口：`effectiveEnableBrush = computed(() => props.options?.enableBrush !== false)`
+- **UI 层**：工具栏笔刷按钮 / eraser 按钮 / BrushStylePanel 全部加 `v-if`
+- **方法层**：brushTool/eraserTool/updateBrushStyle/clearBrush/clearAllBrushLayers/createBrushFromPoints 开头加守卫
+- **数据层**：`initBrushLayers` 跳过 canvas 创建；`setTool('brush'/'eraser')` 被拦截
+- **导出层**：exportMaskImage / exportMaskImageByLayer / exportAllMaskImages / getMaskBlob / getMaskFile / getAllMaskBlobs 返回 null 或 {}
+- **快捷键层**：`b`/`e` 按键 handler 开头加守卫
+- **确认文案**：deleteSelected 的确认提示不出现"笔刷"字样
 
----
+### 4.4 点轨迹生成笔刷区域 (createBrushFromPoints)
 
-## 5. 命令模式实现
+- 将所有点按 `sequenceNumber` 升序排序，取 pixel 坐标连成闭合多边形
+- 调用 `activeCanvasBrush.fillPolygon(points, color)` 填充到当前激活图层
+- 操作前后快照保存 → 支持撤销/重做
 
-### 5.1 命令类型
+### 4.5 Mask 导出（含 Blob/File）
 
-| 命令类 | 功能 | 撤销逻辑 |
-|--------|------|----------|
-| AddPointCommand | 添加点标注 | 移除点标注、从数组删除 |
-| RemovePointCommand | 删除点标注 | 重新添加点标注、插入原位置 |
-| BrushSnapshotCommand | 笔刷快照 | 恢复操作前的图片状态 |
+- **原理**：遍历对应 canvas，将有内容像素 → 前景色（黑/白），无内容 → 透明或背景色
+- **输出形式**：
+  - `data URL` (Base64 PNG/JPEG)
+  - `Blob`（后端上传 `multipart/form-data` 直接用）
+  - `File`（带 filename + mime，直接 formData.append）
+- **单图层 / 多图层都支持**：`getAllMaskBlobs()` 返回 Record<layerValue, Blob>
 
-### 5.2 命令管理器集成
+### 4.6 点标注 COCO / YOLO 导出
 
-```typescript
-// 初始化命令管理器（历史限制 100）
-const commandManager = new CommandManager(100);
+- COCO：把点标注写成 `annotations[].keypoints`（x,y,v 三值，v=2 表示可见）
+- YOLO：生成 yolo 格式标签文件（归一化坐标）
+- 详见 `src/utils/COCOExporter.ts`、`src/utils/YOLOExporter.ts`
 
-// 执行命令
-commandManager.executeCommand(new AddPointCommand(pointLayer, element, pointAnnotations.value, data));
+---
 
-// 撤销/重做
-commandManager.undo();
-commandManager.redo();
+## 5. 构建与发布
+
+### 5.1 package.json 关键脚本
+
+```json
+{
+  "name": "@zzalai/leafer-point-annotation",
+  "version": "1.1.2",
+  "main": "./dist/leafer-point-annotation.umd.js",
+  "module": "./dist/leafer-point-annotation.es.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",                         // 构建 dist（es/umd/css/dts）
+    "docs:build": "vite build --config vite.docs.config.ts",  // 构建演示站点到 docs/
+    "build:all": "npm run build && npm run docs:build",
+    "preview": "vite preview",
+    "type-check": "tsc --noEmit"
+  }
+}
 ```
 
----
+### 5.2 dist 目录结构
 
-## 6. Editor 动态控制
-
-### 6.1 控制策略
-
-| 工具 | Editor 状态 | 说明 |
-|------|-------------|------|
-| select | 启用 | 允许选择和拖拽 |
-| point | 启用 | 允许选择和拖拽点标注 |
-| brush | 禁用 | 避免干扰笔刷绘制 |
-| eraser | 禁用 | 避免干扰擦除操作 |
-
-### 6.2 标签编辑控制
-
-| 工具 | 标签可编辑 | 说明 |
-|------|-----------|------|
-| select | true | 可以编辑标签 |
-| point | true | 可以编辑标签 |
-| brush | false | 禁用编辑，避免冲突 |
-| eraser | false | 禁用编辑，避免冲突 |
-
-### 6.3 实现逻辑
-
-```typescript
-const switchToSelect = () => {
-  currentTool.value = 'select';
-  showBrushPanel.value = false;
-  if (!app) return;
-  app.editor.config.moveable = false;
-  app.editor.config.resizeable = false;
-  app.editor.config.multipleSelect = true;
-  canvasBrush?.setPointerEvents(false);
-  updateLabelEditable(true);
-};
+```
+dist/
+├── leafer-point-annotation.es.js   (ESM)
+├── leafer-point-annotation.umd.js  (UMD)
+├── leafer-point-annotation.css     (样式，必须手动导入)
+└── index.d.ts                      (TypeScript 类型)
 ```
 
----
+> 使用者在项目中必须 `import '@zzalai/leafer-point-annotation/dist/leafer-point-annotation.css'`。
 
-## 7. 对外 API 设计
-
-### 7.1 方法列表
-
-| 方法名 | 参数 | 返回值 | 功能描述 |
-|--------|------|--------|----------|
-| getPointAnnotations | 无 | PointAnnotation[] | 获取所有点标注数据 |
-| createPointAnnotation | (x, y) | string \| null | 创建标注点，返回 id |
-| removePointAnnotation | (id) | boolean | 删除指定 id 的点标注 |
-| clearBrush | 无 | void | 清除所有笔刷内容 |
-| exportCanvasJSON | 无 | string | 导出完整 JSON 数据 |
-| exportMaskImage | (format, fgColor) | string \| null | 导出二值图 dataURL |
-| exportCOCO | 无 | COCOExport | 导出 COCO 格式数据 |
-| exportYOLO | 无 | YOLOExport | 导出 YOLO 格式数据 |
-| importCanvasJSON | (json) | void | 导入 JSON 数据 |
-| loadImage | (url) | Promise | 加载图片 |
-| undo | 无 | void | 撤销操作 |
-| redo | 无 | void | 重做操作 |
-| setTool | (tool) | void | 设置当前工具 |
-| getCurrentTool | 无 | ToolType | 获取当前工具 |
-| zoomIn | 无 | void | 放大画布 |
-| zoomOut | 无 | void | 缩小画布 |
-| resetZoom | 无 | void | 重置缩放 |
-
-### 7.2 Props 配置
-
-| 属性名 | 类型 | 默认值 | 说明 |
-|--------|------|--------|------|
-| imageSource | { id?: string, url: string } \| null | null | 图片源配置（可选，未提供时显示本地上传界面） |
-| pointStyle | Partial\<PointStyle\> | DEFAULT_POINT_STYLE | 点标注样式 |
-| brushStyle | Partial\<BrushStyle\> | DEFAULT_BRUSH_STYLE | 笔刷样式 |
-| options | { maskExportFormat, maskExportForeground } | - | 导出配置 |
-
-### 7.3 图片切换逻辑
-
-**图片加载策略**：
-1. 优先使用本地上传的图片（hasLocalImage 为 true）
-2. 其次使用 props.imageSource.url
-3. 无图片时显示上传界面
-
-**Props 监听**：
-```typescript
-watch(
-  () => props.imageSource?.url,
-  (newUrl, oldUrl) => {
-    if (newUrl) {
-      // 有新图片 URL，加载新图片
-      hasLocalImage.value = false;
-      localImageUrl.value = '';
-      loadImage(newUrl);
-    } else if (oldUrl && !newUrl) {
-      // 图片 URL 变空，清空画布回到上传状态
-      hasLocalImage.value = false;
-      localImageUrl.value = '';
-      clearAllAnnotationsAndBrush();
-      if (imageBox) {
-        contentLayer.clear();
-        imageBox.destroy();
-        imageBox = null;
-      }
-      loadStatus.value = 'idle';
-    }
-  },
-  { immediate: true }
-);
+### 5.3 docs 目录（GitHub Pages 演示站）
+
+```
+docs/
+├── index.html
+└── assets/
+    ├── index-*.js
+    └── index-*.css
 ```
 
-### 7.4 Events
+GitHub Pages 配置：分支 `main` / 目录 `/docs`。
 
-| 事件名 | 参数 | 说明 |
-|--------|------|------|
-| pointChange | PointAnnotation[] | 点标注数据变化 |
-| loadStart | - | 图片开始加载 |
-| loadSuccess | - | 图片加载成功 |
-| loadError | - | 图片加载失败 |
+### 5.4 发布流程
+
+```bash
+pnpm install
+pnpm run build:all     # ← 同时生成 dist 和 docs
+# 确认 dist 有 .es.js / .umd.js / .css / index.d.ts
+# 确认 docs 有最新的演示站点
+npm publish            # 发布到 npm（需先登录 npm）
+```
 
 ---
 
-## 8. 性能优化策略
+## 6. 依赖清单（核心）
+
+| 包 | 版本要求 | 用途 |
+|----|----------|------|
+| `vue` | ^3.3.0 (peerDependency) | 宿主框架 |
+| `leafer-ui` | ^2.0.8 | Canvas 渲染引擎（App/Image/Group/Ellipse/Text） |
+| `@leafer-in/editor` | ^2.0.8 | 编辑器（选择、框选、点状态管理） |
+| `@leafer-in/viewport` | ^2.0.8 | 缩放/平移视口 |
+| `@leafer-in/resize` | ^2.0.8 | 元素 resize 手柄 |
+| `@leafer-in/state` | ^2.1.0 | hover/selected 状态 |
+| `@leafer-in/text-editor` | ^2.1.0 | label 文本编辑 |
+| `@leafer-in/view` | ^2.0.8 | view 盒子 |
+| `@leafer-in/box` | ^2.1.6 | box 布局 |
+| `@zzalai/leafer-undo-redo` | 1.0.3 | 撤销/重做 CommandManager |
+| `tinykeys` | ^3.0.0 | 键盘热键 |
+| `vue-pick-colors` | ^1.8.0 | 颜色选择器组件 |
 
-### 8.1 Canvas 渲染优化
+---
 
-| 策略 | 说明 |
-|------|------|
-| **Group 透明度控制** | 透明度设置在 Group 上，避免 Canvas 上多次叠加 |
-| **批量更新** | 使用 `set()` 批量更新属性，减少重绘次数 |
-| **图层分离** | 图片层、点标注层、笔刷层分离，独立控制 |
-| **路径填充** | 笔刷使用多个圆填充，避免复杂路径计算 |
+## 7. 常见开发问题速查
 
-### 8.2 事件处理优化
+### Q1. 本地图片上传后 props.imageSource.url 变更无效？
+- 组件内部 `hasLocalImage`/`localImageUrl` 标记本地上传后优先本地；若 props.url 变更是在本地上传之后，会监听 `watch(props.imageSource?.url)` 并在检测到新 url 时清空本地标记重新加载。
 
-| 策略 | 说明 |
-|------|------|
-| **事件委托** | LeaferJS 自动处理事件冒泡 |
-| **条件监听** | 笔刷 Canvas 只在需要时拦截事件（pointerEvents） |
-| **updateLabelEditable** | 只在工具切换时更新标签可编辑性 |
+### Q2. 点标注删除后序号不连续？
+- `removePointAnnotation` / `Delete` 操作后调用 `renumberSequenceNumbers()`，按数组顺序重写每个元素的 `sequenceNumber` 及显示文本。undo/redo 时 Text.text 变化通过「与当前 sequenceNumber 的比较」判定是否为自动重排，避免误存为用户自定义修改。
 
-### 8.3 内存管理
+### Q3. 我只需要点标注功能，不需要笔刷，如何配置？
+- `options={{ enableBrush: false }}`，所有笔刷 UI 与方法都会被屏蔽。
 
-| 策略 | 说明 |
-|------|------|
-| **及时清理** | 移除元素时调用 destroy() |
-| **历史限制** | 设置合理的撤销历史记录限制（默认 100） |
-| **Canvas 重用** | CanvasBrush 复用同一 Canvas 对象 |
+### Q4. 我要给后端上传 Mask，用 dataURL 还是 Blob？
+- 后端推荐 Blob/File：`getMaskBlob()` 或 `getMaskFile()` 直接用于 `formData.append('file', blob)`。
 
-### 8.4 导出优化
+### Q5. 父组件要自定义工具栏怎么搞？
+- `options={{ showToolbar: false, showZoomController: false }}`，然后父组件通过 `ref` 调用 expose 中的任意方法（selectTool/pointTool/brushTool/deleteSelected/clearAll/export*/...）。
 
-| 策略 | 说明 |
-|------|------|
-| **异步处理** | 图片导出使用 async/await，避免阻塞 |
-| **DataURL 缓存** | 笔刷快照保存 dataURL，避免重复序列化 |
+### Q6. 多图层如何切换？
+- 通过 `options.brushLayers: [{label, value, color?, opacity?, size?}]` 配置多个图层；父组件可通过 `v-model:currentLayer="'layerA'"` 或 `setActiveLayer('layerA')` 控制当前图层。
 
 ---
 
-**文档版本**：2.1  
-**创建日期**：2026-04-28  
-**最后更新**：2026-05-08
+## 8. 文件索引（快速定位）
+
+```
+src/
+├── components/
+│   ├── PointAnnotation.vue       ← 核心（1900 行）
+│   ├── BrushSizeSlider.vue       ← 大小 slider
+│   └── BrushStylePanel.vue       ← 样式配置面板
+├── elements/
+│   └── PointAnnotationElement.ts ← 点标注自定义元素
+├── utils/
+│   ├── CanvasBrush.ts            ← 笔刷底层（canvas/ctx、fillPolygon、快照）
+│   ├── BrushCommands.ts          ← BrushSnapshotCommand
+│   ├── PointCommands.ts          ← AddPointCommand/RemovePointCommand
+│   ├── BrushStroke.ts            ← 笔画数据结构
+│   ├── COCOExporter.ts           ← COCO 导出
+│   └── YOLOExporter.ts           ← YOLO 导出
+├── types/
+│   └── index.ts                  ← 所有对外类型 + DEFAULT 常量
+├── App.vue                       ← 开发演示页面（含所有功能的测试按钮）
+├── index.ts                      ← 对外导出入口
+└── main.ts                       ← dev 入口
+
+project-docs/                     ← 本文档所在目录（AI 会话上下文来源）
+├── ARCHITECTURE.md               ← 本文（架构与模块）
+├── REQUIREMENTS.md               ← 需求清单
+├── IMPLEMENTATION_PLAN.md        ← 实现方案记录
+├── TODO.md                       ← 待办与已完成
+└── leafer-development-guide/
+    ├── LEAFER_DEVELOPMENT_GUIDE.md
+    ├── LEAFER_UNDO_REDO_GUIDE.md
+    └── TINYKEYS_GUIDE.md
+```