常见状态
核对 UNKNOWN
- 用
/km inspect <操作ID>查询参与玩家、金额/物品、来源节点、会话与执行阶段；查看物品摘要和该操作的管理修复前后记录，保留外部日志或交易凭证。 - 分清操作是在外部执行前失败、已经生效，还是证据不足。
UNKNOWN不等于失败，也不等于可以再扣一次。 - 使用管理员命令明确登记成功或失败及原因。证据不足时继续保留，不通过直接改钱包值掩盖差异。
- 检查余额冻结、领取区和审计记录，再通知玩家结果。
PREPARED 仍是准备／执行中的记录，只能查看和刷新，不能提前登记为成功或失败。执行许可、调用返回和最终账本状态分别展示；有结束回执也不等于外部结果已足够确定。经济调用超时后不会重复提交原调用，迟到回执只补充核对证据、保留 UNKNOWN，不会自动入账、退款或补发。
执行未确认结束、且来源节点仍活跃时，EXECUTION_IN_FLIGHT 会阻止核对，即使管理员选择失败也不能释放资产。来源离线后若缺少结束回执，系统要求单独声明：已停止来源节点，并核实外部经济请求不再在途。只有明确点击声明并再次确认结果后才能登记，声明与处理原因进入审计；租约失效、玩家当前余额或“等了一会”都不能替代这些核验。
可用 /km admin <玩家UUID或在线名> 交叉检查同一玩家的钱包、资产全部状态、订单和历史。离线玩家使用完整 UUID；名字仅解析本服在线玩家。这里是只读审计入口，不提供代领、改余额或通用发币操作。证据页只展示可解释字段，缺失的历史资料会明确标注，不以原始序列化内容代替结论。
备份与迁移
迁移前停止所有旧节点的市场写入，妥善处理或登记未完成操作。备份完整数据库和plugins/KiteMarket/ 配置；网络身份、币种定义、钱包、订单、托管物品及操作记录必须一起保留。
GUI 偏好位于独立 InnoDB 表 km_ui_preferences 和 km_ui_theme_selections，均按网络＋玩家 UUID 保存模式或主题 ID 与数据库更新时间。没有偏好记录为 AUTO，没有主题记录使用所选后端的服务器默认主题。启动通过迁移入口创建，不改变金融表结构版本或快照格式 2。使用固定表清单的备份／恢复工具要纳入两表；不要只迁移金融表而遗漏玩家选择。旧主题 ID 保留读取，缺少对应主题时回退，不改写原偏好。
恢复时先在隔离环境验证数据库和插件，再逐个接入节点。服务器 Minecraft 版本、市场协议、物品配置与币种定义要一致；每个节点 ID 保持唯一。确认旧节点不会继续写入后再开放新网络。
当前数据库模式版本为 1，启动会校验该值和 InnoDB 引擎。升级前先清查未结束订单、领取资产和 PREPARED/UNKNOWN 操作，再备份并在隔离库验证。没有已定义的跨模式自动降级流程，不能用旧 JAR 或部分恢复绕过版本检查。
更换插件 JAR 时仍需全网正常停服、完整备份并统一构件；只有界面改动时，不需要协议升级或清空现有资产。默认采用暖色布局，旧自定义槽位自动使用兼容布局，无效候选保持当前设置。自动顺序为 IA→原版，默认不指定 IA 主题；旧偏好和配置不自动重写。第三方主题无需额外的 KiteMC 主题授权，已有实测范围见兼容说明。
如果数据库中已有 km_dlc_proofs 等扩展表，仍纳入完整 km_* 备份／恢复。已安装的主题资源、证明或密文缓存应随对应构件备份，不自动删除或混用旧加载器。密钥缓存属于私有运维数据，不能放入公开下载。
第三方主题从 plugins/KiteMarket/themes/ 加载，迁移需保留主题声明和各自资源。用 /km ui 查看实际界面与回退原因；资源包内容改变后，登记新的实际下发 UUID 和对应 SHA-1，再 /km reload。同一已登记 UUID 换摘要会被拒绝。主题不可用只影响呈现，不撤单或释放市场冻结资金；具体步骤见ItemsAdder 接入和界面 SDK。
不要只恢复订单表，不要只回滚某一节点配置，不要把生产库同时接到克隆测试服。货币精度或外部后端变化需专门对账迁移。跨 Minecraft 版本转换不属于首版能力。
升级已有市场到协议 4
协议4构件保存出售订单的最低购买量，出售仍使用每件单价、部分购买，拍卖按整标总价。协议由构件确定，不能混用节点或通过热重载切换。数据库模式版本为1，物品快照格式为 2，网络授权使用 HTTP v2；这些编号分别检查。新市场无需迁移字段。具体实测范围以兼容说明为准，升级规则不等于所有组合已经通过验收。
已有协议1、2或3市场均采用以下严格升级步骤，不保留开放订单或托管交易：
- 用旧构件清查钱包、领取箱、开放订单和
PREPARED/UNKNOWN操作。先核对未知副作用，不能盲目补发或退款。 - 通过已验证的授权清退流程进入
EXIT_ONLY，等待未成交订单、拍卖、冻结资金和托管状态全部清退。可用钱包余额与待领物品可以保留。 - 正常停止所有节点，备份完整
km_*数据、各节点plugins/KiteMarket/和原 JAR，验证可还原，并等待所有节点租约失效。 - 首个节点显式配置实际来源
network.upgrade-from-protocol: '3'；实际来源为1或2时分别填写'1'或'2'。将所有节点替换为协议4构件，保持 Minecraft 版本、币种、network.name、network.item-profile一致。来源协议必须准确，不能同时修改币种或物品环境。 - 先启动一个节点。升级只在旧身份完全匹配、市场为
EXIT_ONLY、无有效节点租约、开放订单、冻结资金、PREPARED/UNKNOWN操作，以及ESCROW/DELIVERING物品时进行。身份更新、全部旧节点代次和会话失效、PROTOCOL_UPGRADE审计在同一数据库事务提交，保留网络 UUID、授权绑定、可用钱包、待领快照及历史。租约过期但仍存活的旧节点不能重新心跳或取得会话。 - 验证 UUID、余额、待领资产和授权后，移除临时升级字段，再启动其他新节点。授权恢复后可重新开放市场；已清退订单不会复活。
原始快照与属性比较
新物品快照格式为2。data 保存服务器产生的原始字节，rawDigest 单独校验完整性；属性比较的 fingerprint 忽略数量。原有格式 1 快照不自动重写，仍保留原摘要校验和资产退出。
属性比较只忽略 typed-NBT compound 的字段键序，以及旧版根 tag.Enchantments / tag.StoredEnchantments 中具有唯一字符串 id 的原版附魔条目顺序。名称、Lore、其他列表（包括 PDC 列表）、数据类型、数值、字符串和数组内容仍参与比较。损坏、歧义或超出解析预算的数据会拒绝，不退回宽松匹配。
比较不会改写实际托管物品；领取仍还原原始快照。原始字节完整性与属性等价是独立检查，也不开放玩家自定义 NBT 表达式。验证记录列出准确构件和场景。
支持名单收紧与已有资产
新交易目前只接受经过样本验证的基础UNSPECIFIC、附魔书 ENCHANTED 类型和已验证属性键。药水、书、头颅、地图、特殊盔甲及其他未验证类型会明确拒绝；精确样品不能绕过这道准入。PDC 等已经验证、但高级条件无法解释的数据仍需精确样品。
准入只限制新增样品、发布、供货与托管。已有物品的还原、撤单返还、清退和领取保留，继续检查快照格式、摘要与来源游戏版本；不能因支持名单收紧销毁或永久锁住旧资产。类型准入也不等于整个版本、跨服或经济组合已认证，实际范围见认证状态。
最小验证清单
使用隔离测试玩家和少量测试资产覆盖收购、一口价、竞拍、双节点同时操作、充提、满背包领取和重启恢复。测试完回收测试资产与记录，保留有用的验收结果。详细平台范围见认证状态。 上述清单适用于新环境启用或相关功能改动。界面更新还应检查导航、草稿、金额输入、资源包拒绝／失败和第三方主题回退。使用隔离角色与订单，不重置现有玩家资产。开发者只读接口
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。通知可能延迟，启动前历史不补发，也不是恰好一次或可靠补发接口；消费者应查询权威状态。