# Moon Graph 项目申报书

## 基本信息

- 项目名称：Moon Graph：MoonBit 原生层级图布局与可视化引擎
- 参赛者：待填写
- 联系方式：待填写
- GitHub 仓库链接：https://github.com/code3055/moonpulse（项目位于 moon_graph 子目录）
- 项目方向：MoonBit 图布局基础库 / 可视化基础设施 / 开发者工具
- 是否为移植项目：否，原创 MoonBit 实现，参考 ELK JSON 的数据组织方式
- 项目许可证：MIT

## 项目简介

Moon Graph 面向流程图、数据流水线、状态机和模块依赖图，提供从结构化图数据到节点坐标、边路由与 SVG 的完整处理链路。核心算法、数据校验、JSON 导入导出、文本解析和 SVG 生成使用 MoonBit 实现，命令行宿主仅承担文件输入输出和参数处理。

项目目标是提供可以嵌入 MoonBit 工具链、编译到 JavaScript 并接入 Web 应用的中小规模图可视化基础能力。交付物不仅包括布局库，也包括可运行 CLI、业务示例、错误行为说明、自动测试和生成的 SVG，方便开发者进行实际集成。

## 解决的问题与应用价值

图编辑器、文档系统和工作流平台通常已有节点与关系数据，但缺少自动排布、层级容器和边路由能力。手动拖动节点成本高，而且图结构变化后容易产生重叠。Moon Graph 将数据导入、校验、布局和渲染统一在一个 MoonBit 模块内，降低应用开发者重复实现基础算法的成本。

示例数据展示四个实际场景：数据采集—清洗—存储—报表流水线；具有内部步骤和外部端口的处理服务；带重试与自环的状态机；由文本维护的内容评审流程。JSON 输出可供前端自行渲染，SVG 则可直接进入文档或报告。

## 已实现的功能范围

1. **层级图模型**：节点、复合节点、边、端口、文字标签与布局配置；容器局部坐标，全局 ID 唯一性检查。
2. **五类布局**：layered、force、radial、box、fixed。分层算法包含有向环反馈排序、最长路径分层和重心排序；力导向算法提供种子与迭代次数；各类算法保留节点尺寸并按内容扩展容器。
3. **边与端口**：四边端口、同侧均匀分配、正交和折线路由、自环，输出 ELK 风格 section 数据。
4. **数据交换**：ELK JSON 风格的明确子集、紧凑 / 缩进输出、中文标签、自定义逐行文本输入，非法字段和未知选项明确报错。
5. **统一 API**：new_elk_engine().layout、layout_json、parse_graph、graph_json、parse_text、render_svg、validate、algorithms。
6. **端到端应用**：无第三方 npm 依赖的 Node.js CLI，可从文件 / stdin 读取并输出 JSON / SVG，支持根节点算法和方向覆盖。
7. **工程交付**：MoonBit 回归测试、参数化场景与错误边界测试、真实 CLI 子进程集成测试、四个生成 SVG、API 示例、兼容性文档及持续集成配置。

## 技术路线与原创设计

项目采用 MoonBit 原生包、记录类型、枚举错误和测试工具，不复刻 Java 继承层级或 Eclipse 插件系统。库对图做深拷贝后执行布局，避免出错时部分修改调用者输入；层级布局自底向上完成，再定位父容器端口和外部边。输入、结构和输出三处检查边界，便于在命令行或服务中可靠处理错误数据。

对外接口以 JSON 和 MoonBit 类型为主，JavaScript 通过字符串桥接模块调用同一份 MoonBit 实现，避免两套算法行为漂移。SVG 在 MoonBit 内生成并转义用户文字，无需额外图形库。

## 与参考示例的关系

本项目从用户提供的 Moon ELK 申报示例中借鉴了“图布局基础库 + JSON 交换 + 多算法 + 测试”的交付方向，但没有复制示例参赛者、联系方式或仓库信息，也没有将未实现的功能列为完成。

参考项目为 Eclipse Layout Kernel（https://github.com/eclipse-elk/elk，EPL-2.0），JSON 字段说明来自 ELK 官方文档。Moon Graph 当前为独立原创代码，未移植 ELK / elkjs 源码，因而使用 MIT 许可证；若未来引入第三方源码，应另行检查其许可证并保留相应声明。

本项目不提供完整 ELK 兼容层，不声称与 elkjs 产生相同坐标，也没有将自有回归测试宣称为参考实现差异测试。兼容范围和差异在 docs/COMPATIBILITY.md 中逐项列出。

## 当前边界

仅支持五类列出的算法。Stress、MrTree、RectPacking、Spore、Random、Vertiflex、Graphviz 等名称会报错；超边、跨层容器直连、多 section 边、完整 ELK Text、Eclipse UI、OSGi、服务发现、标签避让和全局避障路由尚未实现。算法为同步执行，最大 500 节点、3000 边、5000 端口，输入最大 1 MiB，不面向超大图或硬实时调度。

## 验证方法与交付状态

通过 MoonBit wasm-gc 和 JavaScript 两后端执行同一套核心测试，并通过 Node.js 子进程测试验证 stdin、文件路径、UTF-8、算法选择、层级图、环、SVG 转义及非零错误退出。测试命令和测试覆盖说明见 README 与 docs/TESTING.md；实际数量以执行结果为准，不以空断言或重复快照凑数。

当前源码、示例、文档和 CLI 位于公开仓库 code3055/moonpulse 的 moon_graph 子目录。包名为 code3055/moon_graph，实际发布和安装核验记录见 docs/ACCEPTANCE.md；参赛者个人资料仍由本人填写。

## 后续计划（未计入当前完成范围）

- 扩展层级跨边与增量布局，降低交互编辑时的节点移动。
- 改进标签尺寸测量、避障路由和交叉优化。
- 建立与选定 ELK / elkjs 版本的参考对比数据集，明确比较指标，而非要求像素级一致。
- 增加浏览器交互示例、性能基准和资源预算选项。
- 持续维护公开 API，并按版本更新可复用 MoonBit 包。