P-018 v0.1 交互系统 — PersistenceSubsystem 命名/语义修正（交互物消耗状态） #43

New Issue

2026-06-17T00:04:32+08:00

Ghost commented

2026-06-17 00:04:32 +08:00

任务信息

任务ID: P-018
所属版本: v0.1
角色: 程序
流水线步骤: ⑥ 程序实现（技术债务清理）
依赖: 无硬依赖（P-012 交互系统实现已交付该文件）
下游: #42 P-017 交互物配置依赖本任务（已设置 block，避免返工）

背景

UPersistenceSubsystem（Source/ChildHood/Interaction/PersistenceSubsystem.h/.cpp）中存在命名/语义误导问题：

CollectedItemIDs 及其方法 IsItemCollected / MarkItemCollected 的真实语义是"交互物消耗状态"，用于配合 InteractableComponent 的 bOneShot（一次性交互物）字段，记录某交互物是否已被触发消耗、防止重复交互。它与收集系统（Collection，CollectionCollectedIDs / GetCollectionState / SetCollectionState）是两套完全独立的数据，名字却都含 "Collected/收集"，极易混淆。

调用点确认：仅 InteractableComponent.cpp 两处 C++ 调用（:102 MarkItemCollected、:128 IsItemCollected）。

更糟的是文件内注释自相矛盾——既承认又否认：

.h:28 分组标题 === 物品消耗状态 === ✅ 正确
.h:55-56 区分注释「CollectedItemIDs 记录交互物消耗状态」✅ 正确
.h:18 类头注释「CollectedItemIDs: 已收集物品 ID 集合」❌ 误导
.h:30,34,68 方法/成员注释「物品是否已被收集/标记为已收集」❌ 误导
.cpp:18 日志「物品已收集」❌ 误导

引入真正 Collection 系统时已意识到此混淆（故加了 :55 区分注释），但未彻底改掉旧命名，留下半改的烂摊子。

预期产出

1. 语义重命名（建议命名，可按技术方案术语微调）

将"物品收集"语义统一改为"交互物消耗"语义：

旧	建议	说明
`CollectedItemIDs` (UPROPERTY)	`ConsumedInteractableIDs`	已消耗交互物 ID 集合
`IsItemCollected(ItemId)`	`IsInteractableConsumed(InteractableId)`	查询是否已消耗
`MarkItemCollected(ItemId)`	`MarkInteractableConsumed(InteractableId)`	标记已消耗
参数名 `ItemId`	`InteractableId`	语义对齐

命名最终由程序定夺，但必须与 Collection 系统的 CollectionCollectedIDs 明确区分，避免 "Collected" 歧义。

2. 同步修正误导注释/日志

.h:18 类头注释：CollectedItemIDs: 已收集物品 ID 集合 → 反映消耗语义
.h:30,34 方法注释：「物品是否已被收集/标记为已收集」→ 改为消耗语义
.h:68 成员注释：「已收集物品 ID 集合」→ 改为消耗语义
.cpp:7 分组标题保留「物品消耗状态」（已正确）
.cpp:18 日志「物品已收集」→ 改为「交互物已消耗」
.h:54-56 那段区分注释：重命名后两套数据名字已不冲突，可简化或删除冗余说明

3. 调用点同步更新

InteractableComponent.cpp:102, :128 两处调用同步改为新方法名。

关联风险（执行前必须确认）

蓝图调用确认：IsItemCollected / MarkItemCollected 是 UFUNCTION(BlueprintCallable)，grep 仅显示 C++ 调用。需确认是否有蓝图节点调用（蓝图调用不在 C++ grep 范围）。若有，需同步更新蓝图。
序列化兼容确认：CollectedItemIDs 是 UPROPERTY()。需确认该字段是否参与存档序列化（SaveGame）。从当前代码看 UPersistenceSubsystem 为纯内存 GameInstanceSubsystem 持有，未见 USaveGame/序列化标记，但需程序最终确认——若有序列化，重命名字段需考虑旧存档兼容（或确认 v0.1 无需兼容旧存档）。

验收标准

命名重命名完成，全工程无残留旧名 CollectedItemIDs / IsItemCollected / MarkItemCollected
所有注释、日志与真实语义一致，文件内无自相矛盾描述
蓝图调用（若有）已同步
编译通过（UE5.7），运行后一次性交互物（bOneShot）仍能正确防止重复触发
收集系统（Collection）功能不受影响

## 任务信息 - **任务ID**: P-018 - **所属版本**: v0.1 - **角色**: 程序 - **流水线步骤**: ⑥ 程序实现（技术债务清理） - **依赖**: 无硬依赖（P-012 交互系统实现已交付该文件） - **下游**: #42 P-017 交互物配置依赖本任务（已设置 block，避免返工） ## 背景 `UPersistenceSubsystem`（Source/ChildHood/Interaction/PersistenceSubsystem.h/.cpp）中存在命名/语义误导问题： `CollectedItemIDs` 及其方法 `IsItemCollected` / `MarkItemCollected` 的**真实语义是"交互物消耗状态"**，用于配合 `InteractableComponent` 的 `bOneShot`（一次性交互物）字段，记录某交互物是否已被触发消耗、防止重复交互。它与收集系统（Collection，`CollectionCollectedIDs` / `GetCollectionState` / `SetCollectionState`）是**两套完全独立的数据**，名字却都含 "Collected/收集"，极易混淆。调用点确认：仅 `InteractableComponent.cpp` 两处 C++ 调用（:102 MarkItemCollected、:128 IsItemCollected）。更糟的是文件内注释自相矛盾——既承认又否认： - `.h:28` 分组标题 `=== 物品消耗状态 ===` ✅ 正确 - `.h:55-56` 区分注释「CollectedItemIDs 记录交互物消耗状态」✅ 正确 - `.h:18` 类头注释「CollectedItemIDs: 已收集物品 ID 集合」❌ 误导 - `.h:30,34,68` 方法/成员注释「物品是否已被收集/标记为已收集」❌ 误导 - `.cpp:18` 日志「物品已收集」❌ 误导引入真正 Collection 系统时已意识到此混淆（故加了 :55 区分注释），但未彻底改掉旧命名，留下半改的烂摊子。 ## 预期产出 ### 1. 语义重命名（建议命名，可按技术方案术语微调）将"物品收集"语义统一改为"交互物消耗"语义： | 旧 | 建议 | 说明 | |----|------|------| | `CollectedItemIDs` (UPROPERTY) | `ConsumedInteractableIDs` | 已消耗交互物 ID 集合 | | `IsItemCollected(ItemId)` | `IsInteractableConsumed(InteractableId)` | 查询是否已消耗 | | `MarkItemCollected(ItemId)` | `MarkInteractableConsumed(InteractableId)` | 标记已消耗 | | 参数名 `ItemId` | `InteractableId` | 语义对齐 | 命名最终由程序定夺，但必须与 Collection 系统的 `CollectionCollectedIDs` 明确区分，避免 "Collected" 歧义。 ### 2. 同步修正误导注释/日志 - `.h:18` 类头注释：`CollectedItemIDs: 已收集物品 ID 集合` → 反映消耗语义 - `.h:30,34` 方法注释：「物品是否已被收集/标记为已收集」→ 改为消耗语义 - `.h:68` 成员注释：「已收集物品 ID 集合」→ 改为消耗语义 - `.cpp:7` 分组标题保留「物品消耗状态」（已正确） - `.cpp:18` 日志「物品已收集」→ 改为「交互物已消耗」 - `.h:54-56` 那段区分注释：重命名后两套数据名字已不冲突，可简化或删除冗余说明 ### 3. 调用点同步更新 `InteractableComponent.cpp:102, :128` 两处调用同步改为新方法名。 ## 关联风险（执行前必须确认） 1. **蓝图调用确认**：`IsItemCollected` / `MarkItemCollected` 是 `UFUNCTION(BlueprintCallable)`，grep 仅显示 C++ 调用。需确认是否有蓝图节点调用（蓝图调用不在 C++ grep 范围）。若有，需同步更新蓝图。 2. **序列化兼容确认**：`CollectedItemIDs` 是 `UPROPERTY()`。需确认该字段是否参与存档序列化（SaveGame）。从当前代码看 `UPersistenceSubsystem` 为纯内存 GameInstanceSubsystem 持有，未见 USaveGame/序列化标记，但需程序最终确认——若有序列化，重命名字段需考虑旧存档兼容（或确认 v0.1 无需兼容旧存档）。 ## 验收标准 - [ ] 命名重命名完成，全工程无残留旧名 `CollectedItemIDs` / `IsItemCollected` / `MarkItemCollected` - [ ] 所有注释、日志与真实语义一致，文件内无自相矛盾描述 - [ ] 蓝图调用（若有）已同步 - [ ] 编译通过（UE5.7），运行后一次性交互物（bOneShot）仍能正确防止重复触发 - [ ] 收集系统（Collection）功能不受影响

Ghost added this to the v0.1-基础交互 milestone 2026-06-17 00:04:33 +08:00

Ghost added the status:ready pipeline:6-impl role:dev stage:iteration labels 2026-06-17 00:04:33 +08:00

Ghost added a new dependency 2026-06-17 00:05:05 +08:00

#42 P-017 v0.1 交互系统 — ⑥交互物放置与Effect数据配置

Ghost added status:in-progress and removed status:ready labels 2026-06-17 18:09:29 +08:00

Ghost added status:in-review and removed status:in-progress labels 2026-06-17 18:13:44 +08:00

Ghost added review:pass and removed status:in-review labels 2026-06-17 18:18:04 +08:00

Ghost closed this issue

2026-06-17 18:35:09 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Blocks

#42 P-017 v0.1 交互系统 — ⑥交互物放置与Effect数据配置

starmen1265/ChildHood

Reference: starmen1265/ChildHood#43