TianjiTown 功能与玩法说明

本文按当前仓库源码整理，适用于 TianjiTown 1.0.0-SNAPSHOT（配置不设版本号）、数据库 schema 1.0。文中标为“默认”的数值来自当前 config.yml，服务器实际规则以部署后的配置为准。

1. 插件定位

TianjiTown 是面向单个 Paper 服务器的小镇治理与统一经济插件。它不向普通玩家注册 /town 一类命令，玩家通过“小镇服务台”或“小镇手册”进入 Paper Dialog，并在 Dialog 内完成菜单、表单和危险操作确认。

当前可用功能包括：

• 建镇资料填写、整镇 25×25 区块选址检查、管理员审批和初始 5×5 区块的 Residence 领地创建；
• 入镇申请、成员角色、规则确认、镇长转让和成员管理投票；
• 公共资金、成员捐款、统一收入税和永久公共账本；
• 固定网格领地激活和 Residence 权限同步；
• 使用公共资金购买公共 Buff；
• 领地内建筑方块概率返还和小镇信标效果覆盖；
• 审计、领地对账、清算账户对账和统一诊断。

2. 玩家快速上手

1. 找到管理员设置的讲台服务台，右键打开“小镇服务”菜单。
2. 点击“领取小镇手册”。以后右键手册也可随时打开同一菜单；改名或仿制普通成书不会获得入口功能。
3. 没有小镇时，可以选择“申请建立小镇”或“申请加入小镇”。
4. 加入小镇后，主菜单固定为小镇资料、公共资产、成员管理、待办中心和个人与帮助五个任务入口。
5. 镇长和副镇长在成员管理中审批入镇申请，并在小镇资料页修改简介与规则；镇长还可在公共资产中调整税率、激活领地，并在个人与帮助中解散小镇。

服务台和手册在维护模式中都会暂停。已有 Residence 领地保护不会因此消失。

3. 身份与权限

每名玩家最多属于一个正常运行的小镇。每镇固定有 1 名镇长，最多有 3 名副镇长，普通镇员数量没有插件级上限。

能力	镇长	副镇长	普通镇员
查看小镇资料、成员、公共余额、税率和完整账本	是	是	是
向公共资金捐款	是	是	是
发起移除成员投票、在有效选民范围内投票	是	是	是
发起强制更换镇长投票	是	是	否
审批入镇申请	是	是	否
管理访客名单	是	是	否
修改小镇简介和规则	是	是	否
移除普通镇员	是	是	否
移除或降职副镇长	是	否	否
任命副镇长	是	否	否
发起双方确认的镇长转让	是	否	否
修改统一收入税率	是	否	否
使用公共资金激活领地	是	否	否
购买公共 Buff	是	是	否
编辑本镇领地内的信标效果	是	是	否
解散小镇	是，仅剩自己时	否	否
主动退出小镇	否，需先转让或解散	是	是

玩家购买公共 Buff 固定要求镇长或副镇长身份，当前配置没有每商品购买角色字段。

Residence 领地中的成员权限由 TianjiTown 统一投影。所有成员都会获得 Residence /res padd 当前配置的完整 trusted 权限组，并额外获得 ignite 点火权限和 vehicledestroy 载具破坏权限；离镇后这些玩家权限会被清除。系统领地不能由玩家使用 /res 或 /residence 命令直接修改。

小镇领地统一设置 monsters=false，阻止 Residence 识别的怪物生成（包括自然生成、刷怪笼和刷怪蛋）。该标记随领地创建及权限同步写入，并纳入领地检查与修复。 同时设置 nomobs=true，启用 Residence 的怪物进入保护，同样纳入创建、权限同步、检查与修复。该功能依赖 Residence 配置开启 AutoMobRemoval，通过周期清理领地内的怪物生效，并非边界即时拦截。

4. 建立小镇

4.1 申请资料

玩家在三步 Paper Dialog 表单中填写资料：基础名称、简介与规则、两名初始成员。表单值不会发送到公共聊天。

字段	校验规则
小镇名称	2～24 个字符；只允许文字、数字、空格、下划线、连字符和间隔点 ·
小镇代码	3～9 个英文字母，不允许数字、空格和符号；同时作为 Residence 名称
简介	最多 500 个字符
规则	1～50 条，每条最多 300 个字符；Dialog 表单中每行一条
初始成员 1、2	两名不同的在线无镇籍玩家，且不能是申请人；通过两个默认成员按钮选择，并在 Dialog 中确认

名称、简介和规则都不接受 Minecraft 格式代码、MiniMessage 标签或危险控制字符。名称在判重时会先执行 Unicode NFC 规范化，再忽略大小写与所有普通空格；因此组合字符与其 NFC 等价字符、连续空格与单个空格不能绕过判重。系统不会执行 NFKC 兼容折叠，全角字符等兼容形式按不同名称处理。小镇代码会转为小写后直接作为 Residence 名称，例如填写 SKY 会创建 sky。

每一步都可返回修改，成员步骤另有“保存草稿”按钮。点击已选成员可更换玩家，也可在选择列表中清空当前选择；选择、更换、清空和保存表单草稿均不发送邀请，只有“完成资料并发送邀请”才通知最终所选成员。已选择初始成员但仍待确认时，申请人可继续申请并重新发送 Dialog 提醒；同一申请的提醒默认有 5 分钟冷却。

任一初始成员拒绝后，本轮邀请全部失效。申请人重新打开申请时会直接进入成员选择，保留已填资料与仍有效的选址；重新完成资料并发送邀请后，两名成员都须重新确认，旧邀请不能继续使用，上一轮提醒冷却也会清除。

撤回或被拒绝建镇申请后，需要等待 1 天才能创建新申请。申请建镇与申请入镇互斥：有待处理入镇申请时不能新建建镇申请，已有未结束建镇申请时也不能申请加入小镇。

4.2 选址规则

点击“选择当前区块”后，玩家脚下区块成为初始单元的中心。初始单元固定为 5×5 区块，即 25 个区块，建镇后自动激活并从世界最低高度保护到最高高度。选址检查的是以它为中心的整张 5×5 单元网格，即 25×25 区块（625 区块、400×400 方块）；其余 24 个单元批准后保持预留，付费激活后才启用完整保护。

选址必须同时满足：

• 整镇 25×25 区块不得与现有 Residence、其他小镇归属范围或有效建镇预留冲突；
• 整镇范围默认还要与其他小镇或申请保留至少 1 个区块的缓冲；
• 整镇 25×25 区块及其缓冲范围必须完整位于目标世界的 WorldBorder 边界内。

WorldBorder 是运行时必需依赖；plugin.yml 以软依赖声明，使其缺失时 TianjiTown 仍能加载并通过 /tianjitown status 报告 LOCKED。未启用、API 不兼容或目标世界未配置边界时，插件会锁定或安全拒绝选址。

成功选址会为整镇范围产生默认 60 分钟的临时预留，并显示初始单元约 15 秒的三维火焰粒子边界。选址预览会将玩家传送到初始单元中心地表附近。预留过期、申请撤回或被拒绝后，临时占位会释放。

4.3 提交和审批

申请的主要流程是：

草稿 → 已选址 → 已提交/审核中 → 要求修改、拒绝或批准创建 → 正常运行

• 申请人在管理员批准前仍可撤回申请。
• 管理员可批准、拒绝或附带原因要求修改；要求修改后，申请人可以重新编辑、选址并提交。
• 只有两名初始成员都确认且仍无镇籍时才能提交；批准时申请人需支付申请费，默认 5000.00，可通过 config.yml 的 town.application.fee 修改。
• 批准时，系统会在一个流程中创建小镇、镇长与两名初始成员记录、初始领地单元、公共账户及 Residence 投影。
• 若 Residence 创建失败，申请会进入可重试的创建失败状态，不会静默生成一个无保护小镇。
• 建镇成功后，申请人成为镇长，两名确认者成为普通成员；实际收取的申请费作为初始公共余额入账（默认 5000.00），统一收入税率初始为 5%。

5. 加入、退出与解散

5.1 入镇申请

无小镇玩家可以浏览所有正常运行的小镇，查看其代码、简介和规则后提交申请。

默认规则如下：

• 每份入镇申请有效 48 小时；
• 每名玩家同时最多保留 3 份待处理申请；
• 被某镇拒绝后，24 小时内不能再次申请同一小镇；
• 主动退出小镇后，24 小时内不能申请任何新小镇；
• 申请人可以在审批前主动撤回；
• 镇长和副镇长都可以批准或拒绝入镇申请。

申请提交时，在线的镇长和副镇长会收到可点击提醒。批准后，玩家立即成为普通镇员并获得 Residence 成员权限；拒绝后，申请人会收到通知。

5.2 主动退出

副镇长和普通镇员可以在主菜单中二次确认后退出。退出会立即移除成员关系、Residence 权限和小镇公共 Buff，并开始默认 24 小时的入镇冷却。

镇长不能直接退出，必须先把镇长转让给其他成员，或者在只剩自己时解散小镇。

5.3 解散小镇

只有镇长且小镇只剩镇长 1 名成员时，菜单才允许解散。解散需要二次确认，完成后会：

• 归档小镇和历史成员；
• 取消待处理入镇申请、治理事项和公共效果；
• 移除 Residence 投影；
• 释放小镇名称、小镇代码和区块占位；
• 保留审计记录和归档历史。

为防止领地保护异常，删除采用“两阶段释放”。如果 Residence 移除失败，小镇会保持安全归档，名称和区块继续锁定，等待管理员处理后再次完成释放。

6. 小镇资料与规则确认

所有成员可以查看小镇名称、代码、简介、规则、成员列表和小镇领地预览。

镇长和副镇长可以直接从小镇资料页通过 Dialog 多行表单修改简介和规则；名称和小镇代码不能在玩家表单中修改。规则变更会递增规则版本：

• 成员下次登录会收到规则更新提醒；
• 打开小镇菜单时，会先显示新规则确认页；
• 在确认最新版本前，成员不能继续使用其他小镇菜单功能。

7. 成员管理

7.1 直接管理

• 镇长可以任命或降职副镇长，每镇最多 3 名副镇长。
• 镇长可以移除普通镇员和副镇长，但不能用普通移除流程删除自己。
• 副镇长可以移除普通镇员，不能移除或降职其他副镇长。
• 成员变化会触发 Residence 权限同步；目标玩家在线时也会立即刷新公共 Buff。

7.2 访客管理

镇长和副镇长可从“成员管理 → 访客管理”进入“访客列表”或“邀请”：

• 邀请页列出当前在线、不是本镇成员且尚未在本镇访客名单中的玩家；其他小镇的成员也可以成为访客；
• 加入名单后，访客立即获得与普通镇员相同的 Residence 领地权限；
• 访客不成为正式成员，不参与治理投票，不归属本镇税务，也不获得公共 Buff；
• 从访客列表移出后会立即清除领地权限；访客正式加入本镇时，其重复访客记录会自动清除。

7.3 双方确认的镇长转让

镇长可以向本镇另一名成员发出接任请求。有效期固定为 24 小时，候选人必须明确接受或拒绝。

• 接受后，候选人成为新镇长，原镇长降为普通镇员；
• 拒绝或过期后，身份不变；
• 候选人离镇、原镇长身份变化或请求被重复处理时，操作会安全失败。

7.4 治理投票

小镇成员可发起移除成员投票；强制更换镇长投票只允许镇长或副镇长发起：

投票类型	目标限制	通过条件	通过后的结果
投票移除成员	本镇非镇长成员	赞成票严格超过有效选民的 50%	目标成员离镇并清除 Residence 权限
强制更换镇长	候选人为本镇非镇长成员	赞成票达到有效选民的 2/3，向上取整	候选人成为镇长，原镇长降为普通镇员

投票规则：

• 同一小镇同一时间只能存在 1 个开放投票，不区分投票类型；
• 持续时间固定为 72 小时；
• 创建时冻结有效选民名单，后续登录或入镇不会改变本次名单；
• 有效选民须在最近 30 天内有活动记录，最低入镇时间固定为 0 天（不额外限制）；
• 被处置对象不进入选民名单：踢人投票排除被踢者，换镇长投票排除现任镇长；
• 发起人通常必须位于冻结选民名单中；现任镇长发起更换镇长投票时例外，可以发起但不获得该次选票；
• 管理员通过玩家界面发起投票也遵守上述镇籍、角色和选民限制，没有管理员发起投票的独立命令；
• 每个 UUID 只能投 1 次，赞成或反对提交后不能修改；
• 所有有效选民投完时会立即结算，否则由每分钟任务在到期后结算；
• 发起人可在投票详情中二次确认终止自己仍为开放状态的投票；管理员可通过 vote cancel 取消。取消不执行提案的人事变更，已结束的投票不能取消；
• 结算前若目标身份已改变，系统会拒绝执行不再成立的结果。

玩家登录和打开主菜单都会更新活动时间，也会收到待投票提醒。

8. 公共资金与统一收入税

8.1 公共账户

每个小镇有一个逻辑公共账户，实际资金统一托管在配置的 Vault 清算账户中。所有成员都能查看：

• 当前公共余额；
• 当前统一收入税率；
• 当前领地单元数量；
• 从建镇起保留的完整公共账本。

任何成员都可以输入自定义正数金额捐款。捐款从个人 Vault 余额转入清算账户，并在小镇账本记录 DONATION 流水。

领地激活和 Buff 购买只扣小镇内部公共余额，相关补偿或同类 Buff 替换退款也只调整内部账户，不调用 Vault 扣款或存款。清算账户因此可高于内部账户合计；建镇费、捐款、税收与管理员调账的外部资金处理按各自流程执行。

账本会记录申请费、QuickShop、Jobs、GlobalMarketPlus 税收及额度内服务器补贴、捐款、激活及其失败补偿、管理员调账和 Buff 购买等。普通收支记录包含金额、变动后余额、操作人、时间和说明。税收按北京时间每日 04:00 至次日 04:00（不含结束时刻）汇总：Jobs 归为“职业收入”，QuickShop 与 GlobalMarketPlus 合并为“商店收入”。汇总展示税款、实际服务器补贴、合计金额和收入税笔数，不展示单笔余额或操作人。当前周期持续累计，资金仍实时入账。周期按税款账本入账时间归属，关联补贴跟随该税款；底层逐笔明细完整保留，重启或错过四点不影响查询汇总。

8.2 税率与征税范围

新小镇默认税率为 5%，允许范围固定为 5%～25%。镇长在 Dialog 滑块中按 1% 步进选择，保存后自动返回公共资金页；管理员命令也遵循相同范围和步进。

同一税率作用于下列收入：

• QuickShop SELLING 商店：按商店所有者所属小镇计税；
• QuickShop BUYING 商店：按与商店交互、实际收款的玩家所属小镇计税；
• Jobs 工资收入；
• GlobalMarketPlus 成交收入。

QuickShop、Jobs 和 GlobalMarketPlus 共用的小镇税收补贴额度按上海时间每周一 04:00、每天 04:00/16:00 刷新；重试沿用首次预留的周期。建筑返还仍按原有每周规则重置。

普通玩家转账、管理员余额调整和其他未接入的 Vault 变动不征收小镇税。非小镇成员的上述收入税率为 0。每笔税款进入小镇公共账本时，服务器在共享额度内提供等额补贴；额度不足时只补贴剩余金额，耗尽后不再补贴，但仍正常收税。公共账户增加税款与实际补贴之和。

税率变更后，成员登录时会收到提示；打开公共资金页后会记录已读版本。

QuickShop 动态税适配器要求 QuickShop-Hikari 版本不低于 6.3.0.0，并使用新版增强税率与交易账户 API。版本或接口不匹配时，插件会关闭 QuickShop 动态税并在状态中显示警告；其他小镇功能以及 Jobs、GlobalMarketPlus 税链路不因此自动停用。

8.3 对账和消费锁

系统会定期比较 Vault 清算账户外部余额、全部小镇内部余额和已在外部执行但尚未完成内部入账的资金操作。最低应有余额为 max(0, 全部小镇内部余额合计 + EXTERNAL_APPLIED 操作金额合计)；外部余额达到或超过此值即满足清算余额要求，允许富余。如果清算账户低于此值：

• 新的激活、Buff 等公共消费会被锁定；
• 公共余额和账本仍可查询；
• 捐款、补偿退款和查询仍可进行；捐款和管理员调账同时改变内部、外部余额，不能单靠它们消除已有清算缺口；
• 差异补足并再次对账后，系统会解除对账锁。

SQLite 暂时不可用时，新的业务写入会暂停；已经存在的 Residence 保护继续有效。

9. 领地保护与激活

9.1 领地结构

一个领地单元固定为 5×5 区块。初始单元位于网格原点 (0,0)。批准后立即获得周围固定 5×5 单元网格的全部 25 个单元，共 625 个区块。初始单元自动激活，具有完整小镇 flag；其余单元仅禁止圈地，其他行为保持野外状态，激活后才启用完整小镇 flag。

激活必须满足：

• 只能由镇长发起；
• 目标通过北、东、南、西方向从现有领地相邻扩展；
• 所有单元必须保持四方向连通，不能出现飞地；
• 目标仍在原点周围 5×5 单元网格内；
• 目标不与其他 Residence 或有效区块占位冲突，且连同缓冲范围完整位于 WorldBorder 内；激活复用同一套环境校验，但允许与本镇已有 Residence 相接；
• 公共账户未锁定且余额足够。

菜单以 5×5 Sprite 按钮地图显示小镇中心、已激活、可激活、暂不可激活和其他小镇区域。选择可激活格子后，系统会显示目标区域的三维边界但不会传送玩家，再进入扣款确认页。

9.2 激活价格

首次激活支付 5000.00 公共资金，第 n 次激活价格为 5000 × 1.05^(n-1)，批量激活逐块累计。失败退款的地块不计入已激活次数。系统按经济服务的货币精度显示和扣款。

扣款、领地区块占位和激活状态在数据库中按可恢复流程处理。Residence 新区域创建失败时，系统会退款并撤回本次激活的保护；整个 5×5 单元网格（25×25 区块）的预留归属不变，重试不会重复扣款。

9.3 投影对账

数据库是小镇成员和领地结构的事实来源，Residence 是保护投影。系统会定期检查边界、区域数量和成员权限。管理员可只读检查、修复权限与区域，或在确认后移除并完整重建投影。

如果运行中的小镇 Residence 被外部删除，系统会阻止删除、向删除来源发送提示，并立即触发投影对账恢复。

10. 公共 Buff

公共 Buff 使用小镇公共资金购买，并跨世界作用于全体在线成员。商品操作按钮不显示冗余悬浮说明；进入购买页后选择 1～4 周和商品允许的等级（最高 V，单等级商品不显示强度滑块），并在确认前显示效果与精确价格。

当前默认目录：

商品	效果	等级上限	每周基础价	默认购买角色
速度 speed	每级速度 +20%	5	6000	镇长、副镇长
生命 health	每级最大生命值 +4（2 颗心）	5	10080	镇长、副镇长
潜水 diving	氧气加成 +19，减少水下耗氧，仍需换气	1	3000	镇长、副镇长
安全落地 safe_fall	每级安全坠落距离 +2 格	3	4000	镇长、副镇长
矿工 mining	每级方块破坏速度属性 +10%	3	6000	镇长、副镇长

价格按“每周基础价 × 周数 × [1 - 5% × (周数 - 1)] × 所选等级”计算。购买同类 Buff 时以新选择的持续时间和等级覆盖旧生效项，不再让玩家选择内部叠加类型。

效果会在玩家登录、重生、跨世界、成员变化和到期时重新计算；玩家登录时会重新检查并恢复或清理效果。关闭 Buff 商店只禁止新购买，不会提前结束已购买效果。

管理员 /tianjitown buff set <小镇代码> <buffKey> [周数] [等级] 免费覆盖同类效果，默认 1 周、1 级，允许 1～4 周及商品合法等级（最高 V）。设置不改变公共或清算余额，不受商店和消费开关限制。玩家重购按旧订单实际付款与剩余毫秒占原总毫秒的比例向下取整退款，退款与新扣款在同一事务完成；免费来源退款为 0。确认页显示新价格、预计退款和预计净支出；提交时重新计算并检查旧订单身份。

11. 建筑返还

建筑返还是领地内自动触发的公共福利。默认情况下，小镇成员在自己小镇的有效 Residence 内，以生存模式手动放置合格方块时，有 25% 概率返还 1 个同种方块。

返还成功后：

• 方块仍正常放置；
• 同种方块优先加入背包，背包满时掉落在玩家当前位置；
• 只向玩家播放物品拾取音效，不显示返还文字或内部额度。

系统按小镇、玩家和周保存内部计数，默认每组每周 3000 次，按配置时区周一 00:00 切换；不会向玩家展示额度信息。

下列情况不会返还：

• 创造模式、非玩家放置、连锁自动放置或多方块放置事件；
• 玩家不属于该镇、放置位置在镇外/他镇，或 Residence 实际边界校验失败；
• 概率未命中、达到周上限或数据库不可用；
• 手中物品带物品元数据，或方块材料与手中物品不一致；
• 床、门、告示牌、旗帜、头颅等多方块或特殊方块；
• 箱子、潜影盒、木桶、熔炉、漏斗、发射器、酿造台、讲台等容器或功能方块；
• 信标、TNT、重生锚、刷怪笼、试炼刷怪笼、Vault、活塞、黏液块、蜂蜜块等特殊方块；
• 默认红石类别和高获取难度黑名单中的材料。

默认黑名单还显式包含远古残骸、下界合金块、钻石/绿宝石/金矿及对应高价值方块、信标、龙蛋、紫水晶母岩、强化深板岩、末地传送门框架、哭泣的黑曜石和附魔台等。实际清单可由服务器调整。

12. 领地信标增强

镇长或副镇长切换本镇领地内的信标效果时，系统读取新的主效果和次效果，与数据库记录比较，只保存尚未存在或等级更高的效果，并将已记录效果覆盖到整个小镇领地。

• 系统不会扫描已加载区块中的信标，只在信标界面关闭后记录效果；
• 玩家必须实际位于该小镇 Residence 边界内才能获得效果；
• 效果按领地位置发放，访客进入领地也可以获得，并不限于本镇成员；
• 同一种效果只保留记录过的最高等级；
• 只有本镇镇长和副镇长能右键信标编辑效果；普通镇员、访客和他镇管理者会被阻止；
• 离开小镇有效领地、领地归档、功能关闭或插件停用后，托管效果会被清理。

记录时信标须满足原版生效条件。记录保存后不再依赖来源信标持续存在，拆除或金字塔失效不会撤销已记录效果；效果只覆盖数据库登记且 Residence 校验有效的小镇领地。

13. 默认配置速查

项目	当前默认值	说明
建镇申请冷却	1 天	撤回或被拒绝后
选址预留	60 分钟	到期后可被其他申请占用
选址缓冲	1 区块	整镇预留与其他小镇/申请的间隔，也参与 WorldBorder 边界检查
领地粒子预览	15 秒	每 20 tick 刷新，垂直范围上下各 24 格
同时待处理入镇申请	3 份	按玩家统计
入镇申请有效期	48 小时	到期不可批准
入镇拒绝冷却	24 小时	对同一小镇
主动离镇冷却	24 小时	期间不能申请新镇
镇长转让确认	24 小时	候选成员明确接受后生效
活跃选民窗口	30 天	最近活动时间
最低入镇时间	0 天	固定不额外限制
投票持续时间	72 小时	到期由每分钟任务结算
初始税率	5%	数据库默认值
税率范围	5%～25%	玩家菜单使用滑块按 1% 步进调整
清算对账周期	5 分钟	比较外部与内部资金
激活基础价格	5000.00	每次激活后价格增长 5%，公共资金支付
最大领地单元	25	每单元 5×5 区块
建筑返还概率	25%	只对合格放置进行抽取
建筑返还重置时区	Asia/Shanghai	周一 00:00
信标效果刷新周期	100 tick	只刷新已记录效果，不扫描信标
启动诊断	初始化阶段 1 次	默认检查近 7 天 QuickShop 历史；失败时保持 LOCKED，运行期间可手动执行

14. 管理功能与命令

完整语法、用途、默认参数、权限、示例和操作后果统一见管理员命令手册。管理员可以审核建镇、调整成员和镇长、取消投票、管理服务台、查询和调整资金、检查修复领地、免费设置 Buff 及执行诊断。发起投票属于玩家 Dialog 流程，按玩家的镇籍、角色及选民资格校验。

15. 诊断、备份与故障保护

插件启动时会检查配置内容、SQLite/Flyway、Residence、Vault、XConomy、WorldBorder、QuickShop-Hikari、Jobs 和 GlobalMarketPlus。必需依赖缺失、未启用，WorldBorder API 不兼容，或 Vault 没有可用 Economy provider 时，写功能保持锁定。

/tianjitown diagnose 会汇总：

• SQLite quick_check、外键违规、关键表计数和失败/待补偿操作；
• 所有运行中小镇的 Residence 边界、区域和成员权限；
• Vault 清算账户的外部余额、内部余额、待完成金额和应有余额；
• QuickShop log_purchase 与本地税记录按商店、交易方向、交易玩家、金额、税额和时间逐笔匹配（允许时间相差 2 分钟，每条历史只能匹配一次）。

QuickShop 历史最多读取 1000 条；达到上限时报告为 INCOMPLETE，不会误报完全一致。诊断报告保存在插件目录的 diagnostics 下，保留最近 30 份。

插件不执行在线配置或数据库备份。生产恢复仍需要按运维流程在同一停服时间点分别准备 SQLite、Residence、QuickShop 和 XConomy 的备份。

16. 功能边界

• 插件不提供跨服小镇、联盟、战争、领地税、成员日常税或玩家自定义 Residence flag。

购买历史核对仅覆盖本地已入账税收，不能发现其他交易的漏记，也不证明历史税款到账账户；商店当前税款账户不代表交易时动态指定的账户。Vault 清算余额仍单独检查。查询异常或扫描达到 1000 条时标记 INCOMPLETE。