# mepaint

**Repository Path**: majorincn/mepaint

## Basic Information

- **Project Name**: mepaint
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-07
- **Last Updated**: 2026-04-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MEPaint

MEPaint 是一个基于 Flutter 的机电改造绘图与材料统计原型，当前重点能力已经从“简单平面绘图”演进为：

- 俯视图设备 / 管线 / 元件编辑
- 端口级规格维护与锁定
- 锁驱动的一键规格传播
- 立管正视图编辑
- 二次配新增场景的材料清单预览
- 画布 Trace 导出与在线回传

本文档以当前仓库代码为准，明确区分“已经实现”“部分实现”“尚未落地”，避免旧文档继续误导开发和测试。

## 当前实现状态

### 已实现

- Flutter 多端工程骨架，主界面为项目列表与画布编辑页。
- 画布四种主模式：默认态 / 选取 / 设备 / 管线 / 元件。
- 设备拖拽创建、框选、删除、复制、长按移动。
- 管线正交绘制、磁吸连接、拖动抬手提交、双击结束 / 取消。
- 元件自动拓扑演化：根据端口数量和方向推断直接、弯头、三通、四通、多通等。
- 长按移动时的一跳联动与最小长度硬约束。
- 端口级材质 / 规格 / 连接方式 / 螺纹标准编辑与字段锁定。
- 从锁定管道端口出发的一键匹配（规格传播）。
- 立管自动补建与正视图编辑入口。
- 材料清单预览，支持损耗率重算。
- 画布 Trace 记录、导出、可选上传。
- 主界面和线上日志页显示版本号 / build 号，便于确认当前前端与日志服务是否已更新。
- Web 端提供 `?e2e=1` 下的 Playwright 真实测试桥接，可稳定验证多段管线、三视图和一键匹配。
- 非 Web 平台的规格目录 SQLite 本地持久化；Web 平台的 SQLite 导出。
- 完整的自动化测试集，覆盖核心交互和规则引擎。

### 部分实现

- `ProjectScenario` 已进入数据模型，但首页新建项目 UI 目前只创建标准项目。
- “保存”按钮当前会上传 / 刷新 Trace，并提示“项目已保存”，但没有把项目数据落盘到本地文件或数据库。
- 规格传播支持冲突检测与写入未锁字段，但不会自动插入异径管、转换接头，也不会拆分管线。
- 材料清单更偏向“预览 / 校核”而非正式导出文件。

### 尚未落地或需谨慎理解

- 首页项目列表仍是内存态，重启应用后不会恢复。
- 远程规格库仓储 `RemoteApiSpecDataRepository` 仍回退到本地 fallback 数据。
- 没有通用项目导入 / 导出格式，也没有完整 BOM 文件导出工作流。

## 运行环境

- Flutter SDK：受 `pubspec.yaml` 约束，当前为 Dart `^3.10.8`
- 主要依赖：`sqlite3`、`sqlite3_flutter_libs`、`path_provider`
- 推荐命令：

```bash
flutter pub get
flutter test
flutter run -d chrome
```

## 代码结构

```text
lib/
├── main.dart                         # 应用入口，初始化规格库仓储
├── models/                          # 领域模型：项目、设备、管线、元件、端口、立管
├── screens/
│   ├── home_screen.dart             # 项目首页（当前为内存态列表）
│   ├── canvas_screen.dart           # 主画布交互状态机与业务编排
│   ├── canvas_screen_overlays.dart  # 画布气泡/覆盖层布局辅助（canvas_screen 分拆）
│   ├── riser_editor_screen.dart     # 立管正视图编辑页
│   ├── riser_editor_toolbar.dart    # 立管编辑工具栏
│   └── riser_elevation_canvas.dart  # 立管正视图画布
├── utils/
│   ├── spec_data_repository.dart    # 规格目录、SQLite 仓储与 fallback 数据
│   ├── port_spec_catalog.dart       # 材质 / 规格 / 连接方式标准化
│   ├── spec_propagation.dart        # 锁驱动规格传播与冲突检测
│   ├── material_takeoff.dart        # 材料统计
│   ├── component_type_rules.dart    # 元件类型与拓扑规则
│   ├── component_port_constraints.dart
│   ├── canvas_geometry.dart         # 画布共享几何工具
│   ├── front_view_rules.dart        # 俯视 / 正视联动规则
│   ├── move_linkage_policy.dart     # 移动联动和约束策略
│   └── canvas_trace_*.dart          # Trace 存储、导出、远端上报
└── widgets/
    └── canvas_painter.dart          # 画布绘制器

test/                                # 规则引擎 + Widget 回归测试

tooling/                             # Web Trace、本地服务、部署辅助脚本
```

## 部署脚本

- macOS 部署入口：`tooling/deploy_and_verify_mepaint.sh`
- Windows 部署入口：`tooling/deploy_and_verify_mepaint_windows.sh`
- 两条脚本是并列关系：保留原有 mac 部署方式，不把 Windows 部署逻辑回填进 mac 脚本。
- 当前 macOS 部署脚本除了发布 `build/web`，还会同步 `tooling/mepaint_trace_server.py`，保证线上日志页与前端一起更新。

## 核心模块说明

### 1. 项目与坐标系统

- `Project` 保存项目元数据、画布、坐标系、场景类型与可选锚点信息。
- 默认比例为 `50 px / m`。
- `CoordinateSystem` 默认把原点放在画布中心。
- `Canvas` 持有 `equipments / pipelines / components / risers` 四类实体。

### 2. 画布编辑

当前画布以 `CanvasScreen` 为中心，集成了大部分交互状态机。

- 默认态：点击对象进入选择与编辑。
- 选取模式：支持单选与框选；右向左为 crossing，左向右为 window。
- 设备模式：按住拖拽创建，创建后自动退出设备模式并保持选中。
- 管线模式：默认正交绘制；支持点击定点、拖动抬手提交、双击结束或取消。
- 元件模式：支持自由放置，也支持贴合到设备边界或现有管线。
- 叠加层布局（属性气泡、遮挡句柄、引导线）已从主文件拆到 `canvas_screen_overlays.dart`，几何计算统一复用 `canvas_geometry.dart`，便于继续做局部维护而不必在主状态机中穿梭。

### 3. 元件与端口

- `Component` 是端口驱动的统一元件模型。
- `Port` 同时承载：材质、规格、连接方式、螺纹标准、锁字段、连接的管线 ID。
- 管道端口的字段编辑使用受控下拉，不允许自由输入任意规格文本。
- 锁是字段级语义，不是整对象锁。

### 4. 一键匹配（锁驱动传播）

- 入口在画布工具栏“`一键匹配`”。
- 起点必须是带锁的管道端口。
- 传播沿“元件端口 - 管线 - 元件端口”图遍历。
- 只写入未锁字段。
- 会在以下情形停止或报冲突：
  - 遇到锁边界
  - 规格不等效
  - 螺纹标准不一致
  - 没有实际磁吸连接记录

### 5. 立管与正视图

- 当连接两端存在标高差时，系统可自动补建立管。
- 选中单个元件或立管可进入正视图 / 立管编辑相关入口。
- 正视图使用 `(u, z)` 与俯视图 `(x, y, z)` 之间的变换实现。
- 立管元件支持在轴线上继续增删改。

### 6. 材料清单

- 当前由 `MaterialTakeoffService` 负责生成统计结果。
- 对管线按 `system + material + specification` 分组。
- 对元件按 `type` 汇总数量。
- 总长度会把俯视水平距离换算成米，并计入高差。
- 二次配新增项目会额外关注锚点阀门和新增设备编号是否填写。

### 7. Trace 与调试

- 画布操作可记录为 JSONL 事件流。
- 可选截图抓取、目录导出与上传到 `MEPAINT_CANVAS_TRACE_UPLOAD_ENDPOINT`。
- 工具栏“保存”当前主要用于触发 Trace 刷新 / 上传，不是项目持久化。
- 工具栏“导出”用于导出当前 Trace 包。
- 首页标题下方会显示当前版本；Web 下格式为 `v<appVersion> · build <timestamp>`。
- 线上日志目录页顶部会显示 `MEPaint 日志页版本`，用于快速确认当前日志页服务版本和 build 时间。

## 文档索引

- 开发与调试流程：`docs/development_workflow.md`
- Playwright 真实测试流程：`docs/PLAYWRIGHT_REAL_TESTING.md`
- 锁驱动规格传播：`docs/workflow_locked_propagation.md`
- 元件类型与拓扑规则：`docs/component_type_topology_rules.md`
- 规格目录与数据库路线：`docs/spec_database_roadmap.md`
- Web Trace 排障与恢复：`docs/WEB_TRACE_RECOVERY.md`
- 项目场景与当前边界：`docs/TODO_project_scenarios.md`
- 移动联动行为说明：`docs/PLAN_2026-02-19_move_linkage_behavior.md`
- 兼容性与已知限制：`docs/BUGS_2026-02-14_mobile_web.md`
- 测试计划与覆盖面：`TEST_PLAN.md`
- 当前测试快照：`TEST_REPORT_2026-02-13.md`

## 当前最重要的事实

如果你要继续开发这个项目，请优先记住下面四点：

1. 这是“画布编辑器 + 规则引擎原型”，不是完成态产品。
2. 项目数据尚未真正持久化，只有规格目录在非 Web 平台会落到 SQLite。
3. 规格传播、拓扑演化、立管编辑、Trace 是现阶段最稳定也最值得继续扩展的主线。
4. 任何需求或文档都应该以测试名称和当前代码行为为准，而不是以早期设计设想为准。