# Mermaid 图表语法速查与项目约定 本文档为需求分析 skill 中各类图表的 Mermaid 语法参考和项目特定约定。 --- ## 1. Mermaid 语法速查 ### 1.1 功能领域图(步骤②) 使用 `flowchart` 展示功能模块及其交互关系。模块级抽象,不涉及类级别细节。 **语法模板**: ```mermaid flowchart TD subgraph 输入层 PlayerInput[玩家输入模块] end subgraph 核心层 Movement[移动控制模块] Interaction[交互管理模块] end subgraph 数据层 ItemData[物品数据模块] CollectionData[收集数据模块] end PlayerInput --> Movement PlayerInput --> Interaction Interaction -->|查询可交互物| ItemData Interaction -->|通知收集| CollectionData ``` **要点**: - 使用 `subgraph` 划分模块边界(如输入层、核心层、数据层) - 节点使用中文标签标注模块职责 - 边上可加 `|文字|` 说明交互类型 - 不同层可用 `style` 着色区分 **样式区分**(可选): ```mermaid flowchart TD A[模块A] --> B[模块B] A -.->|事件通知| C[模块C] style A fill:#e1f5fe style B fill:#f3e5f5 style C fill:#e8f5e9 ``` - `-->` 实线:主数据流 / 同步调用 - `-.->` 虚线:事件通知 / 异步通信 --- ### 1.2 类设计图(步骤③) 使用 `classDiagram` 展示类的关键数据、接口和关系。 **语法模板**: ```mermaid classDiagram class UInteractionManager { -EInteractionState State -EInteractPhase Phase -TArray~UInteractableComponent*~ NearbyInteractables +BeginInteract(UInteractableComponent* Target) void +EndInteract() void +TickComponent(float DeltaTime) void #OnDetectionEnter(UPrimitiveComponent* Overlapped) void } class IChildHoodInteractable { <> +GetInteractableData() FInteractableData +OnInteract(AChildHoodCharacter* Player) void } class UInteractableComponent { -FInteractableData Data -USphereComponent* DetectionSphere +GetInteractableData() FInteractableData +OnInteract(AChildHoodCharacter* Player) void } class AChildHoodCharacter { -UInteractionManager* InteractionManager -bool bIsInteracting +SetInteracting(bool bValue) void } UInteractionManager --> UInteractableComponent : 检测并驱动 UInteractableComponent ..|> IChildHoodInteractable : 实现 AChildHoodCharacter *-- UInteractionManager : 组合(持有) UInteractableComponent o-- USphereComponent : 聚合(引用) ``` **关系类型速查**: | 关系 | 语法 | 含义 | UE5 中的典型场景 | |------|------|------|------------------| | 继承 | `<\|--` | 子类继承父类 | `ACharacter` 的子类 | | 实现 | `..\|>` | 实现接口 | `UInterface` 的实现类 | | 组合 | `*--` | 生命周期绑定,整体拥有部分 | Character 持有 Component | | 聚合 | `o--` | 引用关系,部分可独立存在 | Component 引用另一个 Actor | | 依赖 | `..>` | 使用关系,临时引用 | 方法参数、局部变量 | | 关联 | `-->` | 持久引用 | 成员指针引用 | **可见性标记**: | 标记 | 含义 | UE5 惯例 | |------|------|---------| | `+` | public | `UFUNCTION(BlueprintCallable)` | | `-` | private | 内部状态 | | `#` | protected | 子类可访问 | **UE5 类命名约定**: | 前缀 | 类型 | 示例 | |------|------|------| | `A` | Actor | `AChildHoodCharacter` | | `U` | UObject / Component | `UInteractionManager` | | `I` | Interface | `IChildHoodInteractable` | | `F` | Struct / Enum | `FInteractableData` | | `E` | Enum | `EInteractType` | --- ### 1.3 时序图(步骤④) 使用 `sequenceDiagram` 追踪复杂特性的跨系统调用流程。 **语法模板**: ```mermaid sequenceDiagram autonumber participant Player as 玩家 participant PC as PlayerController participant IM as InteractionManager participant IC as InteractableComponent participant CM as CollectionManager Player->>PC: 按 E 键 (IA_Interact) activate PC PC->>IM: BeginInteract(SelectedInteractable) deactivate PC activate IM IM->>IM: 状态 Free -> Interacting IM->>IM: 子阶段 Enter (转向+推镜) IM->>IC: OnInteract(Player) activate IC IC->>IC: 检查交互类型 (Pickup) IC->>CM: AddItem(ItemId, Category) activate CM CM-->>IC: 收集成功 deactivate CM IC-->>IM: 交互完成 deactivate IC IM->>IM: 子阶段 Exit (回位+淡出) IM->>IM: 状态 Interacting -> Free deactivate IM ``` **要点**: - `participant` 使用 UE5 类名缩写 + 中文别名 - `activate` / `deactivate` 展示调用栈深度 - `->>` 同步调用,`-->>` 返回,`--)` 异步通知 - `autonumber` 自动编号消息 - `Note over` 可添加阶段说明 **消息类型**: | 语法 | 含义 | 适用场景 | |------|------|---------| | `->>` | 实线箭头,同步调用 | 函数调用 | | `-->>` | 虚线箭头,返回 | 函数返回值 | | `--)` | 开放箭头,异步 | 委托广播、事件分发 | | `-x` | 叉号,失败 | 异常、条件不满足 | --- ### 1.4 流程图 / 鲁棒图(步骤⑥) 使用 `flowchart` 描述复杂接口的决策分支和执行流程。 **语法模板**: ```mermaid flowchart TD Start([BeginInteract 被调用]) --> CheckState{当前状态?} CheckState -->|Free| CheckSelected{是否有选中的可交互物?} CheckState -->|Interacting| Reject1([返回:已在交互中]) CheckSelected -->|是| SetState[State = Interacting
Phase = Enter] CheckSelected -->|否| Reject2([返回:无可交互物]) SetState --> TurnAndPush[执行角色转向
执行摄像机推镜] TurnAndPush --> CheckAnim{需要等待动画?} CheckAnim -->|是| AnimLock[Phase = AnimLock
等待动画事件] CheckAnim -->|否| Active[Phase = Active] AnimLock --> Active Active --> ExecuteLogic[根据交互类型执行具体逻辑] ExecuteLogic --> EndFlow([进入 Exit 阶段]) ``` **要点**: - `([...])` 圆角矩形:开始/结束节点 - `{...}` 菱形:判断/分支节点 - `[...]` 矩形:处理/动作节点 - 边上的 `|文字|` 标注分支条件 - 每个分支都要有明确的去向(不允许"悬空"分支) --- ## 2. 项目约定 ### 2.1 命名约定 - **类名节点**:使用 UE5 完整类名(`AChildHoodCharacter`、`UInteractionManager`),不缩写 - **模块名节点**:使用中文(`交互管理模块`、`物品数据模块`) - **时序图参与者**:UE5 类名缩写 + 中文别名(`IM as InteractionManager`) - **函数/方法**:保留 C++ 命名(`BeginInteract()`),不翻译 - **变量/属性**:使用 UE5 属性名(`bIsInteracting`、`MaxWalkSpeed`) ### 2.2 UE5 特有模式的表示 | UE5 概念 | Mermaid 表示 | 示例 | |----------|-------------|------| | Component 挂载 | 组合关系 `*--` | Character `*--` InteractionManager | | Interface 实现 | 实现关系 `..\|>` | InteractableComponent `..\|>` IChildHoodInteractable | | Delegate 广播 | 异步消息 `--)` | `OnItemCollected--)` CollectionManager | | Enhanced Input | 时序图入口 | `Player->>PC: 按 E 键 (IA_Interact)` | | DataAsset | 聚合关系 `o--` | Manager `o--` ConfigDataAsset | | Subsystem | 单例节点 | `UGameInstanceSubsystem` 作为独立节点 | ### 2.3 图表复杂度控制 - **功能领域图**:控制在 5-10 个模块节点。超过 10 个考虑拆分子图。 - **类设计图**:聚焦核心类(3-8 个)。辅助类(如 `FVector`、`FRotator` 等 UE 内置类型)不单独列出。 - **时序图**:单张控制在 15-25 条消息。超过 25 条按子流程拆分多张图。 - **流程图**:控制在 10-20 个节点。超过 20 个按子流程拆分。 --- ## 3. 复杂度判定启发式 ### 3.1 何时需要时序图(步骤④) 时序图为条件性步骤,仅在特性满足以下任一条件时需要绘制: | 条件 | 判定 | 示例 | |------|------|------| | 涉及 3+ 个系统协调 | 需要 | 拾取流程:InteractionManager → ItemManager → CollectionManager | | 有条件分支或循环流程 | 需要 | 交互流程:根据交互类型走不同子流程 | | 跨层级通信(UI ↔ 逻辑 ↔ 数据) | 需要 | 提示 UI 显示 → 检测逻辑 → 数据查询 | | 仅涉及单系统内部配置 | 不需要 | SpringArm 参数调整(纯配置) | | 仅 2 个系统简单调用 | 可选 | Character 设置 flag → Movement 检查 flag | ### 3.2 何时需要复杂接口描述(步骤⑥) 复杂接口描述为条件性步骤,仅在接口满足以下任一条件时需要: | 条件 | 判定 | 示例 | |------|------|------| | 5+ 个决策分支 | 需要 | `BeginInteract()`:状态检查 → 选中检查 → 类型分发 → 阶段管理 | | 协调多个子系统状态 | 需要 | 状态机转换:涉及移动状态、摄像机状态、UI 状态的切换 | | 有异步等待或回调链 | 需要 | 等待动画事件 → 触发后续逻辑 → 等待推镜完成 | | 纯数据查询或简单赋值 | 不需要 | `GetInteractableData()`:直接返回成员变量 | | 2-4 个分支的简单逻辑 | 可选 | `SetInteracting()`:设置 flag + 通知 UI | ### 3.3 项目实际案例参考 **需要时序图的特性**(从现有 `交互系统-技术方案.md` 提取): - 完整交互流程(Enter → AnimLock → Active → Exit) - 拾取流程(交互系统 → 物品系统 → 收集系统) **不需要时序图的特性**(从现有 `玩家控制器-技术方案.md` 提取): - SpringArm 参数配置(纯构造函数设置) - CMC 移动参数调整(纯配置) **需要复杂接口描述的接口**: - `UInteractionManager::BeginInteract()` — 状态检查 + 子阶段管理 + 摄像机推镜 + 动画等待 - `UInteractionManager::TickComponent()` — 检测更新 + 状态机驱动 + 推镜插值 + UI 更新 **不需要复杂接口描述的接口**: - `AChildHoodCharacter::DoMove()` — 直接调用 AddMovementInput - `AChildHoodCharacter::IsInteracting()` — 直接返回 bool