refactor: 重构战斗结构体以支持双打模式

docs/fight-group-implementation-checklist-2026-04-04.md

@@ -17,8 +17,9 @@
 ### 1.2 本清单目标
 
 - 在不破坏现有 `1v1` 的前提下，落地组队战斗可运行版本（MVP）。
-- 对齐 `flash` 组队战斗关键协议与关键行为（开战、出招、切宠、道具、结算、战斗结束）。
-- 留出兼容层，允许旧 `24xx/25xx` 流程继续使用。
+- 对齐 `flash`/社区实现中的关键行为（开战、出招、切宠、道具、结算、战斗结束）。
+- 协议层采用“一个统一结构体 + phase 字段”方案，单打/双打共用同一序列化模型。
+- 保留旧 `24xx/25xx` 流程入口，通过服务端适配映射到统一结构体。
 
 ### 1.3 非目标
 
@@ -49,74 +50,58 @@
   - 回合主链仍以双动作兼容流程为中心
   - 组队相关特性存在 TODO（例如 `501/502/503`）
 
+### 2.3 外部实现参考（本次新增）
+
+- `arcadia-star/seer2-fight-ui`
+  - 双打核心模型不是独立命令集，而是统一帧模型 + `uiStyle + side + position`。
+  - `uiStyle` 支持 `2v2/2v1`，战位通过 `position(main/sub)` 区分。
+- `arcadia-star/seer2-next-message/src/entity/fight.rs`
+  - 采用统一战斗实体结构：`team/user/pet` + `side/position`。
+  - 行为包拆分为 `Load/Hurt/Change/Escape/...`，但底层字段模型统一。
+- `ukuq/seer2-server/src/seer2/fight`
+  - `ArenaResourceLoadCMD -> TeamInfo -> FightUserInfo -> FighterInfo` 为层级化统一结构。
+  - `FighterInfo` 直接包含 `position/hp/maxHp/anger/skills`，适合直接映射为本项目统一结构体。
+
 ---
 
 ## 3. 协议对齐清单（按优先级）
 
-> 说明：命令号来源于 `flash` 的 `4c07fa07:CommandID.as`。  
-> 实施时可先做“服务端可跑+字段兼容”，逐步补全所有字段。
+> 说明：本清单改为“统一协议结构体”路线，不再强制先实现 `75xx` 独立命令族。  
+> 推荐做法：保留旧入口命令，服务端内部统一转为 `FightActionEnvelope/FightStateEnvelope`。
 
 ### 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`
-  - 用途：组队战斗结束
-  - 至少下发：结束原因、胜方标识、结算主体
+- [ ] 统一入站动作结构 `FightActionEnvelope`
+  - 最少字段：`actionType/actorIndex/targetIndex/skillId/itemId/catchTime/escape/chat`
+  - 兼容映射：
+    - `2405 -> actionType=skill`
+    - `2406 -> actionType=item`
+    - `2407 -> actionType=change`
+    - `2410 -> actionType=escape`
+- [ ] 统一出站状态结构 `FightStateEnvelope`
+  - 最少字段：
+    - `phase`（`start/skill_hurt/change/over/load/chat`）
+    - `left[]/right[]`（元素为统一 `FighterState`）
+    - `meta`（回合号、天气、胜负、结束原因）
+- [ ] 统一战位子结构 `FighterState`
+  - 每项至少包含：`side/position(userSlot)/userId/petId(catchTime)/hp/maxHp/level/anger/status/prop/skills`
 
 ### 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)`
-  - 组队加载进度同步
+- [ ] 完善 `phase=skill_hurt`
+  - 至少带：施法方快照、受击方快照、技能、暴击、伤害、HP 变更
+- [ ] 完善 `phase=change`
+  - 至少带：切宠发起位、切入目标位、新精灵状态
+- [ ] 完善 `phase=over`
+  - 至少带：结束原因、胜方、收益主体
+- [ ] 完善 `phase=load/chat`
+  - 组队加载进度、战斗内聊天统一走同一 envelope
 
 ### 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`
+- [ ] `phase=sprite_die/sprite_notice/win_close`
+- [ ] `phase=skill_wait/skill_wait_notice`
+- [ ] `phase=overtime/timeout_exit/relation_notice`
 
 ---
 
@@ -124,13 +109,13 @@
 
 ## 4.1 协议与结构层（Owner A）
 
-- [ ] 新增组队协议结构文件
-  - 建议新建：`logic/service/fight/cmd_group.go`
-  - 要求：所有组队命令入站结构都有 `TomeeHeader cmd:"xxxx"`
+- [ ] 新增统一协议结构文件
+  - 建议新建：`logic/service/fight/cmd_unified.go`
+  - 要求：统一定义 `FightActionEnvelope` 和映射辅助结构
 
-- [ ] 新增组队出站结构
-  - 建议新建：`logic/service/fight/info/group_info.go`
-  - 要求：明确 `side/pos/user/pet/hp/maxHp/level` 等核心字段
+- [ ] 新增统一出站结构
+  - 建议新建：`logic/service/fight/info/unified_info.go`
+  - 要求：定义 `FightStateEnvelope/FighterState`，支持单打与双打
 
 - [ ] 统一战位字段命名规范
   - `actorIndex`：我方执行位
@@ -139,26 +124,20 @@
 
 验收：
 
-- [ ] `controller.Init(true)` 能注册全部新命令，无重复 cmd panic。
-- [ ] 对每个新 cmd，可反序列化入参并进入控制器方法。
+- [ ] 旧 cmd（`2405/2406/2407/2410`）可无损映射到统一入站结构。
+- [ ] 统一出站结构在 `start/skill_hurt/change/over` phase 均可序列化。
 
 ---
 
 ## 4.2 控制器与路由层（Owner B）
 
-- [ ] 新增组队战斗控制器
-  - 建议新建：`logic/controller/fight_group.go`
-  - 包含：
-    - 组队准备
-    - 组队出招
-    - 组队切宠
-    - 组队道具
-    - 组队逃跑
-    - 组队聊天
+- [ ] 新增统一动作入口（可单文件）
+  - 建议新建：`logic/controller/fight_unified.go`
+  - 用途：将旧包和未来扩展包统一落到 `FightActionEnvelope`
 
 - [ ] 兼容旧协议入口
   - `2405/2406/2407` 保持可用（默认 `actorIndex=0,targetIndex=0`）
-  - 新 `75xx` 走组队专用入口
+  - 组队场景由 `actorIndex/targetIndex` 与战斗上下文决定，不再依赖独立 `75xx`
 
 - [ ] 增加战前校验
   - 成员是否在同一组队房间
@@ -167,7 +146,7 @@
 
 验收：
 
-- [ ] 双端同时发送 `7558` 能转化为 `UseSkillAt(...)`。
+- [ ] 任意技能动作都能转化为 `UseSkillAt(...)`（含 `actorIndex/targetIndex`）。
 - [ ] 非法战位命令被拒绝，不影响其他战位。
 
 ---
@@ -215,8 +194,8 @@
   - 战斗结束广播
 
 - [ ] 保留旧包兼容（必要时双发）
-  - 组队战斗对新包
-  - 非组队仍可走旧 `2503/2505/2506`
+  - 单打/双打统一走同一结构体
+  - 如前端未升级，可按需保留旧 `2503/2505/2506` 过渡映射
 
 验收：
 
@@ -276,14 +255,14 @@
 
 - 协议/结构：
   - `logic/service/fight/cmd.go`
-  - `logic/service/fight/cmd_group.go`（新增）
+  - `logic/service/fight/cmd_unified.go`（新增）
   - `logic/service/fight/info/info.go`
-  - `logic/service/fight/info/group_info.go`（新增）
+  - `logic/service/fight/info/unified_info.go`（新增）
 
 - 控制器：
   - `logic/controller/fight_base.go`
   - `logic/controller/fight_pvp_withplayer.go`
-  - `logic/controller/fight_group.go`（新增）
+  - `logic/controller/fight_unified.go`（新增）
 
 - 核心流程：
   - `logic/service/fight/new.go`
@@ -309,8 +288,8 @@
 
 ### M1（协议可通）
 
-- [ ] 75xx 关键命令可收发
-- [ ] 控制器能转发到 `FightC` indexed 接口
+- [ ] 统一结构体可完成 `start/skill_hurt/change/over` 四类下发
+- [ ] 旧命令入口均可映射到 `FightC` indexed 接口
 
 ### M2（核心可跑）
 
@@ -339,7 +318,7 @@
   缓解：把“回合开始/结束”从 pair 执行中抽离，确保每回合只触发一次。
 
 - 风险：协议切换导致旧客户端不可用。  
-  缓解：保留旧包并按战斗类型分流；必要时过渡期双发。
+  缓解：服务端保持旧入口不变，先做“旧包 -> 统一结构”映射；前端按版本切流。
 
 - 风险：effect 批量改动引发回归。  
   缓解：先做组队关键 effect，其他 effect 分批迁移并每批回归。
@@ -363,3 +342,16 @@
 - 如改动协议字段，必须附抓包样例或字段注释，不允许只改代码不补说明。
 - 如发现与本清单冲突的历史逻辑，以“兼容线上行为优先”，并在文档记录偏差原因。
 
+---
+
+## 10. 可实现性结论（统一协议结构体）
+
+- 结论：可实现，且风险可控。
+- 依据：
+  - `seer2-fight-ui` 的双打模型本质是统一数据结构 + `uiStyle/side/position`，不是强依赖独立命令族。
+  - `seer2-next-message` 与 `seer2-server` 都采用统一 `team/user/pet` 层级结构，`position` 作为战位核心字段。
+  - 本仓库已具备 `actorIndex/targetIndex` 与 `UseSkillAt/ChangePetAt/UseItemAt` 能力，协议统一后只需补齐映射和广播。
+- 实施建议：
+  - 先完成“旧入口 -> 统一入站结构”映射。
+  - 再完成“统一出站结构 + phase 广播”。
+  - 最后做前端切换与旧包退场（或长期双通道兼容）。