# 架构说明 / Architecture

XFEServerManager 按纯服务端 Forge 模组设计。它不注册方块、物品或强制客户端网络通道，因此协议设计允许原版客户端连接；正式发布前仍须逐版本完成真实握手验收。仓库用四个彼此隔离的 Forge 构建根产出四个 JAR；不要把任一产物用于未列出的 Minecraft 小版本。

## 分层

```text
Vanilla client / Web browser
          | game protocol / HTTPS reverse proxy
          v
Forge adapter (one exact MC version)
          |
          v
common API -> policy / RBAC / operations -> infrastructure
                                            |-- JDK HttpServer + REST/SSE
                                            |-- control.db / telemetry.db
                                            `-- segmented world-event SQLite
```

- `common/api` 只定义中立模型和 SPI，不引用 Minecraft/Forge。
- `common/core` 包含确定性的策略、操作、审计和领域逻辑。
- `common/infra` 实现 HTTP、认证、SQLite、指标和外部事件投递。
- `platform/forge-*` 只负责生命周期、Brigadier、玩家/物品/实体和事件适配。
- `web-ui` 编译成静态资源并嵌入各平台 JAR；生产服务器不需要 Node.js。

## 线程模型

架构约束是：网络、密码计算、数据库和 Webhook 使用独立有界执行器；任何 Minecraft 世界、玩家、容器或命令树访问都必须封送到服务器主线程。长操作立即返回 `202 Accepted` 和 `operationId`，其进度与完成事件通过 SSE 发布。事件采集队列满时先丢弃低优先级遥测并聚合 gap，不允许阻塞 tick。这些约束仍须通过专服 soak/故障注入验收。

## 命令策略边界

策略先建立 Brigadier 语义 AST，再按“硬安全规则 → UUID → 加权角色 → OP → 默认”决策；同层拒绝优先，更具体规则优先。一个不可变策略版本可包含多个命名策略组，组可独立启停但仍作为一个版本原子校验、发布和回滚。低权限来源仅在显式 `GRANT` 后以最小必要权限重新解析。未知模组命令只能根级允许/拒绝，不能被提权。`execute run` 递归分析，`function` 与 `schedule function` 默认拒绝或只允许白名单。

## 数据与恢复

控制、遥测和世界事件存储按物理隔离设计，使用 WAL、单写线程、批量提交和编号迁移。回滚链路已接通固定 watermark 预览、冲突判断、版本专用状态 codec、临时区块票、分 tick 写回、暂停续跑、崩溃恢复和 redo；Forge 事件与容器 Mixin 写入同一世界日志。缺失注册项、日志 gap 和不兼容 payload 会逐项报告，不能被表述为完整恢复。

## 触发器运行时

触发器采用“组 → 事件 → 条件 → 动作”模型，定义与定时认领状态持久化在 `control.db`。Minecraft 状态先在服务器主线程复制为不可变有界快照，事件索引、脚本编译、条件求值与 SQLite 调度位于独立的有界触发器执行器；玩家、世界和 Brigadier 操作只回到服务器主线程执行。定时任务通过带令牌的短租约认领，过期租约先恢复原 occurrence；首个动作前失败会延迟重试，已有动作成功后的后续失败则以“部分成功”完成，避免重放先前副作用。动作生效与 SQLite 结算间的崩溃窗口仍可能重复，故动作序列不承诺事务性或恰好一次。可视化编辑器和 XFE Script 编译为同一个中立程序模型。代码模式是受限、可校验的 DSL，不加载 JVM 类或执行任意宿主代码；任意控制台指令动作仅 owner 可保存，执行时仍需通过高风险审计准入。旧入服欢迎、首次欢迎、每日公告、规则与维护提醒通过幂等迁移生成普通可编辑触发器。内置 Forge 生命周期、玩家、物品、方块、实体、区块、世界、爆炸和天气事件之外，其他模组可通过 `ForgeManagementRuntime.fireCustomTrigger("custom.<namespace>.<event>", context)` 发布自定义事件。

## Stable extension points

- `CommandSemanticAdapter`: adds semantic analysis for third-party commands.
- `WorldStateCodecAdapter`: safely serializes and restores modded state.
- `ManagementEventSink`: receives alerts and management events.
- `EventStoreProvider`: permits a future external event store; the bundled implementation remains SQLite.
- `custom.*` trigger events: permits Forge/mod adapters to publish additional bounded event contexts.