研发AcornCore 架构方案 v0.1

• 任务：T003
• 编写：研发窗口（Claude Opus 5.5）
• 日期：2026-10-21
• 状态：待审查。本文是研发方案，尚未经总策划审查，不代表已确认
• 依据：D001（Purpur 1.21.10 #2535、自研层）、D002（多语言）、D003（第三节模块、第六节 W1～W6）、想法池（I05、I14、I15、I21、I24、I25、I28、C5、C8、C10）、W001、M2 草案、T004～T006 任务卡
• 资料来源：下文"KB"表示 知识库/橡果与遗迹_CE与云系列_1.21.10_报告与本地知识库/知识库/pages/。凡是不能在 KB 里找到原文的结论，都标了 待验证

---

〇、总体结构一览

┌──────────────── Purpur 1.21.10 #2535 / Java 21 ────────────────┐
│                                                                │
│  AcornCore.jar（主插件，一个 jar）                             │
│  ├─ 平台层 platform：模块管理、配置、数据库、语言、调度、命令 │
│  ├─ 公共服务 services：玩家档案、奖励账本、编年史、世界时钟  │
│  ├─ 业务模块 modules：基础功能、新手、世界事件、冒险重置、   │
│  │                     防挂机……（每个都能单独关闭）           │
│  └─ 外部适配 integrations：Vault、PlayerPoints、云副本、     │
│                            云世界、云物品、MythicMobs……       │
│                                                                │
│  AcornNetEase.jar（网易专属，独立插件，可整体拆掉）          │
│  └─ 只依赖 AcornCore 的公开接口（acorn-api），反过来不依赖  │
└────────────────────────────────────────────────────────────────┘
        │ 只读视图/同步程序（W-5，后期）
        ▼
   网站（W001）

三条基本约束，贯穿全文：

1. AcornCore 是长期数据的唯一存放处。发现记录、奖励账本、编年史、局外成长都不存在闭源插件里（D001 第四节）。
2. 界面层只负责显示。CloudUI 按钮只能"请求" AcornCore 做事，校验、扣费、发放都由 AcornCore 完成（D001 第二节）。
3. 玩家看得到的文字一律走语言键，数据里只存 ID（D002 第四节第 1～3、10 条）。

---

一、模块划分与故障隔离

1.1 工程结构

源码用 Gradle 多工程，打包成两个 jar：

把业务模块分成子工程，并不是为了分开发布，而是为了用编译器强制模块边界：A 模块想调用 B 模块，只能通过 acorn-api 里的接口，拿不到 B 的内部类。这样关掉 B 时，A 只会拿到"服务不可用"，不会因为找不到类而崩溃。

插件描述文件用传统的 plugin.yml（softdepend 列出所有外部插件），不用 paper-plugin.yml。原因：云系列都是闭源 jar，官方示例都写 softdepend（KB cloudplugins/f118205d3fcf6614827a.md，https://cloud.plugins.wiki/docs/dungeon/api ）。paper-plugin.yml 要访问别的插件的类，还得逐个配 join-classpath（KB craftengine-source/d9fb1874b512ee1bc3f3.source.md），收益不大。

1.2 模块清单（对应 D003 第三节）

"多语言"不是一个模块，而是平台层的服务，所有模块都必须使用（D003 原表"贯穿全部模块"）。

1.3 "每个模块都能单独关闭"怎么实现

每个模块实现统一的生命周期接口，由平台层的模块管理器统一调度：

加载描述 → 检查依赖 → 执行数据库迁移 → 启用 → 运行 → 停用
   ↓失败       ↓缺依赖        ↓失败           ↓失败
       ───────────── 模块状态 = FAILED，其他模块照常 ─────────────

• 开关：plugins/AcornCore/modules.yml 里每个模块一行 enabled: true/false。关闭的模块不加载、不注册监听、不注册命令，它的数据表保留不动。
• 依赖声明：每个模块声明"硬依赖"（缺了就不能启用）和"软依赖"（缺了就降级）。例：adventure 硬依赖 worldclock；onboarding 软依赖领地插件，缺了就只是不发新手领地，并在后台警告。
• 启动顺序：按依赖做拓扑排序；有循环依赖时拒绝启动这几个模块，并在日志里报出依赖环。
• 运行中关闭：管理命令 /acorn module disable <id>，会连带停用依赖它的模块，并列出受影响的模块请管理员确认。账本、档案这两个核心服务不允许运行中关闭。

1.4 "一个模块出错不影响其他模块"怎么实现

Java 插件运行在同一个进程、同一个主线程里，做不到操作系统级别的隔离。能做到的是把下面几类常见故障拦在模块内部：

做不到的（如实说明）：死循环卡住主线程、内存溢出、修改了 Bukkit 全局状态（例如乱改游戏规则）。这些只能靠代码审查和测试服压测防住。

1.5 配置约定

• config.yml：平台设置（数据库、默认语言、地区）。
• modules.yml：模块开关。
• modules/<模块ID>.yml：模块自己的参数。配置里不写任何玩家可见文字，只写语言键和数值。
• 配置写错时，模块启用失败并报出文件名、行号和字段，不使用"猜一个默认值继续跑"的做法（会掩盖错误）。
• 权限节点统一 acorn.<模块>.<动作>，由 LuckPerms 管理。

---

二、数据层

2.1 存储选型

怎么保证以后迁得动：

1. 只用 JDBC 和两种数据库都支持的 SQL 子集。必须不同写法的地方（主要是"有则更新、无则插入"、自增主键、时间函数）集中放进一个"方言"接口，SQLite 一份、MySQL 一份。
2. 不用数据库自增主键当业务 ID。所有主键由程序生成（见 2.4），迁移时不会因为自增值冲突而对不上。
3. 时间一律存 UTC 毫秒整数，不存数据库的日期类型，避免两种数据库时区处理不同。
4. 表结构变更走迁移脚本：每个模块自己的迁移脚本放在 db/<模块ID>/V<n>__说明.sql，按方言各一份。每个模块单独记录自己的结构版本，一个模块迁移失败只让这个模块 FAILED。
5. 提供停服迁移工具：/acorn db export 把 SQLite 导出成中立格式，在 MySQL 上导入后逐表比对行数和校验值。迁移流程交给 sol 执行，研发写工具和说明。
6. 测试：每个数据访问类同时跑 SQLite 和 MySQL 两套测试（MySQL 用容器）。

数据库驱动和连接池打包进 jar 并重定位包名，避免和其他插件自带的版本冲突。Purpur 自带的 SQLite 驱动版本是多少、能不能直接用，待验证。

2.2 "只存 ID"的落实方式

ID 规则：

• 全小写英文、数字、下划线，格式 命名空间:路径。
• ID 一旦上线就不改、不复用。内容下架时 ID 保留，在内容登记表里标"已下架"；确实要改名的，建别名表映射，旧数据不改。
• 外部插件的 ID 原样加命名空间前缀存，例如云物品 clouditems:long_sword/thunder_sword（云物品是"类型 + ID"两级，KB cloudplugins/f93e1f41430e45de22f2.md）。

⚠️ 关键前提，待验证：网易认证接入后，同一个网易账号每次进服的 UUID 是否固定。如果网易认证走的是离线模式，UUID 由用户名计算，那么玩家改名就会变成"另一个人"，整个"只存 ID"体系都会失效。这一条必须在 T6（网易认证接入验证）时确认。如果不固定，就要在 netease 模块里加一张"网易账号 ID → 内部玩家 ID"的映射表，所有模块使用内部 ID。

2.3 数据表（大致结构，首批）

以下只列主要字段，最终字段在写代码时细化。

平台与档案

奖励账本（详见第四节）

编年史（详见第六节）

世界与模块

主题货币（第二批）用 wallet(uuid, currency_id, balance, version)，每次变动都在账本里留记录，用版本号做乐观锁，防止并发扣减出错。

2.4 ID 生成

• 结算号、事件号统一用 ULID（26 位，按时间有序，可在多台机器上独立生成，不会冲突）。
• 给人看的结算号（客服、补偿时使用）显示为 S- 加 ULID 后 10 位，数据库里仍然存完整 ULID。

---

三、多语言

3.1 文件格式与目录

plugins/AcornCore/lang/
├── zh_cn/              主语言，唯一必须完整的语言
│   ├── common.yml
│   ├── basics.yml
│   ├── ledger.yml
│   └── …（一个模块一个文件）
├── zh_tw/              先建空壳（D002 第四节第 5 条）
└── en_us/              先建空壳

• 格式：YAML，扁平键，一行一个完整键名，例如 acorn.basics.home.set_success: "已把这里设为家「<home>」。" 之所以用扁平键，不按点号嵌套，是为了让键名能直接全文搜索，翻译人员也不会弄乱层级。YAML 允许写注释，可以给翻译人员留上下文说明。
• 文字格式：MiniMessage（Paper 自带的 Adventure 文字库，CloudWorlds 的提示文字也支持 MiniMessage，KB cloudplugins/449a2c3abb154caa11f9.md）。
• 占位符：D002 写的是 {item}，MiniMessage 里对应写成 <item>。整句一个键，变量只能用占位符插入，禁止在代码里拼接两个语言键。
• 默认语言文件打包在 jar 里；服务器上的文件可以覆盖。启动时把 jar 里有、服务器文件里没有的键补进去，并写日志提示。

3.2 按玩家语言选择与回退

玩家客户端语言（Paper 接口取得，如 zh_tw）
  → 精确匹配 zh_tw
  → 同语族映射（zh_hk → zh_tw；zh_sg → zh_cn；en_gb/en_au → en_us）
  → 部署默认语言（config.yml 的 default-locale；大陆服 zh_cn，台湾服 zh_tw）
  → zh_cn
  → 仍然找不到：显示键名本身，并写一次警告日志（同一个键只警告一次）

• 玩家切换客户端语言后，下一条消息就用新语言。Paper 的取得语言接口和语言变更事件，KB 里没有收录 Paper 开发者文档，待验证（参考 https://docs.papermc.io/paper/dev/ ，未能离线核对）。
• 地区部署（D002 方案 A）：config.yml 提供 forced-locale。台湾服设为 zh_tw 后，所有人都看繁体，不跟随客户端。
• 服务端渲染为主：AcornCore 在服务端按玩家语言把键翻译成文字再发出去。这样不依赖资源包是否加载成功，后台日志也能看到实际文字。
• 可选的 CE 通道：CraftEngine 支持"在其他插件的消息和物品里使用 <l10n> 标签，CE 在发包时按玩家语言替换"（KB craftengine-zh/790bef0b7d25ef28f226.md，https://xiao-momi.github.io/craft-engine-wiki/zh-Hans/configuration/translations ）。物品名、物品描述这类会被保存、会被别人看到的文字，适合用这个通道，否则一件物品掉到别人手里还是原主人的语言。注意 CE 的回退顺序是"zh_cn → zh → en"，和我们的"回退到 zh_cn"不同，用这个通道的键必须保证 zh_cn 完整。
• 网站：语言文件可以导出成 JSON 交给网站，网站和游戏用同一份文字（W001 第三节第 5 条）。

3.3 语言键命名规则

• 格式：acorn.<模块>.<对象>.<用途>（D002 第四节第 3 条），全小写英文，单词之间用下划线，不用拼音。
• <模块> 与模块 ID 一致：common、basics、ledger、chronicle、worldclock、adventure、onboarding、afk 等。
• 常用用途后缀统一：title、desc、button、success、fail、confirm、broadcast、hint。
• 编年史事件的文字键由事件类型推出：类型 acorn:world_boss.defeated → acorn.chronicle.world_boss_defeated.summary、.detail。
• 专有名词（地名、生物名、货币名）的键登记在 策划/术语表.md，代码里引用术语表的键，不另起一个。

3.4 自动检查

• 构建时检查：代码里出现的每个语言键在 zh_cn 里都存在；zh_cn 里的每个占位符，其他语言里都有对应。不通过就构建失败。
• 启动时检查：输出各语言的缺失键数量报告。
• 代码审查规则：发给玩家的字符串必须来自语言服务；直接写中文字符串的代码不合并（日志和后台调试信息除外）。

---

四、奖励账本

4.1 原则

• 所有高价值发放都必须经过账本：副本通关的核心奖励、世界 Boss 奖励、充值发货、补偿、活动大奖、新手旅人包。低价值的随手掉落（普通怪掉金币）不进账本，否则写入量太大。哪些算"高价值"由总策划给清单，账本只提供能力。
• 账本只负责"发且只发一次"，不决定发什么。
• 记录只追加。发错了不删记录，补一条"撤回"记录冲正。

4.2 结算号与幂等键

一笔发放有两个号：

幂等键的规则：<来源类型>:<来源事件号>:<玩家UUID>:<奖励槽位>。

为什么不用随机号防重复：如果每次都生成一个新的随机号，同一个"通关"事件被处理两次（插件重载、事件重复触发、重启后重放）就会得到两个不同的号，数据库认为是两笔，于是发两次。幂等键由事实决定，第二次插入会被唯一约束拒绝，这才能真正防重复。

4.3 发放流程（状态机）

         写入（唯一约束）
请求 ──────────────→ PENDING ──玩家在线──→ GRANTING ──→ GRANTED
          ↓已存在                │                  │
     直接返回原结果           玩家离线             失败
     （不会第二次发）            ↓                  ↓
                          等玩家上线再发        FAILED（重试，超过次数进人工）

1. 登记：后台线程插入 PENDING 记录。插入被唯一约束拒绝，说明这件事已经处理过，直接返回原记录，什么都不发。
2. 执行：玩家在线时，回到主线程：先把状态改为 GRANTING 并提交，再逐行执行发放。
3. 完成：全部成功，改为 GRANTED。

每类奖励怎么保证"只发一次"：

GRANTING 卡住的时间窗口只有几毫秒（从改状态到改完状态之间），只有正好在这时崩溃才会进入人工队列。账本要做到宁可让管理员多核对一笔，也不自动重复发。

4.4 断线、离线与重启恢复

• 玩家离线：记录停在 PENDING，玩家下次登录时自动发放。第二批接入星月邮箱后，可以改成发邮件，邮件接口本身也支持幂等键（.key(String)，"同一个 key 只会存一次邮件"，KB cloudplugins/4f893cd86ba5cd670de2.md，https://cloud.plugins.wiki/docs/starmail/api ），用结算号当邮件键，两层都防重复。
• 玩家在发放中途断线：主线程上的发放是一次性完成的，不会在执行到一半时断线；断线发生在这之前，记录就仍是 PENDING。
• 服务器重启：启动时扫描所有非终态记录：PENDING 照常等待；GRANTING 记录在玩家上线时按上表核对 PDC，金币和点券类的进入人工队列；FAILED 按退避时间重试，超过次数进入人工队列。
• 人工队列：/acorn ledger review 列出待核对记录，管理员核对后选择"确认已发"或"补发"。所有操作写入审计表。

4.5 和云副本自带奖励的关系（⚠️ 需要总策划定规则）

云副本自己有完整的结算奖励和掉线补发机制（end.yml 的 rewards，"通关时掉线中的人：指令与物品会存起来，下次登录时补发"，KB cloudplugins/a857f47a9f1a176b8b39.md，https://cloud.plugins.wiki/docs/dungeon/end ）。如果副本奖励一部分走云副本、一部分走账本，就会回到 D001 担心的"各自发奖"的局面。

研发建议：

• 高价值奖励一律由 AcornCore 监听云副本的 Clear 事件发放，不写进 end.yml 的 rewards。这样数据在我们手里，幂等键里有实例 ID。
• end.yml 的 rewards 只放低价值、可以重复也没关系的东西，或者干脆不用。
• 入场券退还（refund-on-crash）继续交给云副本，那是它自己的数据。
• 不建议用 end.yml 里的 command 调 AcornCore 发奖：命令变量里没有实例 ID（可用变量只有 {player}、{uuid}、{dungeon}、{rank}），算不出可靠的幂等键。

4.6 防抢奖励与对账

• 同一事件只结算一次：世界 Boss 等多人事件，先生成编年史事件号，结算以事件号为单位加锁，后续每个人的奖励都以这个事件号为幂等键的一部分。
• 每日对账报告：每天统计各货币、各物品通过账本发出的总量，以及单个玩家的发放量；超过阈值（如单人单日神奇橡果发放量）在后台告警。这同时服务于 C8（活动掉橡果的上限）和 C10（橡果市场兑换上限）。

---

五、外部接口

5.1 总原则

• 每个外部插件对应一个适配器，放在 integrations 包里，对内只暴露 AcornCore 自己定义的接口。外部插件的 API 一变，只改适配器。
• 全部 softdepend。启动时检测是否存在、是否已通过授权；不存在时，依赖它的功能降级，并在日志里写明"哪个模块的哪项功能因为缺少什么而关闭"。
• 云系列闭源 jar 作为编译期依赖，放在工程的 libs/ 目录（compileOnly files(...)，KB cloudplugins/f118205d3fcf6614827a.md）。这些 jar 不提交到任何公开仓库，授权文件也不进版本管理。
• 云系列授权失效时：云副本"不会启用（副本世界、指令都不会出现）"，云物品"所有功能与指令停用"，云世界"世界照常加载，只有 /cw 管理指令被锁"（KB cloudplugins 的 dungeon/items/worlds 安装页）。适配器每次调用前都检查可用性，不可用时由账本把发放留在 PENDING，不发也不丢。

5.2 Vault（金币）

5.3 PlayerPoints（神奇橡果）

5.4 CloudWorlds（多世界、冒险世界重置）

AcornCore 怎么判断冒险世界已经重置：在冒险世界的世界级持久化数据里写一个"世界代号"（每次开服检查）。模板里存的是模板制作时的代号，模板覆盖后，代号就变回模板的值，和数据库里记录的不一致，说明发生了重置。这时：世界代号加一，作废所有冒险世界里的 back 点和临时记录，写编年史。如果用了新模板（月换种子），就记一条"第 N 纪元开启"（W2）。Paper 的世界级持久化数据在模板复制后是否随世界文件一起被覆盖，待验证（T005 实测时一并确认）。

重置流程中 AcornCore 负责的部分（W5）：

1. 每日重启前 N 分钟开始全服预告和倒计时（语言键 + 时间参数），冒险世界里的玩家额外提示"箱子和临时据点会消失"。
2. 关服前把冒险世界里的玩家送回主城（不依赖 CloudWorlds 的"送到出生点"，因为那时我们自己已经关服）。
3. 关服由 sol 的定时重启流程执行；AcornCore 只发出"可以重启了"的信号或执行关服命令，具体由 T005 结果决定。

5.5 云副本 CloudDungeon

5.6 MythicMobs

5.7 其他接口（简述）

5.8 网易模块：怎么做到可以整体拆掉

现状：网易的认证接口和商业化接口资料不公开。网易入驻指南写明，服务器入驻时需要修改 BungeeCord 的认证接入；拿到正式机后由官方对接人员发送相关文件，这些文件属于保密资料（https://mc.163.com/m/dev/mcmanual/mc-dev/mcguide/35-%E4%B8%8A%E6%9E%B6%E4%B8%8E%E5%85%A5%E9%A9%BB/%E8%AF%BE%E7%A8%8B13-%E3%80%8A%E6%88%91%E7%9A%84%E4%B8%96%E7%95%8C%E3%80%8B%E4%B8%AD%E5%9B%BD%E7%89%88JAVA%E7%BD%91%E7%BB%9C%E6%B8%B8%E6%88%8F%E5%85%A5%E9%A9%BB%E6%8C%87%E5%8D%97.html ；KB 只有概述页 netease-java/8e7127b4e0149ed38673.md）。所以本节只定结构，具体对接全部待验证。

结构：

1. 独立 jar（AcornNetEase.jar），只依赖 acorn-api。AcornCore 里没有任何一行网易相关代码。台湾服或其他地区部署时，不放这个 jar 即可。
2. AcornCore 在 acorn-api 里定义几个"插口"，网易模块往里插实现：

3. 认证本身在代理端（BungeeCord），不在 Paper 上。网易认证插件由网易提供，按网易资料配置，归 sol 部署。Paper 上的网易模块只负责发货和合规提示。
4. 充值发货的防重复：网易回调可能重复通知同一个订单（一般支付系统都会重发直到确认）。账本的幂等键天然挡住重复；网易模块只在账本确认已登记（PENDING 写入成功）后才回复网易"已收到"。这条按通用支付惯例设计，网易的实际协议待资料到手后核对。
5. 不在 Minecraft 进程里开公网 HTTP 端口。如果网易采用"回调我们的接口"方式，回调由一个独立的小服务接收，写入数据库的待发货表，网易模块从表里取单发货。这样即使回调服务被攻击，也碰不到游戏进程。具体形式等网易资料。

---

六、编年史事件

6.1 事件数据结构

一条事件 = 一行 chronicle_event + 若干行 chronicle_participant。

参与者表 chronicle_participant：event_id、player_uuid、role（last_hit 最后一击、top_damage 输出第一、participant 参与者、first 首个达成者……）、rank、metric（伤害等数值）。

世界 Boss 的参与者名单和参与奖励用同一份数据（I25）：worldboss 模块战斗结束时先写编年史事件和参与者，再以 event_id 发奖。这样"编年史上有名"和"拿到了参与奖励"永远一致。

展示时才变成句子：type_id 对应语言键（3.3），data 和参与者填进占位符。玩家名在展示时从 player_profile 取当前名字。

隐私（W001 第三节第 2 条）：是否匿名在读取时判断，不在写入时判断。玩家在任何时候把自己设为"不上榜"，过去所有记录都会立刻显示为"一位旅人"（语言键 acorn.chronicle.anonymous_player）；改回公开也立即恢复。数据本身不删，统计和发奖不受影响。

第 0 纪元：编年史/第0纪元_筹备纪.md 在开服前一次性导入为 epoch = 0 的事件，类别对应 W001 约定的立项、决策、美术、技术、里程碑。

6.2 为网站预留的读取方式（W001）

W001 的原则是"游戏内和网站读的是同一份数据"，同时网站只负责展示。研发建议分三步：

为什么不在 AcornCore 里直接开 HTTP 接口：游戏进程开公网端口会增加被攻击面，网站流量大时也会拖慢主线程。

玩家输入文字过滤（W001 第三节第 3 条）：玩家名、以后的公会名在写入只读视图前标记"是否已通过过滤"，网站只显示通过的；没通过的显示为"一位旅人"。过滤规则和网易审核要求怎么接，待定。

---

七、开发顺序建议

P0 不依赖任何外部条件，审查通过后可以立刻开工，和 sol 的 T001、T002 并行。

---

八、待验证清单