常见状态
核对 UNKNOWN
- 用
/km inspect <操作ID>查询参与玩家、金额/物品、来源节点、会话与执行阶段；查看物品摘要和该操作的管理修复前后记录，保留外部日志或交易凭证。 - 分清操作是在外部执行前失败、已经生效，还是证据不足。
UNKNOWN不等于失败，也不等于可以再扣一次。 - 使用管理员命令明确登记成功或失败及原因。证据不足时继续保留，不通过直接改钱包值掩盖差异。
- 检查余额冻结、领取区和审计记录，再通知玩家结果。
PREPARED 仍是准备／执行中的记录，只能查看和刷新，不能提前登记为成功或失败。执行许可、调用返回和最终账本状态分别展示；有结束回执也不等于外部结果已足够确定。经济调用超时后不会重复提交原调用，迟到回执只补充核对证据、保留 UNKNOWN，不会自动入账、退款或补发。
执行未确认结束、且来源节点仍活跃时，EXECUTION_IN_FLIGHT 会阻止核对，即使管理员选择失败也不能释放资产。来源离线后若缺少结束回执，系统要求单独声明：已停止来源节点，并核实外部经济请求不再在途。只有明确点击声明并再次确认结果后才能登记，声明与处理原因进入审计；租约失效、玩家当前余额或“等了一会”都不能替代这些核验。
可用 /km admin <玩家UUID或在线名> 交叉检查同一玩家的钱包、资产全部状态、订单和历史。离线玩家使用完整 UUID；名字仅解析本服在线玩家。kitemarket.audit.all 提供只读审计，kitemarket.manage 另行允许管理操作；管理写入必须选择明确目标、填写原因并确认，结果保留审计。
资金补偿消耗管理员实际已有资金，物品操作使用真实持有物或已有资产，不提供任意造币或改写余额的入口。核对未知操作仍需真实执行证据，不能用一笔补偿掩盖原操作。证据页只展示可解释字段，缺失的历史资料会明确标注，不以原始序列化内容代替结论。
备份与迁移
迁移前停止所有旧节点的市场写入，妥善处理或登记未完成操作。备份完整数据库、plugins/KiteMarket/、匹配 JAR，以及玩家、世界和外部经济插件数据。网络身份、币种定义、钱包、订单、托管物品及操作记录必须作为同一环境检查点保留。
v1.1 新建单服默认使用独立 SQLite；多服共享使用 MySQL／MariaDB 的 InnoDB 数据库。SQLite 要通过一致性备份或正常停服、完成 checkpoint 后取得副本。运行中的 -wal／-shm 可能包含未合入主文件的状态，不要只复制主文件或删除这些文件来绕过检查。离线导入和迁移工具要求来源已经停服、完成 checkpoint 且无 sidecar。
GUI 偏好位于 km_ui_preferences 和 km_ui_theme_selections，按网络＋玩家 UUID 保存后端或主题 ID 与数据库更新时间。两种存储模式都要纳入备份；共享模式使用 InnoDB。没有偏好记录为 AUTO，没有主题记录使用所选后端的服务器默认主题。旧主题 ID 保留读取，缺少对应主题时回退，不改写原偏好。
恢复时先在隔离环境验证数据库和插件，再逐个接入节点。服务器 Minecraft 版本、市场协议、物品配置与币种定义要一致；每个节点 ID 保持唯一。确认旧节点不会继续写入后再开放新网络。
v1.0.0 数据库模式版本为 1，启动会校验该值和 InnoDB 引擎。v1.1 使用结构版本 2，共享数据库仍要求事务引擎。迁移前先清查未结束订单、领取资产和 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 版本转换不属于首版能力。
离线导入与存储迁移
从 zAuctionHouse 导入时只读取停服副本，先审核预检、币种映射与真实物品，再确认报告摘要。已有 v1.1 SQLite 市场也可通过离线工具迁到空的共享数据库，保留原网络身份，不与另一市场合并。离线导入与存储迁移
分开了解来源副本、维护暂停、逐项导入，以及 SQLite 转共享数据库的步骤。
v1.1 安装与已有数据准备
v1.1 以全新安装交付，不承诺 v1.0.0 直接换包或无缝升级。新市场使用独立目录和新数据库，运行包见下载页，日常流程见使用指南。 已有数据先按以下步骤准备独立副本：- 正常停止全部旧节点，备份完整数据库、各节点的
plugins/KiteMarket/、旧 JAR，以及玩家、世界和经济插件数据，验证同一时间点的完整环境检查点可还原。 - 副本使用独立数据库、目录和端口；不连接生产经济数据或修改生产授权绑定。保留原网络、币种、物品配置、游戏版本及授权文件，先检查副本中的配置、钱包／冻结、订单、领取资产和未决操作。
- 在副本核对迁移前后数据、实际领取和恢复流程，再制定原环境的切换与回滚步骤。仅有启动成功不足以证明可用。
4／结构 1 到协议 5／结构 2 的迁移机制：检查旧结构、节点租约和身份，在写入前备份完整 km_* 数据至 plugins/KiteMarket/backups/database-upgrade/，并保留资产及旧节点围栏。已有 MySQL/MariaDB 连接不会被切换成空 SQLite 库；配置、语言和主题需要按实际文件核对。这些保护不是完整旧环境已通过迁移的保证。
备份失败、旧资产表或字段缺失、旧节点仍活动时停止迁移，保留原数据，不用空表或另一数据库继续。未决操作保留核对路径，不自动退款或补发。回滚必须全网停服，核对变更后的资产，再恢复同一完整备份及匹配配置与旧包；不能只换回旧 JAR。
下方协议1–3到4的步骤属于历史迁移流程，不是 v1.1 新安装步骤。
升级已有市场到协议 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 表达式。验证记录列出准确构件和场景。
支持名单收紧与已有资产
新交易以当前构件的物品准入和序列化往返检查为准。v1.1 可以保存已通过检查的特殊物品与容器，并提供只读容器预览；不能沿用早期只有基础类型和附魔书的支持名单，也不能据此认定所有特殊物品均可交易。 ItemsAdder、Oraxen、Nexo、MMOItems 的公共 API 身份桥接用于识别真实来源与业务 ID，不代替完整属性比较或保真检查。精确样品也不能绕过准入。看到UNVERIFIED_SPECIAL_ITEM、UNVERIFIED_ITEM_DATA 或 ITEM_ROUNDTRIP_UNSAFE 时保留原因并停止发布，详见物品准入与保真。
准入只限制新增样品、发布、供货与托管。已有物品的还原、撤单返还、清退和领取保留，继续检查快照格式、摘要与来源游戏版本；不能因支持名单收紧销毁或永久锁住旧资产。类型准入也不等于整个版本、跨服或经济组合已认证，实际范围见认证状态。
最小验证清单
使用隔离测试玩家和少量测试资产覆盖收购、一口价、竞拍、双节点同时操作、充提、满背包领取和重启恢复。测试完回收测试资产与记录，保留有用的验收结果。详细平台范围见认证状态。 上述清单适用于新环境启用或相关功能改动。界面更新还应检查导航、草稿、金额输入、资源包拒绝／失败和第三方主题回退。使用隔离角色与订单，不重置现有玩家资产。开发者只读接口
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。通知可能延迟，启动前历史不补发，也不是恰好一次或可靠补发接口；消费者应查询权威状态。
扩展服务与玩家确认请求
v1.1 另外提供KiteMarketExtensions 和 KiteMarketRequests 服务，原 KiteMarketApi 的只读语义保持不变。
交易规则和复核扩展只能拒绝请求，不能改价、换收款人或替换真实物品。经济调用沿用核心执行许可、操作编号与精度；扩展不能绕过资产保护。提供者状态变化后应调用
changed(owner)，让原报价失效。
报价绑定所属插件、玩家会话、订单与规则版本及有效期。发布、购买、供货、竞拍和撤单仍由玩家在 KiteMarket 保护的确认页手动确认，并再次检查真实背包和当前状态。PENDING_REVIEW 不可当作失败自动重试。签名、线程约束和最小示例见市场 API。