# 🏦 CraftBank（工艺银行）

> 适用于 **Folia 1.21.8** 的全能经济与银行核心插件 —— 旨在完全替代 XConomy 等传统经济插件。

[![Folia](https://img.shields.io/badge/Folia-1.21.8-blue)](https://papermc.io/software/folia)
[![Java](https://img.shields.io/badge/Java-21%2B-orange)](https://adoptium.net/)
[![Vault](https://img.shields.io/badge/Vault-required-green)](https://www.spigotmc.org/resources/vault.34315/)

CraftBank 内置完善的「个人钱包 / 现金」系统，并引入深度模拟的银行系统：实体银行卡、可交易支票、活期储蓄与严格的定期存款（带利息）。全程遵循 **Folia 多核服务端**的线程模型，使用 `AsyncScheduler` / `GlobalRegionScheduler` / `RegionScheduler` 调度，绝不使用已弃用的 `Bukkit.getScheduler()`。

---

## ✨ 核心功能

| 模块 | 说明 |
|------|------|
| 💵 **核心经济** | 每位玩家独立现金账户；实现 Vault `Economy` 接口并以 `Highest` 优先级注册，接管全服扣款 |
| 💳 **银行卡** | 实体物品，PDC 绑定 UUID + 序列号；右键指定方块开柜；丢失可挂失补办（旧卡作废）|
| 📜 **支票** | `/cheque <金额>` 具现化为可流通实体物品；右键兑现入钱包；PDC 防伪 + 防刷 |
| 💰 **活期储蓄** | 存取自由，按真实时间戳逐日复利结算（含离线补偿，带封顶）|
| ⏳ **定期存款** | 7/15/30 天可选，到期前**任何情况不可提前支取**；到期本息自动入活期 |

---

## 🛠️ 依赖

- **必须**：[Vault](https://www.spigotmc.org/resources/vault.34315/)（CraftBank 作为其 Service Provider 注入）
- **可选**：[PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/)

> MySQL 驱动默认未内置；若使用 MySQL，请将驱动放入服务端 `libraries`，或在 `build.gradle.kts` 中取消相应依赖注释后自行打包。

---

## 💻 指令与权限

### 基础经济（所有人）
| 指令 | 说明 |
|------|------|
| `/money [玩家]` | 查看现金余额（查他人需 `craftbank.money.others`）|
| `/pay <玩家> <金额>` | 现金转账 |
| `/baltop [页码]` | 现金排行榜 |

### 银行玩家（`craftbank.use`）
| 指令 | 说明 |
|------|------|
| `/bank open` | 打开银行 GUI（可配置是否允许）|
| `/bank card apply` | 申请新银行卡 |
| `/bank card revoke` | 挂失并作废当前银行卡 |
| `/bank deposit <金额>` | 现金 → 活期 |
| `/bank withdraw <金额>` | 活期 → 现金 |
| `/cheque <金额>` | 开具支票 |

### 管理员（`craftbank.admin`）
| 指令 | 说明 |
|------|------|
| `/bankadmin reload` | 重载配置 |
| `/bankadmin give/take/set <玩家> <金额>` | 增加 / 扣除 / 设置现金 |
| `/bankadmin setinterest <savings\|term_7d\|term_15d\|term_30d> <利率>` | 动态修改利率 |

---

## 🔌 PlaceholderAPI 变量

| 变量 | 含义 |
|------|------|
| `%craftbank_cash%` | 现金（纯数字）|
| `%craftbank_cash_formatted%` | 现金（含货币符号）|
| `%craftbank_bank_saving%` | 活期（纯数字）|
| `%craftbank_bank_saving_formatted%` | 活期（含货币符号）|

---

## ⚙️ 配置文件

详见生成的 `config.yml`，涵盖：数据库（SQLite/MySQL）、货币设置、利率（活期 / 各定期）、银行交互方块、银行卡与支票的自定义材质 / CustomModelData / 名称 / Lore、以及全部消息文案。

---

## 🔨 从源码构建

```bash
# 需要 JDK 21+（已用 JDK 25 验证通过）
./gradlew shadowJar
```

产物位于 `build/libs/CraftBank-<version>.jar`，已内置 SQLite 与 HikariCP 驱动，可直接丢进 `plugins/` 目录。

---

## 🤖 Folia 线程安全设计

- **后台任务**（数据库、`/baltop` 排序、利息扫描）走 `AsyncScheduler`。
- **玩家相关操作**（扣物品、开 GUI、发消息）从异步切回时调度到 `player.getScheduler()`（实体区域线程）。
- 经济数据缓存使用 `ConcurrentHashMap`，单账户余额变更用 `synchronized` 保证原子，抵御来自其它插件异步线程（经 Vault）的并发刷钱。
- 支票兑现在玩家区域线程独占操作物品栏；定期领取用数据库 `UPDATE ... WHERE claimed = 0` 原子置位防重复发放。

---

## 📄 许可证

见 [LICENSE](LICENSE)。