mtgodot-poc/audit/contracts/social.party-guild-messenger.md

social.party_guild_messenger

Scope

审计组队邀请/接受/离队、队员状态/HP/角色、经验分配模式和组队技能；公会信息、成员/权限、技能、公告、公会战和邀请；好友/Messenger 在线与移动状态；以及会徽/战旗下载、缓存、上传和角色头顶徽章刷新。判断标准是当前端是否以 40250 的网络回包和资源服务为权威，并复现 UI 分支、协议副作用、失败清理和角色显示更新，而不是本地系统类能否独立模拟同样数值。

Reference call chain

• UserInterface/PythonNetworkStreamPhaseGame.cpp / PythonNetworkStreamPhaseGameActor.cpp
  • 解析 GC_PARTY_*、GC_GUILD_*、GC_MESSENGER、GC_CHARACTER_*；组队邀请、加入、移除、角色/HP/affect、分配模式由服务器回包驱动。
  • 公会 INFO/LIST/GRADE/GRADE_NAME/GRADE_AUTH/CHANGE_EXP/SKILL_INFO/COMMENTS/WAR/WAR_POINT/GUILD_NAME/MONEY_CHANGE 都只更新 CPythonGuild/窗口状态，客户端不计算经验、战绩奖励或权限结果。
  • Messenger 通过 CPythonMessenger 维护好友、公会和家族三组，登录/登出/移动回调 UI；添加/删除和邀请应答走 CG_MESSENGER 或 /messenger_auth。
• UserInterface/PythonGuild.cpp / PythonMessenger.cpp / PythonCharacterManager.cpp
  • 公会成员、等级名称/权限、公告、技能、战争列表和角色 guild id 由网络同步；ChangeGVG/RefreshAllGuildMark 使角色关系和会徽资源刷新。
  • CPythonCharacterManager 不负责本地结算公会战奖励或自动增长公会技能点；这些结果由服务器 GC_GUILD/聊天提示给出。
• UserInterface/GuildMarkDownloader.cpp / GuildMarkUploader.cpp / MarkManager.cpp
  • 会徽是独立连接和资源链：登录握手→mark index→本地 CRC 列表→压缩 block→拼接 mark image；符号另有 CRC/数据包；完成后通知角色刷新。
  • 上传前检查会长/权限、BMP/尺寸和数据；成功以 mark server 回包为准，不是把像素写入一个脚本字典就完成。
• Client/Eternexus/root/uiparty.py / uiguild.py / uimessenger.py / uiuploadmark.py
  • UI 只展示网络状态、发送请求和等待回包；队伍角色/affect、经验和公会战积分不能由客户端本地 authoritative 计算。

Current call chain

• native M2Client/ClassicSession 已提供 party invite/answer/remove/state/skill/parameter，friend add/remove/answer，guild 成员/权限/公告/技能/战争/邀请和 mark download/upload 等接口；EntityStore 也有对应的 party/friend/guild/war/mark 状态、dirty 标记和事件队列。
• project/ui/party_ui.gd、guild_ui.gd、friend_ui.gd 已连接 live native signal/getter，主要操作会发送 M2Client 请求；这部分是当前实现中最接近 40250 的路径。
• project/party_management_system.gd 是独立本地系统：直接创建队伍、计算按等级/均分经验、分配角色光环和数值加成；project/guild_skill_system.gd 本地计算公会升级/技能点/技能 buff；project/guild_war_system.gd 本地计算比分、目标分、天梯变化和 1,000,000 公会金币奖励。这些算法不是 40250 客户端的 authority 链，主要由 parity 测试使用。
• project/messenger_system.gd 直接修改 friends/guild/family 字典并记录事件；live FriendUI 则使用 native get_friends、add_friend、remove_friend 和 friend_answer，两套状态源未统一。
• project/guild_mark_uploader_system.gd 直接把上传数据写入本地 cached_marks；live game_scene.gd/GuildUI 使用 native mark server 方法，且默认图源可能是 res://ui/default_guild_mark.png 或运行时生成的 16x12 占位图。
• extension/src/net/classic/classic_mark_client.* 和 M2Client 已有独立 mark 连接/缓存/图片接口，app_flow.gd 会在登录/选人后启动下载并在 guild_mark_updated 后重试；但现有自动测试主要用 fake client，缺真实 mark packet/压缩 block/CRC/断线恢复证明。

Branch matrix

场景	40250	当前端	结论
组队邀请/应答/移除	CG 请求→GC 邀请/加入/移除；失败由服务器提示	native 包、store、UI 对应存在	PARTIAL：真实拒绝/重复/断线序列不足
队员状态/HP/affect/VID	GC_PARTY_ADD/UPDATE/LINK/UNLINK/PARAMETER 驱动 UI	EntityStore 与 PartyUI 能展示	PARTIAL：unordered map 顺序与重连恢复未验证
经验分配/角色光环	客户端只显示 server state/affects，结算在服务器	本地 helper 直接计算 exp 与 buff	GAP（helper 不等于 40250 implementation）
Messenger 好友	server list/login/logout/mobile/remove，邀请用 auth 流程	native live 路径完整，独立 helper 直接改字典	PARTIAL：两套状态源及真实拒绝/恢复缺证据
公会 info/member/grade/auth	GC_GUILD 回包更新，权限由服务器执行	native parser/getter/UI 操作链存在	PARTIAL：请求结果、顺序、权限拒绝和重连未完整覆盖
公会技能/捐献/公告	client 发请求，skill/exp/point/comments 由 GC 回包提供	live UI/native 请求存在；本地 GuildSkillSystem 另算升级/技能点	PARTIAL/GAP：本地 helper 不能作为 parity 证明
公会战声明/状态/列表/积分	GC_WAR/WAR_LIST/WAR_POINT/END 驱动展示，结算权威在服务端	native status/event/score 存在；本地 war system 自己结算奖励	PARTIAL：live native 近似，helper 分支为 GAP
公会邀请/创建	对话/确认后 CG_GUILD，结果 GC/command	UI/native 应答和创建请求存在	PARTIAL：失败文案和回包清理不足
会徽下载	独立 mark session、index/CRC/block、解压/缓存、角色刷新	classic mark client/native API/app_flow 与 Sprite3D 刷新存在	PARTIAL：真实资源协议和损坏 block 恢复未测
会徽/战旗上传	权限、BMP/尺寸/实际数据→mark server 回包	native upload 存在；本地 uploader 另有直接缓存 helper，默认可上传占位图	PARTIAL/GAP：本地 helper 不是服务端上传结果
角色徽章刷新/移除	RefreshAllGuildMark 与 guild id/mark 数据共同驱动	NetWorld 根据 mark image 创建/刷新 Sprite3D	PARTIAL：实际角色模型/换图/死亡/重连资源生命周期未端到端验证

Implementation-equivalence matrix

项目	状态	证据/限制
Preconditions	PARTIAL	native 对 VID/PID/阶段和部分字段做边界校验；本地 party/guild/mark helper 可绕过服务端权限、当前角色和会长身份
Branch structure	PARTIAL	live party/guild/friend/mark 主干存在；helper 本地结算、公会战奖励、技能升级、Messenger 缓存和上传缓存形成额外旁路
Algorithms/formulas	GAP	40250 客户端不拥有经验分配、公会技能升级、公会战奖励公式；当前 helper 的计算不能宣称与 40250 客户端实现统一
State transition order	PARTIAL	live native 是请求→GC 回包→dirty/signal→UI；本地系统是立即改字典/发 signal，未按权威回包顺序运行
Constants/units	PARTIAL	PARTY 角色/affect槽、guild grade/skill、mark 16x12/64x128 和协议布局部分存在；本地 buff、奖励、等级阈值需由 server 数据证明
Timing/event sources	PARTIAL	live signal/dirty/mark retry 存在；好友/公会/队伍登录、重连、mark block 分片和战争连续事件未完整验证
Resource/data sources	PARTIAL	native mark store 与角色资源接口存在；默认上传图源和本地缓存 helper 可能取代真实用户资源/服务器 mark 数据
Protocol side effects	PARTIAL	classic party/guild/friend/mark wire 基础存在；服务器错误、权限拒绝、命令提示和 mark 独立连接所有副作用缺完整测试
Interruption/failure/cleanup	GAP	本地 helper 可在无回包时进入成功状态；断线/换图/离会/好友清空/重复 mark 下载、坏 block、战争结束和 UI 弹窗清理未端到端覆盖

Regression evidence

• project/test_party_management_parity.gd：30/30 通过，但验证的是本地队伍创建、经验和角色 buff helper，未启动服务端或消费 GC_PARTY_*。
• project/test_messenger_parity.gd：27/27 通过，但验证的是独立 messenger_system.gd 字典/事件；live native Messenger list/login/logout/mobile/邀请回包未被此测试覆盖。
• project/test_guild_mark_uploader_parity.gd：12/12、project/guild_mark_test.gd 和 project/guild_mark_tail_test.gd 通过；主要使用本地 uploader/fake client，未覆盖真实 mark server index/CRC/compressed block 和坏数据清理。
• project/test_guild_war_parity.gd：25/25、test_guild_war_observer_arena_parity.gd：21/21、test_guild_skill_parity.gd：31/31、guild_creation_ui_test.gd：通过；公会战/技能测试主要验证本地公式和状态机，不等价于 40250 GC_GUILD 权威结果。
• project/test_privilege_empire_guild_parity.gd、project/p8_test.gd：通过；覆盖 UI/辅助系统，不覆盖所有 social 回包拒绝/乱序/重连。
• build/extension/net_entity_test、build/extension/net_classic_session_test：party/messenger/guild 基础 parser/session 检查通过；没有完整 GC_GUILD、GC_MESSENGER、GC_PARTY 错误序列和 mark client packet 测试。

Deep audit round 2026-09-21

Fresh regression results

• godot --headless --path project --script test_party_management_parity.gd：退出码 0，30/30 通过；覆盖本地队伍创建、离队、角色光环和经验分配 helper。
• godot --headless --path project --script test_messenger_parity.gd：退出码 0，27/27 通过；覆盖独立 messenger 字典/事件状态。
• godot --headless --path project --script test_guild_mark_uploader_parity.gd：退出码 0，12/12 通过；覆盖本地尺寸、权限和缓存 helper。
• godot --headless --path project --script guild_mark_test.gd、guild_mark_tail_test.gd：均退出码 0；会徽 UI/尾标局部路径通过。
• godot --headless --path project --script test_guild_war_parity.gd：退出码 0，25/25 通过；test_guild_war_observer_arena_parity.gd：21/21 通过；均主要验证本地战争/观察者状态机。
• godot --headless --path project --script test_guild_skill_parity.gd：退出码 0，31/31 通过；覆盖本地公会技能等级、消耗、buff 和 cooldown 公式。
• godot --headless --path project --script guild_creation_ui_test.gd、test_privilege_empire_guild_parity.gd、p8_test.gd：均退出码 0；UI/权限辅助路径通过。
• build/extension/net_entity_test 与 build/extension/net_classic_session_test：均退出码 0；基础 party/messenger/guild/mark parser/session 检查通过。

Static parity findings

• 40250 的队伍成员、经验分配、角色光环和公会技能/战争结果都由 GC_PARTY_*/GC_GUILD_* 与服务器状态驱动；当前 PartyManagementSystem、GuildSkillSystem、GuildWarSystem 仍可在无回包时直接计算并发成功信号，不能作为等价实现。
• live FriendUI 使用 native friend list/请求，MessengerSystem 却直接改本地 friends/guild/family 字典；两套状态源在拒绝、重复、离会、重连时可能分叉。
• 会徽 native mark client 已有独立连接、index/CRC/block 和缓存骨架，但当前测试没有真实 mark server 分片、压缩/CRC 失败、断线恢复和完成后所有角色刷新 fixture；本地 uploader helper 直接写 cached_marks 仍是旁路。
• 公会创建、邀请、权限、公告、技能和战争的 live native 入口存在，但错误文本、权限拒绝、事件顺序、换图/离会清理和重复回包没有形成统一状态合同。
• 角色徽章/公会关系刷新当前由 NetWorld 的 Sprite3D 适配承接，没有证明与 40250 RefreshAllGuildMark、真实角色模型、死亡/重连/换图资源生命周期保持一致。

Round conclusion

本轮仍为 PARTIAL：native 社交协议和 UI 主干较完整，局部测试全部通过；但本地结算/缓存旁路、真实权限与错误回包、队伍/公会/好友重连清理以及会徽独立连接仍未与 40250 统一。本轮未修改实现代码。

Active UserInterface guild-mark and social-state review

• GuildMarkDownloader.h 的可达状态机是独立 CNetworkStream：离线/登录/握手/ping/mark-index/mark-block/symbol/key-agreement/完成，并在请求前发送本地 mark CRC/index 列表；GuildMarkUploader.h 还要求读取并校验 BMP/符号、发送 mark 或 symbol、等待完成后断开。
• MarkImage.cpp/h 不是单个图片缓存：它按 mark/block 网格保存压缩块，使用 LZO 安全解压、CRC、差异 block 列表、空槽分配和本地持久化；MarkManager.h 维护 guild id→mark id、index、图片文件和 block CRC 的持久映射。
• PythonGuild.h 明确区分 guild 基础信息、等级/权限、成员 grade/job/level/offer、公告、技能点和敌对公会；PythonMessenger.h 暴露好友、公会成员、登录/登出、移动状态和删除回调。这些都属于回包驱动状态，不是本地公会战或 messenger 字典的 authority。
• 当前端虽有 classic_mark_client 和 native guild/messenger 入口，但本地 GuildMarkUploaderSystem、MessengerSystem 仍可旁路直接写缓存/字典；真实分片、CRC/LZO 失败、权限拒绝、重连清理和完成后的全部角色刷新仍无等价证据，合同保持 PARTIAL。

Static review evidence

已将 GuildMarkDownloader.h、GuildMarkUploader.h、MarkImage.cpp/h、MarkManager.h、PythonGuild.h、PythonMessenger.h 纳入本合同的 active source 证据；未因此提升状态。

Status

PARTIAL。当前端的 native 社交协议和主要 UI 已有较完整骨架，组队、公会、好友和会徽 live 主路径大体接上 40250；但本地 party/guild skill/war/messenger/mark helper 仍把服务端权威逻辑复制成直接状态机，且真实权限拒绝、回包顺序、重连清理和独立会徽连接缺端到端证据。因此不能把现有 parity 测试通过等同于实现统一。本轮完成审计并记录，未修改实现代码。

2026-09-22 死代码删除

以下文件只被自身测试引用、运行时从不加载，已删除；本文中以它们为实现或证据的结论作废，相关行为需按 40250 源码单元重新移植：guild_mark_uploader_system.gd, guild_skill_system.gd, guild_war_system.gd, messenger_system.gd, party_management_system.gd, test_guild_mark_uploader_parity.gd, test_guild_skill_parity.gd, test_guild_war_observer_arena_parity.gd, test_guild_war_parity.gd, test_messenger_parity.gd, test_party_management_parity.gd, test_privilege_empire_guild_parity.gd。