# 架构图生成规则

## 你必须遵循的工作流程

### 架构图生成完整流程（严格执行）

1. **需求澄清阶段**:
   - 必须明确用户需要生成哪一种或哪几种架构视图
   - 禁止在需求不明确的情况下开始代码分析

2. **代码阅读阶段**:
   - 必须使用 `read_code` 工具完整地、仔细地阅读和分析用户提供的所有相关源代码
   - 禁止只阅读部分代码或凭空猜测

3. **组件识别与关系分析阶段**:
   - 必须识别核心类、模块、接口和函数
   - 必须分析它们之间的依赖、继承、调用和数据流关系
   - 必须根据视图类型，对组件进行适当的抽象和分组

4. **视图绘制阶段 (DOT语言)**:
   - **逻辑视图**: 必须关注功能和系统结构，主要呈现分层关系，避免组件间过于密集的连线
   - **实现视图**: 必须关注代码的物理组织，展示文件、模块、包及其依赖关系
   - **进程视图**: 必须关注系统的运行时行为，展示主要的进程、线程、任务以及它们之间的通信
   - **部署视图**: 必须关注系统的物理部署，展示硬件节点、网络连接以及在节点上部署的软件组件
   - **用例视图**: 必须关注用户与系统的交互，展示参与者和用例

5. **图表生成与渲染阶段**:
   - 必须将生成的Graphviz DOT代码输出到以`.dot`为后缀的文件中
   - 必须使用`execute_script`工具调用`dot`命令将`.dot`文件渲染为`.png`图片
   - 必须向用户报告渲染后的图片路径

## 你必须遵守的原则

### 代码完整性原则

- **禁止**：只阅读部分代码或凭空猜测系统架构
- **必须**：完整地、仔细地阅读和分析用户提供的所有相关源代码
- **必须**：准确识别核心类、模块、接口和函数及其相互关系

### 视图准确性原则

- **必须**：图表必须准确反映代码的实际结构
- **必须**：在同一系列的图表中，相同组件的表示应保持一致
- **禁止**：在图表中体现具体实现名称或路径，必须使用抽象的职责或角色命名

### 图表清晰性与视觉美感原则

- **必须**：图表必须简单明了，易于理解，具有专业的外观
- **必须**：避免组件间过于密集的连线，保持图表清晰，留白充足
- **必须**：使用协调统一的配色方案，不同层级使用不同色系，确保视觉层次分明
- **必须**：节点样式统一（圆角矩形、填充色、边框色），提升整体美观度
- **必须**：字体大小适中，标签文字清晰可读，避免文字重叠或过小
- **必须**：连线样式统一，使用合适的箭头样式和线条粗细，重要关系可加粗显示
- **必须**：子图（cluster）使用柔和的背景色和清晰的边框，增强分组视觉效果
- **必须**：整体布局平衡，节点分布均匀，避免局部过于拥挤或稀疏

### 专业性原则

- **必须**：严格遵循架构设计和Graphviz的最佳实践
- **必须**：所有输出的DOT代码必须是完整的、可直接渲染的
- **必须**：包含在 `digraph G { ... }` 中，遵循统一的样式规范

## 具体要求和规范

- 所有输出的DOT代码必须是完整的、可直接渲染的。
- 必须包含在 `digraph G { ... }` 中。
- **布局方向**: 对于层次结构明显的图（如组织架构、调用链），
  应优先使用 `rankdir="TB"` 实现从上到下的布局。对于流程或序列
  关系，`rankdir="LR"` (从左到右) 可能更合适。
- **布局对齐**: 为了获得规整对齐的布局，请积极使用
  `subgraph cluster_...` 对节点进行分组，并使用
  `{ rank=same; ... }` 语句将需要水平对齐的节点放在同一层级。
- **布局间距**: 为了避免节点或文字重叠，可以在 `graph [...]`
  中设置 `nodesep` 和 `ranksep` 属性来增大节点和层级间距，
  例如 `nodesep=0.6, ranksep=1.0`。同时可设置 `overlap=false` 禁止
  重叠。
- 使用graph、node和edge属性来美化图表。推荐使用以下专业且美观的样式规范：

```dot
digraph G {
    // --- Global Settings ---
    // 使用专业的全局样式设置，确保图表美观统一
    graph [rankdir="TB", 
           splines=ortho,                    // 使用正交连线，更专业
           fontname="Sans-serif", 
           fontsize=11,                      // 合适的字体大小
           label="图表标题：[在此处填写视图名称]", 
           labelloc="t", 
           fontcolor="#333333",              // 标题文字颜色
           newrank=true, 
           nodesep=0.8,                      // 节点间距，避免拥挤
           ranksep=1.2,                      // 层级间距，层次分明
           overlap=false,                    // 禁止重叠
           bgcolor="#FFFFFF",                // 背景色为白色
           pad=0.5];                         // 边距，留白充足
    
    // --- Default Node Style ---
    // 默认节点样式：圆角矩形，柔和填充，清晰边框
    node [shape=box, 
          style="rounded,filled", 
          fillcolor="#F5F5F5",               // 浅灰填充，柔和舒适
          color="#666666",                    // 深灰边框，清晰不突兀
          fontname="Sans-serif",
          fontsize=10,
          fontcolor="#333333",                // 文字颜色，确保可读性
          penwidth=1.5];                      // 边框粗细适中
    
    // --- Default Edge Style ---
    // 默认连线样式：清晰简洁
    edge [fontname="Sans-serif",
          fontsize=9,
          fontcolor="#555555",                // 标签文字颜色
          color="#888888",                    // 连线颜色，不抢夺注意力
          penwidth=1.2,                       // 连线粗细
          arrowsize=0.8];                     // 箭头大小适中

    // --- Interface/Entry Point Nodes ---
    // 接口层/入口节点：使用醒目的暖色调
    node [group=interface, 
          shape=cds,                         // 圆角矩形，表示接口
          fillcolor="#FFE6CC",               // 温暖的橙色填充
          color="#D79B00",                    // 深橙色边框
          penwidth=2.0];                      // 稍粗的边框，突出重要性
    api_gateway [label="API网关"];

    // --- Service Layer Subgraph ---
    // 服务层子图：使用专业的蓝色系，清晰分组
    subgraph cluster_services {
        label = "业务服务层";
        style = "filled,rounded";            // 填充+圆角，更美观
        fillcolor="#F0F4F8",                 // 浅蓝灰背景，柔和专业
        color="#6C8EBF",                      // 蓝色边框，与节点呼应
        fontname="Sans-serif";
        fontsize=11;
        fontcolor="#4A5568";                  // 深灰文字，清晰可读
        penwidth=2.0;                         // 边框稍粗，突出分组
        
        node [group=service, 
              fillcolor="#DAE8FC",            // 浅蓝色填充
              color="#6C8EBF",                // 蓝色边框
              penwidth=1.8];                  // 边框粗细
        service_A [label="服务A"];
        service_B [label="服务B"];
    }

    // --- Data Layer ---
    // 数据层：使用绿色系，表示存储和持久化
    node [group=database, 
          shape=cylinder,                      // 圆柱形，表示数据库
          fillcolor="#D5E8D4",                // 浅绿色填充
          color="#82B366",                    // 深绿色边框
          penwidth=2.0];                      // 边框稍粗，突出重要性
    database_A [label="数据库"];

    // --- Relationships ---
    // 关系连线：使用清晰的标签和样式
    api_gateway -> service_A [label="路由", 
                               color="#6C8EBF",    // 使用服务层颜色
                               penwidth=1.5];
    api_gateway -> service_B [label="路由", 
                               color="#6C8EBF",
                               penwidth=1.5];
    service_A -> database_A [label="读写", 
                             color="#82B366",     // 使用数据层颜色
                             penwidth=1.5];
    service_B -> database_A [label="读", 
                             color="#82B366",
                             penwidth=1.5,
                             style="dashed"];      // 只读关系使用虚线

    // --- Horizontal Alignment ---
    // 水平对齐：确保同级节点在同一水平线上
    { rank=same; service_A; service_B; }
}
```

**样式美化要点**：

- **配色方案**：使用协调的色系，接口层用暖色（橙/黄），服务层用冷色（蓝），数据层用绿色，外部系统用紫色
- **字体规范**：统一使用 Sans-serif 字体，标题11pt，节点标签10pt，连线标签9pt
- **边框样式**：重要节点使用稍粗边框（penwidth=2.0），普通节点1.5-1.8
- **填充效果**：使用柔和的浅色填充，避免过于鲜艳，确保专业感
- **连线样式**：重要关系使用实线加粗，次要关系使用虚线，不同层级使用对应颜色
- **子图美化**：使用圆角填充背景（style="filled,rounded"），柔和的背景色，清晰的边框
- **留白设计**：通过 nodesep 和 ranksep 控制间距，pad 控制边距，确保图表不拥挤

- 根据不同的视图，使用合适的形状和样式。
- 模块节点尽量使用矩形（shape=box）；除数据库、外部系统、消息队列等特殊组件外，避免用其它形状表示"模块"。
- 抽象命名规范：不要在图中体现具体实现名称或路径（如 utils.output、xxx.py、具体函数名），使用抽象的职责或角色命名（如 输出模块、存储模块、网络层、鉴权服务）。
- 注释清晰，解释图表中的关键元素和关系。
- **准确性**: 图表必须准确反映代码的实际结构。
- **清晰性**: 图表必须简单明了，易于理解。
- **一致性**: 在同一系列的图表中，相同组件的表示应保持一致。
- **专业性**: 严格遵循架构设计和Graphviz的最佳实践。

## 实践指导

### 代码分析最佳实践

- **从入口点开始**：先识别系统的主要入口点（如API网关、主函数、核心控制器）
- **分层分析**：按照表现层、业务逻辑层、数据访问层的层次结构进行分析
- **依赖追踪**：使用工具或手动追踪代码间的依赖关系，绘制依赖图谱
- **模块识别**：识别高内聚、低耦合的模块单元

### 组件抽象技巧

- **使用抽象命名**：将具体的类名、函数名抽象为职责描述（如将`UserService`抽象为"用户管理服务"）
- **合理分组**：将相关功能组件分组到同一子图中，使用`subgraph cluster_xxx`语法
- **层级划分**：明确区分接口层、服务层、数据层等不同层级
- **外部系统标识**：清晰标识外部系统、数据库、消息队列等外部组件

### 视图选择指导

- **逻辑视图**：适用于展示系统功能模块划分和交互关系
- **实现视图**：适用于展示代码组织结构、包依赖关系
- **进程视图**：适用于展示系统运行时进程、线程间的并发和通信
- **部署视图**：适用于展示系统在物理环境中的部署拓扑
- **用例视图**：适用于展示用户与系统的交互场景

### Graphviz 使用技巧与美化指南

#### 布局与对齐技巧

- **布局选择**：
  - 层次结构使用`rankdir="TB"`（从上到下），适合展示分层架构
  - 流程关系使用`rankdir="LR"`（从左到右），适合展示数据流或调用链
  - 复杂关系可尝试`rankdir="BT"`或`rankdir="RL"`，根据内容选择最佳方向

- **节点对齐**：
  - 使用`{ rank=same; node1; node2; }`实现同级节点的水平对齐
  - 对于重要节点，可使用`rank=source`或`rank=sink`将其置于顶层或底层
  - 使用`group`属性将相关节点分组，自动对齐

- **间距调整**：
  - `nodesep=0.8-1.2`：控制同级节点间距，避免拥挤
  - `ranksep=1.0-1.5`：控制不同层级间距，层次分明
  - `pad=0.5-1.0`：控制图表边距，留白充足
  - `overlap=false`：禁止节点重叠，确保清晰

#### 颜色与视觉美化

- **配色方案**（推荐专业配色）：
  - **接口层/入口**：暖色调 `#FFE6CC`（浅橙）填充，`#D79B00`（深橙）边框
  - **服务层/业务逻辑**：冷色调 `#DAE8FC`（浅蓝）填充，`#6C8EBF`（深蓝）边框
  - **数据层/存储**：绿色系 `#D5E8D4`（浅绿）填充，`#82B366`（深绿）边框
  - **外部系统**：紫色系 `#E1D5E7`（浅紫）填充，`#9673A6`（深紫）边框
  - **工具/工具层**：红色系 `#F8CECC`（浅红）填充，`#B85450`（深红）边框
  - **事件/消息**：黄色系 `#FFF2CC`（浅黄）填充，`#B57800`（深黄）边框

- **颜色使用原则**：
  - 同一层级使用相同色系，保持视觉一致性
  - 填充色使用浅色（#F0-F8范围），边框使用深色（#4-9范围），形成层次
  - 避免使用过于鲜艳的颜色（如纯红、纯蓝），使用柔和的中间色调
  - 背景色统一为白色（`bgcolor="#FFFFFF"`），确保专业感

#### 节点样式美化

- **形状规范**：
  - 接口/API：`shape=cds`（圆角矩形），突出入口特性
  - 服务/模块：`shape=box, style="rounded,filled"`（圆角填充矩形），标准样式
  - 数据库：`shape=cylinder`（圆柱形），传统表示方法
  - 外部系统：`shape=box, style="rounded,filled,dashed"`（虚线边框），区分外部
  - 队列/消息：`shape=box, style="rounded,filled"`，可用特殊颜色区分

- **节点美化技巧**：
  - 使用`penwidth=1.5-2.0`控制边框粗细，重要节点稍粗
  - 使用`fillcolor`设置柔和的填充色，避免纯白或纯黑
  - 使用`fontsize=10-11`确保文字清晰可读
  - 使用`fontcolor="#333333"`设置深色文字，确保对比度

#### 连线样式美化

- **连线样式**：
  - 重要关系：`penwidth=1.5-2.0`，实线，使用对应层级颜色
  - 次要关系：`penwidth=1.0-1.2`，虚线（`style="dashed"`）
  - 数据流：可使用箭头样式`arrowhead=normal`或`arrowhead=vee`
  - 双向关系：使用`dir=both`，两端都有箭头

- **连线标签**：
  - 使用简洁的标签文字，避免过长
  - `fontsize=9`，确保不抢夺节点注意力
  - `fontcolor="#555555"`，使用中等灰色，清晰但不突兀

#### 子图（Cluster）美化

- **子图样式**：
  - 使用`style="filled,rounded"`，填充+圆角，更美观
  - 背景色使用对应层级的浅色版本（如服务层用`#F0F4F8`）
  - 边框使用对应层级的深色（如服务层用`#6C8EBF`）
  - `penwidth=2.0`，边框稍粗，突出分组
  - 标签使用`fontsize=11`，清晰标识分组

#### 字体与文字美化

- **字体选择**：
  - 统一使用`fontname="Sans-serif"`，现代简洁
  - 标题：`fontsize=11-12`，加粗显示
  - 节点标签：`fontsize=10`，清晰可读
  - 连线标签：`fontsize=9`，不抢夺注意力

- **文字颜色**：
  - 标题：`fontcolor="#333333"`（深灰）
  - 节点标签：`fontcolor="#333333"`（深灰）
  - 连线标签：`fontcolor="#555555"`（中灰）

#### 整体视觉效果

- **专业感提升**：
  - 使用统一的样式规范，确保整体协调
  - 避免过度装饰，保持简洁专业
  - 合理使用留白，避免拥挤
  - 确保颜色对比度足够，文字清晰可读

- **层次感营造**：
  - 通过颜色深浅区分层级
  - 通过边框粗细突出重要性
  - 通过间距大小体现关系紧密程度
  - 通过子图分组明确模块边界

## 渲染步骤

1. 首先，使用 REWRITE 操作或 PATCH 操作将生成的DOT代码写入`.dot`文件。
2. 然后，使用`execute_script`调用`dot`命令进行渲染。
3. 最后，将生成的`.png`文件路径告知用户。

## 执行检查清单

在开始架构图生成前，你必须确认：

- [ ] 已明确用户需要生成的架构视图类型（逻辑/实现/进程/部署/用例视图）
- [ ] 已获取所有相关的源代码文件路径
- [ ] 已准备好代码分析工具和环境

在进行代码分析时，你必须确认：

- [ ] 完整阅读了所有相关源代码，没有遗漏关键文件
- [ ] 准确识别了系统的核心组件和模块
- [ ] 分析了组件间的依赖、继承、调用和数据流关系
- [ ] 根据视图类型对组件进行了适当的抽象和分组

在绘制架构图时，你必须确认：

- [ ] 选择了合适的视图类型来展示系统架构
- [ ] 使用了正确的Graphviz语法和DOT语言格式
- [ ] 遵循了统一的样式规范和颜色搭配，使用了专业的配色方案
- [ ] 图表布局清晰，易于理解，留白充足，节点分布均匀
- [ ] 组件命名抽象，没有暴露具体实现细节
- [ ] 节点样式统一（圆角、填充、边框），视觉效果专业美观
- [ ] 连线样式合理（粗细、颜色、虚实），重要关系突出显示
- [ ] 子图分组清晰，背景色和边框协调，标签清晰可读
- [ ] 字体大小适中，文字颜色对比度足够，确保可读性
- [ ] 整体配色协调，层次分明，具有专业的外观

在生成和渲染图表时，你必须确认：

- [ ] DOT代码完整且语法正确
- [ ] 使用`dot`命令成功渲染为PNG图片
- [ ] 生成的图片文件路径正确并可访问
- [ ] 向用户提供了清晰的图片访问路径

在交付结果前，你必须确认：

- [ ] 架构图准确反映了代码的实际结构
- [ ] 图表符合架构设计的最佳实践
- [ ] 所有组件和关系都正确表示
- [ ] 图片质量清晰，适合展示和分享
- [ ] 图表具有专业美观的外观，配色协调，样式统一
- [ ] 视觉层次分明，重要组件突出，整体布局平衡
- [ ] 文字清晰可读，颜色对比度足够，无重叠或拥挤
- [ ] 符合企业级架构图的视觉标准，适合正式文档和演示
