ChildHood/.claude/skills/requirements-analysis/references/diagram-guide.md

# 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 {
        <<interface>>
        +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<br/>Phase = Enter]
    CheckSelected -->|否| Reject2([返回：无可交互物])

    SetState --> TurnAndPush[执行角色转向<br/>执行摄像机推镜]
    TurnAndPush --> CheckAnim{需要等待动画?}
    CheckAnim -->|是| AnimLock[Phase = AnimLock<br/>等待动画事件]
    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