ChildHood/.claude/skills/requirements-analysis/references/examples.md

需求分析各步骤示例

本文档从项目现有技术设计文档中提取注释示例，展示每步分析的实际输出效果。

---

示例来源

示例	来源文档
交互系统	docs/technical/interaction-system-tech.md
角色控制	docs/technical/player-controller-tech.md
收集系统	docs/technical/collection-system-tech.md

---

1. 需求功能点罗列示例

以交互系统为例，展示如何从执行文档的行为规则中提取功能点并分类：

UE 内置功能

功能点	使用的 UE 内置能力	对应行为规则	备注
交互触发输入（E/ESC/Tab）	Enhanced Input (IA_Interact / IA_Cancel / IA_SwitchInteract)	I3 交互输入	通过 IMC 映射，无需自定义输入框架
摄像机推镜	SetViewTargetWithBlend + SpringArm	C1-C5 摄像机系统	推镜时切换 ViewTarget，回位时切回
移动输入屏蔽	CMC 移动组件 + bIsInteracting 标志	P1 交互中忽略移动	在 DoMove() 中检查标志即可
视角旋转限幅	PlayerCameraManager::ViewPitchMin/Max	C3 视角旋转	直接设置属性
摄像机碰撞	SpringArm::bDoCollisionTest	C4 摄像机碰撞	原生支持

自定义实现

功能点	实现方式概述	对应行为规则	预估复杂度
交互类型分发（观察/拾取/操作/对话）	枚举 EInteractType + switch 分发	交互类型系统	中
可交互物检测与选择	自定义 SphereComponent 碰撞检测 + 距离排序	检测与选择规则	中
交互状态机（Free/Interacting + 子阶段）	自定义 UActorComponent 管理状态	交互流程规则	高
交互提示 UI	自定义 UMG Widget	提示显示规则	低
叙事文本展示	自定义 UMG Widget + 文本列表随机选取	文本展示规则	低

---

2. 功能领域图示例

以交互系统为例，展示模块级的功能领域图：

flowchart TD
    subgraph 玩家侧
        Input[输入处理模块]
        CharState[角色状态模块]
    end

    subgraph 交互核心
        Detection[检测与选择模块]
        StateMachine[交互状态机模块]
        CameraCtrl[摄像机控制模块]
    end

    subgraph 可交互物侧
        InteractableData[交互物数据模块]
        Trigger[触发区域模块]
    end

    subgraph 表现层
        PromptUI[提示 UI 模块]
        TextUI[叙事文本 UI 模块]
    end

    subgraph 下游系统
        ItemSys[物品系统]
        CollectionSys[收集系统]
    end

    Input -->|E/ESC/Tab| StateMachine
    Detection -->|可交互物列表| StateMachine
    StateMachine -->|锁定/解锁| CharState
    StateMachine -->|推镜/回位| CameraCtrl
    StateMachine -->|显示/隐藏| PromptUI
    StateMachine -->|显示文本| TextUI
    StateMachine -.->|拾取通知| ItemSys
    ItemSys -.->|收集通知| CollectionSys
    Trigger -->|进入/离开| Detection
    InteractableData -->|交互数据| Detection

模块职责说明

模块	职责	关键输入	关键输出
输入处理模块	接收玩家按键，转发给状态机	Enhanced Input IA 回调	BeginInteract / Cancel / Switch
检测与选择模块	维护附近可交互物列表，选择最近的	SphereComponent 碰撞事件	NearbyInteractables 列表
交互状态机模块	管理交互全流程状态转换	玩家输入 + 检测结果 + 动画事件	状态转换 + 驱动其他模块
摄像机控制模块	交互中推镜和回位	状态机阶段信号	ViewTarget 切换
交互物数据模块	存储单个可交互物的配置数据	配置文件	FInteractableData
触发区域模块	检测玩家进入/离开交互范围	SphereComponent 碰撞	注册/注销检测列表
提示 UI 模块	显示 [E] 查看旧冰箱 格式的提示	选中状态变化	视觉提示
叙事文本 UI 模块	显示半透明背景 + 文字的叙事内容	交互完成信号	文本展示 + 淡出

---

3. 类设计图示例

以交互系统为例，将功能领域图细化为类设计：

classDiagram
    class AChildHoodCharacter {
        -UInteractionManager* InteractionManager
        -UItemManager* ItemManager
        -UCollectionManager* CollectionManager
        -bool bIsInteracting
        +SetInteracting(bool bValue) void
        +IsInteracting() bool
        +DoMove(float Right, float Forward) void
    }

    class AChildHoodPlayerController {
        +SetupPlayerInputComponent() void
    }

    class UInteractionManager {
        -EInteractionState State
        -EInteractPhase Phase
        -TArray~UInteractableComponent*~ NearbyInteractables
        -int32 SelectedIndex
        -UInteractableComponent* CurrentInteractable
        +BeginInteract() void
        +CancelInteract() void
        +SwitchTarget(int32 Direction) void
        #OnDetectionEnter(UPrimitiveComponent*) void
        #OnDetectionExit(UPrimitiveComponent*) void
    }

    class IChildHoodInteractable {
        <<interface>>
        +GetInteractableData() FInteractableData
        +OnInteract(AChildHoodCharacter*) void
    }

    class UInteractableComponent {
        -FInteractableData Data
        -USphereComponent* DetectionSphere
        +GetInteractableData() FInteractableData
        +OnInteract(AChildHoodCharacter*) void
    }

    class FInteractableData {
        +FName ItemId
        +FString DisplayName
        +EInteractType Type
        +float TriggerRadius
        +bool bOneShot
        +FString InteractVerb
        +TArray~FString~ NarrativeTexts
        +bool bUseCameraPush
        +EPostAction PostAction
    }

    AChildHoodCharacter *-- UInteractionManager : 组合（持有）
    AChildHoodCharacter --> AChildHoodPlayerController : 关联
    UInteractionManager --> UInteractableComponent : 检测并驱动
    UInteractableComponent ..|> IChildHoodInteractable : 实现
    UInteractableComponent *-- FInteractableData : 组合（内含）
    UInteractableComponent o-- USphereComponent : 聚合（引用）

---

4. 时序图示例

以交互系统拾取流程为例，展示复杂特性的时序图：

sequenceDiagram
    autonumber
    participant Player as 玩家
    participant PC as PlayerController
    participant IM as InteractionManager
    participant IC as InteractableComponent
    participant Char as Character
    participant ItemMgr as ItemManager
    participant CollMgr as CollectionManager

    Player->>PC: 按 E 键 (IA_Interact)
    activate PC
    PC->>IM: BeginInteract()
    deactivate PC

    activate IM
    IM->>IM: 检查 State == Free
    IM->>IM: State = Interacting, Phase = Enter

    IM->>Char: SetInteracting(true)
    IM->>IM: 执行角色转向 + 摄像机推镜

    Note over IM: Phase: Enter → AnimLock/Active

    IM->>IC: OnInteract(Character)
    activate IC
    IC->>IC: 检查 Type == Pickup

    IC->>ItemMgr: OnItemPickedUp(ItemId, Category)
    activate ItemMgr
    ItemMgr-->>IC: 处理完成
    deactivate ItemMgr

    ItemMgr--)CollMgr: OnItemCollectedEvent(ItemId, Category)
    activate CollMgr
    CollMgr->>CollMgr: 判重 → 记录 → 弹通知
    deactivate CollMgr

    IC-->>IM: 交互完成
    deactivate IC

    IM->>IM: Phase = Exit (回位 + 淡出)
    IM->>Char: SetInteracting(false)
    IM->>IM: State = Free
    deactivate IM

---

5. 核心数据结构示例

以交互系统的 FInteractableData 为例，展示良好的数据结构文档：

// 交互类型
UENUM(BlueprintType)
enum class EInteractType : uint8
{
    Examine,  // 观察
    Pickup,   // 拾取
    Operate,  // 操作
    Talk      // 对话
};

// 交互系统顶层状态
UENUM(BlueprintType)
enum class EInteractionState : uint8
{
    Free,        // 自由状态
    Interacting, // 交互中
};

// Interacting 子阶段
UENUM(BlueprintType)
enum class EInteractPhase : uint8
{
    None,
    Enter,     // 进入：转向 + 推镜
    AnimLock,  // 动画锁定：等待动画播完
    Active,    // 活跃：等待玩家输入
    Exit       // 退出：回位 + 淡出
};

// 可交互物配置数据
USTRUCT(BlueprintType)
struct FInteractableData
{
    GENERATED_BODY()

    // 基本信息
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FName ItemId;                    // 物品唯一ID（如 "fridge_home"）

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FString DisplayName;             // 显示名称（如 "旧冰箱"）

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    EInteractType Type = EInteractType::Examine;

    // 触发
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    float TriggerRadius = 150.0f;    // 触发半径（cm）

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    bool bOneShot = false;           // 一次性消耗

    // 提示文本
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FString InteractVerb;            // 动作词（如 "查看"、"拾取"）

    // 叙事文本
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    TArray<FString> NarrativeTexts;  // 文本列表，随机选取

    // 摄像机推镜
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    bool bUseCameraPush = false;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    float CameraPushDistance = 100.0f;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    float CameraPushDuration = 0.5f;

    // 结束动作
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    EPostAction PostAction = EPostAction::Return;
};

要点：

• 使用 UPROPERTY 标记所有需要暴露给蓝图的属性
• 每个属性都有中文注释说明用途
• 提供合理的默认值
• UE5 类型前缀规范：E 枚举、F 结构体

---

6. 复杂接口描述示例

以交互系统 BeginInteract() 为例，展示如何用流程图描述复杂接口：

流程图示例

flowchart TD
    Start([BeginInteract 被调用]) --> CheckState{State == Free?}
    CheckState -->|否| Reject1([返回：已在交互中])

    CheckState -->|是| CheckSelected{SelectedInteractable 有效?}
    CheckSelected -->|否| Reject2([返回：无选中目标])

    CheckSelected -->|是| SetState[State = Interacting<br/>Phase = Enter]
    SetState --> LockInput[Character.SetInteracting true<br/>屏蔽移动输入]
    LockInput --> Turn[角色转向目标<br/>插值旋转]

    Turn --> PushCam{需要推镜?}
    PushCam -->|是| DoPush[摄像机推镜<br/>SetViewTargetWithBlend]
    PushCam -->|否| CheckAnim
    DoPush --> CheckAnim{需要等待动画?}

    CheckAnim -->|是| AnimLock[Phase = AnimLock<br/>等待 AnimNotify]
    CheckAnim -->|否| Active[Phase = Active]

    AnimLock -->|AnimNotify 触发| Active
    Active --> ExecuteType[根据 InteractType 分发]

    ExecuteType -->|Examine| ShowText[显示叙事文本<br/>Phase = Exit]
    ExecuteType -->|Pickup| DoPickup[通知 ItemManager<br/>Phase = Exit]
    ExecuteType -->|Operate| DoOperate[执行操作逻辑<br/>Phase = Exit]
    ExecuteType -->|Talk| DoTalk[进入对话<br/>Phase = Exit]

伪代码示例

以收集系统 OnItemReceived() 为例，展示伪代码风格：

function OnItemReceived(ItemId, Category, Number):
    前置检查:
    1. Category != TargetCategory → 忽略（不是追踪品类）
    2. CollectedIDs.Contains(ItemId) → 忽略（已收集过）

    核心逻辑:
    3. CollectedIDs.Add(ItemId) → 记录收集
    4. Progress++ → 更新计数
    5. 延迟 NotificationDelay 后:
       - 创建 WBP_CollectionNotification
       - 显示 "发现了新的杂物，进度 X/Y"
    6. 更新 WBP_CollectionProgress → 弹性动画

    完成判定:
    7. if Progress >= TotalCount AND NOT bIsComplete:
       - bIsComplete = true
       - 延迟后: 进度 UI 变金色 + 弹出完成提示

要点：

• 先做前置检查（快速失败）
• 核心逻辑按顺序执行
• 异步操作（延迟、动画）明确标注
• 完成判定/边界情况放在最后