BayTemplate/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

BayTemplate is a **Bay Template Designer of Grid Framework DesignTime** tool - a Qt-based application for designing electrical power grid structures. It features a dockable UI with a graphics canvas for placing and manipulating grid elements.

## Build Commands

### Build the Project

使用 CMake presets 进行配置和构建：

```bash
# Configure using preset
cmake --preset default

# Build with Ninja
ninja -C build/Debug
```

### Output Location

- Executable: `build/Debug/BayTemplate.app` (macOS)

## Architecture

### Core Components

#### 1. Docking System (Qt Advanced Docking System 4.3.1)
- **CDockManager** manages dockable panels
- **Left Dock**: 图元面板 (GraphicElementsPanel) - library of draggable grid elements
- **Center**: DrawingPanel - main canvas area with DesignerScene
- **Right Dock**: 属性编辑器 (PropertyEditor) - QDetailsView for editing selected item properties

#### 2. Graphics View Framework
- **DesignerView** (`QGraphicsView` subclass): Custom view with zoom (0.02-50x), pan (middle-button drag), checkerboard background
- **DesignerScene** (`QGraphicsScene` subclass): Custom scene with grid overlay (20px spacing), routes mouse events through SelectorManager

#### 3. Selector System
Selector hierarchy in `include/util/`:
- **BaseSelector**: Abstract base for all selectors
- **CreatingSelector**: Mode for creating new items from template
- **MovingSelector**: Mode for moving items
- **RotationSelector**: Mode for rotating items around origin
- **ScalingSelector**: Mode for scaling items
- **EditingSelector**: Mode for editing polygon vertex positions
- **SelectorManager**: Singleton that manages the active working selector

Mouse events flow: `DesignerScene` → `SelectorManager::getWorkingSelector()` → specific selector implementation

#### 4. Graphics Items (`include/graphicsItem/`)
- **GraphicsBaseItem**: Abstract base class for all grid elements
- **GraphicsRectItem**: Rectangle element
- **GraphicsPolygonItem**: Polygon element (editable vertices)
- **GraphicsItemGroup**: Container for grouped items (supports flattening to prevent nesting)
- **GraphicsBusSectionItem**: Bus section element
- **ItemControlHandle**: Visual handles for manipulation (rotation, scaling, editing)

#### 5. Property Editor (Qt PropertyEditor)
- **QDetailsView**: Qt Quick-based property editor in right dock
- **QCustomType**: Custom property type for graphics item properties
- **PropertyTypeCustomization_CustomType**: Custom property editor integration
- Property editor observes `QGraphicsScene` and displays properties of selected items

#### 6. Command Pattern (Undo/Redo)
- **QUndoStack** (`m_pUndoStack` in CMainWindow) manages undo/redo
- **OperationCommand**: Base command class
- **AddItemCommand**: Add item to scene
- **DeleteItemCommand**: Remove item from scene
- **CreateItemGoupCommand**: Group selected items (with flattening)
- **DestroyItemGoupCommand**: Ungroup items

### Signal Flow

1. **User drags from 图元面板** → `GraphicElementsPanel` emits signal → `DesignerScene::signalAddItem()` → creates item with `AddItemCommand`

2. **User clicks on canvas** → `DesignerView` → `DesignerScene` → `SelectorManager::getWorkingSelector()` → selector processes event

3. **User selects items** → `DesignerScene::selectionChanged()` → `CMainWindow::onSignal_selectionChanged()` → updates property editor

4. **User modifies property in 属性编辑器** → `QDetailsView` updates item property → scene updates

### Key Files and Relationships

```
source/main.cpp              # Entry point - creates CMainWindow
└── source/mainwindow.h/.cpp # Main window with CDockManager, initializes all components
    ├── initializeDockUi()   # Sets up docks (left, center, right)
    ├── initializeAction()   # Sets up QUndoStack and menu actions
    ├── initializeDocument() # Creates Document, associates with DesignerScene
    ├── Event handlers       # onSignal_addItem, onSignal_selectionChanged, etc.
    └── File operations      # onAction_new(), onAction_open(), onAction_save()

source/document.h/.cpp       # Document class - serialization and state management
    ├── serialize()/deserialize()    # Core JSON serialization
    ├── saveToFile()/loadFromFile()  # File I/O operations
    └── State management    # filename, modified, timestamps, meta data

source/drawingPanel.h/.cpp   # Central dock widget containing DesignerView
└── DesignerView + DesignerScene

source/designerView.h/.cpp   # QGraphicsView subclass - zoom, pan, middle-button navigation

source/designerScene.h/.cpp  # QGraphicsScene subclass - grid background, group operations
└── Delegates to SelectorManager for mouse events

source/util/selectorManager.h/.cpp  # Singleton managing active selector
└── Selector::mousePressEvent/ReleaseEvent/MoveEvent()

source/graphicsItem/         # Graphics item implementations
    ├── GraphicsBaseItem    # Base class with common functionality
    ├── GraphicsRectItem    # Rectangle
    ├── GraphicsPolygonItem # Editable polygon
    ├── GraphicsItemGroup   # Item grouping
    └── GraphicsBusSectionItem

source/propertyType/         # Custom property editor integration
    ├── CustomType.h
    ├── CustomGadget.h
    └── PropertyTypeCustomization_CustomType.cpp
```

### Third-Party Dependencies

1. **QtADS** (`QtADS/` subdirectory, v4.3.1): Advanced docking system - must be present as subdirectory
2. **PropertyEditor** (`PropertyEditor/` subdirectory): Qt Quick-based property editing system with QDetailsView

Both are added via `add_subdirectory()` in CMakeLists.txt and must exist in the repository root.

### Platform Support

- **Qt Version**: Qt5 or Qt6 (auto-detected, `find_package(QT NAMES Qt6 Qt5 ...)`)
- **Architectures**: x86, x64, arm64, aarch64 (auto-detected in CMakeLists.txt)
- **Platforms**: Windows, macOS, Linux, Android (Android uses shared library)

### Important Implementation Details

1. **CMAKE_AUTOUIC_SEARCH_PATHS**: Set to `"ui"` in CMakeLists.txt because .ui files are in separate directory from header files

2. **Group Flattening**: When creating a group that contains existing groups, the scene flattens nested groups first to prevent group nesting (see `DesignerScene::createGroup()`)

3. **Zoom Implementation**: Uses `QGraphicsView::zoom()` with smooth factor `qPow(1.0015, angleDelta.y())` per wheel event

4. **Wchar String Conversion**: Uses `QString::fromWCharArray(L"中文")` for Chinese UI strings

5. **Resource File**: `resource/BayTemplate.qrc` contains checkerboard background and icons, referenced in .ui files and CMakeLists.txt

---

## Graphics View Architecture Deep Dive

### MVC/MVVM Architecture Mapping

BayTemplate implements a classic **Model-View-Controller** pattern using Qt's Graphics View Framework:

| Layer | Qt Graphics View | BayTemplate Implementation | Responsibility |
|-------|------------------|---------------------------|----------------|
| **Model** | QGraphicsItem | GraphicsBaseItem, GraphicsRectItem, GraphicPolygonItem, GraphicsItemGroup | 数据模型：存储图元几何数据、样式属性（pen/brush）、变换信息（位置/旋转/缩放）|
| **Model Manager** | QGraphicsScene | DesignerScene | 模型管理：管理 item 生命周期、选择状态、碰撞检测、背景绘制（网格）|
| **View** | QGraphicsView | DesignerView | 视图呈现：坐标系变换、滚动条控制、鼠标事件捕获、缩放/平移 |
| **Controller** | (Qt 无内置) | SelectorManager + BaseSelector 体系 | 控制器：解释用户输入，转换为模型操作（创建/移动/旋转/缩放/编辑）|

**关键点：**
- Qt 的 Graphics View 框架提供了 MVC 中的 Model 和 View 层
- Controller 层需要开发者自行实现，BayTemplate 使用 SelectorManager 作为中枢
- DesignerScene 介于 Model Manager 和 Controller 之间，负责事件分发

### View-Scene-Item 三层架构详解

```
┌─────────────────────────────────────────────────────────────┐
│                     DesignerView                            │
│                   (Viewport / Presentation)                 │
├─────────────────────────────────────────────────────────────┤
│  • 坐标变换：Viewport Coordinates ↔ Scene Coordinates       │
│  • 缩放控制：0.02x - 50x (mouse wheel with smooth zoom)    │
│  • 平移控制：Middle-button drag (translate transform)       │
│  • 事件捕获：mousePressEvent/moveEvent/releaseEvent         │
│  • 无滚动条：setHorizontal/VerticalScrollBarPolicy(Off)     │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    DesignerScene                            │
│                  (Scene Graph Manager)                      │
├─────────────────────────────────────────────────────────────┤
│  • Item 管理：addItem(), removeItem(), selectedItems()      │
│  • 背景绘制：drawBackground() 绘制 20px 间距的藏青色虚线网格     │
│  • 事件分发：将鼠标事件转发给 SelectorManager               │
│  • 组操作：createGroup() 实现扁平化打组                     │
│  • 信号发射：signalAddItem(), selectionChanged()            │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                     GraphicsItem                           │
│                     (Data Model)                            │
├─────────────────────────────────────────────────────────────┤
│  GraphicsBaseItem (AbstractShapeType<QGraphicsItem>)        │
│    ├── GraphicsRectItem (rectangle, 圆角矩形)               │
│    ├── GraphicPolygonItem (多点绘制，顶点编辑)               │
│    ├── GraphicsBusSectionItem (总线段)                      │
│    └── GraphicsItemGroup (AbstractShapeType<QGroup>)        │
└─────────────────────────────────────────────────────────────┘
```

### 坐标系与变换系统

BayTemplate 使用多层坐标系，理解它们对添加 Document 类至关重要：

```
1. Viewport Coordinates (像素坐标)
   └── DesignerView 的 viewport 矩形，(0,0) 在左上角
   └── 受窗口大小、缩放影响

2. Scene Coordinates (场景坐标)
   └── 全局坐标系，(0,0) 为场景原点
   └── 通过 mapToScene()/mapFromScene() 与 Viewport 互转
   └── 图元的位置 pos() 使用场景坐标

3. Item Coordinates (图元局部坐标)
   └── 每个 item 的局部坐标系，原点在 (0,0)
   └── BayTemplate 中，图元中心点通常与 (0,0) 重合
   └── boundingRect() 返回局部坐标中的边界

4. Parent Coordinates (父项坐标)
   └── 当 item 加入 group 后，使用 group 的局部坐标
   └── mapToParent()/mapFromParent() 用于转换
```

**变换链（Transform Chain）：**
```
Item Coordinates → Item Transform → Parent Coordinates → ... → Scene Coordinates → View Transform → Viewport Coordinates
```

- **Item Transform**: 由 `setPos()`, `setRotation()`, `setScale()` 控制的 3×3 变换矩阵
- **Transform Origin**: `setTransformOriginPoint()` 设置变换中心（BayTemplate 中通常为中心点）
- **View Transform**: DesignerView 的 zoom/pan 产生的变换，影响所有 item 的显示

**关键函数：**
- `item->mapToScene(point)`: Item 局部坐标 → 场景坐标
- `item->mapToView(point)`: Item 局部坐标 → Viewport 坐标
- `view->mapToScene(point)`: Viewport 坐标 → 场景坐标
- `view->mapSceneToViewport(rect)`: 场景矩形 → Viewport 矩形

### 操作模式与状态机（Selector 系统）

SelectorManager 实现了一个**状态机**，不同的 Selector 代表不同的操作模式：

```
                      ┌─────────────────┐
                      │   ST_base       │
                      │  (空闲状态)     │
                      └────────┬────────┘
                               │
            ┌──────────────────┼──────────────────┐
            │                  │                  │
            ▼                  ▼                  ▼
    ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
    │ ST_creating  │  │ ST_moving    │  │ ST_editing   │
    │ (创建模式)   │  │ (移动模式)   │  │ (顶点编辑)   │
    └──────────────┘  └──────────────┘  └──────────────┘
            │                  │
            │                  │
            ▼                  ▼
    ┌──────────────┐  ┌──────────────┐
    │ ST_scaling   │  │ ST_rotation  │
    │ (缩放模式)   │  │ (旋转模式)   │
    └──────────────┘  └──────────────┘
            │                  │
            └────────┬─────────┘
                     │
                     ▼
                ┌────────┐
                │ ST_base│ (操作完成后返回)
                └────────┘
```

**状态转换规则：**

| 触发条件 | 从状态 | 到状态 | 说明 |
|---------|--------|--------|------|
| 从图元面板拖拽 | ST_base | ST_creating | 设置 CreatingSelector 的 m_pCreatingItem |
| 点击选中 item（左键） | ST_base | ST_moving/ST_scaling/ST_rotation | 根据是否点击在 handle 上判断 |
| 点击空白处 | 任何 | ST_base | 取消选择，禁用 RubberBandDrag |
| mouseReleaseEvent | ST_moving/scaling/rotation | ST_base | 操作完成，返回空闲状态 |

**BaseSelector 静态成员（所有 Selector 共享）：**
```cpp
static QPointF ms_ptMouseDown;           // 鼠标按下位置（场景坐标）
static QPointF ms_ptMouseLast;          // 鼠标当前位置（场景坐标）
static double ms_dAngleMouseDownToItem; // 按下时鼠标与 item 中心的夹角（弧度→角度）
static int ms_nDragHandle;              // 当前拖拽的 handle 类型
```

### Handle 控制系统

ItemControlHandle 是围绕在选中 item 周围的视觉控件，用于精细操作：

```
    H_leftTop ──── H_top ──── H_rightTop
         │            │            │
         │            │            │
    ┌────┴────────────┴────────────┴────┐
    │                                   │
    │         Item Bounding             │
    │           Rect                    │
    │                                   │
    └────┬────────────┬────────────┬────┘
         │            │            │
    H_left ────── H_bottom ──── H_rightBottom
```

**Handle 类型枚举：**
```cpp
enum HandleTag {
    H_none = 0,           // 无 handle
    H_leftTop,            // 左上角（缩放）
    H_top,                // 上边中点（缩放）
    H_rightTop,           // 右上角（缩放）
    H_right,              // 右边中点（缩放）
    H_rightBottom,        // 右下角（缩放）
    H_bottom,             // 下边中点（缩放）
    H_leftBottom,         // 左下角（缩放）
    H_left,               // 左边中点（缩放）
    H_rotate_leftTop,     // 左上角外侧（旋转）
    H_rotate_rightTop,    // 右上角外侧（旋转）
    H_rotate_rightBottom, // 右下角外侧（旋转）
    H_rotate_leftBottom,  // 左下角外侧（旋转）
    H_edit,               // 自定义编辑点（多边形顶点、圆角控制点）
    // ... 更多编辑点
};
```

**Handle 工作机制：**
1. `AbstractShapeType::updateHandles()` 根据 boundingRect 计算 handle 位置
2. Handle 位置在 boundingRect 外扩 5px (nMargin = 5)
3. `collidesWithHandle()` 检测鼠标点击在哪个 handle 上
4. 不同操作模式对 handle 的响应不同

### 操作副本（Operation Copy）模式

移动和旋转操作使用"预览副本"技术，提供视觉反馈：

```cpp
// 1. mousePressEvent: 创建副本
void createOperationCopy() {
    m_pOperationCopy = new QGraphicsPathItem(this->shape());
    m_pOperationCopy->setPen(Qt::DashLine);  // 虚线表示预览
    m_pOperationCopy->setPos(this->pos());
    scene->addItem(m_pOperationCopy);
    m_movingIniPos = this->pos();
}

// 2. mouseMoveEvent: 移动副本（本体不动）
void moveOperationCopy(const QPointF& delta) {
    m_pOperationCopy->setPos(m_movingIniPos + delta);
}

// 3. mouseReleaseEvent: 副本位置应用到本体
void removeOperationCopy() {
    this->setPos(m_pOperationCopy->pos());  // 本体移动到副本位置
    scene->removeItem(m_pOperationCopy);
    delete m_pOperationCopy;
}
```

**优势：**
- 移动过程中保持原来的 selection state
- 可以拖出 boundingRect_selected 范围（否则会被误认为取消选择）
- 旋转/缩放同理

### 图元基类架构（AbstractShapeType 模板）

```cpp
// 使用模板继承，允许继承 QGraphicsItem 或 QGraphicsItemGroup
template <typename BaseType = QGraphicsItem>
class AbstractShapeType : public BaseType {
protected:
    ShapeType m_type;                    // T_undefined/T_item/T_group
    QPen m_pen;                          // 画笔（边框）
    QBrush m_brush;                      // 画刷（填充）
    double m_dWidth, m_dHeight;         // 宽高
    QRectF m_boundingRect;              // 局部坐标中的边界矩形
    QRectF m_boundingRect_selected;     // 选中框（外扩 5px）
    double m_dSyncRotationByParent;     // 父项旋转同步数据
    QVector<ItemControlHandle*> m_vecHanle;
    QGraphicsPathItem* m_pOperationCopy;
    QPointF m_movingIniPos;
};

// 具体类型定义
typedef AbstractShapeType<QGraphicsItem> AbstractShape;      // 单图元基类
// GraphicsBaseItem : QObject, AbstractShape

// GraphicsItemGroup : QObject, AbstractShapeType<QGraphicsItemGroup> // 组图元基类
```

**关键点：**
- `m_boundingRect` 的中心点与 item 的 (0,0) 原点重合，简化变换计算
- `updateCoordinate()` 在 resize/editShape 后重新校准原点
- `m_dSyncRotationByParent` 用于组内 item 跟踪父组的旋转（因为 item 的 rotation() 不会自动更新）

### 命令模式（Command Pattern）

所有可撤销操作都通过 QUndoCommand 实现：

```cpp
class AddItemCommand : public QUndoCommand {
    void undo() override { scene->removeItem(m_pItem); }
    void redo() override { 
        if(!m_pItem->scene()) scene->addItem(m_pItem); 
    }
};

class DeleteItemCommand : public QUndoCommand {
    void undo() override { 
        foreach(item, m_listItem) scene->addItem(item); 
    }
    void redo() override { 
        foreach(item, m_listItem) scene->removeItem(item); 
    }
};
```

**关键点：**
- `QUndoStack::push(command)` 会自动调用 `command->redo()`
- `DeleteItemCommand` 使用 `removeItem()` 而非 `delete`，确保 undo 能恢复
- 命令对象持有 item 的引用（非所有权）

### 组（Group）扁平化策略

`DesignerScene::createGroup()` 实现组扁平化：

```cpp
// 如果选中的 item 中包含已有的 group，先解散该 group，将子项加入新组
foreach (item, selectedItems) {
    if (item->getType() == T_group) {
        GraphicsItemGroup* group = qgraphicsitem_cast<GraphicsItemGroup*>(item);
        foreach (child, group->childItems()) {
            listItem.push_back(child);  // 将子项加入新列表
        }
        removeItem(group);
        delete group;  // 删除旧组
    }
}
// 创建新组，避免嵌套
```

**目的：**
- 简化场景图结构（无嵌套的树）
- 简化坐标计算和碰撞检测
- 统一 undo/redo 逻辑

---

## Document 类架构（持久化层）

### Document 类在 MVC 中的位置

Document 类作为**持久化层**插入现有架构，位于 Model 层之下：

```
┌─────────────────────────────────────────┐
│              Controller                 │
│        (SelectorManager + 各种 Selector) │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│                   View                  │
│          (DesignerView + UI)            │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│               Model Manager             │
│           (DesignerScene)               │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│                  Model                  │
│     (GraphicsItem 层次结构)              │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│               Document                  │
│           (序列化/状态管理)              │
└──────────────────────────────────────────┘
```

**设计原则：**
- **组合优于继承**：Document 持有 `DesignerScene*` 弱引用，不继承 Scene
- **单向依赖**：Document 只依赖 DesignerScene 的接口，不依赖 CMainWindow
- **信号槽通信**：通过信号与外部通信修改状态，避免紧耦合

### Document 类职责

1. **序列化/反序列化**（JSON 格式）
   - `serialize()` / `deserialize()`: 核心序列化为 QByteArray
   - `saveToFile()` / `loadFromFile()`: 文件 I/O 封装
   - 递归序列化/反序列化图元层次结构（支持组图元嵌套）

2. **状态管理**
   - `m_filename`: 文档文件名（空表示未保存的新文档）
   - `m_modified`: 是否被修改（通过 `setModified()` 和 `modifiedChanged` 信号通知）
   - `m_created` / `m_modifiedTime` / `m_lastSavedTime`: 时间戳
   - `m_metaData`: 可扩展的自定义元数据 (`QMap<QString, QVariant>`)

3. **与 CMainWindow 的集成**
   - `initializeDocument()`: 创建 Document 并关联 DesignerScene
   - 连接 `modifiedChanged` 信号来更新窗口标题（添加 * 标记）
   - `closeEvent()` 中检查 `isModified()` 提示用户保存
   - 文件操作：New/Open/Save 通过 Document 完成

### 序列化格式（v1.0）

```json
{
    "version": "1.0",
    "created": "2024-01-01T12:00:00",
    "modified": "2024-01-01T14:30:00",
    "filename": "/path/to/file.bay",
    "metaData": {
        "customKey": "customValue"
    },
    "items": [
        {
            "type": "GraphicsRectItem",
            "id": "140737488320",
            "pos": {"x": 100.0, "y": 200.0},
            "rotation": 45.0,
            "scale": {"x": 1.0, "y": 1.0},
            "pen": {"color": "#000000", "width": 1.0, "style": 0},
            "brush": {"color": "#FF0000"},
            "width": 100.0,
            "height": 50.0,
            "properties": {},
            "children": []
        },
        {
            "type": "GraphicsItemGroup",
            "pos": {"x": 300.0, "y": 150.0},
            "rotation": 0.0,
            "scale": {"x": 1.0, "y": 1.0},
            "width": 200.0,
            "height": 100.0,
            "children": [
                { "type": "GraphicsRectItem", ... },
                { "type": "GraphicsBusSectionItem", ... }
            ]
        }
    ]
}
```

### 实现细节

**类型识别：** 使用 `qobject_cast<T*>(item)` 配合 `getTypeString()` 函数识别图元类型（要求类型有 `Q_OBJECT` 宏）

**QVariant ↔ QJsonValue 转换：** 提供 `toJsonValue()` / `fromJsonValue()` 辅助函数处理元数据序列化

**坐标系统：** 图元使用中心原点，`pos()` 存储场景坐标，`boundingRect()` 使用局部坐标

**文件扩展名：** `.bay` 作为 BayTemplate 专用格式

### 关键文件

- `include/document.h`: Document 类声明
- `source/document.cpp`: 序列化/反序列化实现
- `source/mainwindow.cpp`: `initializeDocument()`, `onAction_new()`, `onAction_open()`, `onAction_save()`

---

## Selector 系统设计模式总结

### 状态模式（State Pattern）

SelectorManager 实现状态模式，不同的 Selector 子类代表不同的状态：

```cpp
// Context
class SelectorManager {
    BaseSelector* getWorkingSelector();  // 返回当前状态的 Selector
    void setWorkingSelector(SelectorType);
};

// State 接口
class BaseSelector {
    virtual void mousePressEvent(...) = 0;
    virtual void mouseMoveEvent(...) = 0;
    virtual void mouseReleaseEvent(...) = 0;
};

// Concrete State
class MovingSelector : public BaseSelector { ... };
class ScalingSelector : public BaseSelector { ... };
// ...
```

**静态成员共享的原因：**
BaseSelector 的静态成员（ms_ptMouseDown 等）在所有 Selector 实例间共享，使得状态切换时无需传递上下文数据。

### 操作副本模式（Operation Preview Pattern）

移动、旋转、缩放都使用"操作副本"作为视觉预览：
1. mousePressEvent: 创建虚线副本
2. mouseMoveEvent: 移动副本（本体不动）
3. mouseReleaseEvent: 将副本的变换应用到本体，删除副本

### Handle 系统（Manipulator Pattern）

ItemControlHandle 实现操纵器模式，将抽象的变换操作（缩放、旋转）映射到可视化的交互控件。

---

## 坐标系转换速查表

| 转换 | 函数 | 说明 |
|------|------|------|
| Item → Scene | `item->mapToScene(point)` | 局部坐标转场景坐标 |
| Scene → Item | `item->mapFromScene(point)` | 场景坐标转局部坐标 |
| Item → Viewport | `item->mapToView(point)` | 局部坐标转屏幕像素 |
| Item → Parent | `item->mapToParent(point)` | 局部坐标转父项坐标 |
| Viewport → Scene | `view->mapToScene(point)` | 屏幕像素转场景坐标 |
| Scene Rect → Viewport Rect | `view->mapSceneToViewport(rect)` | 场景矩形转屏幕矩形 |

## Handle 类型速查表

| Handle 类型 | 位置 | 功能 |
|------------|------|------|
| H_leftTop ~ H_left | boundingRect 八方向 | 缩放 |
| H_rotate_leftTop ~ H_rotate_leftBottom | boundingRect 外扩 | 旋转 |
| H_edit + N | 自定义位置 | 形状编辑（多边形顶点、圆角控制点）|

## 操作模式速查表

| SelectorType | 触发方式 | 用途 |
|-------------|---------|------|
| ST_base | 默认 | 空闲状态，允许橡胶框选择 |
| ST_creating | 从图元面板拖拽 | 创建新图元 |
| ST_moving | 点击 item 主体 | 移动选中项 |
| ST_scaling | 点击缩放 handle | 缩放选中项 |
| ST_rotation | 点击旋转 handle | 旋转选中项 |
| ST_editing | 点击编辑 handle | 编辑多边形顶点等 |