mermaid-go/ANALYSIS.md

Mermaid-Go 实现分析报告

基于 others/mermaid-develop 中的 mermaid.js 源码分析，对比当前 Go 实现的完整性。

📊 当前已实现的图表类型

✅ 已完全实现

1. Flowchart - 流程图

   • 路径: pkg/parser/flowchart.go, pkg/renderer/flowchart.go
   • 基于: mermaid-develop/packages/mermaid/src/diagrams/flowchart/parser/flow.jison
   • 状态: 完整实现，支持节点、边、子图、样式

2. Sequence Diagram - 序列图

   • 路径: pkg/parser/sequence.go, pkg/renderer/sequence.go
   • 基于: mermaid-develop/packages/mermaid/src/diagrams/sequence/parser/sequenceDiagram.jison
   • 状态: 完整实现，支持参与者、消息、循环、选择、并行、盒子、激活

3. Class Diagram - 类图

   • 路径: pkg/parser/class.go, pkg/renderer/class.go
   • 基于: mermaid-develop/packages/mermaid/src/diagrams/class/parser/classDiagram.jison
   • 状态: 完整实现，支持类、关系、成员、方法

4. State Diagram - 状态图

   • 路径: pkg/parser/state.go, pkg/renderer/state.go
   • 基于: mermaid-develop/packages/mermaid/src/diagrams/state/parser/stateDiagram.jison
   • 状态: 完整实现，支持状态、转换、复合状态

🚫 未实现的图表类型 (需要新增)

高优先级 (有 .jison 解析器)

1. ER Diagram - 实体关系图

   • mermaid.js 路径: diagrams/er/parser/erDiagram.jison
   • 文件: erDb.js, erDetector.ts, erDiagram.ts, erRenderer.ts
   • 关键字: erDiagram

2. Gantt Chart - 甘特图

   • mermaid.js 路径: diagrams/gantt/parser/gantt.jison
   • 文件: ganttDb.js, ganttDetector.ts, ganttDiagram.ts, ganttRenderer.ts
   • 关键字: gantt

3. Pie Chart - 饼图

   • mermaid.js 路径: diagrams/pie/ (使用简单解析器)
   • 文件: pieDb.ts, pieDetector.ts, pieDiagram.ts, pieRenderer.ts
   • 关键字: pie

4. Timeline - 时间线图

   • mermaid.js 路径: diagrams/timeline/parser/timeline.jison
   • 文件: timelineDb.ts, timelineDetector.ts, timelineDiagram.ts, timelineRenderer.ts
   • 关键字: timeline

5. User Journey - 用户旅程图

   • mermaid.js 路径: diagrams/user-journey/parser/journey.jison
   • 文件: journeyDb.js, journeyDetector.ts, journeyDiagram.ts, journeyRenderer.ts
   • 关键字: journey

6. Requirement Diagram - 需求图

   • mermaid.js 路径: diagrams/requirement/parser/requirementDiagram.jison
   • 文件: requirementDb.js, requirementDetector.ts, requirementDiagram.ts, requirementRenderer.ts
   • 关键字: requirementDiagram

7. Quadrant Chart - 象限图

   • mermaid.js 路径: diagrams/quadrant-chart/parser/quadrant.jison
   • 文件: quadrantDb.ts, quadrantDetector.ts, quadrantDiagram.ts, quadrantRenderer.ts
   • 关键字: quadrantChart

8. Block Diagram - 块图

   • mermaid.js 路径: diagrams/block/parser/block.jison
   • 文件: blockDB.ts, blockDetector.ts, blockDiagram.ts, blockRenderer.ts
   • 关键字: block

9. C4 Diagram - C4 架构图

   • mermaid.js 路径: diagrams/c4/parser/c4Diagram.jison
   • 文件: c4Db.js, c4Detector.ts, c4Diagram.ts, c4Renderer.js
   • 关键字: C4Context, C4Container, C4Component, C4Dynamic, C4Deployment

10. Mindmap - 思维导图

    • mermaid.js 路径: diagrams/mindmap/parser/mindmap.jison
    • 文件: mindmapDb.ts, mindmapDetector.ts, mindmapDiagram.ts, mindmapRenderer.ts
    • 关键字: mindmap

11. Kanban - 看板图

    • mermaid.js 路径: diagrams/kanban/parser/kanban.jison
    • 文件: kanbanDb.ts, kanbanDetector.ts, kanbanDiagram.ts, kanbanRenderer.ts
    • 关键字: kanban

12. Sankey Diagram - 桑基图

    • mermaid.js 路径: diagrams/sankey/parser/sankey.jison
    • 文件: sankeyDb.ts, sankeyDetector.ts, sankeyDiagram.ts, sankeyRenderer.ts
    • 关键字: sankey

13. XY Chart - XY 图表

    • mermaid.js 路径: diagrams/xychart/parser/xychart.jison
    • 文件: xychartDb.ts, xychartDetector.ts, xychartDiagram.ts, xychartRenderer.ts
    • 关键字: xychart

中优先级 (无 .jison 解析器，使用自定义解析)

1. Git Graph - Git 图

   • mermaid.js 路径: diagrams/git/
   • 文件: gitGraphDb.js, gitGraphDetector.ts, gitGraphDiagram.ts, gitGraphRenderer.ts
   • 关键字: gitGraph

2. Architecture Diagram - 架构图

   • mermaid.js 路径: diagrams/architecture/
   • 文件: architectureDb.ts, architectureDetector.ts, architectureDiagram.ts, architectureRenderer.ts
   • 关键字: architecture

3. Info - 信息图

   • mermaid.js 路径: diagrams/info/
   • 文件: infoDb.ts, infoDetector.ts, infoDiagram.ts, infoRenderer.ts
   • 关键字: info

4. Packet - 数据包图

   • mermaid.js 路径: diagrams/packet/
   • 文件: db.ts, parser.ts, packetDetector.ts, packetDiagram.ts, packetRenderer.ts
   • 关键字: packet

5. Radar Chart - 雷达图

   • mermaid.js 路径: diagrams/radar/
   • 文件: db.ts, parser.ts, radarDetector.ts, radarDiagram.ts, radarRenderer.ts
   • 关键字: radar

6. Treemap - 树图

   • mermaid.js 路径: diagrams/treemap/
   • 文件: db.ts, parser.ts, treemapDetector.ts, treemapDiagram.ts, treemapRenderer.ts
   • 关键字: treemap

📋 AST 结构分析

当前已在 pkg/ast/other_diagrams.go 中定义了部分 AST 结构：

• ✅ ERDiagram
• ✅ GanttDiagram
• ✅ PieChart
• ✅ TimelineDiagram
• ✅ UserJourneyDiagram
• ✅ QuadrantChart
• ✅ RequirementDiagram

需要新增的 AST 结构：

• ❌ BlockDiagram
• ❌ C4Diagram (多种类型)
• ❌ Mindmap
• ❌ KanbanBoard
• ❌ SankeyDiagram
• ❌ XYChart
• ❌ GitGraph
• ❌ ArchitectureDiagram
• ❌ InfoDiagram
• ❌ PacketDiagram
• ❌ RadarChart
• ❌ TreemapDiagram

🔄 渲染器分析

当前在 pkg/renderer/mermaid.go 中为未实现的类型提供了占位符渲染器。需要完整实现这些渲染器。

🎯 实现优先级建议

第一批 (用户需求高，相对简单)

1. Pie Chart - 饼图 (语法简单)
2. ER Diagram - 实体关系图 (有完整 jison)
3. Gantt Chart - 甘特图 (项目管理常用)

第二批 (功能图表)

1. Timeline - 时间线
2. User Journey - 用户旅程
3. Quadrant Chart - 象限图

第三批 (高级图表)

1. Block Diagram - 块图
2. C4 Diagram - C4 架构图
3. Mindmap - 思维导图

第四批 (专业图表)

1. Kanban - 看板
2. Sankey - 桑基图
3. XY Chart - XY 图表

第五批 (特殊用途)

1. Git Graph - Git 图
2. Architecture - 架构图
3. 其他专业图表

📁 建议的文件结构

为每个新图表类型创建：

pkg/ast/{diagram_name}.go           - AST 结构定义
pkg/parser/{diagram_name}.go        - 解析器实现
pkg/renderer/{diagram_name}.go      - 渲染器实现
cmd/demo-{diagram_name}/main.go     - 演示程序

🧪 测试策略

1. 为每个新图表类型创建单元测试
2. 添加集成测试验证解析→渲染的完整性
3. 从 mermaid.js 的测试案例中提取测试数据
4. 确保与原版 mermaid.js 的输出兼容性

📚 参考资源

• mermaid.js 源码: others/mermaid-develop/packages/mermaid/src/diagrams/
• JISON 语法文件: */parser/*.jison
• 数据库状态管理: *Db.ts 或 *db.js
• 渲染器: *Renderer.ts 或 *renderer.js
• 类型定义: *Types.ts

📊 实现统计

• ✅ 已实现: 4 种图表类型 (21%)
• 🔄 进行中: 0 种图表类型
• ❌ 未实现: 15+ 种图表类型 (79%)

总计: mermaid.js 支持 19+ 种主要图表类型，当前 Go 实现仅覆盖了 21%。