mtgodot-poc/audit/contracts/item.refine-socket-costume.md

item.refine_socket_costume

Scope

审计强化窗口、强化请求与回包、普通/魔石/首饰镶嵌、属性添加与洗炼、时装栏位与外观更新，以及当前端额外的幻化/衣柜逻辑。判断标准不是本地字典能否算出相同结果，而是是否复现 40250 的物品原型校验、请求协议、服务器权威结果、GC_ITEM_* 状态更新、角色部件刷新、特效/资源和失败清理链。

Reference call chain

• UserInterface/PythonNetworkStreamPhaseGame.cpp / PythonNetworkStreamModule.cpp
  • SendRefinePacket 发送 CG_REFINE(pos,type)；40250 取消强化使用 (255,255)，写包后进入序列发送。
  • RecvRefineInformationPacket 解析旧版 GC_REFINE_INFORMATION(95)；RecvRefineInformationPacketNew 解析新版 GC_REFINE_INFORMATION_NEW(119)，两者都把服务端给出的源物品、结果 vnum、费用、概率和材料交给 OpenRefineDialog。
  • 强化信息由服务器提供，客户端不拥有强化成功率、结果 vnum、费用或材料公式。
• UserInterface/Packet.h / GameLib/ItemData.cpp / PythonItemModule.cpp
  • 旧、新强化包的 wire layout 不同；ITEM_USE 子类型包括 USE_TUNING、USE_CLEAN_SOCKET、USE_CHANGE_ATTRIBUTE、USE_ADD_ATTRIBUTE、USE_ADD_ATTRIBUTE2、USE_ADD_ACCESSORY_SOCKET、USE_PUT_INTO_ACCESSORY_SOCKET 等。
  • ItemData 提供 GetSocket、GetSocketCount、GetRefine、GetRefinedVnum、GetValue、flags/anti-flags、装备类型和外观资源；客户端用这些信息做 UI/目标校验，不替代服务端物品变更。
• UserInterface/PythonPlayer.cpp / PythonPlayerModule.cpp / PythonNetworkStreamPhaseGameItem.cpp
  • SetItemData 对非零 vnum 先验证 ItemManager；SetItemCount、socket、attribute 按服务器回包写入本地物品，并刷新窗口。
  • CanRefine、CanAttachMetin 等只依据 ItemManager 的真实 type/subtype/flag/socket 数据判断允许与否，然后由物品使用协议请求服务端执行。
  • 物品更新顺序是服务器回包驱动的 count、socket、attribute 与窗口刷新，不是 UI 或脚本直接扣除材料。
• UserInterface/InstanceBase.cpp / PythonNetworkStreamPhaseGameActor.cpp
  • 角色的 armor、weapon、hair 部件来自角色同步包；SetArmor 通过 ItemData 映射模型、specular 和强化特效，SetHair/weapon attachment 刷新实际角色模型。
  • __GetRefinedEffect 按 ItemData 的 refine/socket/type/subtype 选择并挂接/清理强化特效。
• Client/Eternexus/root/uirefine.py / uiinventory.py
  • 强化窗口只负责显示服务器给出的 refine table、材料库存和警告；确认/取消均发送网络请求。属性、清孔、首饰孔和物品使用入口同样依赖 item_proto 的 use type 与服务器 GC_ITEM_* 回包。
• 服务器权威位于 Server/metin2/src/server/game/src/char_item.cpp、item.cpp、item_attribute.cpp 及 item_proto。这些文件决定属性池、概率、socket/强化限制、消耗和最终 item data；客户端源码没有对应的独立权威算法。

Current call chain

• project/ui/refine_ui.gd 已接收 M2Client.refine_ask，显示材料/概率/费用并调用 M2Client.refine；extension/src/net/classic/classic_session.cpp 已能构造 CGRefine，EntityStore 已有 RefineCue。
• extension/src/net/m2_client.cpp::refine 只允许 0 <= pos < INVENTORY_MAX_NUM，所以 RefineUI.cancel_refine() 发出的 40250 取消哨兵 255,255 在 native 层直接返回 false，未到达服务器。
• extension/src/net/classic/classic_parser.cpp 已分别解析旧版 GCRefineInfoOld（95，59 字节，无 type）和新版 GCRefineInfo（119，60 字节，有 type），并将两者送入 EntityStore::mut_refine；旧版 wire layout 本身已补齐，但旧版真实服务器回包和类型默认值仍缺端到端 fixture。
• project/item_attr_system.gd、item_enchant_system.gd 直接在传入 Dictionary/Array 上生成/重置普通和稀有属性并扣本地卷轴；没有调用 M2Client::use_item_to_item、等待 GC_ITEM_UPDATE 或从 ItemManager 读取真实 use subtype/attribute set。
• project/jewelry_socket_system.gd 直接用硬编码 vnum、首饰 vnum 前缀、成功率、寿命和 bonus tier 修改 sockets/gem_times；没有通过 40250 的 ITEM_USE/USE_ADD_ACCESSORY_SOCKET/USE_PUT_INTO_ACCESSORY_SOCKET 请求和服务器更新闭环。
• project/costume_system.gd 维护独立的 equipped_costumes，复制传入时装、默认本地 7 天计时并计算 bonus/model_id；未发现它接入 M2Client、EntityStore 的 equipment 回包或 project/ui/equip_model.gd 的角色部件更新。
• project/costume_attr_transfer_system.gd 和 project/wardrobe_transmog_system.gd 直接修改库存、金币、属性和 transmog_* 字段。现有 40250 客户端源码中没有与 wardrobe_transmog_system.gd 对应的幻化协议/角色字段，因此它是当前端自定义扩展，不应标记为 40250 已实现。
• project/refine_effect_system.gd 有本地强化光效规格和粒子测试，但尚未证明由权威装备回包触发，且当前模型/角色路径与 40250 的 InstanceBase 部件、ItemData 和 effect attach 链未形成端到端测试。

Branch matrix

场景	40250	当前端	结论
打开强化窗口	服务器发送旧/新版 refine info；客户端按 packet layout 交给 UI	native parser 已分别接受 95/119 并生成 cue	PARTIAL：旧版真实回包与 UI 行为缺 fixture
强化确认	UI 发 CG_REFINE(pos,type)，结果和消耗由服务器回包决定	正常 pos/type 可发 CGRefine	PARTIAL：缺完整成功/失败后的 item/point/effect 顺序证明
强化取消/超距/ESC	发送 CG_REFINE(255,255)	RefineUI 调用 refine(255,255)，native 范围校验先拒绝	GAP
强化数据来源	src_vnum/result_vnum/cost/prob/materials 全部服务端提供	RefineCue 能保存字段，窗口能显示	MAPPED + tests：旧包与真实回包覆盖不足
普通/魔石/首饰镶嵌	ItemManager use subtype/flag/socket 校验后发物品使用请求，服务器改 item data	本地系统按字典直接改 socket/attrs	GAP
属性添加/洗炼/第五属性	客户端显示 ItemData/回包，成功率和属性生成在服务器 char_item.cpp/item_attribute.cpp	本地硬编码池/概率并直接写 attrs	GAP：算法复制不等于客户端协议实现
稀有属性 6/7 条	在当前 40250 客户端引用中未找到与当前 71151/71152 本地系统相同的完整客户端链	ItemEnchantSystem 本地新增稀有池并直接扣卷轴	CUSTOM/PARTIAL，不能宣称 40250 1:1
时装穿戴/卸下	角色同步包给 armor/weapon/hair 部件，ItemData/InstanceBase 刷新模型与强化效果	CostumeSystem 只更新本地字典和信号；未接 actor/model 回包	GAP
时装属性/限时	服务器 item data/affect/point 回包决定状态	本地 bonuses 与 remaining_time 逐帧扣减	PARTIAL：缺权威计时、point/affect 和过期回包
幻化/衣柜	40250 客户端源码未找到相同协议或 transmog_* 角色部件链	本地直接扣金币/卷轴/皮肤并改字段	CUSTOM，不属于已验证的 40250 parity
强化外观效果	InstanceBase::__GetRefinedEffect 依 ItemData 的 refine/socket/type/subtype attach/clear effect	本地 RefineEffectSystem 可计算规格并创建粒子	PARTIAL：资源、部件更新和清理未闭环

Implementation-equivalence matrix

项目	状态	证据/限制
Preconditions	PARTIAL	refine 基础 pos 校验存在；取消哨兵被错误拒绝；属性/socket/costume helper 不统一使用 ItemManager 的 type/subtype/flag/anti-flag/equipment slot 校验
Branch structure	PARTIAL	强化 UI 分支和 native 请求存在；本地属性、镶嵌、时装操作绕过 CG_ITEM_USE/GC_ITEM_UPDATE，并增加了参考端不存在的幻化分支
Algorithms/formulas	PARTIAL	40250 的强化、属性、socket 结果由服务器权威计算；当前本地池/概率/寿命只通过孤立测试，不能证明与运行时服务端一致
State transition order	GAP	参考是请求→服务器判定→GC_ITEM_*/point/affect/actor update→刷新；当前多个 helper 是本地立即写入和发 signal
Constants/units	PARTIAL	refine packet header/字段和部分 vnum 已定位；socket 前缀、gem tier、时装 7 天、幻化 1000 万等硬编码未由当前 40250 运行时数据链证明
Timing/event sources	PARTIAL	RefineCue/signal/UI 事件存在；旧包、取消包、真实 item update/actor update 顺序和过期竞态未覆盖
Resource/data sources	PARTIAL	当前可读部分 item proto/模型数据；属性池、socket 规则和 costume model_id 多来自脚本常量，未接 40250 ItemData/资源选择链
Protocol side effects	PARTIAL	CGRefine 和基础 refine cue 存在；取消 sentinel、旧 refine header、item-use/socket/costume request、SendSequence/失败反馈未完整闭合
Interruption/failure/cleanup	GAP	本地操作成功前就能改变库存/金币/attrs/sockets；网络拒绝、重复回包、断线、换图、时装过期和 actor model 清理没有同一权威回滚路径

Regression evidence

• project/test_refine_parity.gd：通过，覆盖窗口显示、材料颜色、确认/取消 UI 规则和超距行为；使用 fake client，未证明 native 255,255 取消包真实发出，也未覆盖旧版 95 包。
• project/test_refine_effect_parity.gd：25/25 通过，覆盖本地强化等级和粒子规格；未覆盖 40250 InstanceBase 真实 ItemData 部件更新、attach/clear 和资源加载失败。
• project/test_item_attr_parity.gd：28/28 通过；project/test_item_enchant_manager_parity.gd：36/36 通过。两者都直接对 Dictionary 做本地生成/扣除，未启动服务器或消费 GC_ITEM_UPDATE。
• project/test_jewelry_socket_parity.gd：23/23 通过；覆盖本地打孔/镶嵌/寿命计算，但没有 40250 物品使用协议、ItemData socket count、服务器拒绝或回包。
• project/test_costume_system_parity.gd：23/23 通过；project/test_costume_attr_transfer_parity.gd：23/23 通过；project/test_wardrobe_transmog_parity.gd：22/22 通过。它们验证本地 helper 的字典和 signal 行为，不能证明角色模型、服务端库存/金币或 40250 客户端协议等价。
• native/refine 现有测试覆盖 CGRefine/cue 基础布局，但未覆盖 GC_REFINE_INFORMATION(95) 与 (119) 双版本解析、255,255 取消发送和 refine 后 item/point/affect/actor 更新顺序。

Deep audit round 2026-09-21

Fresh regression results

• godot --headless --path project --script test_refine_parity.gd：退出码 0；强化窗口/材料/确认/取消 UI 规则通过，但 fake client 不能证明 native 取消包真正发出。
• godot --headless --path project --script test_refine_effect_parity.gd：退出码 0，25/25 通过；只证明本地强化等级到粒子规格的映射。
• godot --headless --path project --script test_item_attr_parity.gd：退出码 0，28/28 通过；只证明本地属性字典算法。
• godot --headless --path project --script test_item_enchant_manager_parity.gd：退出码 0，36/36 通过；只证明本地普通/稀有属性管理器的直接修改路径。
• godot --headless --path project --script test_jewelry_socket_parity.gd：退出码 0，23/23 通过；只证明本地首饰打孔、镶嵌和寿命计算。
• godot --headless --path project --script test_costume_system_parity.gd、test_costume_attr_transfer_parity.gd、test_wardrobe_transmog_parity.gd：均退出码 0，分别 23/23、23/23、22/22 通过；验证的是本地时装/属性转移/幻化字典状态，不是服务器权威链路。
• godot --headless --path project --script guild_refine_test.gd：退出码 0，确认 UI 取消会调用 client.refine(255,255)。
• ./build/extension/net_classic_session_test、./build/extension/net_entity_test：均退出码 0；native 基础 refine/DS refine 包和新版 cue 通过。源码复核确认 parser 已分别支持旧版 95（59 字节）与新版 119（60 字节）。

Static parity findings

• 当前明确的协议缺陷仍是 M2Client::refine 要求 0 <= pos < INVENTORY_MAX_NUM；因此 RefineUI.cancel_refine() 发出的 40250 取消哨兵 (255,255) 在 native 层被拒绝，ClassicSession::send_refine 虽可编码该字节，但 UI 入口到不了它。
• 旧/新版 refine parser 已经分别存在，先前“旧版 95 包被统一结构丢弃”的判断已纠正；尚缺旧版实际字节 fixture、旧包 type=0 对 UI 分支的行为和成功/失败后的 item/point/actor 更新时序。
• 40250 的属性、socket、装备外观和时装穿戴依赖 ItemManager/ItemData + CG_ITEM_USE/CG_ITEM_USE_TO_ITEM + 服务器 GC_ITEM_*/affect/point/character parts；当前 ItemAttrSystem、ItemEnchantSystem、JewelrySocketSystem、CostumeSystem 仍能直接修改传入字典、金币、socket、attributes 或本地计时。
• 当前 CostumeSystem 的 bonus/model/7 天过期以及 wardrobe_transmog_system.gd 的金币/卷轴扣除都没有连接 EntityStore equipment/point/affect 回包；幻化分支在 40250 源码中没有对应协议，应继续标记为 CUSTOM，而不是 parity 已实现。
• EquipModel 存在由 equipment 状态刷新强化光效的路径，但本轮没有证明 refine 后 GC_ITEM_UPDATE 与 character part/模型资源更新按 40250 顺序触发，资源失败和清理也未闭合。

Round conclusion

本轮仍为 PARTIAL：旧/新版 refine 解析已确认存在，强化/DS 基础包和局部 UI 测试通过；但取消 sentinel 是明确失败点，本地属性/镶嵌/时装/幻化旁路仍绕过服务器权威结果，真实 item/point/affect/actor 更新和失败清理尚未与 40250 统一。本轮未修改实现代码。

Next audit round 2026-09-20T18:19Z

本轮对强化/镶嵌/时装链进行一次入口级复核，重点验证 UI 认为“已发出”的请求是否真的能穿过 native 层：

• RefineUI.cancel_refine() 按 40250 发送 client.refine(255, 255)，但 M2Client::refine（extension/src/net/m2_client.cpp:2351-2356）要求 pos >= 0 && pos < INVENTORY_MAX_NUM，因此取消请求在 native 入口直接返回 false；ClassicSession::send_refine 的字节编码能力无法弥补这个前置门。现有 test_refine_parity.gd 使用 fake client，不能捕获该失败。
• RecvRefineInformationPacket（95）和 RecvRefineInformationPacketNew（119）均已在 parser 中存在，本轮没有把此前的“旧包完全缺失”继续列为事实；但旧版真实字节 fixture、type=0 的 UI 分支和强化后 GC_ITEM_UPDATE/point/affect/actor 更新顺序仍没有证据。
• ItemAttrSystem、ItemEnchantSystem、JewelrySocketSystem、CostumeSystem 仍直接修改传入字典、属性、socket、金币或本地剩余时间；40250 客户端对应入口只做 ItemData 校验并发 CG_ITEM_USE/CG_ITEM_USE_TO_ITEM，结果由服务器回包驱动。局部脚本测试通过不能证明这两条链统一。

本轮没有修改实现代码。合同继续为 PARTIAL，其中取消 sentinel 是可直接复现的协议级差异，优先级高于继续增加本地属性公式测试。

Status

PARTIAL。强化窗口已有可用的新版协议骨架和本地 UI 回归；属性、socket、时装和幻化的本地脚本测试通过，实际实现仍主要是本地字典状态机，尚未复现 40250 的 ItemManager→CG 请求→服务器权威结果→GC item/actor/model 更新完整链路。

Implementation fix round 2026-09-21

• mtnet::bounds::refine_request 与 M2Client::refine 现在保留普通库存位置校验，同时按 40250 接受强化取消哨兵 (255,255)；net_bounds_test 覆盖普通位置、哨兵和非法混合值。
• test_refine_parity.gd/guild_refine_test.gd 仍证明 UI 会发出取消调用；native 回归现在证明该调用不会在入口被错误拦截。真实服务器回包、旧版 95 字节 fixture 和强化后权威 item/point/actor 顺序仍待补齐。
• EntityStore 的正 HP 点数更新会清除 dead，M2Client 会重置 dead_seen，保证复活后下一次死亡可以再次发出 entity_dead。

本合同继续为 PARTIAL：本轮只修复了可直接验证的协议边界和死亡状态边沿，没有把本地属性/镶嵌/时装旁路误标为 40250 等价实现。

2026-09-22 死代码删除

以下文件只被自身测试引用、运行时从不加载，已删除；本文中以它们为实现或证据的结论作废，相关行为需按 40250 源码单元重新移植：costume_attr_transfer_system.gd, costume_system.gd, item_enchant_system.gd, jewelry_socket_system.gd, refine_effect_system.gd, test_costume_attr_transfer_parity.gd, test_costume_system_parity.gd, test_item_enchant_manager_parity.gd, test_jewelry_socket_parity.gd, test_refine_effect_parity.gd, test_wardrobe_transmog_parity.gd, wardrobe_transmog_system.gd。