1

2026-04-04 13:52:57 +08:00
parent fbc845526b
commit 8ac2833ce2
1 changed files with 365 additions and 0 deletions
--- a/docs/fight-group-implementation-checklist-2026-04-04.md
+++ b/docs/fight-group-implementation-checklist-2026-04-04.md
@@ -0,0 +1,365 @@
+# 战斗系统对齐 `flash/group` 组队战斗实施清单（执行版）
+
+日期：2026-04-04  
+适用仓库：`E:\newcode\sun`  
+参考客户端仓库：`E:\newcode\flash`
+
+---
+
+## 1. 结论与范围
+
+### 1.1 结论
+
+- `sun` 当前战斗系统具备多战位骨架（`ActorIndex/TargetIndex`、`Our/Opp []*input.Input`），但未完成组队战斗全链路。
+- `flash` 的 `group` 分支当前 HEAD 已回滚组队重构；组队实现主要存在于历史提交 `4c07fa07`。
+- 因此本次不是“直接搬代码”，而是“按协议与行为对齐实现”。
+
+### 1.2 本清单目标
+
+- 在不破坏现有 `1v1` 的前提下，落地组队战斗可运行版本（MVP）。
+- 对齐 `flash` 组队战斗关键协议与关键行为（开战、出招、切宠、道具、结算、战斗结束）。
+- 留出兼容层，允许旧 `24xx/25xx` 流程继续使用。
+
+### 1.3 非目标
+
+- 不要求一次性 100% 复刻客户端所有 UI/演出细节。
+- 不要求一次性改完全部 effect；先保证核心流程可跑，再分批清理。
+
+---
+
+## 2. 基线事实（实施前必须统一认知）
+
+### 2.1 `flash` 仓库事实
+
+- `group` 分支相对 `main` 的提交：
+  - `4c07fa07 refactor(group-fight)`（引入组队）
+  - `a410bfca Revert "refactor(group-fight)"`（回滚组队）
+  - `e2382a4f`（地图重构）
+  - `bd84f206`（.gitignore）
+- 所以 `group` HEAD 不再包含 `GroupFightDLL`、`core/group/*` 组队代码；需参考 `4c07fa07` 的内容。
+
+### 2.2 `sun` 战斗现状
+
+- 已有多战位骨架：
+  - `logic/service/fight/input.go`：`Our/Opp []*input.Input`
+  - `logic/service/fight/action/BattleAction.go`：`ActorIndex/TargetIndex`
+  - `logic/service/fight/new_options.go`：`WithFightPlayersOnSide/WithFightInputs`
+- 仍有关键缺口：
+  - 控制器入站仍是单战位参数（如 `2405/2406/2407` 只传技能/道具/catchTime）
+  - 回合主链仍以双动作兼容流程为中心
+  - 组队相关特性存在 TODO（例如 `501/502/503`）
+
+---
+
+## 3. 协议对齐清单（按优先级）
+
+> 说明：命令号来源于 `flash` 的 `4c07fa07:CommandID.as`。  
+> 实施时可先做“服务端可跑+字段兼容”，逐步补全所有字段。
+
+### 3.1 P0 必做（MVP 必须）
+
+- [ ] `7555 GROUP_READY_TO_FIGHT`
+  - 用途：组队成员准备
+  - 入参建议：`room/groupId + userId + actorSlotsReady`
+  - 出参建议：广播 ready 状态变化
+
+- [ ] `7557 GROUP_START_FIGHT`
+  - 用途：下发组队开战结构
+  - 参考客户端结构：
+    - `isVsNPC`
+    - `groupOneMembCnt + groupOneList[]`
+    - `groupTwoMembCnt + groupTwoList[]`
+  - `group list` 每项至少要有：`side/pos/userID/petID/catchTime/hp/maxHP/level/catchType`
+
+- [ ] `7558 GROUP_FT_USE_SKILL`
+  - 用途：组队技能指令
+  - 参考客户端 payload：`skillId(uint32) + side(byte) + pos(byte)`（6字节）
+  - 服务端内部映射：`actorIndex + targetIndex`
+
+- [ ] `7563 GROUP_FT_CHG_PET`
+  - 用途：组队切宠请求
+  - 至少支持：按操作者位切宠
+
+- [ ] `7562 GROUP_FT_USE_ITEM`
+  - 用途：组队用道具
+  - 至少支持：按 actor/target 生效
+
+- [ ] `7560 GROUP_FT_OVER`
+  - 用途：组队战斗结束
+  - 至少下发：结束原因、胜方标识、结算主体
+
+### 3.2 P1 强烈建议（提升一致性）
+
+- [ ] `7559 GROUP_FT_SKILL_HURT`
+  - 对齐技能伤害播报（攻击方+受击方快照）
+  - 参考结构包含：状态数组、能力等级、技能、HP 变化、暴击、伤害值
+
+- [ ] `7567 GROUP_FT_CHG_PET_SUC`
+  - 切宠成功广播，保障前端战位同步
+
+- [ ] `7568 GROUP_FT_ESCAPE_SUC`
+  - 逃跑成功广播（含退出战位）
+
+- [ ] `7570 GROUP_CHAT_MSG`
+  - 组队战斗聊天转发
+
+- [ ] `7571/7572 GROUP_LOAD_PERCENT(_NOTICE)`
+  - 组队加载进度同步
+
+### 3.3 P2 视时间补齐
+
+- [ ] `7561 GROUP_FT_SPRITE_DIE`
+- [ ] `7573 GROUP_FT_SPRITE_NOTICE`
+- [ ] `7574 GROUP_FT_WIN_CLOSE`
+- [ ] `7575 GP_SKILL_WAIT_PERT`
+- [ ] `7576 GP_SKILL_WAIT_NOTICE`
+- [ ] `7585 GROUP_FT_OVERTIME_NOTICE`
+- [ ] `7586 GROUP_FT_SKILL_PLAY_OVER`
+- [ ] `7587 GROUP_FT_TIME_OUT_EXIT`
+- [ ] `7588 GROUP_FT_RELATION_NOTICE`
+
+---
+
+## 4. 代码改造任务清单（可直接分工）
+
+## 4.1 协议与结构层（Owner A）
+
+- [ ] 新增组队协议结构文件
+  - 建议新建：`logic/service/fight/cmd_group.go`
+  - 要求：所有组队命令入站结构都有 `TomeeHeader cmd:"xxxx"`
+
+- [ ] 新增组队出站结构
+  - 建议新建：`logic/service/fight/info/group_info.go`
+  - 要求：明确 `side/pos/user/pet/hp/maxHp/level` 等核心字段
+
+- [ ] 统一战位字段命名规范
+  - `actorIndex`：我方执行位
+  - `targetIndex`：敌方目标位
+  - `side+pos` 与 `actorIndex/targetIndex` 转换规则写入注释
+
+验收：
+
+- [ ] `controller.Init(true)` 能注册全部新命令，无重复 cmd panic。
+- [ ] 对每个新 cmd，可反序列化入参并进入控制器方法。
+
+---
+
+## 4.2 控制器与路由层（Owner B）
+
+- [ ] 新增组队战斗控制器
+  - 建议新建：`logic/controller/fight_group.go`
+  - 包含：
+    - 组队准备
+    - 组队出招
+    - 组队切宠
+    - 组队道具
+    - 组队逃跑
+    - 组队聊天
+
+- [ ] 兼容旧协议入口
+  - `2405/2406/2407` 保持可用（默认 `actorIndex=0,targetIndex=0`）
+  - 新 `75xx` 走组队专用入口
+
+- [ ] 增加战前校验
+  - 成员是否在同一组队房间
+  - 战斗状态互斥
+  - 战位可操作权限
+
+验收：
+
+- [ ] 双端同时发送 `7558` 能转化为 `UseSkillAt(...)`。
+- [ ] 非法战位命令被拒绝，不影响其他战位。
+
+---
+
+## 4.3 战斗核心层（Owner C）
+
+- [ ] 固化“多动作一回合”模型
+  - `collectPlayerActions`：按预期战位数收集，不是按两人收集
+  - `resolveRound`：每回合一次统一排序与执行
+
+- [ ] 降低对“双动作 enterturn”的耦合
+  - 当前 `enterturn(first, second)` 作为兼容层保留
+  - 新逻辑要确保：
+    - 回合开始钩子只执行一次/回合
+    - 回合结束钩子只执行一次/回合
+    - 不因 pair 分片导致重复触发
+
+- [ ] 完善动作-战位映射
+  - `GetInputByAction` 在组队模式下严格按 `playerID + actorIndex/targetIndex` 定位
+  - 超时补默认动作按战位补齐
+
+- [ ] 完善死亡换宠/主动换宠
+  - 按 actorIndex 粒度处理
+  - 切宠广播必须携带 actor 位信息
+
+验收：
+
+- [ ] 2v2 场景一回合四动作都参与排序，不丢动作。
+- [ ] 同玩家多战位动作不会互相覆盖。
+- [ ] 任一战位死亡只影响对应战位换宠链路。
+
+---
+
+## 4.4 组队战报与广播层（Owner D）
+
+- [ ] 统一战报快照结构
+  - 至少包含：
+    - 施法方：`userId/actorIndex/skillId/crit/dmg/hpAfter/status/prop`
+    - 受击方：`userId/actorIndex/hpAfter/status/prop`
+
+- [ ] 完成关键广播
+  - 开战广播
+  - 技能结果广播
+  - 切宠成功广播
+  - 战斗结束广播
+
+- [ ] 保留旧包兼容（必要时双发）
+  - 组队战斗对新包
+  - 非组队仍可走旧 `2503/2505/2506`
+
+验收：
+
+- [ ] 观战端/队友端收到的战位与 HP 同步一致。
+- [ ] 切宠后不会出现“错位显示”。
+
+---
+
+## 4.5 Effect 与规则层（Owner E）
+
+- [ ] 先补明确组队依赖效果
+  - `logic/service/fight/boss/NewSeIdx_501.go`
+  - `logic/service/fight/boss/NewSeIdx_502.go`
+  - `logic/service/fight/boss/NewSeIdx_503.go`
+
+- [ ] 统一“队友”查询工具函数
+  - 建议在 `input` 或 `fight` 层提供：
+    - 获取同阵营存活战位
+    - 获取队友列表（排除自己）
+    - 群体目标选择上限
+
+- [ ] 扫描组队敏感 effect
+  - 特别关注含“组队对战时无效”描述项（如 effect 457）
+  - 明确：是直接禁用，还是按组队模式替代逻辑
+
+验收：
+
+- [ ] `501/502/503` 在 2v2 场景行为符合设计。
+- [ ] 组队模式下不再出现空指针或越界。
+
+---
+
+## 4.6 测试与回归（Owner F）
+
+- [ ] 单测补齐
+  - `logic/service/fight/action_test.go`：继续扩充多战位覆盖
+  - 新增建议：
+    - `logic/service/fight/loop_multi_test.go`
+    - `logic/service/fight/fight_group_test.go`
+
+- [ ] 集成回归用例（最少）
+  - Case 1：1v1 旧流程
+  - Case 2：2v2 双方四动作
+  - Case 3：同一玩家两战位各自出招
+  - Case 4：中途切宠 + 被动死亡切宠
+  - Case 5：超时默认动作补齐
+  - Case 6：逃跑/掉线结束
+
+- [ ] 构建与测试命令
+  - `cd logic && go test ./service/fight/...`
+  - `cd logic && go test ./controller/...`
+  - `cd logic && go build ./...`
+
+---
+
+## 5. 文件级任务地图（便于派工）
+
+- 协议/结构：
+  - `logic/service/fight/cmd.go`
+  - `logic/service/fight/cmd_group.go`（新增）
+  - `logic/service/fight/info/info.go`
+  - `logic/service/fight/info/group_info.go`（新增）
+
+- 控制器：
+  - `logic/controller/fight_base.go`
+  - `logic/controller/fight_pvp_withplayer.go`
+  - `logic/controller/fight_group.go`（新增）
+
+- 核心流程：
+  - `logic/service/fight/new.go`
+  - `logic/service/fight/new_options.go`
+  - `logic/service/fight/input.go`
+  - `logic/service/fight/action.go`
+  - `logic/service/fight/loop.go`
+  - `logic/service/fight/fightc.go`
+
+- Effect：
+  - `logic/service/fight/boss/NewSeIdx_501.go`
+  - `logic/service/fight/boss/NewSeIdx_502.go`
+  - `logic/service/fight/boss/NewSeIdx_503.go`
+  - 其他含组队语义的 effect 文件
+
+- 测试：
+  - `logic/service/fight/action_test.go`
+  - `logic/service/fight/*_test.go`（新增）
+
+---
+
+## 6. 里程碑与交付标准
+
+### M1（协议可通）
+
+- [ ] 75xx 关键命令可收发
+- [ ] 控制器能转发到 `FightC` indexed 接口
+
+### M2（核心可跑）
+
+- [ ] 2v2 全回合可稳定执行
+- [ ] 切宠/道具/超时可用
+
+### M3（规则可用）
+
+- [ ] 501/502/503 完成
+- [ ] 主要组队战报可用
+
+### M4（回归上线）
+
+- [ ] 1v1 不回归
+- [ ] `go test` 与 `go build` 通过
+- [ ] 文档补充已完成项与遗留项
+
+---
+
+## 7. 风险清单与缓解
+
+- 风险：旧逻辑大量默认 `CurPet[0]`，多人战位容易错位。  
+  缓解：引入统一 `CurrentPetByActor`/`TargetByIndex` 访问函数，禁止新代码直接写死 `[0]`。
+
+- 风险：`enterturn` 兼容层导致钩子重复触发。  
+  缓解：把“回合开始/结束”从 pair 执行中抽离，确保每回合只触发一次。
+
+- 风险：协议切换导致旧客户端不可用。  
+  缓解：保留旧包并按战斗类型分流；必要时过渡期双发。
+
+- 风险：effect 批量改动引发回归。  
+  缓解：先做组队关键 effect，其他 effect 分批迁移并每批回归。
+
+---
+
+## 8. 实施顺序建议（最小阻塞）
+
+1. 协议结构与控制器入口
+2. 动作收集与回合统一执行
+3. 切宠/道具/超时按战位修正
+4. 关键广播与战报
+5. 组队 effect（501/502/503）
+6. 全量测试与回归
+
+---
+
+## 9. 交接要求（给执行同学）
+
+- 每完成一个里程碑，在 `docs/` 新增一段“完成项/未完成项/阻塞项”。
+- 如改动协议字段，必须附抓包样例或字段注释，不允许只改代码不补说明。
+- 如发现与本清单冲突的历史逻辑，以“兼容线上行为优先”，并在文档记录偏差原因。
+