故障处理与安全迁移

处理资金或物品问题时先保留操作 ID、玩家 UUID、节点、时间、订单 ID 与错误代码。先暂停相关写入并核查，避免同一请求被反复提交。

常见状态

现象	处理
页面过期、订单数量或价格变化	重新打开订单再确认，不绕过版本检查
INVENTORY_FULL	留出背包空间后领取；不要在世界里补发同一物品
GATEWAY_NODE	切换到该货币配置的充提节点
UNCERTIFIED_PROVIDER_VERSION	核对实际插件版本并完成测试；不直接添加未知版本
PROVIDER_API_INCOMPATIBLE	停用充提，确认 provider 与发行版；不要用其他适配器顶替
UI_BACKEND_RETIRED	旧萌芽／龙核偏好或主题没有自行注册的实际提供者；保留偏好并使用原版，可在 /km ui 改选当前原版或IA
IA_PACK_NOT_REGISTERED / IA_PACK_NOT_APPLIED	核对实际下发的 UUID、SHA-1与玩家成功加载；可临时启用 gui.itemsadder.diagnostics，不把无关包或仅接受状态当作就绪
旧开发包出现 DLC_NAMESPACE_CHANGED / DLC_INSTALLED_PACKAGE_INVALID	官方主题已取消；保留旧命名空间和备份，不删除目录绕过校验。改选原版或自己的 IA 主题，历史文件不影响第三方主题与市场资产
UNKNOWN	停止重放，查操作详情和外部证据，由管理员确认结果
EXECUTION_IN_FLIGHT	来源节点仍活跃且调用尚未确认结束，不能退款或补发；先等待真实完成回执或处理来源节点
SOURCE_QUIESCENCE_REQUIRED	来源离线不代表调用已经停止；核实停止来源及外部请求不再在途后，才在单独声明页继续确认
EXECUTION_WINDOW_EXPIRED	该次执行许可启动窗口已过，未开始新的扣物/发物/经济调用；先检查操作结果，再重新确认
数据库不可用	恢复数据库后再开放；禁止让不同节点独立继续成交
NODE_ALREADY_RUNNING	检查是否重复使用节点 ID；正常停服后的短暂租约等待不等于资产丢失
NODE_FENCED	本节点已失去写入租约；核查重复节点和旧进程后重启，不让旧节点自动抢回身份
UNVERIFIED_SPECIAL_ITEM / UNVERIFIED_ITEM_DATA	该类型或属性尚未进入新交易支持名单；精确样品不能绕过准入，已有托管资产仍可安全退出
PROTOCOL_UPGRADE_REQUIRES_EXIT	先用旧构件完成授权清退，不能在开放市场直接升级协议
PROTOCOL_UPGRADE_NOT_QUIESCENT	检查有效节点租约、开放订单、冻结资金、待核对操作及托管/交付中的物品；不要删除记录绕过检查
许可证进入退出模式	保留查询、取消和资产退出，核查凭据、到期与网络绑定

核对 UNKNOWN

1. 用 /km inspect <操作ID> 查询参与玩家、金额/物品、来源节点、会话与执行阶段；查看物品摘要和该操作的管理修复前后记录，保留外部日志或交易凭证。
2. 分清操作是在外部执行前失败、已经生效，还是证据不足。UNKNOWN 不等于失败，也不等于可以再扣一次。
3. 使用管理员命令明确登记成功或失败及原因。证据不足时继续保留，不通过直接改钱包值掩盖差异。
4. 检查余额冻结、领取区和审计记录，再通知玩家结果。

PREPARED 仍是准备／执行中的记录，只能查看和刷新，不能提前登记为成功或失败。执行许可、调用返回和最终账本状态分别展示；有结束回执也不等于外部结果已足够确定。经济调用超时后不会重复提交原调用，迟到回执只补充核对证据、保留 UNKNOWN，不会自动入账、退款或补发。

执行未确认结束、且来源节点仍活跃时，EXECUTION_IN_FLIGHT 会阻止核对，即使管理员选择失败也不能释放资产。来源离线后若缺少结束回执，系统要求单独声明：已停止来源节点，并核实外部经济请求不再在途。只有明确点击声明并再次确认结果后才能登记，声明与处理原因进入审计；租约失效、玩家当前余额或“等了一会”都不能替代这些核验。

可用 /km admin <玩家UUID或在线名> 交叉检查同一玩家的钱包、资产全部状态、订单和历史。离线玩家使用完整 UUID；名字仅解析本服在线玩家。这里是只读审计入口，不提供代领、改余额或通用发币操作。证据页只展示可解释字段，缺失的历史资料会明确标注，不以原始序列化内容代替结论。

备份与迁移

迁移前停止所有旧节点的市场写入，妥善处理或登记未完成操作。备份完整数据库和 plugins/KiteMarket/ 配置；网络身份、币种定义、钱包、订单、托管物品及操作记录必须一起保留。 界面改版新增独立 InnoDB 表 km_ui_preferences 和 km_ui_theme_selections，均按网络＋玩家 UUID 保存模式或主题 ID 与数据库更新时间。没有偏好记录为 AUTO，没有主题记录使用所选后端的服务器默认主题。启动按既有迁移入口创建，不改变已有金融表结构版本、协议3或快照格式2。使用固定表清单的备份／恢复／精确清理工具要纳入两表；不要只迁移金融表而遗漏玩家选择。历史 official.market-stall／market-stall 选择保留兼容读取，不再作为默认主题或发布功能。

恢复时先在隔离环境验证数据库和插件，再逐个接入节点。服务器 Minecraft 版本、市场协议、物品配置与币种定义要一致；每个节点 ID 保持唯一。确认旧节点不会继续写入后再开放新网络。

当前数据库模式版本为 1，启动会校验该值和 InnoDB 引擎。升级前先清查未结束订单、领取资产和 PREPARED/UNKNOWN 操作，再备份并在隔离库验证。没有已定义的跨模式自动降级流程，不能用旧 JAR 或部分恢复绕过版本检查。 界面开发包替换仍需全网正常停服、完整备份并统一构件，不需要协议升级或清空现有资产。新增配置默认选择暖色布局，旧自定义槽位自动保留兼容布局；无效候选保持当前设置。当前保留原版＋ItemsAdder v4兼容，自动顺序为IA→原版；默认不指定 IA 主题。萌芽／龙核接入已取消，旧偏好、配置和 SDK 扩展位置保留，不自动重写用户选择。第三方自由界面无需官方 DLC；官方 Market Stall 主题开发与上架已取消。固定组合已有真实界面检查，证据范围见兼容说明。

历史开发包的 km_dlc_proofs 保存网络内独立 DLC 证明的绑定代次、序号与签名证据，已有此表时仍纳入完整 km_* 备份／恢复。已安装的 DLC 密文、证明缓存和 plugins/ItemsAdder/contents/km_market_stall/ 保留作历史或回滚资料，不因取消产品自动删除。密钥缓存属于私有运维数据，不能放入公开下载。

第三方主题从 plugins/KiteMarket/themes/ 加载，不调用历史官方 DLC 安装接口；迁移需保留主题声明和各自资源。用 /km ui 查看实际界面与回退原因，重建 ItemsAdder 资源包改变内容后，登记新的实际下发 UUID 和对应 SHA-1，再 /km reload；同一已登记 UUID 换摘要会被拒绝。主题或历史 DLC 状态不会撤单、释放市场冻结资金或封锁社区主题；具体步骤见ItemsAdder 接入和界面开发。

历史官方安装曾使用签名字节校验及可选 PNG像素摘要；保留对应构件、命名空间和私有缓存供回滚，不能假定优化后的安装兼容旧加载器。该流程不再用于新官方主题发行，也不要求第三方主题沿用它。

不要只恢复订单表，不要只回滚某一节点配置，不要把生产库同时接到克隆测试服。货币精度或外部后端变化需专门对账迁移。跨 Minecraft 版本转换不属于首版能力。

协议 1 或 2 升级到协议 3

1.0.0 使用市场协议 3；准入修复后的历史构件使用协议 2，更早构件使用协议 1。协议由构件确定，不能混用节点或通过热重载切换。数据库模式版本仍为 1，网络授权仍使用 HTTP v2；这些编号与物品快照格式分别检查。新市场无需迁移字段。

已有协议 1 或 2 市场的升级步骤：

1. 用旧构件清查钱包、领取箱、开放订单和 PREPARED / UNKNOWN 操作。先核对未知副作用，不能盲目补发或退款。
2. 通过已验证的授权清退流程进入 EXIT_ONLY，等待未成交订单、拍卖、冻结资金和托管状态全部清退。可用钱包余额与待领物品可以保留。
3. 正常停止所有节点，备份完整 km_* 数据、各节点 plugins/KiteMarket/ 和原 JAR，验证可还原，并等待所有节点租约失效。
4. 首个节点显式配置 network.upgrade-from-protocol: '2'；如果实际旧协议为 1，则填写 '1'。将所有节点替换为协议 3 构件，保持 Minecraft 版本、币种、network.name、network.item-profile 一致。来源协议必须准确，不能同时修改币种或物品环境。
5. 先启动一个节点。升级只在旧身份完全匹配、市场为 EXIT_ONLY、无有效节点租约、开放订单、冻结资金、待核对操作，以及 ESCROW / DELIVERING 物品时进行。身份更新、全部旧节点代次和会话失效、PROTOCOL_UPGRADE 审计在同一数据库事务提交，保留网络 UUID、授权绑定、钱包、真实物品快照及历史。租约过期但仍存活的旧节点不能重新心跳或取得会话。
6. 验证 UUID、余额、待领资产和授权后，移除临时升级字段，再启动其他新节点。授权恢复后可重新开放市场；已清退订单不会复活。

检查失败时保留记录并排查，不篡改身份摘要或数据库租约。旧构件接入已升级网络会被拒绝。协议 3 没有自动降级路径；回滚须全网停服，核对升级后资产变化，再恢复同一时间点的完整数据库及匹配配置/JAR。不能把旧 JAR 接到已经发生新交易的数据库。

原始快照与属性比较

新物品快照格式为 2。data 保存服务器产生的原始字节，rawDigest 单独校验完整性；属性比较的 fingerprint 忽略数量。原有格式 1 快照不自动重写，仍保留原摘要校验和资产退出。

属性比较只忽略 typed-NBT compound 的字段键序，以及旧版根 tag.Enchantments / tag.StoredEnchantments 中具有唯一字符串 id 的原版附魔条目顺序。名称、Lore、其他列表（包括 PDC 列表）、数据类型、数值、字符串和数组内容仍参与比较。损坏、歧义或超出解析预算的数据会拒绝，不退回宽松匹配。

比较不会改写实际托管物品；领取仍还原原始快照。原始字节完整性与属性等价是独立检查，也不开放玩家自定义 NBT 表达式。既有认证记录保留准确构件和场景；本轮不重复未改动的物品或交易全量测试。

支持名单收紧与已有资产

新交易目前只接受经过样本验证的基础 UNSPECIFIC、附魔书 ENCHANTED 类型和已验证属性键。药水、书、头颅、地图、特殊盔甲及其他未验证类型会明确拒绝；精确样品不能绕过这道准入。PDC 等已经验证、但高级条件无法解释的数据仍需精确样品。

准入只限制新增样品、发布、供货与托管。已有物品的还原、撤单返还、清退和领取保留，继续检查快照格式、摘要与来源游戏版本；不能因支持名单收紧销毁或永久锁住旧资产。类型准入也不等于整个版本、跨服或经济组合已认证，实际范围见认证状态。

最小验证清单

使用隔离测试玩家和少量测试资产覆盖收购、一口价、竞拍、双节点同时操作、充提、满背包领取和重启恢复。测试完回收测试资产与记录，保留有用的验收结果。详细平台范围见认证状态。

上述清单用于新环境启用或相关功能改动。IA 兼容改动仅按实际范围定向检查页面、草稿、输入、资源包和第三方主题回退，不重跑未改动的金融事务或版本矩阵，不重置原玩家资产；官方主题与其发行验收已取消。

开发者只读接口

com.kitemc.market.api.KiteMarketApi 在数据库初始化成功后通过 Bukkit ServicesManager 注册。独立 Java 11／MIT SDK 提供网络 ID、币种精度、订单、钱包、领取资产和历史的不可变白名单摘要；没有公开规则匹配、发币、远程充提或通用交易写接口。安装与签名见市场 API 入门。

查询返回 CompletableFuture；不要在游戏主线程或 Folia 玩家线程上调用 join()/get()。原始审计 JSON、物品字节、执行令牌、许可证和恢复证据不外发，返回列表与嵌套对象不可变。读取玩家/背包或更新界面需调度到正确的玩家上下文。

MarketCommittedEvent 仅通知已提交的购买、供货和竞拍胜出，是不可取消的异步事件，返回 TradeSummary 而非原始 JSON。监听者按网络 ID 和事件 ID 去重，并将玩家操作调度到对应 Entity Scheduler。通知可能延迟，启动前历史不补发，也不是恰好一次或可靠补发接口；消费者应查询权威状态。