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

Mermaid 图表语法速查与项目约定

本文档为需求分析 skill 中各类图表的 Mermaid 语法参考和项目特定约定。

---

1. Mermaid 语法速查

1.1 功能领域图（步骤②）

使用 flowchart 展示功能模块及其交互关系。模块级抽象，不涉及类级别细节。

语法模板：

flowchart TD
    subgraph 输入层
        PlayerInput[玩家输入模块]
    end

    subgraph 核心层
        Movement[移动控制模块]
        Interaction[交互管理模块]
    end

    subgraph 数据层
        ItemData[物品数据模块]
        CollectionData[收集数据模块]
    end

    PlayerInput --> Movement
    PlayerInput --> Interaction
    Interaction -->|查询可交互物| ItemData
    Interaction -->|通知收集| CollectionData

要点：

• 使用 subgraph 划分模块边界（如输入层、核心层、数据层）
• 节点使用中文标签标注模块职责
• 边上可加 |文字| 说明交互类型
• 不同层可用 style 着色区分

样式区分（可选）：

flowchart TD
    A[模块A] --> B[模块B]
    A -.->|事件通知| C[模块C]

    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e9

• --> 实线：主数据流 / 同步调用
• -.-> 虚线：事件通知 / 异步通信

---

1.2 类设计图（步骤③）

使用 classDiagram 展示类的关键数据、接口和关系。

语法模板：

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 追踪复杂特性的跨系统调用流程。

语法模板：

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 描述复杂接口的决策分支和执行流程。

语法模板：

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