# 多货币经济系统 / Multi-currency economy

经济模块使用控制库中的独立货币、余额和流水表。金额只接受十进制字符串，并按货币的 `fractionDigits` 转换为 64 位最小单位；不会经过 `double`，因此转账不会产生浮点误差。单笔操作后的余额必须位于该货币配置的最低值和最高值之间。

## 货币生命周期

- 最多可配置 64 种货币；代码全局唯一且创建后不可修改（1–32 位小写字母、数字或下划线）。
- 必须且只能有一个已启用的主货币。要更换主货币，直接将另一种货币设为主货币。
- 货币可以使用上传图片或 `item:`、`block:`、`texture:` 资源；图片被货币引用时不能从图片库删除。
- 已产生账户或流水的货币不能删除，只能停用。停用会保留历史数据并拒绝新交易。
- 产生账户后不能修改小数位数；缩小余额边界前会检查所有现有账户。

## 账户、并发与流水

玩家首次加入或首次被查询时，会在同一事务中为现有货币惰性创建余额。增加、扣除、设置和转账均使用修订号进行乐观并发控制。转账会一次性校验并更新双方余额，然后写入一条不可变流水；任一步失败都会回滚整个事务。

管理端操作要求 `economy_manage` 和近期强认证，并先写入管理审计。流水另外记录来源、目标、变更前后余额、原因、执行者、来源通道与关联 ID。玩家自助转账记录为 `command` 来源，其命令仍由命令策略决定是否允许。

## 玩家指令

```text
/xfesm-money
/xfesm-money balance [currency]
/xfesm-money currencies
/xfesm-money pay <player> <amount> [currency]
```

省略货币时使用主货币。金额必须大于零、精度不能超过货币配置，付款人与收款人必须不同，并且货币必须允许玩家转账。该开关只限制玩家自助付款；具备强认证与审计的 Web 管理，以及触发器动作仍可执行管理性转账。

## 触发器与菜单联动

经济变更会发布 `economy.deposit`、`economy.withdraw`、`economy.set` 或 `economy.transfer`，并额外发布 `economy.balance_changed`。触发器可以执行 `economy_deposit`、`economy_withdraw`、`economy_set_balance` 和 `economy_transfer`；金额、货币、目标与原因均可插入变量。余额增减和设置只依赖事件中的玩家 UUID，因此玩家离线后仍可执行；转账目标目前必须在线，以便按服务端身份解析并防止伪造名称。

玩家上下文包含主货币、货币数量和每种货币的精确余额，例如 `{economy.primary.formatted}`、`{economy.balance.coins}` 和 `{economy.formatted.coins}`。经济事件还提供交易 ID、类型、执行者、来源通道、关联 ID、货币（含图标与精度）、金额、来源/目标玩家和双方变更前后余额。相同变量目录由富文本、普通操作参数和 UI 菜单共同使用。

## 性能边界

在线玩家账户保存在有界缓存中，玩家离线即移除；高频事件读取缓存，不逐事件查询 SQLite。Web 管理与玩家经济指令的数据库工作在控制执行器中运行；触发器内的经济动作按其有序动作语义提交，最终 Minecraft 动作仍回到服务器线程。账户和流水查询最多返回 200 项。
