Purpur Build
eddc706c9a
实现完整的现金/钱包、银行卡、支票、活期储蓄与定期存款系统， 实现并以 Highest 优先级注册 Vault Economy 接口，接入 PlaceholderAPI。 全程遵循 Folia 调度模型（AsyncScheduler / 实体区域线程）， 数据缓存线程安全，支票兑现与定期领取做防刷处理。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
94 lines
6.6 KiB
Plaintext
94 lines
6.6 KiB
Plaintext
# 🏦 CraftBank (工艺银行) - 适用于 Folia 1.21.8 的全能经济与银行核心插件
|
||
|
||
## 📖 简介
|
||
CraftBank 是一款专为 **Folia 1.21.8 (多核服务端)** 设计的全能经济核心插件，**旨在完全替代 XConomy 等传统经济插件**。它不仅内置了完善的“个人钱包/现金”系统，还引入了深度模拟的银行系统：包含实体银行卡、可交易支票、活期储蓄以及严格的定期存款（带利息）。
|
||
|
||
**⚠️ 核心目标开发者注意 (Folia 兼容性)**：
|
||
本插件运行在 **Folia** 服务端上！这意味着传统的 Bukkit Scheduler 已被弃用。你必须使用 Folia 的 `AsyncScheduler`, `GlobalRegionScheduler` 和 `RegionScheduler` 来处理所有任务。要求使用 Java 21 编译。本插件必须自己实现 Vault 的 Economy 接口。所有自定义物品必须使用 `PersistentDataContainer (PDC)` 存储数据。
|
||
|
||
---
|
||
|
||
## ✨ 核心功能 (Core Features)
|
||
|
||
### 1. 💵 核心经济与钱包 (Core Economy - 替代 XConomy)
|
||
* **独立经济系统**：每个玩家拥有独立的“现金（Cash）”账户。
|
||
* **Vault 注册**：插件必须实现 Vault API，成为服务器的默认经济提供者（Economy Provider），接管所有商店、权限插件的扣款请求。
|
||
* **基础指令**：内置原生的 `/money`, `/pay`, `/baltop` 等基础经济指令。
|
||
|
||
### 2. 💳 银行卡系统 (Bank Cards)
|
||
* **实体物品**：玩家可以通过指令或银行 GUI 办理一张实体银行卡。
|
||
* **数据绑定**：银行卡通过 PDC 绑定玩家的 UUID。
|
||
* **交互操作**：玩家拿着银行卡右键点击特定的方块（例如：铁块，可在 Config 自定义），即可打开个人银行 GUI。
|
||
* **防丢机制**：如果银行卡丢失，玩家可以去银行挂失并补办（旧卡将自动作废）。
|
||
|
||
### 3. 📜 支票系统 (Cheques)
|
||
* **开具支票**：玩家通过指令 `/cheque <金额>` 将钱包或银行里的钱具现化为一张实体支票物品。
|
||
* **流通与兑换**：支票可以扔给其他玩家。任何人手持支票右键点击，即可将金额存入自己的钱包。
|
||
* **防伪验证**：支票包含开票人 UUID、生成时间戳和金额，数据均存储在 PDC 中。
|
||
|
||
### 4. 💰 活期储蓄 (Savings Account)
|
||
* **存取自由**：玩家可以将钱包里的“现金”存入银行活期账户，随时通过 GUI 或指令取回。
|
||
* **基础利息**：活期账户可享受较低的日利率（利息结算在每日午夜或玩家首次登录时离线结算）。
|
||
|
||
### 5. ⏳ 定期存款 (Term Deposits)
|
||
* **强制锁定**：玩家可以选择将资金存入“定期账户”，可选期限（如：7天、15天、30天）。**一旦存入，在到期之前，任何情况都不允许提前取出**。
|
||
* **高额利息**：定期存款享受比活期高得多的利率。
|
||
* **到期结算**：时间到期后，本金加利息将自动转入玩家的活期账户，或允许玩家手动在 GUI 中领取。
|
||
* **存储方式**：定期存款记录应使用真实时间戳（Timestamp）计算，以防服务器重启导致时间丢失。
|
||
|
||
---
|
||
|
||
## 🛠️ 依赖项 (Dependencies)
|
||
* **必须**: [Vault](https://www.spigotmc.org/resources/vault.34315/) (本插件将作为其 Service Provider 注入)
|
||
* **可选/推荐**: [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) (用于提供 `%craftbank_cash%`, `%craftbank_bank_saving%` 等变量)
|
||
|
||
---
|
||
|
||
## 💻 指令与权限 (Commands & Permissions)
|
||
|
||
### 基础经济指令 (所有人可用)
|
||
* `/money [玩家]` - 查看自己或他人的现金余额。
|
||
* `/pay <玩家> <金额>` - 给其他玩家转账（现金）。
|
||
* `/baltop` - 查看现金排行榜。
|
||
|
||
### 银行玩家指令 (基础权限: `craftbank.use`)
|
||
* `/bank open` - 打开银行 GUI（可配置为需要银行卡或身处特定区域）。
|
||
* `/bank card apply` - 申请一张新的银行卡。
|
||
* `/bank card revoke` - 挂失并作废当前的银行卡。
|
||
* `/cheque <金额>` - 开具一张指定金额的支票。
|
||
* `/bank deposit <金额>` - 存入现金到活期账户。
|
||
* `/bank withdraw <金额>` - 从活期账户提取现金。
|
||
|
||
### 管理员指令 (管理员权限: `craftbank.admin`)
|
||
* `/bankadmin reload` - 重载配置文件。
|
||
* `/bankadmin give <玩家> <金额>` - 给予玩家现金。
|
||
* `/bankadmin take <玩家> <金额>` - 扣除玩家现金。
|
||
* `/bankadmin set <玩家> <金额>` - 设置玩家现金。
|
||
* `/bankadmin setinterest <saving/term> <利率>` - 动态修改银行利率。
|
||
|
||
---
|
||
|
||
## ⚙️ 配置文件 (config.yml 需求)
|
||
开发者请确保生成包含以下配置项的 `config.yml`：
|
||
* **Database**: 支持 SQLite (默认) 和 MySQL。玩家数据表应包含：`uuid`, `player_name`, `cash`, `bank_saving`，以及独立的定期存款表。
|
||
* **Economy_Settings**:
|
||
* `currency_symbol`: "$"
|
||
* `starting_balance`: 1000.0 (新玩家初始现金)
|
||
* **Interest_Rates**:
|
||
* `savings`: 0.001 (活期日利率 0.1%)
|
||
* `term_7d`: 0.005 (7天定期日利率 0.5%)
|
||
* `term_30d`: 0.01 (30天定期日利率 1%)
|
||
* **Items**: 自定义银行卡和支票的 Material (材质)、CustomModelData、Name 和 Lore。
|
||
|
||
---
|
||
|
||
## 🤖 给 AI 开发者的代码要求 (AI Developer Notes - Folia 严格规范)
|
||
请严格遵循以下要求编写代码，**任何违反 Folia 规范的代码都将被拒绝**：
|
||
1. **Folia 任务调度 (核心)**：
|
||
* 严禁使用 `Bukkit.getScheduler()`。
|
||
* 纯后台任务（如数据库查询、`/baltop` 排序、定期存款的定时扫描）必须使用 `Bukkit.getAsyncScheduler().runNow()` 或 `runAtFixedRate()`。
|
||
* 涉及玩家操作（如扣除支票物品、打开 GUI、发送消息），如果从异步线程切回主逻辑，必须调度到该玩家所在的实体区域线程：`player.getScheduler().run(...)`。
|
||
2. **Vault 注册必须正确**：在 `onEnable()` 中，必须实例化一个实现 `net.milkbowl.vault.economy.Economy` 接口的类，并通过 ServiceManager 注册，优先度设为 `Highest`。
|
||
3. **PDC 防伪**：支票的生成和兑现，必须在 `NamespacedKey` 中读写特定的标识符，并在 `PlayerInteractEvent` 中处理防伪与兑换逻辑。
|
||
4. **并发与线程安全**：Vault 接口的调用（如 `withdrawPlayer`）可能会在其他插件的异步线程中被触发。所有的经济数据操作必须是线程安全的（建议对缓存数据使用 `ConcurrentHashMap`，并确保数据库入库操作不会出现脏读）。
|
||
5. **GUI 系统与防刷**：请使用 1.21.8 标准的 Inventory API 构建 GUI。处理支票兑现时，一定要注意 `ItemStack#setAmount()` 的安全逻辑，防止多线程并发导致的刷钱问题。 |