[docs][refactor]: 将旧 01~06 中文教程合并整理为 modules/frameworks 文件夹结构

- 删除 01~05 旧中文教程目录 - 将 03 核心功能教程拆分为各 framework 模块的子文档 - 06 工具脚本移入 modules/frameworks/编辑器工具/UI工具/ - 非框架内容合并进 rules/20-开发规则.md 与 rules/40-工作流清单.md - 更新所有交叉链接与文档关联表 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-07 18:36:15 +08:00
parent 5e5b9f8c80
commit ee1ff7f444
77 changed files with 6263 additions and 1133 deletions
--- a/business-reference/playballoons/features/GM调试.md
+++ b/business-reference/playballoons/features/GM调试.md
@@ -0,0 +1,134 @@
+# GM/调试功能
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录 GM 面板、调试请求、测试入口和开发验证流程。
+
+## 已知线索
+
+- UI 路径：`Assets/Game/GameHFScripte/GameFunction/UIWindows/GMWindow/`
+- 背包数据：`GMWindow_BagData.cs`
+- 请求配置：`GMWindow_GM.cs`
+- 能看到背包、战斗、商店等调试请求线索。
+
+## 已确认内容
+
+窗口定义：
+
+```text
+GMWindow : AbsHFUIWindow
+  -> [HFAssetBundlePath(..., "UIWindows/GMWindow/GMWindow.prefab")]
+  -> [HFUIWindowLayer(UIWindow, Popup)]
+```
+
+生命周期：
+
+```text
+GMWindow.OnRunAwake()
+  -> OnRunAwake_BagData()
+  -> OnRunAwake_GM()
+
+GMWindow.OnOpen()
+  -> OnOpen_BagData()
+  -> OnOpen_GM()
+
+GMWindow.OnClose()
+  -> OnClose_BagData()
+  -> OnClose_GM()
+```
+
+GM 请求结构：
+
+```text
+GM_Network_MsgId
+  -> msgId : Network_MsgId
+  -> tip
+  -> args : List<GM_Network_MsgId_Arg>
+
+GM_Network_MsgId_Arg
+  -> tip
+  -> contentType
+  -> value
+```
+
+发送链路：
+
+```text
+点击 btnSendGM
+  -> OnSendGM()
+  -> new GMC2S()
+  -> gmC2S.Msgid = (int)selected.msgId
+  -> gmC2S.Args.AddRange(...)
+  -> HFSeverManager.Instance.SendMsg(gmC2S)
+```
+
+当前 GM 覆盖范围：
+
+- 背包：
+  - 请求背包数据：`GetBagItem`
+  - 添加道具：`PlayerResourceChange`
+- 关卡：
+  - `BattleLevelEnter`
+  - `BattleLevelExit`
+  - `BattleLevelWin`
+  - `BattleLevelFail`
+- 用户外围数据：
+  - 设置关卡完成波数：`SetUserRolePeripheryLevelWaveProgress`
+  - 领取用户关卡进度奖励：`UserRolePeripheryClaimedProgressReward1Reward`
+- 时间：
+  - `GetServerTimeStamp`
+- 宝箱：
+  - 添加用户宝箱：`AddUserRolePeripheryTreasureChest`
+  - 删除用户宝箱：`DelUserRolePeripheryTreasureChest`
+  - 获取/开启/领取/结束冷却相关操作存在注释。
+- 商店：
+  - `SetDailyFeaturedTotalRefreshCount` 使用硬编码 `(Network_MsgId)7090`。
+- Tower：
+  - 上阵、下阵、升级、添加 Tower 的 GM 配置块存在，但全部注释。
+
+当前接入状态：
+
+- GMWindow 本身是完整 UI 窗口。
+- GM 请求通过统一 `GMC2S` 包装真实业务 `Network_MsgId` 和参数。
+- 未看到明显的开发环境开关；MainWindow 中 GM 按钮也有编辑器开关注释，当前入口是否开放待确认。
+
+## 梳理任务
+
+- [ ] 梳理 GMWindow 打开入口。
+- [x] 梳理 GM 请求结构和参数配置。
+- [x] 梳理 GM 对背包、PVE、商店等功能的覆盖范围。
+- [ ] 梳理 GM 功能是否只在开发环境启用。
+- [x] 梳理 GM 请求和网络框架的关系。
+
+## 待确认
+
+- GMWindow 的正式打开入口待确认。
+- 是否有权限/环境开关待确认。
+- 是否允许线上包保留 GM 面板待确认。
+- GM 操作通过服务器 GM 协议，有修改服务器数据的能力风险，需要上线前明确禁用策略。
+
+## 相关框架
+
+- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md)
+- [网络框架](../../../modules/frameworks/网络系统.md)
+- [事件框架](../../../modules/frameworks/事件系统/README.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/frameworks/事件系统/README.md](../../../modules/frameworks/事件系统/README.md) | 事件框架 |
+| [modules/frameworks/网络系统.md](../../../modules/frameworks/网络系统.md) | 网络框架 |
+| [modules/frameworks/UI窗口系统/README.md](../../../modules/frameworks/UI窗口系统/README.md) | UI 框架 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
+| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 |
--- a/business-reference/playballoons/features/PVE关卡战斗.md
+++ b/business-reference/playballoons/features/PVE关卡战斗.md
@@ -0,0 +1,94 @@
+# PVE/关卡战斗
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录 PVE 关卡进入、战斗流程、胜负结算、波次和奖励逻辑。
+
+## 已知线索
+
+- 逻辑路径：`Assets/Game/GameHFScripte/GameFunction/Logic/GameScenes/`
+- 地图路径：`Assets/Game/GameHFScripte/GameFunction/Logic/MapManager/`
+- 伤害路径：`Assets/Game/GameHFScripte/GameFunction/Logic/DamageManager/`
+- 地图资源：`Assets/Game/GameHFResource/CN/Map/`
+- 网络消息线索：`BattleLevelEnter`、`BattleLevelExit`、`BattleLevelWin`、`BattleLevelFail`
+- 配置线索：`XLSX_SRC/CN/Wave.xlsx`
+
+## 已确认内容
+
+当前 PVE/关卡战斗处于“有核心框架和协议线索，但主流程接入不完整或待确认”的状态。
+
+已确认的子系统：
+
+- `HFWaveManager`：从 `HFFunCatalogue.NDB.ds_WaveD0D9AA20TableData.ReadTableList()` 读取波次配置。
+- `WaveInfo`：根据 `WaveTime`、`WaveID`、`WaveHpInc`、`GateFirst` 生成波次信息。
+- `CreateMonsterInfo`：解析 `start_end_delay_monsterId_count` 格式的发怪配置。
+- `HFMapManager.CreateMap(levelid, finish)`：当前会先 `ClearMap()`，再通过 `HFFunCatalogue.Asset.LoadAsset(1501, ...)` 加载地图 prefab。
+- `HFDamageManager`：存在伤害计算、掉落、死亡事件、HUD 飘字逻辑，但大部分实现当前被注释。
+- 网络协议和事件已生成：`BattleLevelEnter`、`BattleLevelExit`、`BattleLevelWin`、`BattleLevelFail`。
+
+`HFWaveManager` 当前有 Editor GUI 调试入口：
+
+```text
+OnRunGUI
+  -> 按钮“游戏开始”
+  -> InitCampWaveInfo(Red/Blue)
+  -> TryCreateMonster
+```
+
+`OnRunFixedUpdate` 每秒尝试发怪：
+
+```text
+OnRunFixedUpdate
+  -> TryCreateMonster
+  -> CampWaveInfo.TryCreateMonster
+  -> WaveInfo.TryCreateMonster
+  -> CreateMonsterInfo.TryCreateMonster
+```
+
+## 梳理任务
+
+- [ ] 找到 PVE 入口：从主界面、地图或 GM 进入关卡的调用点。
+- [ ] 梳理关卡状态：进入、战斗中、胜利、失败、退出。
+- [x] 梳理波次配置和怪物/实体生成关系。
+- [x] 梳理伤害计算和实体框架之间的关系。
+- [ ] 梳理结算奖励如何进入背包和奖励展示。
+- [x] 梳理 PVE 相关网络消息和事件。
+
+## 待确认
+
+- 是否有明确的 PVE manager。
+- 战斗是纯本地模拟、服务器校验，还是服务器主导。
+- `GameScenes`、`MapManager`、`LineManager` 在 PVE 中的边界。
+- `HFMapManager.CreateMap` 的 `levelid` 当前未用于读表，资源 id 固定为 `1501`，是否临时逻辑待确认。
+- `HFWaveManager` 是否只通过 Editor GUI 调试启动，还是存在运行时入口待确认。
+- `HFDamageManager` 大量逻辑被注释，当前战斗伤害是否启用待确认。
+
+## 相关框架
+
+- [实体框架](../../../modules/frameworks/实体系统/README.md)
+- [场景框架](../../../modules/frameworks/场景系统.md)
+- [网络框架](../../../modules/frameworks/网络系统.md)
+- [事件框架](../../../modules/frameworks/事件系统/README.md)
+- [数据/配置框架](../../../modules/frameworks/数据配置框架.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/frameworks/数据配置框架.md](../../../modules/frameworks/数据配置框架.md) | 数据/配置框架 |
+| [modules/frameworks/实体系统/README.md](../../../modules/frameworks/实体系统/README.md) | 实体框架 |
+| [modules/frameworks/事件系统/README.md](../../../modules/frameworks/事件系统/README.md) | 事件框架 |
+| [modules/frameworks/网络系统.md](../../../modules/frameworks/网络系统.md) | 网络框架 |
+| [modules/frameworks/场景系统.md](../../../modules/frameworks/场景系统.md) | 场景框架 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
+| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 |
--- a/business-reference/playballoons/features/PVP.md
+++ b/business-reference/playballoons/features/PVP.md
@@ -0,0 +1,80 @@
+# PVP
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录 PVP 是否存在、入口、协议、匹配、战斗和结算流程。
+
+## 已知线索
+
+- 当前未在初步扫描中发现明确的 PVP 目录或关键词。
+
+## 已确认内容
+
+已搜索关键词：
+
+- `PVP`
+- `PvP`
+- `pvp`
+- `Arena`
+- `Rank`
+- `Duel`
+- `竞技`
+- `排行`
+- `匹配`
+
+搜索范围：
+
+- `Assets/Game/GameHFScripte/`
+- `Assets/AutoBuildScript/`
+- `XLSX_SRC/`
+- `Assets/Editor/XLSX_SRC/`
+
+结果：
+
+- 未发现明确 PVP / 竞技场 / 排行 / 匹配业务代码。
+- 未发现 PVP 相关 UIWindow。
+- 未发现 PVP 相关配置表。
+- 未发现 PVP 相关 protobuf 消息。
+- 搜到的“匹配”均为正则匹配工具注释，不属于业务功能。
+
+当前判断：
+
+- 当前工程未发现 PVP 实现。
+- 该模块目前只作为规划/占位模块保留。
+
+## 梳理任务
+
+- [x] 全局搜索 PVP、Arena、Match、Rank、Opponent 等关键词。
+- [x] 检查 protobuf 是否有 PVP/匹配/排行相关消息。
+- [x] 检查配置表是否有 PVP、竞技场或排行配置。
+- [x] 检查 UIWindows 是否有隐藏或未接入的 PVP 窗口。
+- [ ] 确认项目当前是否规划 PVP。
+
+## 待确认
+
+- 是否产品规划中存在 PVP。
+- 如果短期不做，可以从模块索引移除，或保持为“规划占位”。
+
+## 相关框架
+
+- [网络框架](../../../modules/frameworks/网络系统.md)
+- [PVE/关卡战斗](PVE关卡战斗.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/features/PVE关卡战斗.md](PVE关卡战斗.md) | PVE/关卡战斗 |
+| [modules/frameworks/网络系统.md](../../../modules/frameworks/网络系统.md) | 网络框架 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
+| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 |
--- a/business-reference/playballoons/features/商店.md
+++ b/business-reference/playballoons/features/商店.md
@@ -0,0 +1,128 @@
+# 商店
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录商店商品、购买、货币消耗、体力/资源购买和商店 UI 入口。
+
+## 已知线索
+
+- GM 线索：`Assets/Game/GameHFScripte/GameFunction/UIWindows/GMWindow/GMWindow_GM.cs` 中有商店模块注释。
+- Tips 线索：`Tips_GetPower` 引用 `ShopGoodsInfo`。
+- 图集线索：`SpriteAtlasAssets/Shop`
+- 代码中可见 `ShopWindow`、`ShopGetCurrency` 注释引用。
+
+## 已确认内容
+
+协议和数据结构已生成：
+
+- `Network_MsgId.GetShop = 2500`
+- `Network_MsgId.ShopBuy = 2501`
+- `Network_MsgId.ShopRefresh = 2502`
+- `HFEvent_STC_GetShopS2C`
+- `HFEvent_STC_ShopBuyS2C`
+- `HFEvent_STC_ShopRefreshS2C`
+
+请求/响应字段：
+
+```text
+GetShopC2S
+  -> ShopId
+GetShopS2C
+  -> repeated ShopInfo
+
+ShopBuyC2S
+  -> GoodsId
+  -> BuyType
+ShopBuyS2C
+  -> ShopId
+  -> Goods
+  -> Item
+
+ShopRefreshC2S
+  -> ShopId
+  -> RefreshType
+ShopRefreshS2C
+  -> Shop
+```
+
+核心数据结构在：
+
+- `Assets/Game/GameHFScripte/CopyToHF/Network/Player.cs`
+- `Assets/Game/GameHFScripte/CopyToHF/Network/Common.cs`
+
+```text
+ShopInfo
+  -> ShopId
+  -> RefreshInfo : Map<int, ShopRefreshInfo>
+  -> Goods : Map<int, ShopGoodsInfo>
+
+ShopGoodsInfo
+  -> GoodsId
+  -> BuyNum : Map<int, GoodsBuyNumInfo>
+  -> Item
+
+ShopRefreshInfo
+  -> RefreshType
+  -> RefreshNum
+
+GoodsBuyNumInfo
+  -> BuyType
+  -> BuyNum
+```
+
+体力购买相关：
+
+- `Tips_GetPower` 是当前能看到的体力购买/领取 UI 线索。
+- `Tips_GetPower` 读取 `Constants.PurchaseStamina`。
+- `Tips_GetPower` 监听 `HFEvent_BagItemUpdate` 刷新展示。
+- `Stamina_QueryC2S` / `Stamina_GetC2S` 协议已生成，但当前未看到实际发送点。
+
+当前接入状态：
+
+- `MainWindow` 中 `OpenWindow<ShopWindow>`、`ShopGetCurrency`、`Tips_GetPower` 入口大多处于注释状态。
+- 未发现 `GetShopC2S`、`ShopBuyC2S`、`ShopRefreshC2S` 在业务代码中的实际发送点。
+- 未发现独立商店 manager。
+- 因此当前判断：商店协议和部分 UI/资源痕迹存在，但客户端业务主流程未完整接入或处于注释/待开发状态。
+
+## 梳理任务
+
+- [x] 查找是否存在独立商店 manager、window 或配置表。
+- [x] 梳理商品数据结构和 `ShopGoodsInfo` 来源。
+- [ ] 梳理购买流程：打开、选择、校验、扣费、到账。
+- [x] 梳理商店与背包、资源、体力之间的关系。
+- [x] 确认当前商店功能是完整实现、部分接入还是已注释/待开发。
+
+## 待确认
+
+- 是否存在未纳入当前工程的 `ShopWindow`、`ShopGetCurrency` 或旧分支代码。
+- 是否存在 `Shop.xlsx`、`Goods.xlsx`、`DailyDeals.xlsx` 等相关配置；当前配置列表未登记这些表，但生成代码里有旧表痕迹。
+- 商店是否区分普通商店、体力购买、礼包、广告等类型。
+- 商店 UI 当前看起来未接入，需要后续确认是否是产品阶段未启用。
+
+## 相关框架
+
+- [背包](背包.md)
+- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md)
+- [网络框架](../../../modules/frameworks/网络系统.md)
+- [数据/配置框架](../../../modules/frameworks/数据配置框架.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/features/背包.md](背包.md) | 背包 |
+| [modules/frameworks/数据配置框架.md](../../../modules/frameworks/数据配置框架.md) | 数据/配置框架 |
+| [modules/frameworks/网络系统.md](../../../modules/frameworks/网络系统.md) | 网络框架 |
+| [modules/frameworks/UI窗口系统/README.md](../../../modules/frameworks/UI窗口系统/README.md) | UI 框架 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
+| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 |
--- a/business-reference/playballoons/features/地图进度.md
+++ b/business-reference/playballoons/features/地图进度.md
@@ -0,0 +1,148 @@
+# 地图/关卡进度
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录地图、关卡、波次、进度奖励和关卡状态。
+
+## 已知线索
+
+- 地图逻辑：`Assets/Game/GameHFScripte/GameFunction/Logic/MapManager/`
+- 关卡资源：`Assets/Game/GameHFResource/CN/Map/Level.prefab`
+- 配置线索：`XLSX_SRC/CN/Wave.xlsx`
+- 网络线索：`UserRolePeripheryProgressReward*`
+
+## 已确认内容
+
+地图加载：
+
+```text
+HFMapManager.CreateMap(levelid, finish)
+  -> ClearMap()
+  -> HFFunCatalogue.Asset.LoadAsset(1501)
+  -> GetOrAddComponent<HFM_DLevelSetting>()
+  -> OnSetFinishLoad()
+```
+
+当前 `CreateMap` 传入了 `levelid`，但实际读取关卡配置的代码被注释：
+
+```text
+// MapInfo = HFFunCatalogue.NDB.ds_Level83D033B2TableData.ReadTableByPK(levelid);
+```
+
+地图配置数据：
+
+- `stMapInfo` 使用 `MemoryPack`，包含障碍物/实体位置列表 `ObstaclesPos`。
+- `stMapEntityInfo` 包含 `Postion`、`EntityId`、`CellIndexs`。
+- `HF_MapEditor` 可以保存/读取地图配置文件到 `Assets/Game/GameHFResource/CN/MapInfoData/<Configuration>.txt`，但实体加载/放置代码大多处于注释状态。
+- `HFM_MapSetting` 记录地图出生点、终点、Hero 引用。
+- `HF_WaveInfo` 记录波次中的起止时间、怪物 id、数量和 Boss 卡显示等。
+
+关卡/波次协议：
+
+- `GetLevelInfo = 3004`
+- `GetLevelWaveReward = 3005`
+- `BattleLevelEnter = 3000`
+- `BattleLevelExit = 3001`
+- `BattleLevelWin = 3002`
+- `BattleLevelFail = 3003`
+
+字段线索：
+
+```text
+GetLevelInfoS2C
+  -> Levels
+
+GetLevelWaveRewardC2S
+  -> Id
+  -> Wave
+GetLevelWaveRewardS2C
+  -> Level
+  -> Item
+
+BattleLevelEnterC2S
+  -> Id
+BattleLevelWinC2S
+  -> Id
+  -> ChestType
+  -> KillMons
+  -> MaxWave
+BattleLevelFailC2S
+  -> Id
+  -> MaxWave
+  -> KillMons
+```
+
+外围进度奖励协议：
+
+- `GetUserRolePeripheryProgressReward1Data = 5000`
+- `UserRolePeripheryClaimedProgressReward1Reward = 5001`
+- `SetUserRolePeripheryLevelWaveProgress = 5901`，当前主要在 GM 调试入口看到。
+
+字段线索：
+
+```text
+UserRolePeripheryDataProgressReward1
+  -> LevelId
+  -> MaxWave
+  -> State
+  -> ClaimedWave
+
+GetUserRolePeripheryProgressReward1DataS2C
+  -> ProgressReward1 : repeated UserRolePeripheryDataProgressReward1
+
+UserRolePeripheryClaimedProgressReward1RewardC2S
+  -> LevelId
+UserRolePeripheryClaimedProgressReward1RewardS2C
+  -> Rewards : Map<int, int>
+```
+
+当前接入状态：
+
+- PVE 战斗内波次由 `HFWaveManager` 读取 `Wave.xlsx`，属于战斗流程。
+- 地图/关卡进度协议已生成，但业务 UI 和普通发送链路未确认。
+- `GMWindow_GM.cs` 中有外围进度设置和领取奖励调试入口。
+- 地图编辑器、关卡配置、地图实体摆放等代码保留较多注释，当前更像半接入/调试状态。
+
+## 梳理任务
+
+- [x] 梳理地图/关卡数据结构。
+- [ ] 梳理关卡解锁、当前关卡、已通关状态。
+- [x] 梳理波次和关卡配置的关系。
+- [x] 梳理进度奖励领取条件和网络消息。
+- [ ] 梳理地图进度如何驱动主界面或 PVE 入口。
+
+## 待确认
+
+- 地图是否有章节/大关/小关层级；`ChapterWindow` 有注释入口，但当前未确认实装。
+- `Level` 相关配置表是否为旧表残留或当前未登记源表。
+- 关卡进度是否全部由服务器维护。
+- `GetLevelWaveReward` 与外围进度奖励 `ProgressReward1` 的产品边界。
+- 地图进度如何驱动主界面或 PVE 入口。
+
+## 相关框架
+
+- [PVE/关卡战斗](PVE关卡战斗.md)
+- [数据/配置框架](../../../modules/frameworks/数据配置框架.md)
+- [网络框架](../../../modules/frameworks/网络系统.md)
+- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/features/PVE关卡战斗.md](PVE关卡战斗.md) | PVE/关卡战斗 |
+| [modules/frameworks/数据配置框架.md](../../../modules/frameworks/数据配置框架.md) | 数据/配置框架 |
+| [modules/frameworks/网络系统.md](../../../modules/frameworks/网络系统.md) | 网络框架 |
+| [modules/frameworks/UI窗口系统/README.md](../../../modules/frameworks/UI窗口系统/README.md) | UI 框架 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
+| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 |
--- a/business-reference/playballoons/features/塔养成.md
+++ b/business-reference/playballoons/features/塔养成.md
@@ -0,0 +1,123 @@
+# 塔/角色养成
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录塔、角色或卡片的升级、升星、技能升级、展示和养成配置。
+
+## 已知线索
+
+- 逻辑路径：`Assets/Game/GameHFScripte/GameFunction/Logic/TowerLevelUpManager/`
+- 逻辑路径：`Assets/Game/GameHFScripte/GameFunction/Logic/TowerSkillUpManager/`
+- UI 路径：`Assets/Game/GameHFScripte/GameFunction/UIWindows/AvatarItem/`
+- 配置线索：`XLSX_SRC/CN/EntityConfig.xlsx`
+- 配置线索：`XLSX_SRC/CN/SkillGroup.xlsx`、`SkillReleaser.xlsx`、`SkillTrigger.xlsx`、`SkillUp.xlsx`
+
+## 已确认内容
+
+启动初始化：
+
+```text
+HFGameStart.InitManager()
+  -> HFTowerStarUpManager.Instance
+  -> HFTowerSkillUpManager.Instance
+```
+
+协议已生成：
+
+- `GetPlayerTower = 4000`
+- `TowerLevelFormation = 4001`
+- `TowerLevelUpLv = 4002`
+- route：
+  - `game.player.getTower`
+  - `game.player.formationTower`
+  - `game.player.levelUpTower`
+
+请求/响应字段：
+
+```text
+GetPlayerTowerC2S
+  -> 无主要字段
+GetPlayerTowerS2C
+  -> Formation : repeated long
+
+TowerLevelFormationC2S
+  -> Formation : repeated long
+TowerLevelFormationS2C
+  -> Formation : repeated long
+
+TowerLevelUpLvC2S
+  -> Id
+TowerLevelUpLvS2C
+  -> Id
+  -> Formation : repeated long
+```
+
+STC 事件：
+
+- `HFEvent_STC_GetPlayerTowerS2C`
+- `HFEvent_STC_TowerLevelFormationS2C`
+- `HFEvent_STC_TowerLevelUpLvS2C`
+
+配置和实体侧线索：
+
+- `Constants` 中有塔相关字段：`BossTowerCardNum`、`BossTowerGetNum`、`TowerRange`、`TowerRectangle`、`NewTowerInitLevel`、`TowerPutEffect*`、`LucySpinSameTower` 等。
+- 实体侧会读取 `EntityConfig`、`Resource`、`SkillGroup`、`SkillReleaser`、`SkillTrigger` 等表来驱动塔实体、模型、AI、技能。
+- 历史/生成代码里存在 `Tower`、`Towerlevel`、`StarUpgrade`、`CardWeight` 等表的读取痕迹，但当前 `ZYXlsxProjectSettings` 登记的 CN 表没有显式列出这些源表，需要确认是否是旧生成残留或表源未纳入当前列表。
+
+当前接入状态：
+
+- `HFTowerStarUpManager` 主体逻辑几乎全部注释，包括选择塔、显示升级 HUD、读取 `StarUpgrade`、修改实体属性等。
+- `HFTowerSkillUpManager` 主体逻辑也处于注释状态，包括监听 `HFEvent_TowerSkillState` 并修改实体技能能力。
+- `AvatarItem` 的资源路径 attribute 被注释，当前更像 MainWindow 内嵌组件；`SetAvatarFrame` 尚未实装。
+- `CardItem` 有卡片 UI 基础绑定，但 `SetData` 为空。
+- 未发现 `GetPlayerTowerC2S`、`TowerLevelFormationC2S`、`TowerLevelUpLvC2S` 在业务代码中的实际发送点。
+
+当前判断：
+
+- “塔/角色养成”协议、配置痕迹、实体战斗联动线索都存在。
+- 客户端养成主流程当前未完整实装，或被注释保留。
+- 运行中的塔更偏战斗实体/技能系统；大厅养成、编队、升级 UI 还需要进一步确认产品接入状态。
+
+## 梳理任务
+
+- [x] 确认“塔”“角色”“卡片”在代码和配置中的对应概念。
+- [x] 梳理塔升级和技能升级的入口。
+- [ ] 梳理升级消耗和背包资源关系。
+- [x] 梳理 Avatar/Card UI 展示数据来源。
+- [x] 梳理养成数据是否同步服务器。
+
+## 待确认
+
+- `TowerLevelUpManager` / `TowerSkillUpManager` 当前初始化但主体逻辑被注释，需确认是否计划恢复。
+- 升级、升星、技能升级是否属于同一产品功能域，需要结合 UI/策划表确认。
+- 升级消耗、卡片碎片、背包资源之间的真实关系待确认。
+- 养成结果如何同步并影响 PVE 实体属性，需要确认服务端返回和客户端应用链路。
+- `Tower`、`Towerlevel`、`StarUpgrade`、`CardWeight` 等表是否是旧表残留或当前缺失源表。
+
+## 相关框架
+
+- [实体框架](../../../modules/frameworks/实体系统/README.md)
+- [背包](背包.md)
+- [数据/配置框架](../../../modules/frameworks/数据配置框架.md)
+- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/features/背包.md](背包.md) | 背包 |
+| [modules/frameworks/数据配置框架.md](../../../modules/frameworks/数据配置框架.md) | 数据/配置框架 |
+| [modules/frameworks/实体系统/README.md](../../../modules/frameworks/实体系统/README.md) | 实体框架 |
+| [modules/frameworks/UI窗口系统/README.md](../../../modules/frameworks/UI窗口系统/README.md) | UI 框架 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
+| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 |
--- a/business-reference/playballoons/features/奖励道具.md
+++ b/business-reference/playballoons/features/奖励道具.md
@@ -0,0 +1,105 @@
+# 奖励/道具展示
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录通用奖励、道具展示、资源展示、弹窗提示和奖励到账表现。
+
+## 已知线索
+
+- 奖励提示：`Assets/Game/GameHFScripte/GameFunction/UIWindows/Tips/Tips_CommonReward.cs`
+- 资源组件：`Assets/Game/GameHFScripte/GameFunction/UIWindows/Components/ResourceItem.cs`
+- 道具 UI：`Assets/Game/GameHFScripte/GameFunction/UIWindows/Item/`
+- 配置线索：`XLSX_SRC/CN/Gift.xlsx`、`Resource.xlsx`
+
+## 已确认内容
+
+通用入口：
+
+```text
+HFFunCatalogue.Tips.ShowCommonRewardTips(reward, cardReward)
+  -> HFFunCatalogue.UIManager.OpenWindow<Tips_CommonReward>()
+  -> Tips_CommonReward.SetData(reward, cardReward)
+```
+
+定义位置：
+
+- `Assets/Game/GameHFScripte/GameFunction/Logic/UI/HFFunCatalogue_UI_TipsManager.cs`
+- `Assets/Game/GameHFScripte/GameFunction/UIWindows/Tips/Tips_CommonReward.cs`
+
+奖励数据结构：
+
+- `Tips_CommonReward.SetData` 接收 `RepeatedField<BagItem>`。
+- `BagItem` 来自网络 protobuf。
+- 当前代码中把奖励分成 `cards` 和 `items` 的逻辑存在，但核心分类代码被注释：
+  - 原计划通过 `Item` 配置表判断 `enItemType.Tower`。
+  - 当前 `ZYXlsxProjectSettings` 未登记 `Item.xlsx`，但旧代码里有 `ds_Item860D2A9ETableData` 痕迹。
+
+展示组件：
+
+- `Tips_CommonReward`
+  - 标题固定设置为 `REWARDS`。
+  - `ResourceItem` 当前固定调用 `SetData(1)` 展示顶部资源。
+  - 普通道具用 `ItemIcon` 池展示。
+  - 卡片奖励区域逻辑存在，但资源设置代码被注释。
+- `ResourceItem`
+  - 监听 `HFEvent_InitBag`。
+  - 通过 `HFFunCatalogue.Bag.GetGameResourceCount(resourceId)` 展示资源数量。
+  - 资源变化动画和主动刷新事件逻辑存在注释。
+- `Tips_UnlockTower`
+  - 用于解锁塔/卡片提示。
+  - 当前读 `Tower` / `Item` 配置和设置图标的代码被注释。
+
+配置线索：
+
+- `Gift.xlsx` 已登记到 ZYXlsx，生成 `Gift14537B33Sheet1`。
+- `Resource.xlsx` 已登记到 ZYXlsx，生成 `Resource840C5F09TableData`。
+- `Constants.xlsx` 中有奖励相关字段：`LuckyLootRewardTimes`、`LoginUsersItem`、`QuickOfflineReward`、`FreeOfflineReward` 等。
+
+当前接入状态：
+
+- 通用奖励弹窗入口存在。
+- 奖励 UI 框架存在，但道具/卡片配置读取大量注释。
+- 入包逻辑不在奖励弹窗里，当前主要由背包/服务器推送 `PlayerResourceChangeS2C` 更新。
+
+## 梳理任务
+
+- [x] 梳理奖励数据结构和展示入口。
+- [x] 梳理奖励中道具、卡片、资源的分类。
+- [x] 梳理奖励展示和背包更新的先后关系。
+- [x] 梳理通用 Tips 的打开方式和资源加载方式。
+- [ ] 梳理奖励来源：PVE、任务、商店、GM 或其他系统。
+
+## 待确认
+
+- 奖励展示当前看起来只负责表现，不负责入包；仍需结合具体领取协议确认。
+- `Gift.xlsx` 和实际奖励结构的对应关系待确认。
+- `Item.xlsx` / `Tower.xlsx` 是否是旧表残留或当前缺失源表。
+- 飞图事件 `HFEvent_FlyIcon` 存在，但实际调用链待继续确认。
+
+## 相关框架
+
+- [背包](背包.md)
+- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md)
+- [资源框架](../../../modules/frameworks/资源管理/README.md)
+- [数据/配置框架](../../../modules/frameworks/数据配置框架.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/features/背包.md](背包.md) | 背包 |
+| [modules/frameworks/数据配置框架.md](../../../modules/frameworks/数据配置框架.md) | 数据/配置框架 |
+| [modules/frameworks/资源管理/README.md](../../../modules/frameworks/资源管理/README.md) | 资源框架 |
+| [modules/frameworks/UI窗口系统/README.md](../../../modules/frameworks/UI窗口系统/README.md) | UI 框架 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
+| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 |
--- a/business-reference/playballoons/features/登录.md
+++ b/business-reference/playballoons/features/登录.md
@@ -0,0 +1,167 @@
+# 登录
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录登录流程、登录窗口、网络交互和进入游戏后的衔接关系。
+
+## 关键文件
+
+| 用途 | 路径 | 说明 |
+|---|---|---|
+| 登录管理器 | `Assets/Game/GameHFScripte/GameFunction/Logic/Login/HFLoginManager.cs` | 单例，负责连接服务器、发送登录协议、处理登录后事件链 |
+| 登录窗口 | `Assets/Game/GameHFScripte/GameFunction/UIWindows/Login/LoginWindow.cs` | 继承 `AbsHFUIWindow`，绑定输入框和登录按钮 |
+| 登录 Prefab | `Assets/Game/GameHFResource/UIWindows/Login/LoginWindow.prefab` | 窗口资源，由 `HFAssetBundlePath` 指定 |
+| 启动入口 | `Assets/Game/GameHFScripte/GameFunction/GameRoot/HFGameStart.cs`（待确认） | 初始化 manager 并打开 `LoginWindow` |
+
+## 数据流
+
+```text
+[启动]
+HFGameStart.InitManager
+  -> OpenWindow<LoginWindow>
+
+[用户点击]
+LoginWindow.OnBtnLogin
+  -> 校验用户名非空
+  -> PlayerPrefs 保存用户名/密码
+  -> HFLoginManager.Instance.Login(InputName.text)
+
+[连接服务器]
+HFLoginManager.Login(account)
+  -> UNITY_EDITOR 下读取 EditorPrefs["IPData"] 覆盖 IP
+  -> HFSeverManager.ReConnect(OnReConnect)
+  -> HFSeverManager.Connect(MainConnect, WebSocket, m_IP, m_Port, m_Token, callback)
+  -> 连接成功后 OnSendLogin
+
+[登录协议]
+OnSendLogin
+  -> LoginAuthC2S
+       ServerId = 10001
+       Token    = m_Token
+       Pid      = "2126001"
+       UserName = m_Account
+       Password = m_Account
+
+[服务端响应链]
+LoginAuthS2C (ErrorCode == 0)
+  -> PlayerSelectC2S
+  -> PlayerSelectS2C
+       有角色：PlayerEnterC2S
+       无角色：PlayerCreateC2S -> PlayerEnterC2S
+  -> PlayerEnterS2C
+  -> PlayerFlushC2S(All = true)
+  -> RequestLoginData 触发后续背包、资源等初始化
+```
+
+## 关键协议
+
+- `LoginAuthC2S` / `LoginAuthS2C`
+- `PlayerSelectC2S` / `PlayerSelectS2C`
+- `PlayerCreateC2S` / `PlayerCreateS2C`
+- `PlayerEnterC2S` / `PlayerEnterS2C`
+- `PlayerFlushC2S` / `PlayerFlushS2C`
+- `ChangeNicknameC2S` / `ChangeNicknameS2C`
+
+## 已确认流程
+
+当前登录入口：
+
+```text
+HFGameStart.InitManager
+  -> OpenWindow<LoginWindow>
+  -> LoginWindow.OnBtnLogin
+  -> HFLoginManager.Login(InputName.text)
+```
+
+`HFLoginManager.Login` 流程：
+
+```text
+Login(account)
+  -> 读取 EditorPrefs["IPData"] 覆盖 IP（仅 UNITY_EDITOR）
+  -> ConnectServer
+  -> HFSeverManager.ReConnect(OnReConnect)
+  -> HFSeverManager.Connect(MainConnect, WebSocket, m_IP, m_Port, m_Token)
+  -> OnSendLogin
+  -> LoginAuthC2S.Dispatch
+```
+
+服务端事件链：
+
+```text
+LoginAuthS2C
+  -> PlayerSelectC2S
+  -> PlayerSelectS2C
+    -> 有角色：PlayerEnterC2S
+    -> 无角色：PlayerCreateC2S -> PlayerEnterC2S
+  -> PlayerEnterS2C
+  -> PlayerFlushC2S(All = true)
+```
+
+`LoginWindow` 会把用户名和密码写入 `PlayerPrefs`，但实际登录请求当前使用用户名作为 account，密码未参与 `LoginAuthC2S`。
+
+## 梳理任务
+
+- [x] 找到登录功能的入口方法和首个调用点。
+- [x] 梳理登录请求、响应和错误处理。
+- [x] 梳理登录成功后初始化了哪些 manager。
+- [x] 梳理登录窗口 prefab 和脚本绑定关系。
+- [ ] 确认登录完成后进入主界面或 PVE 的流程。
+
+## 待确认
+
+- 登录是否区分游客、账号、平台登录。
+- 登录数据是否会初始化背包、关卡、角色/塔数据。
+- 是否存在断线重连或重新登录流程。
+- `PlayerFlushS2C` 收到后由谁打开主界面，目前未确认。
+- 密码输入框当前只保存到 `PlayerPrefs`，是否应参与登录待确认。
+
+## 相关框架
+
+- [网络框架](../../../modules/frameworks/网络系统.md)
+- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md)
+- [Hotfix 启动/目录](../../../modules/frameworks/Hotfix启动.md)
+
+---
+
+## 文档关联
+
+> **注意**：当本模块发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+### 关联模块
+
+| 模块 | 文档 | 关联原因 |
+|---|---|---|
+| 背包 | [背包](背包.md) | 登录成功后 `RequestLoginData` 触发背包初始化 |
+| 奖励/道具展示 | [奖励/道具展示](奖励道具.md) | 登录流程涉及资源、道具配置 |
+| GM/调试功能 | [GM/调试功能](GM调试.md) | `HFLoginManager` 在 Editor 下读取 `EditorPrefs["IPData"]` 覆盖 IP |
+| PVE/关卡战斗 | [PVE/关卡战斗](PVE关卡战斗.md) | 登录后进入主界面或 PVE 的流程衔接 |
+| 地图/关卡进度 | [地图/关卡进度](地图进度.md) | 登录后角色数据与关卡进度同步 |
+
+### 关联框架文档
+
+| 框架 | 文档 | 关联原因 |
+|---|---|---|
+| 网络框架 | [网络框架](../../../modules/frameworks/网络系统.md) | 登录协议（`LoginAuthC2S/S2C`、`PlayerEnterS2C` 等） |
+| UI 框架 | [UI 框架](../../../modules/frameworks/UI窗口系统/README.md) | `LoginWindow` 继承 `AbsHFUIWindow` |
+| Hotfix 启动/目录 | [Hotfix 启动/目录](../../../modules/frameworks/Hotfix启动.md) | `HFGameStart.InitManager` 为入口 |
+| 事件框架 | [事件框架](../../../modules/frameworks/事件系统/README.md) | `RequestLoginData` 触发后续初始化事件链 |
+| 场景框架 | [场景框架](../../../modules/frameworks/场景系统.md) | 登录后进入主界面涉及场景切换 |
+
+### 关联规则
+
+| 规则 | 文档 | 关联原因 |
+|---|---|---|
+| 模块登记规则 | [30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 登录模块登记与状态 |
+| 归档规则 | [50-归档规则.md](../../../rules/50-归档规则.md) | 变更后需同步归档相关文档 |
+| 架构说明 | [10-架构说明.md](../../../rules/10-架构说明.md) | 登录为游戏入口，涉及整体架构 |
+| 开发规则 | [20-开发规则.md](../../../rules/20-开发规则.md) | 网络协议、UI 窗口开发规范 |
+
+### 关联 Spec / OpenSpec
+
+| Spec | 文档 | 关联原因 |
+|---|---|---|
+| 规则工作流 Spec | [2026-06-11-rules-workflow-v1.md](../../../specs/Spec索引.md) | 项目文档和规则系统建立 |
--- a/business-reference/playballoons/features/背包.md
+++ b/business-reference/playballoons/features/背包.md
@@ -0,0 +1,174 @@
+# 背包
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录道具、资源数量、背包数据同步、资源展示和奖励入包逻辑。
+
+## 关键文件
+
+| 用途 | 路径 | 说明 |
+|---|---|---|
+| 背包管理器 | `Assets/Game/GameHFScripte/GameFunction/Logic/Bag/BagInfo/HFBagManager.cs` | 单例 `AbsHFSingleRunTime`，管理背包页签、道具/资源数量 |
+| 背包数据结构 | `Assets/Game/GameHFScripte/GameFunction/Logic/Bag/BagInfo/StItem.cs` | 单个道具数据 |
+| 背包数据结构 | `Assets/Game/GameHFScripte/GameFunction/Logic/Bag/BagInfo/stItemInfo.cs` | 道具信息 |
+| 道具类型枚举 | `Assets/Game/GameHFScripte/GameFunction/Logic/Constant/enItemType.cs` | 货币、材料、防御塔、经验、道具等 |
+| 背包窗口 | `Assets/Game/GameHFScripte/GameFunction/UIWindows/ItemWindow/ItemWindow.cs` | 单个道具/资源展示单元 |
+| GM 调试 | `Assets/Game/GameHFScripte/GameFunction/UIWindows/GMWindow/GMWindow_BagData.cs` | GM 修改背包数据入口 |
+| 资源配置 | `XLSX_SRC/CN/Resource.xlsx` | 资源/道具基础配置 |
+
+## 数据流
+
+### 登录初始化
+
+```text
+HFLoginManager.RequestLoginData
+  -> PlayerFlushC2S(All = true)
+  -> 服务端推送 GetBagItemS2C（待确认具体时序）
+  -> HFBagManager.OnPushBagItem
+  -> AddItem(item)
+  -> HFEvent_InitBag.Dispatch
+```
+
+### 增量更新
+
+```text
+PlayerResourceChangeS2C
+  -> ItemChange.Add / Del / Update
+  -> HFBagManager.OnUpdateBagItem
+  -> AddItem / DelItem
+  -> HFEvent_BagItemUpdate.Dispatch
+```
+
+## 关键 API
+
+| 方法 | 用途 |
+|---|---|
+| `Init(int maxpage)` | 初始化背包页签 |
+| `AddItem(Item item)` | 添加/更新道具 |
+| `DelItem(...)` | 删除道具 |
+| `GetGameResourceCount(int resId)` | 按 resid 快速获取资源数量 |
+| `GetItemCount(int resid)` | 遍历具体 item 累加数量 |
+| `BagPageIndex` | 当前背包页签 |
+
+## 内部存储
+
+- `m_BagPage`：按页签保存 `RB_Tree`。
+- `m_DicPageUUid`：按 `resid` 记录 uuid 到 page 的映射。
+- `m_DicItemCount`：按 `resid` 快速记录数量（当前为覆盖值，不是累加值）。
+
+## 关键事件
+
+- `enHFSTCEvent.GetBagItem`：首次推送背包数据。
+- `enHFSTCEvent.PlayerResourceChange`：资源/道具增量变化。
+- `HFEvent_InitBag`：背包初始化完成。
+- `HFEvent_BagItemUpdate`：背包数据更新。
+
+## 已确认内容
+
+背包 manager：
+
+- 主类：`HFBagManager`
+- 基类：`AbsHFSingleRunTime<HFBagManager>`
+- 初始化：`HFGameStart.InitManager` 访问 `HFBagManager.Instance` 时创建。
+
+监听的服务端事件：
+
+- `GetBagItemS2C` -> `OnPushBagItem`
+- `PlayerResourceChangeS2C` -> `OnUpdateBagItem`
+
+首次背包数据：
+
+```text
+HFLoginManager.RequestLoginData
+  -> PlayerFlushC2S(All = true)
+  -> 服务端推送 GetBagItemS2C（待确认具体时序）
+  -> HFBagManager.OnPushBagItem
+  -> AddItem
+  -> HFEvent_InitBag.Dispatch
+```
+
+增删改更新：
+
+```text
+PlayerResourceChangeS2C
+  -> ItemChange.Add / Del / Update
+  -> AddItem / DelItem
+  -> HFEvent_BagItemUpdate.Dispatch
+```
+
+内部存储：
+
+- `m_BagPage`：按页签保存 `RB_Tree`。
+- `m_DicPageUUid`：按 `resid` 记录 uuid 到 page 的映射。
+- `m_DicItemCount`：按 `resid` 快速记录数量。
+- `GetGameResourceCount(resId)`：常用于资源数量展示。
+- `GetItemCount(resid)`：遍历具体 item 累加数量。
+
+## 梳理任务
+
+- [x] 找到 `HFBagManager` 或背包 manager 的入口和生命周期。
+- [x] 梳理背包数据来源：登录初始化、网络消息、GM 请求或本地配置。
+- [x] 梳理道具和资源的查询 API。
+- [x] 梳理背包更新事件如何驱动 UI 刷新。
+- [ ] 梳理奖励入包和奖励展示的关系。
+
+## 待确认
+
+- 背包是否区分道具、资源、卡片。
+- 背包数据是否全部来自服务器。
+- 是否有消耗、添加、合并、排序等本地逻辑。
+- `PlayerFlushS2C` 和 `GetBagItemS2C` 的服务端推送时序需确认。
+- `m_DicItemCount[resid] = count` 当前是覆盖值，不是累加值，是否符合资源类型语义待确认。
+
+## 相关框架
+
+- [事件框架](../../../modules/frameworks/事件系统/README.md)
+- [网络框架](../../../modules/frameworks/网络系统.md)
+- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md)
+- [数据/配置框架](../../../modules/frameworks/数据配置框架.md)
+
+---
+
+## 文档关联
+
+> **注意**：当本模块发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+### 关联模块
+
+| 模块 | 文档 | 关联原因 |
+|---|---|---|
+| 登录 | [登录](登录.md) | `HFLoginManager.RequestLoginData` 触发背包首次初始化 |
+| 商店 | [商店](商店.md) | 商店购买/出售涉及背包道具增减 |
+| 奖励/道具展示 | [奖励/道具展示](奖励道具.md) | 奖励入包展示、道具配置（`Resource.xlsx`、`Gift.xlsx`） |
+| 塔/角色养成 | [塔/角色养成](塔养成.md) | 养成消耗涉及背包资源扣除 |
+| 地图/关卡进度 | [地图/关卡进度](地图进度.md) | 关卡奖励可能涉及背包道具更新 |
+| GM/调试功能 | [GM/调试功能](GM调试.md) | `GMWindow_BagData` 为 GM 修改背包数据入口 |
+
+### 关联框架文档
+
+| 框架 | 文档 | 关联原因 |
+|---|---|---|
+| 事件框架 | [事件框架](../../../modules/frameworks/事件系统/README.md) | `HFEvent_InitBag`、`HFEvent_BagItemUpdate` 事件驱动 |
+| 网络框架 | [网络框架](../../../modules/frameworks/网络系统.md) | `GetBagItemS2C`、`PlayerResourceChangeS2C` 协议 |
+| UI 框架 | [UI 框架](../../../modules/frameworks/UI窗口系统/README.md) | `ItemWindow` 为背包 UI 展示单元 |
+| 数据/配置框架 | [数据/配置框架](../../../modules/frameworks/数据配置框架.md) | `Resource.xlsx` 资源配置源 |
+| 内存/对象管理 | [内存/对象管理](../../../modules/frameworks/内存对象管理/README.md) | `RB_Tree` 存储结构、对象池 |
+
+### 关联规则
+
+| 规则 | 文档 | 关联原因 |
+|---|---|---|
+| 模块登记规则 | [30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 背包模块登记与状态 |
+| 归档规则 | [50-归档规则.md](../../../rules/50-归档规则.md) | 变更后需同步归档相关文档 |
+| 架构说明 | [10-架构说明.md](../../../rules/10-架构说明.md) | 背包为全局数据模块，涉及架构分层 |
+| 开发规则 | [20-开发规则.md](../../../rules/20-开发规则.md) | 数据管理、事件使用规范 |
+
+### 关联 Spec / OpenSpec
+
+| Spec | 文档 | 关联原因 |
+|---|---|---|
+| 规则工作流 Spec | [2026-06-11-rules-workflow-v1.md](../../../specs/Spec索引.md) | 项目文档和规则系统建立 |