适用源码：fd73c2ee0dac31c7b7a96560623207e15046cd1c。本页记录领域效果的持久化、结算与线程实现。

数据

town_hall_buffs 独立 SQLite 表保存配置、目标、类型、开关、付费截止和扣款检查点。外部公库扣款前先持久提交意图；结果不确定时停止生效，不自动重扣。OP 在大厅界面可选择“已确认扣款成功”或“已确认未扣款”，核对公库记录后通过确认弹窗解除检查点。成功核对保留原有截止时间，不额外赠送时长；核对后仍须手动启用。操作记录到服务器日志。

结算

默认每 60 秒先扣城镇公库，扣款成功且持久提交后才施加该周期效果。仅打开启用开关不会授予效果，扣款失败或结果不确定也不会授予效果。药水刷新时长不超过当前已付周期剩余时间。公库不足自动关闭，补足后手动重新启用。关闭不退款；同一配置重新启用可使用原周期剩余时间；修改配置会使原周期失效。

停服不补扣离线时间；重启保留配置和已买周期，离线到期只购买一个新周期。单价配置为 0 表示服主明确允许免费效果。

目录与解锁

buffs 是完整 Buff 目录，正面、负面效果不分组；目录存在不等于已经解锁。unlocks.initial 与 unlocks.hall-levels 决定初始和按大厅等级新增的解锁项，累计合并而不替换。新出现的服务端原版持续效果会自动补入配置文件，使用固定 I 级和默认价格，但不会自动解锁。未知 ID、重复 ID 及无效引用会在加载时报告。

所有 Buff 固定为 I 级，仅选择类型；max-active-effects 控制同时启用数量。

模式与目标

ALWAYS 持续生效；WAR_ONLY 仅在本镇参加战争时续加和购买新周期，和平时暂停。作用目标为 OWN_TOWN 或 ALL；ALL 会影响己方及访客，负面效果不会自动识别敌军。

线程

周期以墙钟时间结算。玩家每秒在其实体线程检测领地并刷新 3 秒效果；离开、关闭或停战后最多约 3 秒自然消退。不主动移除原有效果，也不覆盖其他来源更强或超过 3 秒的长时效果。旁观者和死亡玩家不生效。设施完整性只在核心所属区域检查，公库结算串行执行。

旧配置迁移

旧 levels 或平铺 effects 配置会先备份，再转成 buffs 目录；同名效果采用原最高档配置，保留自定义名称及价格，删除 Buff 强度配置，效果上限取旧配置的最大值。旧选择和已付周期不会重置或重复扣费。

来源

docs/town-hall-buffs.md、folia_plugin/src/main/resources/town-hall-buffs.yml；代码根 folia_plugin/src/main/java/com/flrv/：logic/townbuff/、infrastructure/persistence/facility/TownBuffRepository.java。