mtgodot-poc/audit/contracts/npc.dialog-shop.md

# npc.dialog_shop

## Scope

审计 NPC 点击与脚本对话、普通 NPC 商店、扩展多货架商店、购买/出售、商店错误和结束清理，以及个人商店招牌、点击打开、摆摊编辑和关闭流程。判断标准是当前端是否复现 40250 的服务端货架数据来源、全局槽位索引、NPC/玩家商店分支、动作门控、请求包副作用和失败清理，而不是本地 helper 是否能算出一个价格或库存结果。

## Reference call chain

- `UserInterface/PythonNetworkStreamPhaseGame.cpp`
  - `RecvShopPacket` 处理 `START`、`START_EX`、`END`、`UPDATE_ITEM`、`UPDATE_PRICE` 与错误子包；普通商店固定读取 40 个槽位，多货架按 tab 读取每个货架的名称、货币类型和 40 个槽位。
  - `CPythonShop::SetItemData(globalIndex, item)` 将增量更新的全局位置映射为 `tabIdx = globalIndex / SHOP_HOST_ITEM_MAX_NUM`、`slot = globalIndex % SHOP_HOST_ITEM_MAX_NUM`，因此多货架位置不是永远落在 tab 0。
  - `SendOnClickPacket` 发送 NPC/个人商店点击请求并追加 sequence；脚本回包通过事件管理器打开对话窗口。
  - `RecvShopSignPacket` 将玩家商店招牌绑定到已有角色实体；个人商店广告牌点击后由 `uiprivateshopbuilder.py` 发送 `SendOnClickPacket(vid)`。
- `UserInterface/PythonNetworkStreamPhaseGameItem.cpp`
  - `SendShopEndPacket`、`SendShopBuyPacket`、`SendShopSellPacket` 和 `SendShopSellPacketNew` 都先经过 `__CanActMainInstance()`，再写 `CG_SHOP` 子头、槽位/数量并 `SendSequence()`。
  - 购买包使用数量 1 加显示位置；出售分旧版单槽包和新版槽位+数量包。结果、金币、背包和售罄状态由服务器回包更新。
- `UserInterface/PythonShop.cpp`、`Client/Eternexus/root/uishop.py`
  - `CPythonShop` 保存所有 tab 和全部 40 个位置，普通、NPC 扩展、多货架和个人商店由窗口状态区分。
  - `ShopDialog.Open(vid)` 根据 NPC、他人玩家和主角自己的商店分别显示买卖、货架或关闭控件；自己商店不能走买卖分支。
  - 左键购买有确认，右键/取消选中可直接购买；出售检查反出售标记、贵重物品确认并发送服务端请求。
- `Client/Eternexus/root/uiprivateshopbuilder.py`、`PythonShop.cpp`、`Packet.h`
  - 摆摊最多 39 个商品，商品按展示位置排序，源物品位置和价格由服务端消费；标题有长度限制，禁止状态和 anti flag 在提交前检查。
  - `BuildPrivateShop` 发送 `CG_MYSHOP`，关闭自己的摊位也使用相应的个人商店协议语义。
- `PythonNonPlayer.cpp`、`PythonPlayerInput.cpp`、`PythonPlayerInputMouse.cpp`
  - NPC/商店点击由实体类型、可点击状态和距离/输入流程进入 `SendOnClickPacket`；个人商店广告牌是可点击的独立入口，不等同于普通 PC 攻击或选中。

## Current call chain

- `project/net_play.gd::_on_pick` 对 NPC/WARP 走 `click_npc`，有距离预约和同 VID 节流；但没有对带 `shop_sign` 的 PC 建立 40250 广告牌点击分支，当前 `project/net_world.gd::_refresh_shop_sign` 只创建显示用 `Label3D`。
- `project/ui/quest_dialog.gd` 和网络事件可以承接脚本/对话显示；`extension/src/net/m2_client.cpp::click_npc`、`classic_session.cpp::send_click_npc` 能发送基础点击包。
- `extension/src/net/entity_store.cpp` 已解析普通 `START`、扩展 `START_EX`、`END`、更新和常见错误，并保存商店 VID、tab 和 item；但 `mut_shop_update_item` 拒绝 `pos >= 40`，且多 tab 时只更新 tab 0，未复现 40250 的全局位置映射。
- `project/ui/shop_ui.gd` 有买/卖模式、40 格、多货架、确认框、距离关闭和右键购买；但是 `_drop_to_sell` 在购买模式下仍继续执行出售请求，当前 `project/complex_item_drop_test.gd` 已复现该失败。
- `ShopUI.refresh` 没有根据 `shop.vid` 区分主角自己的个人商店、他人个人商店和 NPC 商店，因此当前买/卖按钮状态不等价于 `ShopDialog.Open`。
- `project/npc_shop_system.gd` 使用硬编码 NPC 库存与本地 `buy_item`/`sell_item` 直接修改金币和背包；它不是 `CPythonShop` 的服务器货架回包链，且目前主要由孤立 parity 测试使用。
- `project/private_shop_system.gd` 同样是本地 stock/价格 helper；live `project/ui/private_shop_ui.gd` 能提交 `M2Client.open_private_shop`，但未在 live 提交前统一调用死亡、骑乘、战斗状态和 50200 摆摊道具校验。
- `M2Client::shop_buy`、`shop_sell` 只做 in-game、u8 和数量边界，缺少 40250 的 `__CanActMainInstance`、实际物品/anti flag/商店状态门控；`open_private_shop` 只验证字段 wire bounds 与最多 39 条。
- `classic_session.cpp` 的买卖、关闭和个人商店包布局及 sequence 基础存在；现有 native 测试验证布局，但没有真实 `GC_SHOP` 多阶段包和失败回包驱动的 UI 状态测试。

## Branch matrix

| 场景 | 40250 | 当前端 | 结论 |
|---|---|---|---|
| NPC 点击/脚本对话 | 实体输入、距离和 `SendOnClickPacket` 后由服务器脚本回包驱动 | NPC 点击、距离预约、节流和基础点击存在 | PARTIAL：事件/脚本结果与异常清理缺真实包覆盖 |
| 普通商店 START | 服务器提供 VID 和固定 40 格，空槽也有确定位置 | 能解析并保存非空 item，UI 补 40 格 | PARTIAL：空槽原始状态和真实 UI 回包顺序未证明 |
| START_EX 多货架 | 每 tab 40 格，更新位置是全局 `tab*40+slot` | 初始 tab 能显示；增量更新限制 `<40` 且只更新 tab 0 | GAP |
| 商品更新/售罄/错误 | `SetItemData`、价格更新、错误事件和 UI 刷新 | 基础错误字符串和刷新存在 | PARTIAL：更新索引和回包失败后 UI/金币/库存清理不足 |
| 买入 | `__CanActMainInstance`→CG_SHOP/BUY→sequence→服务器结果 | UI/native 能发买包并有确认 | PARTIAL：缺动作门控、pos 全范围和服务器结果闭环 |
| 卖出/批量卖出 | anti-sell/贵重确认后旧 SELL 或 SELL2，服务端扣物品加金币 | UI 有部分 anti flag/确认；native 只做 u8 边界 | PARTIAL：购买模式拖入仍可出售，实际库存/服务端回包未闭环 |
| 自己的个人商店 | 隐藏买卖，只显示关闭；个人商店协议关闭自己的摊位 | ShopUI 主要按普通买卖模式显示，未按 shop VID 统一区分 | GAP |
| 他人个人商店/招牌 | 广告牌点击发送 `SendOnClickPacket(vid)` 后打开玩家商店 | 招牌目前只有 `Label3D`，PC 点击未路由到点击商店 | GAP |
| 摆摊编辑/提交 | 39 条、标题/禁止状态/anti flag/源物品校验后 `CG_MYSHOP` | UI/Native 字段和数量限制存在 | PARTIAL：live 状态校验和服务端消费/拒绝反馈不足 |
| 关闭/离开/断线 | `END` 清理访问商店；个人商店关闭遵循独立协议语义 | 基础 close 和本地 UI 关闭存在 | PARTIAL：访问商店、自己的摆摊和断线/乱序清理未统一验证 |

## Implementation-equivalence matrix

| 项目 | 状态 | 证据/限制 |
|---|---|---|
| Preconditions | PARTIAL | NPC 距离和部分 UI anti flag 存在；native 买卖缺 `__CanActMainInstance`、真实物品/商店状态和动作门控，摆摊 live 缺死亡/骑乘/战斗及 bundle 校验 |
| Branch structure | PARTIAL | 普通商店、多货架、购买确认和脚本对话分支存在；自己的个人商店、玩家招牌点击和购买模式拖放分支不等价 |
| Algorithms/formulas | PARTIAL | 货架槽位和价格由协议保存；硬编码 NPC stock、本地买卖 helper 和本地出售价格不是 40250 的服务端权威实现 |
| State transition order | GAP | 参考是请求→服务端判定→item/gold/shop update/error→UI 刷新；本地 helper 可直接改库存/金币，且 UI 购买模式错误放行出售 |
| Constants/units | PARTIAL | 40 格、最多 3 tab、最多 39 条、标题/招牌和字段 wire bounds 基本存在；全局多 tab 更新范围未实现，价格/数量服务端约束未闭合 |
| Timing/event sources | PARTIAL | 点击节流、距离关闭、确认框和 shop signal 存在；真实 START→UPDATE→ERROR/END 时序、招牌点击和重复请求未覆盖 |
| Resource/data sources | GAP | 40250 商品库存来自服务器 `CPythonShop`/item data；当前 `NpcShopSystem` 额外维护硬编码本地库存，和 live authority 不是同一数据源 |
| Protocol side effects | PARTIAL | CG_SHOP、CG_ON_CLICK、CG_MYSHOP 的基础布局和 sequence 存在；动作门控、个人招牌点击和完整错误/结果副作用不完整 |
| Interruption/failure/cleanup | GAP | 购买模式拖放泄漏到出售；多 tab 更新可能落错/丢失；断线、拒绝、售罄、自己摊位关闭和未找到实体的招牌清理没有统一端到端回滚 |

## Regression evidence

- `project/test_npc_shop_parity.gd`：26/26 通过，但主要验证硬编码 `NpcShopSystem` 的本地库存、金币和背包变化，不能作为 40250 服务器商店等价证明。
- `project/test_npc_shop_flow.gd`：NPC 点击距离/节流、UI 多 tab/右键购买和距离关闭通过；使用 fake client，未覆盖真实 GC shop 包。
- `project/test_npc_dialog_shop_ui_parity.gd`：窗口尺寸、格子、按钮、脚本对话与 fake client 通过；没有多 tab 全局更新和 PC 招牌点击。
- `project/private_shop_ui_test.gd`、`project/test_private_shop_bundle_parity.gd`、`project/shop_rules_test.gd`、`project/p8_test.gd`：本地摆摊编辑与规则通过；未证明 live UI 的状态门控、`CG_MYSHOP` 服务端拒绝/关闭和招牌打开。
- `project/complex_item_drop_test.gd`：当前有 1 项失败，购买模式仍允许把背包物品拖到商店出售目标；这是可复现的实现回归。
- `build/extension/net_classic_session_test`、`build/extension/net_entity_test`：基础 packet/store 行为通过，但没有 `START_EX` 位置 40..119 的更新回归，也没有完整错误/结束/重新打开序列。

## Deep audit round 2026-09-21

### Fresh regression results

- `godot --headless --path project --script test_npc_shop_parity.gd`：退出码 0，26/26 通过；覆盖的是 `NpcShopSystem` 的本地库存、价格、金币和背包 helper。
- `godot --headless --path project --script test_npc_shop_flow.gd`：退出码 0，38 项通过；覆盖 NPC 距离/预约/节流、fake shop 多货架 UI、右键购买和距离关闭，没有真实 `GC_SHOP START_EX/UPDATE/ERROR/END` 包。
- `godot --headless --path project --script test_npc_dialog_shop_ui_parity.gd`：退出码 0；窗口、40 格、买卖按钮、脚本对话和 QuestCurtain 通过，仍使用 fake client。
- `godot --headless --path project --script private_shop_ui_test.gd`、`test_private_shop_bundle_parity.gd`、`shop_rules_test.gd`、`p8_test.gd`：均退出码 0；本地摆摊规则、bundle、价格和社交窗口通过，不等价于真实 `CG_MYSHOP`/个人商店招牌/失败回包。
- `godot --headless --path project --script complex_item_drop_test.gd`：退出码 1；购买模式下卖出目标仍错误接受背包物品拖放。
- `build/extension/net_classic_session_test` 与 `build/extension/net_entity_test`：退出码 0；基础包/store 行为通过，但没有覆盖多货架全局位置 40..119 的增量更新。

### Static parity findings

- 40250 `START_EX` 的每个 tab 固定 40 格，`UPDATE_ITEM` 使用全局位置 `tab * 40 + slot`；当前 `EntityStore::mut_shop_update_item` 仍要求 `pos < 40`，并且只更新 `m_shop_tabs[0]`，所以 tab 1+ 的增量回包会被丢失或落错货架。
- `ShopUI::_drop_to_sell` 没有以 `_mode == 2` 作为硬门，购买模式拖拽仍能调用 `_request_sell`；这与 `ShopDialog` 的买/卖分支不一致，也是本轮失败测试的直接原因。
- 40250 `ShopDialog.Open(vid)` 按 NPC、他人个人商店和自己的个人商店分支显示；当前 `ShopUI` 主要按通用买卖窗口处理，未以 `shop_vid` 和主角 VID 做统一分支，自己的摊位与他人摊位行为仍可能混用。
- `shop_sign` 在 native/entity store 中有保存和显示数据，但 `NetPlay::_on_pick` 没有完整复刻 `SendOnClickPacket(shop_vid)` 的个人商店广告牌分支；显示招牌不等于可打开玩家商店。
- `NpcShopSystem`、`PrivateShopSystem` 等本地 helper 可以直接修改金币、库存和 stock；live UI 的 native 请求路径存在，但两套权威来源并存，测试通过不能证明服务端回包覆盖本地结果。
- `M2Client::shop_buy/shop_sell/shop_close/open_private_shop` 的基础 wire bounds 存在，但没有统一 `__CanActMainInstance`、商店状态、实际 item/anti-flag 和重复/失败请求门控；`SendSequence`/错误/售罄/重开顺序也未由真实 fixture 验证。

### Round conclusion

本轮仍为 `PARTIAL`：NPC 点击、普通商店 UI、基础买卖/摆摊包和局部规则测试可运行，但多货架增量索引、购买模式拖放门、个人商店招牌/自有摊位分支和服务器权威回包仍未统一；本轮未修改实现代码。

## Status

`PARTIAL`。NPC 点击、基础对话承接、普通/扩展商店协议骨架、购买出售 UI 和个人商店字段已经存在，但当前端仍有明确的多 tab 更新索引错误、购买模式错误放行出售、个人商店招牌不可点击打开、自己商店状态不分支、native 动作门控缺失以及本地硬编码库存/金币旁路。已完成审计并记录，未修改实现代码。

### 2026-09-22 死代码删除

以下文件只被自身测试引用、运行时从不加载，已删除；本文中以它们为实现或证据的结论作废，相关行为需按 40250 源码单元重新移植：`npc_shop_system.gd`, `private_shop_system.gd`, `test_npc_shop_parity.gd`, `test_private_shop_bundle_parity.gd`。